three-base 2.0.169 → 2.0.175

package/PipeMesh/PipeMesh.d.ts

@@ -1,25 +1,97 @@
-import { Mesh, Vector3, Material } from "three";
-import { PathPointList } from "./PathPointList";
-import { PathTubeGeometry } from "./PathTubeGeometry";
-export type PipeMeshProps = {
-    vector3s: Array<Vector3>;
-    radius?: number;
-    segments?: number;
-};
+import { Color, Group } from "three";
+import PipeJoint from "./PipeJoint";
+import PipeStraight from "./PipeStraight";
+import { type PipeJson, type Vec3 } from "./directRoute";
+export interface PipeMeshProps {
+    /** 控制点（米）。**相邻两点之间直连一根直管**（可斜），拐角自动补一颗同径球 */
+    points?: Vec3[];
+    /** 管道直径（米），默认 1 */
+    diameter?: number;
+    /** 管壁颜色（逐实例色，不是材质底色） */
+    color?: Color | number | string;
+    /** 多 InstancedGroup 共存时的归属（配合 `new InstancedGroup(owner)`，如预览弹窗） */
+    owner?: string;
+}
 /**
- * 创建基础的管道模型
+ * 组合管道（点与点直连）：**直管 + 拐角补角球全部是 InstancedChild**，由 ThreeBase 的 InstancedGroup
+ * 每帧自动合批。
+ *
+ * ⭐ 为什么这样划算：全场景只有两份几何（单位圆柱、单位球），所以**不管多少折点，
+ *   draw call 恒为 2**；改直径/改长度只动实例矩阵，不重建任何几何。旧的 PipeMesh（现
+ *   `three-base/PipeMeshLegacy/`）是一条折线扫一张合并 BufferGeometry，改点要重算顶点，两者路线互斥。
+ *
+ * ⭐ 走线口径（皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」）：
+ *   控制点 i 与 i+1 之间就是一根直管 —— 长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *   没有轴序、没有正交拆段、没有 90° 弯头。走线算术全在 `directRoute.ts`（零依赖，可纯数字断言）。
+ *
+ * 用法：
+ * ```ts
+ * const pipe = new PipeMesh({ points: [[-4,0,0],[0,3,0],[4,3,-4]], diameter: 1 });
+ * scene.add(pipe);
+ * pipe.setDiameter(0.6);          // 只改缩放
+ * pipe.movePoint(1, [0, 5, 0]);   // 只改控制点，走线自动重算
+ * const json = pipe.exportJson();   // 存档 / 导出
+ * PipeMesh.fromJson(json);          // 引用 JSON 重建
+ * pipe.setShown(false);             // 藏起这条管道（走注册表，不是 visible）
+ * ```
+ *
+ * ⚠️ 实例池是**差分复用**的：段数变少时多出来的实例会被摘出注册表并 dispose，不会留在注册表里
+ *   继续被合批（注册表是全局 Set，`scene.remove` 停不了它）。
  */
-export default class PipeMesh extends Mesh<PathTubeGeometry, Material> {
-    constructor(props: PipeMeshProps);
-    type: string;
-    vector3s: Array<Vector3>;
-    radius: number;
-    segments: number;
-    pathPointList: PathPointList;
-    material: Material;
-    set(props: PipeMeshProps): void;
-    setVector(i: number, vector: Vector3): void;
-    getVector(i: number): Vector3;
-    setLatestVector(vector: Vector3): void;
-    getLatestVector(): Vector3;
+export default class PipeMesh extends Group {
+    points: Vec3[];
+    diameter: number;
+    color: Color;
+    /** 最近一次走线的退化提示（供面板显示；不影响渲染） */
+    warnings: string[];
+    /** 直管实例（段数 = 有效控制点对数） */
+    readonly straights: PipeStraight[];
+    /** 拐角补角球实例（内部控制点各一颗） */
+    readonly joints: PipeJoint[];
+    private _owner?;
+    private _shown;
+    constructor(props?: PipeMeshProps);
+    /**
+     * 显隐：走注册表摘除/挂回，而不是靠 `visible` 标志。
+     * ⚠️ 实例化那条路的真实几何在 InstancedGroup 的 batch 里（不在这棵树下面），
+     *   所以 `pipe.visible = false` 对它**不起作用**；要藏起来就调本方法。
+     */
+    setShown(shown: boolean): this;
+    get shown(): boolean;
+    /** 按当前 points/diameter 重算实例位姿；只在段数变化时增删实例 */
+    rebuild(): this;
+    private _allInstances;
+    /** 把池子拉到目标长度：不足 new + add 进本组，超出摘出并 dispose（连带注册表） */
+    private _fitPool;
+    setPoints(points: Vec3[]): this;
+    /** 改单个控制点（拖拽现场用，比整表重设省一次数组拷贝） */
+    movePoint(index: number, p: Vec3): this;
+    addPoint(p: Vec3): this;
+    insertPoint(index: number, p: Vec3): this;
+    removePoint(index: number): this;
+    /**
+     * 控制点顺序整体颠倒（皇上旨 2026-10-25「做一个节点倒序的功能，让管道点的顺序颠倒一下」）。
+     *
+     * ⚠️ 直连方案下几何**逐段等价**（圆柱两端对称、球压在点上，都不认方向）⇒ 画面上看不出变化，
+     *   变的是**数据序**：存档 / 导出 JSON / 将来带方向性的特性（流向箭头、渐变、开孔位置）都按这个序。
+     *   所以别指望点一下画面有动静 —— 要验它，去面板看「控制点 #N」的编号，或导出 JSON 比对。
+     */
+    reversePoints(): this;
+    setDiameter(d: number): this;
+    setColor(c: Color | number | string): this;
+    /** 导出当前管道的 JSON 数据（不碰 three 的 Object3D 序列化格式，那个是场景树用的） */
+    exportJson(): PipeJson;
+    /** 引用 JSON 重建当前管道：非法数据不动现场，返回人话原因 */
+    importJson(input: unknown): {
+        ok: boolean;
+        reason?: string;
+    };
+    /** 用 JSON 起一个新管道对象；失败时 pipe 为 undefined，reason 可直接弹给用户 */
+    static fromJson(input: unknown): {
+        pipe?: PipeMesh;
+        ok: boolean;
+        reason?: string;
+    };
+    /** 摘掉全部实例并释放注册表登记（组本身留在 scene 里由调用方 remove） */
+    dispose(): void;
 }

package/PipeMesh/PipeMesh.js

@@ -1,63 +1,202 @@
-/*
- * @Author: xiaosihan
- * @Date: 2022-02-16 23:13:14
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2024-11-23 13:06:54
- */
-import { DoubleSide, DynamicDrawUsage, Mesh, MeshLambertMaterial } from "three";
-import { PathPointList } from "./PathPointList";
-import { PathTubeGeometry } from "./PathTubeGeometry";
+import { Color, Group } from "three";
+import { instancedChildRegistry } from "../instanced/InstancedChild";
+import PipeJoint from "./PipeJoint";
+import PipeStraight from "./PipeStraight";
+import { PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+import { planDirectLayout, makePipeJson, parsePipeJson } from "./directRoute";
 /**
- * 创建基础的管道模型
+ * 组合管道（点与点直连）：**直管 + 拐角补角球全部是 InstancedChild**，由 ThreeBase 的 InstancedGroup
+ * 每帧自动合批。
+ *
+ * ⭐ 为什么这样划算：全场景只有两份几何（单位圆柱、单位球），所以**不管多少折点，
+ *   draw call 恒为 2**；改直径/改长度只动实例矩阵，不重建任何几何。旧的 PipeMesh（现
+ *   `three-base/PipeMeshLegacy/`）是一条折线扫一张合并 BufferGeometry，改点要重算顶点，两者路线互斥。
+ *
+ * ⭐ 走线口径（皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」）：
+ *   控制点 i 与 i+1 之间就是一根直管 —— 长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *   没有轴序、没有正交拆段、没有 90° 弯头。走线算术全在 `directRoute.ts`（零依赖，可纯数字断言）。
+ *
+ * 用法：
+ * ```ts
+ * const pipe = new PipeMesh({ points: [[-4,0,0],[0,3,0],[4,3,-4]], diameter: 1 });
+ * scene.add(pipe);
+ * pipe.setDiameter(0.6);          // 只改缩放
+ * pipe.movePoint(1, [0, 5, 0]);   // 只改控制点，走线自动重算
+ * const json = pipe.exportJson();   // 存档 / 导出
+ * PipeMesh.fromJson(json);          // 引用 JSON 重建
+ * pipe.setShown(false);             // 藏起这条管道（走注册表，不是 visible）
+ * ```
+ *
+ * ⚠️ 实例池是**差分复用**的：段数变少时多出来的实例会被摘出注册表并 dispose，不会留在注册表里
+ *   继续被合批（注册表是全局 Set，`scene.remove` 停不了它）。
  */
-export default class PipeMesh extends Mesh {
-    constructor(props) {
+export default class PipeMesh extends Group {
+    points = [];
+    diameter = 1;
+    color = new Color(PIPE_DEFAULT_COLOR);
+    /** 最近一次走线的退化提示（供面板显示；不影响渲染） */
+    warnings = [];
+    /** 直管实例（段数 = 有效控制点对数） */
+    straights = [];
+    /** 拐角补角球实例（内部控制点各一颗） */
+    joints = [];
+    _owner;
+    _shown = true;
+    constructor(props = {}) {
         super();
-        this.set(props);
-    }
-    type = "pipemesh";
-    vector3s = []; // 管道上的点
-    radius = 1; //管道的半径
-    segments = 10; //管道的段数
-    pathPointList = new PathPointList();
-    material = new MeshLambertMaterial({
-        side: DoubleSide,
-        color: "#fff",
-    });
-    // 设置数据
-    set(props) {
-        this.vector3s = props.vector3s;
-        this.radius = props.radius || 1;
-        this.segments = props.segments || 10;
-        this.pathPointList.set(this.vector3s, props.radius * 2, 10);
-        this.geometry = new PathTubeGeometry({
-            pathPointList: this.pathPointList,
-            options: {
-                arrow: true,
-                progress: 1,
-                radius: props.radius,
-                radialSegments: this.segments,
-            },
-            usage: DynamicDrawUsage,
-            transparent: true,
+        this.type = "PipeMesh";
+        this.name = "PipeMesh";
+        this._owner = props.owner;
+        this.diameter = props.diameter ?? 1;
+        if (props.color !== undefined)
+            this.color.set(props.color);
+        this.points = (props.points ?? []).map((p) => [p[0], p[1], p[2]]);
+        this.rebuild();
+    }
+    /**
+     * 显隐：走注册表摘除/挂回，而不是靠 `visible` 标志。
+     * ⚠️ 实例化那条路的真实几何在 InstancedGroup 的 batch 里（不在这棵树下面），
+     *   所以 `pipe.visible = false` 对它**不起作用**；要藏起来就调本方法。
+     */
+    setShown(shown) {
+        this._shown = shown;
+        for (const child of this._allInstances()) {
+            if (shown)
+                instancedChildRegistry.add(child);
+            else
+                instancedChildRegistry.delete(child);
+        }
+        return this;
+    }
+    get shown() {
+        return this._shown;
+    }
+    /** 按当前 points/diameter 重算实例位姿；只在段数变化时增删实例 */
+    rebuild() {
+        const plan = planDirectLayout(this.points, { diameter: this.diameter });
+        this.warnings = plan.warnings;
+        this._fitPool(this.straights, plan.straights.length, () => new PipeStraight());
+        this._fitPool(this.joints, plan.joints.length, () => new PipeJoint());
+        plan.straights.forEach((part, i) => {
+            const inst = this.straights[i];
+            inst.applyAt(part.center, part.dir, this.diameter, part.length);
+            inst.setPartIndex(part.index);
+            inst.setColor(this.color);
         });
+        plan.joints.forEach((part, i) => {
+            const inst = this.joints[i];
+            inst.applyAt(part.center, this.diameter);
+            inst.setPartIndex(part.index);
+            inst.setColor(this.color);
+        });
+        return this;
+    }
+    _allInstances() {
+        return [...this.straights, ...this.joints];
+    }
+    /** 把池子拉到目标长度：不足 new + add 进本组，超出摘出并 dispose（连带注册表） */
+    _fitPool(pool, want, make) {
+        while (pool.length < want) {
+            const inst = make();
+            if (this._owner)
+                inst.setOwner(this._owner);
+            this.add(inst);
+            pool.push(inst);
+        }
+        while (pool.length > want) {
+            const inst = pool.pop();
+            this.remove(inst);
+            inst.dispose();
+        }
+    }
+    // ===== 参数入口：每一条都收口到 rebuild()，避免各处各自改矩阵 =====
+    setPoints(points) {
+        this.points = points.map((p) => [p[0], p[1], p[2]]);
+        return this.rebuild();
     }
-    // 设置指定点的坐标
-    setVector(i, vector) {
-        this.vector3s[i].copy(vector);
-        this.pathPointList.set(this.vector3s, this.radius * 2, this.segments);
-        this.geometry.update(this.pathPointList, { radius: this.radius });
+    /** 改单个控制点（拖拽现场用，比整表重设省一次数组拷贝） */
+    movePoint(index, p) {
+        if (index < 0 || index >= this.points.length)
+            return this;
+        this.points[index] = [p[0], p[1], p[2]];
+        return this.rebuild();
     }
-    // 获取指定点的坐标
-    getVector(i) {
-        return this.vector3s[i];
+    addPoint(p) {
+        this.points.push([p[0], p[1], p[2]]);
+        return this.rebuild();
     }
-    // 设置最后一个点的坐标
-    setLatestVector(vector) {
-        this.setVector(this.vector3s.length - 1, vector);
+    insertPoint(index, p) {
+        if (index < 0 || index > this.points.length)
+            return this;
+        this.points.splice(index, 0, [p[0], p[1], p[2]]);
+        return this.rebuild();
+    }
+    removePoint(index) {
+        if (index < 0 || index >= this.points.length)
+            return this;
+        this.points.splice(index, 1);
+        return this.rebuild();
+    }
+    /**
+     * 控制点顺序整体颠倒（皇上旨 2026-10-25「做一个节点倒序的功能，让管道点的顺序颠倒一下」）。
+     *
+     * ⚠️ 直连方案下几何**逐段等价**（圆柱两端对称、球压在点上，都不认方向）⇒ 画面上看不出变化，
+     *   变的是**数据序**：存档 / 导出 JSON / 将来带方向性的特性（流向箭头、渐变、开孔位置）都按这个序。
+     *   所以别指望点一下画面有动静 —— 要验它，去面板看「控制点 #N」的编号，或导出 JSON 比对。
+     */
+    reversePoints() {
+        this.points.reverse();
+        return this.rebuild();
+    }
+    setDiameter(d) {
+        this.diameter = d;
+        return this.rebuild();
+    }
+    setColor(c) {
+        this.color.set(c);
+        // 颜色走逐实例 instanceColor，与位姿无关 ⇒ 不动矩阵、不必 rebuild
+        for (const inst of this._allInstances())
+            inst.setColor(this.color);
+        return this;
+    }
+    // ===== JSON：对象与项目存档共用的形状 =====
+    /** 导出当前管道的 JSON 数据（不碰 three 的 Object3D 序列化格式，那个是场景树用的） */
+    exportJson() {
+        return makePipeJson(this.points.map((p) => [p[0], p[1], p[2]]), this.diameter, `#${this.color.getHexString()}`);
+    }
+    /** 引用 JSON 重建当前管道：非法数据不动现场，返回人话原因 */
+    importJson(input) {
+        const parsed = parsePipeJson(input);
+        if (!parsed.ok || !parsed.json)
+            return { ok: false, reason: parsed.reason ?? "JSON 解析失败" };
+        const json = parsed.json;
+        this.diameter = json.diameter;
+        if (json.color)
+            this.color.set(json.color);
+        this.points = json.points.map((p) => [p[0], p[1], p[2]]);
+        this.rebuild();
+        return { ok: true };
+    }
+    /** 用 JSON 起一个新管道对象；失败时 pipe 为 undefined，reason 可直接弹给用户 */
+    static fromJson(input) {
+        const parsed = parsePipeJson(input);
+        if (!parsed.ok || !parsed.json)
+            return { ok: false, reason: parsed.reason ?? "JSON 解析失败" };
+        const json = parsed.json;
+        const pipe = new PipeMesh({
+            points: json.points,
+            diameter: json.diameter,
+            color: json.color,
+        });
+        return { pipe, ok: true };
     }
-    // 回去最后一个点的坐标
-    getLatestVector() {
-        return this.getVector(this.vector3s.length - 1);
+    /** 摘掉全部实例并释放注册表登记（组本身留在 scene 里由调用方 remove） */
+    dispose() {
+        for (const inst of this._allInstances()) {
+            this.remove(inst);
+            inst.dispose();
+        }
+        this.straights.length = 0;
+        this.joints.length = 0;
     }
 }