three-base 2.0.172 → 2.0.180

package/PipeMesh/axisSnap.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 控制点轴向吸附（纯数字，零运行时依赖）。
+ *
+ * 皇上旨 2026-10-25：「添加节点和编辑节点的时候，实时计算当前节点在 x/y/z 轴上的投影距离，
+ * 距离谁最近就改到哪里，让管道随时保持横平竖直。」
+ *
+ * ⭐ 什么叫「投影到轴上」——不是投影到世界坐标轴，而是投影到**过参考点（相邻控制点）的三条轴线**：
+ *   三条候选各保留一个坐标、另两个坐标抄参考点：
+ *     只沿 X 走 ⇒ [p.x, ref.y, ref.z]，偏离量 = √(Δy² + Δz²)
+ *     只沿 Y 走 ⇒ [ref.x, p.y, ref.z]，偏离量 = √(Δx² + Δz²)
+ *     只沿 Z 走 ⇒ [ref.x, ref.y, p.z]，偏离量 = √(Δx² + Δy²)
+ *   取偏离量最小的那条 ⇒ 该段只剩一根轴有位移 ⇒ 横平竖直。
+ *
+ * ⚠️ 三个候选都**保留待吸附点自身的那根轴坐标**（比如「只沿 X」保留 p.x）——这是关键：
+ *   沿 X 箭头拖动时 p.x 能自由变化，吸附不会把点钉死；被拉回的只是另外两根轴的偏移。
+ *
+ * ⚠️ 这里改的是**控制点本身**（数据层），不是走线算术：PipeMesh 仍是相邻点直连（directRoute.ts），
+ *   只是点的位置被挪到轴线上。⛔ 别在这里插折点 —— 那是已删除的 orthogonalRoute 老路，
+ *   两件事的区别是：正交走线「自动加拐点把斜线拆成三段」，这里是「把点挪正，段还是那一段」。
+ *
+ * 留成零运行时依赖（只用 `import type`，编译时擦除）⇒ `test/pipeRoute.test.js` 能直接 require
+ * 编译产物逐条断言，不必起浏览器。
+ */
+import type { Vec3 } from "./directRoute";
+/** 轴名（与编辑页面板的 X / Y / Z 三行同口径） */
+export type AxisName = "x" | "y" | "z";
+/** 吸附结果：落点 + 保留的轴 + 原位置到落点的欧氏距离 */
+export interface AxisSnapResult {
+    /** 吸附后的位置（新数组，不改入参） */
+    point: Vec3;
+    /** 被保留（即该段唯一有位移）的轴；另两根轴已对齐到参考点 */
+    axis: AxisName;
+    /** 原位置到吸附位置的欧氏距离（米）= 这次「挪了多少」 */
+    distance: number;
+}
+/**
+ * 沿指定轴吸附：保留 p 在这根轴上的坐标，另外两根轴抄参考点。
+ * 用于面板数字输入 —— 用户输入 X 就是「沿 X 走这么远」，Y/Z 自动回落到来路，段仍是横平竖直。
+ */
+export declare function snapAlongAxis(p: Vec3, ref: Vec3, axis: AxisName): Vec3;
+/**
+ * 把 p 吸到「过 ref 的三条轴线」上最近的那条。
+ *
+ * ⚠️ 永远返回结果（不返回 null）：p 已经在某条轴线上时，该候选的 distance 就是 0，
+ *   写回后坐标一个不变 —— 调用方不必再判空。
+ */
+export declare function snapToNearestAxis(p: Vec3, ref: Vec3): AxisSnapResult;
+/**
+ * 两点是否轴对齐（三个坐标里至少两个相等 ⇒ 这一段只沿一根轴）。
+ * 纯判定、不改数据：编辑页面板拿它给「这一段是不是歪的」上提示，测试拿它做断言。
+ */
+export declare function isAxisAligned(a: Vec3, b: Vec3, eps?: number): boolean;

package/PipeMesh/axisSnap.js

@@ -0,0 +1,52 @@
+/** 轴名 → 分量下标 */
+const AXIS_INDEX = { x: 0, y: 1, z: 2 };
+/**
+ * 候选顺序固定 x → y → z。
+ * 偏离量打平时（浮点噪声级）保留先出现的那个 ⇒ 结果可复现，不会因为一次 1e-17 的抖动换轴。
+ */
+const AXIS_ORDER = ["x", "y", "z"];
+/** 判定「两轴坐标相同」的容差（与走线模块的 PIPE_EPS 同量级） */
+const ALIGN_EPS = 1e-6;
+/**
+ * 沿指定轴吸附：保留 p 在这根轴上的坐标，另外两根轴抄参考点。
+ * 用于面板数字输入 —— 用户输入 X 就是「沿 X 走这么远」，Y/Z 自动回落到来路，段仍是横平竖直。
+ */
+export function snapAlongAxis(p, ref, axis) {
+    const k = AXIS_INDEX[axis];
+    const q = [ref[0], ref[1], ref[2]];
+    q[k] = p[k];
+    return q;
+}
+/**
+ * 把 p 吸到「过 ref 的三条轴线」上最近的那条。
+ *
+ * ⚠️ 永远返回结果（不返回 null）：p 已经在某条轴线上时，该候选的 distance 就是 0，
+ *   写回后坐标一个不变 —— 调用方不必再判空。
+ */
+export function snapToNearestAxis(p, ref) {
+    let best = null;
+    for (const axis of AXIS_ORDER) {
+        const point = snapAlongAxis(p, ref, axis);
+        const dx = point[0] - p[0];
+        const dy = point[1] - p[1];
+        const dz = point[2] - p[2];
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        // 用「严格小于」+ 容差：平局时保留先出现的轴，不被浮点噪声换来换去
+        if (!best || distance < best.distance - 1e-12)
+            best = { point, axis, distance };
+    }
+    // 循环一定跑过一轮 ⇒ best 非空；写这个兜底只为满足 strict 关闭时的可读性
+    return best;
+}
+/**
+ * 两点是否轴对齐（三个坐标里至少两个相等 ⇒ 这一段只沿一根轴）。
+ * 纯判定、不改数据：编辑页面板拿它给「这一段是不是歪的」上提示，测试拿它做断言。
+ */
+export function isAxisAligned(a, b, eps = ALIGN_EPS) {
+    let same = 0;
+    for (let i = 0; i < 3; i++) {
+        if (Math.abs(a[i] - b[i]) < eps)
+            same++;
+    }
+    return same >= 2;
+}

package/PipeMesh/axisSnap.ts

@@ -0,0 +1,93 @@
+/**
+ * 控制点轴向吸附（纯数字，零运行时依赖）。
+ *
+ * 皇上旨 2026-10-25：「添加节点和编辑节点的时候，实时计算当前节点在 x/y/z 轴上的投影距离，
+ * 距离谁最近就改到哪里，让管道随时保持横平竖直。」
+ *
+ * ⭐ 什么叫「投影到轴上」——不是投影到世界坐标轴，而是投影到**过参考点（相邻控制点）的三条轴线**：
+ *   三条候选各保留一个坐标、另两个坐标抄参考点：
+ *     只沿 X 走 ⇒ [p.x, ref.y, ref.z]，偏离量 = √(Δy² + Δz²)
+ *     只沿 Y 走 ⇒ [ref.x, p.y, ref.z]，偏离量 = √(Δx² + Δz²)
+ *     只沿 Z 走 ⇒ [ref.x, ref.y, p.z]，偏离量 = √(Δx² + Δy²)
+ *   取偏离量最小的那条 ⇒ 该段只剩一根轴有位移 ⇒ 横平竖直。
+ *
+ * ⚠️ 三个候选都**保留待吸附点自身的那根轴坐标**（比如「只沿 X」保留 p.x）——这是关键：
+ *   沿 X 箭头拖动时 p.x 能自由变化，吸附不会把点钉死；被拉回的只是另外两根轴的偏移。
+ *
+ * ⚠️ 这里改的是**控制点本身**（数据层），不是走线算术：PipeMesh 仍是相邻点直连（directRoute.ts），
+ *   只是点的位置被挪到轴线上。⛔ 别在这里插折点 —— 那是已删除的 orthogonalRoute 老路，
+ *   两件事的区别是：正交走线「自动加拐点把斜线拆成三段」，这里是「把点挪正，段还是那一段」。
+ *
+ * 留成零运行时依赖（只用 `import type`，编译时擦除）⇒ `test/pipeRoute.test.js` 能直接 require
+ * 编译产物逐条断言，不必起浏览器。
+ */
+import type { Vec3 } from "./directRoute";
+
+/** 轴名（与编辑页面板的 X / Y / Z 三行同口径） */
+export type AxisName = "x" | "y" | "z";
+
+/** 吸附结果：落点 + 保留的轴 + 原位置到落点的欧氏距离 */
+export interface AxisSnapResult {
+    /** 吸附后的位置（新数组，不改入参） */
+    point: Vec3;
+    /** 被保留（即该段唯一有位移）的轴；另两根轴已对齐到参考点 */
+    axis: AxisName;
+    /** 原位置到吸附位置的欧氏距离（米）= 这次「挪了多少」 */
+    distance: number;
+}
+
+/** 轴名 → 分量下标 */
+const AXIS_INDEX: Record<AxisName, 0 | 1 | 2> = { x: 0, y: 1, z: 2 };
+
+/**
+ * 候选顺序固定 x → y → z。
+ * 偏离量打平时（浮点噪声级）保留先出现的那个 ⇒ 结果可复现，不会因为一次 1e-17 的抖动换轴。
+ */
+const AXIS_ORDER: AxisName[] = ["x", "y", "z"];
+
+/** 判定「两轴坐标相同」的容差（与走线模块的 PIPE_EPS 同量级） */
+const ALIGN_EPS = 1e-6;
+
+/**
+ * 沿指定轴吸附：保留 p 在这根轴上的坐标，另外两根轴抄参考点。
+ * 用于面板数字输入 —— 用户输入 X 就是「沿 X 走这么远」，Y/Z 自动回落到来路，段仍是横平竖直。
+ */
+export function snapAlongAxis(p: Vec3, ref: Vec3, axis: AxisName): Vec3 {
+    const k = AXIS_INDEX[axis];
+    const q: Vec3 = [ref[0], ref[1], ref[2]];
+    q[k] = p[k];
+    return q;
+}
+
+/**
+ * 把 p 吸到「过 ref 的三条轴线」上最近的那条。
+ *
+ * ⚠️ 永远返回结果（不返回 null）：p 已经在某条轴线上时，该候选的 distance 就是 0，
+ *   写回后坐标一个不变 —— 调用方不必再判空。
+ */
+export function snapToNearestAxis(p: Vec3, ref: Vec3): AxisSnapResult {
+    let best: AxisSnapResult | null = null;
+    for (const axis of AXIS_ORDER) {
+        const point = snapAlongAxis(p, ref, axis);
+        const dx = point[0] - p[0];
+        const dy = point[1] - p[1];
+        const dz = point[2] - p[2];
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        // 用「严格小于」+ 容差：平局时保留先出现的轴，不被浮点噪声换来换去
+        if (!best || distance < best.distance - 1e-12) best = { point, axis, distance };
+    }
+    // 循环一定跑过一轮 ⇒ best 非空；写这个兜底只为满足 strict 关闭时的可读性
+    return best as AxisSnapResult;
+}
+
+/**
+ * 两点是否轴对齐（三个坐标里至少两个相等 ⇒ 这一段只沿一根轴）。
+ * 纯判定、不改数据：编辑页面板拿它给「这一段是不是歪的」上提示，测试拿它做断言。
+ */
+export function isAxisAligned(a: Vec3, b: Vec3, eps = ALIGN_EPS): boolean {
+    let same = 0;
+    for (let i = 0; i < 3; i++) {
+        if (Math.abs(a[i] - b[i]) < eps) same++;
+    }
+    return same >= 2;
+}

package/PipeMesh/directRoute.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 直连管道走线（纯数字，零依赖）。
+ *
+ * 皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」：
+ * 相邻两个控制点之间就是一根直管（可以是斜的），不再按轴序拆正交段、不再有 90° 弯头。
+ * 每段只算三件事：长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *
+ * ⭐ 为什么仍单独一个零 import 模块：管道几何要写进 InstancedChild 的实例矩阵（见 PipeMesh.ts），
+ *   而「几段、每段多长、朝哪、球放哪」是可独立核对的算术。留成零依赖 ⇒ `test/pipeRoute.test.js`
+ *   能直接 require 编译产物逐字段断言，不必起浏览器。
+ *
+ * ⚠️ 拐角为什么必须补一颗球：直管是**开口圆柱**（CylinderGeometry openEnded，见 PipeStraight.ts），
+ *   两段斜管在拐角处只有轴线相交、端面是斜的 ⇒ 夹角外侧必然露一个楔形缺口，能直接看穿管子。
+ *   补法取最省事的一种：控制点上放一颗「直径同管」的球（PipeJoint），球面把缺口盖满。
+ *   球与管同径 ⇒ 共线时完全看不出来，有夹角时是光滑过渡，不是一串珠子。
+ *
+ * ⚠️ 上一版（`orthogonalRoute.ts`，2026-10-21 ～ 10-25）是按 axisOrder 逐轴补齐的正交走线 + 90° 弯头，
+ *   已整份删除。要找回请从 git 取，别在半路上重新发明一遍。
+ */
+/** 世界坐标点，单位米 */
+export type Vec3 = [number, number, number];
+/** 直管段：几何中心 + 轴向单位向量 + 段长 */
+export interface StraightPart {
+    /** 段序号（从 0 起，对应「控制点 i → 控制点 i+1」） */
+    index: number;
+    /** 直管几何体的中心（单位圆柱沿 +Y 生成，容器再旋转/缩放到此位姿） */
+    center: Vec3;
+    /** 走线方向，单位向量（任意朝向，不限六向） */
+    dir: Vec3;
+    /** 段长（米）= 两控制点欧氏距离 */
+    length: number;
+}
+/** 拐角补角球：球心压在控制点上，半径 = 直径/2 */
+export interface JointPart {
+    /** 对应控制点下标（1 … n-2；两端没有拐角，不补球） */
+    index: number;
+    center: Vec3;
+    radius: number;
+}
+export interface PipePlan {
+    straights: StraightPart[];
+    joints: JointPart[];
+    /** 退化输入说明（点重合、走线全零、直径非法…）；渲染不受影响，供面板提示 */
+    warnings: string[];
+}
+/** 段长可忽略的判据（与上一版正交方案同量级） */
+export declare const PIPE_EPS = 0.000001;
+/**
+ * 算出整条管道的直管 + 补角球清单。
+ *
+ * ⚠️ 重合的控制点对**不产生直管**（长度 0 的圆柱缩放会让法线退化），但两端点仍参与球的判定 ——
+ *   只要该点还连着别的有效直管，球照放，接缝才不会因为一个废段而开口。
+ */
+export declare function planDirectLayout(points: Vec3[], opts?: {
+    diameter?: number;
+}): PipePlan;
+/**
+ * JSON 是「管道对象」与「编辑页项目」共用的唯一数据形状。
+ * 单位米；points 是控制点（不是段），所以重新走线/改直径只改这几个字段即可。
+ *
+ * ⚠️ version 仍是 1：形状（points / diameter / color）与上一版一致，只是上一版的 `axisOrder`
+ *   从「必填参数」降级成「忽略的多余键」⇒ 皇上库里的旧项目照样打得开，只是形状按直连重算。
+ */
+export interface PipeJson {
+    format: "three-base.pipe";
+    version: 1;
+    diameter: number;
+    color?: string;
+    points: Vec3[];
+}
+export declare const PIPE_JSON_FORMAT = "three-base.pipe";
+export declare const PIPE_JSON_VERSION = 1;
+export declare function makePipeJson(points: Vec3[], diameter: number, color?: string): PipeJson;
+/**
+ * 解析结果：`ok=false` 时 `reason` 是人话，可直接弹给编辑页显示；`ok=true` 时 `json` 已归一化。
+ * ⚠️ 刻意不用 `{ok:true;json} | {ok:false;reason}` 可辨识联合：库编译走的是 `strict:false`
+ *   （three-base/tsconfig.json），实测那种写法在 `if (!r.ok)` 之后取 `r.reason` 会报 TS2339。
+ */
+export interface PipeJsonResult {
+    ok: boolean;
+    json?: PipeJson;
+    reason?: string;
+}
+/** 宽松校验：接受对象/字符串，字段缺失或类型错都返回 reason 而不抛异常（导入现场不许崩） */
+export declare function parsePipeJson(input: unknown): PipeJsonResult;

package/PipeMesh/directRoute.js

@@ -0,0 +1,126 @@
+/**
+ * 直连管道走线（纯数字，零依赖）。
+ *
+ * 皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」：
+ * 相邻两个控制点之间就是一根直管（可以是斜的），不再按轴序拆正交段、不再有 90° 弯头。
+ * 每段只算三件事：长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *
+ * ⭐ 为什么仍单独一个零 import 模块：管道几何要写进 InstancedChild 的实例矩阵（见 PipeMesh.ts），
+ *   而「几段、每段多长、朝哪、球放哪」是可独立核对的算术。留成零依赖 ⇒ `test/pipeRoute.test.js`
+ *   能直接 require 编译产物逐字段断言，不必起浏览器。
+ *
+ * ⚠️ 拐角为什么必须补一颗球：直管是**开口圆柱**（CylinderGeometry openEnded，见 PipeStraight.ts），
+ *   两段斜管在拐角处只有轴线相交、端面是斜的 ⇒ 夹角外侧必然露一个楔形缺口，能直接看穿管子。
+ *   补法取最省事的一种：控制点上放一颗「直径同管」的球（PipeJoint），球面把缺口盖满。
+ *   球与管同径 ⇒ 共线时完全看不出来，有夹角时是光滑过渡，不是一串珠子。
+ *
+ * ⚠️ 上一版（`orthogonalRoute.ts`，2026-10-21 ～ 10-25）是按 axisOrder 逐轴补齐的正交走线 + 90° 弯头，
+ *   已整份删除。要找回请从 git 取，别在半路上重新发明一遍。
+ */
+/** 段长可忽略的判据（与上一版正交方案同量级） */
+export const PIPE_EPS = 1e-6;
+/**
+ * 算出整条管道的直管 + 补角球清单。
+ *
+ * ⚠️ 重合的控制点对**不产生直管**（长度 0 的圆柱缩放会让法线退化），但两端点仍参与球的判定 ——
+ *   只要该点还连着别的有效直管，球照放，接缝才不会因为一个废段而开口。
+ */
+export function planDirectLayout(points, opts = {}) {
+    const diameter = opts.diameter ?? 1;
+    const warnings = [];
+    const radius = diameter / 2;
+    if (points.length < 2) {
+        warnings.push("控制点少于 2 个，无法走线");
+        return { straights: [], joints: [], warnings };
+    }
+    if (!(diameter > 0)) {
+        warnings.push(`直径 ${diameter} 非法（必须为正数，单位米）`);
+        return { straights: [], joints: [], warnings };
+    }
+    const straights = [];
+    /** 第 i 段（控制点 i → i+1）是否真的产生了一根直管 */
+    const segOk = [];
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        const dx = b[0] - a[0];
+        const dy = b[1] - a[1];
+        const dz = b[2] - a[2];
+        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (len < PIPE_EPS) {
+            segOk.push(false);
+            warnings.push(`第 ${i + 1} 与第 ${i + 2} 个控制点重合，跳过这一段`);
+            continue;
+        }
+        segOk.push(true);
+        straights.push({
+            index: i,
+            center: [a[0] + dx / 2, a[1] + dy / 2, a[2] + dz / 2],
+            dir: [dx / len, dy / len, dz / len],
+            length: len,
+        });
+    }
+    const joints = [];
+    for (let i = 1; i < points.length - 1; i++) {
+        // 前后都没生出直管 ⇒ 这是个孤立点，补球只是凭空多一颗，没意义
+        if (!segOk[i - 1] && !segOk[i])
+            continue;
+        const p = points[i];
+        joints.push({ index: i, center: [p[0], p[1], p[2]], radius });
+    }
+    if (straights.length === 0 && warnings.length === 0) {
+        warnings.push("没有产生任何直管");
+    }
+    return { straights, joints, warnings };
+}
+export const PIPE_JSON_FORMAT = "three-base.pipe";
+export const PIPE_JSON_VERSION = 1;
+export function makePipeJson(points, diameter, color) {
+    const json = { format: PIPE_JSON_FORMAT, version: PIPE_JSON_VERSION, diameter, points };
+    if (color)
+        json.color = color;
+    return json;
+}
+/** 宽松校验：接受对象/字符串，字段缺失或类型错都返回 reason 而不抛异常（导入现场不许崩） */
+export function parsePipeJson(input) {
+    let raw = input;
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch (e) {
+            return { ok: false, reason: "不是合法 JSON 文本" };
+        }
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, reason: "顶层不是 JSON 对象" };
+    }
+    const obj = raw;
+    if (obj.format !== PIPE_JSON_FORMAT) {
+        return { ok: false, reason: `format 应为 "${PIPE_JSON_FORMAT}"，实际 ${JSON.stringify(obj.format)}` };
+    }
+    if (obj.version !== PIPE_JSON_VERSION) {
+        return { ok: false, reason: `暂不支持 version ${String(obj.version)}（当前只认 ${PIPE_JSON_VERSION}）` };
+    }
+    const points = obj.points;
+    if (!Array.isArray(points) || points.length < 2) {
+        return { ok: false, reason: "points 至少要有 2 个控制点" };
+    }
+    const vecs = [];
+    for (let i = 0; i < points.length; i++) {
+        const p = points[i];
+        const isTuple = Array.isArray(p) && p.length === 3 && p.every((n) => typeof n === "number" && Number.isFinite(n));
+        if (!isTuple) {
+            return { ok: false, reason: `第 ${i + 1} 个控制点不是 [x,y,z] 三个有限数字` };
+        }
+        vecs.push([p[0], p[1], p[2]]);
+    }
+    const diameter = typeof obj.diameter === "number" && Number.isFinite(obj.diameter) && obj.diameter > 0
+        ? obj.diameter
+        : NaN;
+    if (!(diameter > 0)) {
+        return { ok: false, reason: "diameter 缺失或不是正数（单位米）" };
+    }
+    const color = typeof obj.color === "string" ? obj.color : undefined;
+    return { ok: true, json: makePipeJson(vecs, diameter, color) };
+}

package/PipeMesh/directRoute.ts

@@ -0,0 +1,190 @@
+/**
+ * 直连管道走线（纯数字，零依赖）。
+ *
+ * 皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」：
+ * 相邻两个控制点之间就是一根直管（可以是斜的），不再按轴序拆正交段、不再有 90° 弯头。
+ * 每段只算三件事：长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *
+ * ⭐ 为什么仍单独一个零 import 模块：管道几何要写进 InstancedChild 的实例矩阵（见 PipeMesh.ts），
+ *   而「几段、每段多长、朝哪、球放哪」是可独立核对的算术。留成零依赖 ⇒ `test/pipeRoute.test.js`
+ *   能直接 require 编译产物逐字段断言，不必起浏览器。
+ *
+ * ⚠️ 拐角为什么必须补一颗球：直管是**开口圆柱**（CylinderGeometry openEnded，见 PipeStraight.ts），
+ *   两段斜管在拐角处只有轴线相交、端面是斜的 ⇒ 夹角外侧必然露一个楔形缺口，能直接看穿管子。
+ *   补法取最省事的一种：控制点上放一颗「直径同管」的球（PipeJoint），球面把缺口盖满。
+ *   球与管同径 ⇒ 共线时完全看不出来，有夹角时是光滑过渡，不是一串珠子。
+ *
+ * ⚠️ 上一版（`orthogonalRoute.ts`，2026-10-21 ～ 10-25）是按 axisOrder 逐轴补齐的正交走线 + 90° 弯头，
+ *   已整份删除。要找回请从 git 取，别在半路上重新发明一遍。
+ */
+
+/** 世界坐标点，单位米 */
+export type Vec3 = [number, number, number];
+
+/** 直管段：几何中心 + 轴向单位向量 + 段长 */
+export interface StraightPart {
+    /** 段序号（从 0 起，对应「控制点 i → 控制点 i+1」） */
+    index: number;
+    /** 直管几何体的中心（单位圆柱沿 +Y 生成，容器再旋转/缩放到此位姿） */
+    center: Vec3;
+    /** 走线方向，单位向量（任意朝向，不限六向） */
+    dir: Vec3;
+    /** 段长（米）= 两控制点欧氏距离 */
+    length: number;
+}
+
+/** 拐角补角球：球心压在控制点上，半径 = 直径/2 */
+export interface JointPart {
+    /** 对应控制点下标（1 … n-2；两端没有拐角，不补球） */
+    index: number;
+    center: Vec3;
+    radius: number;
+}
+
+export interface PipePlan {
+    straights: StraightPart[];
+    joints: JointPart[];
+    /** 退化输入说明（点重合、走线全零、直径非法…）；渲染不受影响，供面板提示 */
+    warnings: string[];
+}
+
+/** 段长可忽略的判据（与上一版正交方案同量级） */
+export const PIPE_EPS = 1e-6;
+
+/**
+ * 算出整条管道的直管 + 补角球清单。
+ *
+ * ⚠️ 重合的控制点对**不产生直管**（长度 0 的圆柱缩放会让法线退化），但两端点仍参与球的判定 ——
+ *   只要该点还连着别的有效直管，球照放，接缝才不会因为一个废段而开口。
+ */
+export function planDirectLayout(points: Vec3[], opts: { diameter?: number } = {}): PipePlan {
+    const diameter = opts.diameter ?? 1;
+    const warnings: string[] = [];
+    const radius = diameter / 2;
+
+    if (points.length < 2) {
+        warnings.push("控制点少于 2 个，无法走线");
+        return { straights: [], joints: [], warnings };
+    }
+    if (!(diameter > 0)) {
+        warnings.push(`直径 ${diameter} 非法（必须为正数，单位米）`);
+        return { straights: [], joints: [], warnings };
+    }
+
+    const straights: StraightPart[] = [];
+    /** 第 i 段（控制点 i → i+1）是否真的产生了一根直管 */
+    const segOk: boolean[] = [];
+
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        const dx = b[0] - a[0];
+        const dy = b[1] - a[1];
+        const dz = b[2] - a[2];
+        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (len < PIPE_EPS) {
+            segOk.push(false);
+            warnings.push(`第 ${i + 1} 与第 ${i + 2} 个控制点重合，跳过这一段`);
+            continue;
+        }
+        segOk.push(true);
+        straights.push({
+            index: i,
+            center: [a[0] + dx / 2, a[1] + dy / 2, a[2] + dz / 2],
+            dir: [dx / len, dy / len, dz / len],
+            length: len,
+        });
+    }
+
+    const joints: JointPart[] = [];
+    for (let i = 1; i < points.length - 1; i++) {
+        // 前后都没生出直管 ⇒ 这是个孤立点，补球只是凭空多一颗，没意义
+        if (!segOk[i - 1] && !segOk[i]) continue;
+        const p = points[i];
+        joints.push({ index: i, center: [p[0], p[1], p[2]], radius });
+    }
+
+    if (straights.length === 0 && warnings.length === 0) {
+        warnings.push("没有产生任何直管");
+    }
+    return { straights, joints, warnings };
+}
+
+/**
+ * JSON 是「管道对象」与「编辑页项目」共用的唯一数据形状。
+ * 单位米；points 是控制点（不是段），所以重新走线/改直径只改这几个字段即可。
+ *
+ * ⚠️ version 仍是 1：形状（points / diameter / color）与上一版一致，只是上一版的 `axisOrder`
+ *   从「必填参数」降级成「忽略的多余键」⇒ 皇上库里的旧项目照样打得开，只是形状按直连重算。
+ */
+export interface PipeJson {
+    format: "three-base.pipe";
+    version: 1;
+    diameter: number;
+    color?: string;
+    points: Vec3[];
+}
+
+export const PIPE_JSON_FORMAT = "three-base.pipe";
+export const PIPE_JSON_VERSION = 1;
+
+export function makePipeJson(points: Vec3[], diameter: number, color?: string): PipeJson {
+    const json: PipeJson = { format: PIPE_JSON_FORMAT, version: PIPE_JSON_VERSION, diameter, points };
+    if (color) json.color = color;
+    return json;
+}
+
+/**
+ * 解析结果：`ok=false` 时 `reason` 是人话，可直接弹给编辑页显示；`ok=true` 时 `json` 已归一化。
+ * ⚠️ 刻意不用 `{ok:true;json} | {ok:false;reason}` 可辨识联合：库编译走的是 `strict:false`
+ *   （three-base/tsconfig.json），实测那种写法在 `if (!r.ok)` 之后取 `r.reason` 会报 TS2339。
+ */
+export interface PipeJsonResult {
+    ok: boolean;
+    json?: PipeJson;
+    reason?: string;
+}
+
+/** 宽松校验：接受对象/字符串，字段缺失或类型错都返回 reason 而不抛异常（导入现场不许崩） */
+export function parsePipeJson(input: unknown): PipeJsonResult {
+    let raw: unknown = input;
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        } catch (e) {
+            return { ok: false, reason: "不是合法 JSON 文本" };
+        }
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, reason: "顶层不是 JSON 对象" };
+    }
+    const obj = raw as Record<string, unknown>;
+    if (obj.format !== PIPE_JSON_FORMAT) {
+        return { ok: false, reason: `format 应为 "${PIPE_JSON_FORMAT}"，实际 ${JSON.stringify(obj.format)}` };
+    }
+    if (obj.version !== PIPE_JSON_VERSION) {
+        return { ok: false, reason: `暂不支持 version ${String(obj.version)}（当前只认 ${PIPE_JSON_VERSION}）` };
+    }
+    const points = obj.points;
+    if (!Array.isArray(points) || points.length < 2) {
+        return { ok: false, reason: "points 至少要有 2 个控制点" };
+    }
+    const vecs: Vec3[] = [];
+    for (let i = 0; i < points.length; i++) {
+        const p = points[i];
+        const isTuple =
+            Array.isArray(p) && p.length === 3 && p.every((n) => typeof n === "number" && Number.isFinite(n));
+        if (!isTuple) {
+            return { ok: false, reason: `第 ${i + 1} 个控制点不是 [x,y,z] 三个有限数字` };
+        }
+        vecs.push([p[0] as number, p[1] as number, p[2] as number]);
+    }
+    const diameter = typeof obj.diameter === "number" && Number.isFinite(obj.diameter) && obj.diameter > 0
+        ? obj.diameter
+        : NaN;
+    if (!(diameter > 0)) {
+        return { ok: false, reason: "diameter 缺失或不是正数（单位米）" };
+    }
+    const color = typeof obj.color === "string" ? obj.color : undefined;
+    return { ok: true, json: makePipeJson(vecs, diameter, color) };
+}

package/PipeMesh/index.d.ts

@@ -1 +1,7 @@
 export { default } from "./PipeMesh";
+export { default as PipeMesh } from "./PipeMesh";
+export { default as PipeStraight } from "./PipeStraight";
+export { default as PipeJoint } from "./PipeJoint";
+export { createPipeMaterial, pipeMaterial, PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+export * from "./directRoute";
+export * from "./axisSnap";

package/PipeMesh/index.js

@@ -1 +1,7 @@
 export { default } from "./PipeMesh";
+export { default as PipeMesh } from "./PipeMesh";
+export { default as PipeStraight } from "./PipeStraight";
+export { default as PipeJoint } from "./PipeJoint";
+export { createPipeMaterial, pipeMaterial, PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+export * from "./directRoute";
+export * from "./axisSnap";

package/PipeMesh/index.ts

@@ -1 +1,7 @@
-export { default } from "./PipeMesh";
+export { default } from "./PipeMesh";
+export { default as PipeMesh } from "./PipeMesh";
+export { default as PipeStraight } from "./PipeStraight";
+export { default as PipeJoint } from "./PipeJoint";
+export { createPipeMaterial, pipeMaterial, PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+export * from "./directRoute";
+export * from "./axisSnap";

package/PipeMesh/pipeMaterial.d.ts

@@ -0,0 +1,16 @@
+import { MeshStandardMaterial } from "three";
+/**
+ * 直管与弯头共用一份材质。
+ *
+ * ⭐ 为什么底色是白：实例化那条路，逐实例颜色走 `InstancedMesh.instanceColor`（InstancedBatch 预填 1.0，
+ *   setColor 覆盖），three 里最终 diffuse = material.color × instanceColor。材质底色若非白，setColor 的值
+ *   就会被整体压暗，面板上「这根管子涂什么色」就对不上画面了。
+ * ⭐ 为什么两边共享同一份：材质只有一份 ⇒ 粗糙度/金属度改一次，两个 batch（直管、弯头）同时跟上；
+ *   合批是按 geometry+material 分桶的，共享材质不会把它们并成一个 batch（几何不同），draw call 仍是 2。
+ * ⚠️ DoubleSide 是必需的：直管是开口圆柱（无端面），从管口往里看要能看到内壁，否则管子里是黑的空洞。
+ */
+export declare function createPipeMaterial(): MeshStandardMaterial;
+/** 全库共享的那一份材质实例（InstancedChild 的 static material 必须是同一个对象才会同桶/同改） */
+export declare const pipeMaterial: MeshStandardMaterial;
+/** 管道默认颜色，取自参考稿 */
+export declare const PIPE_DEFAULT_COLOR = 5227511;

package/PipeMesh/pipeMaterial.js

@@ -0,0 +1,23 @@
+import { DoubleSide, MeshStandardMaterial } from "three";
+/**
+ * 直管与弯头共用一份材质。
+ *
+ * ⭐ 为什么底色是白：实例化那条路，逐实例颜色走 `InstancedMesh.instanceColor`（InstancedBatch 预填 1.0，
+ *   setColor 覆盖），three 里最终 diffuse = material.color × instanceColor。材质底色若非白，setColor 的值
+ *   就会被整体压暗，面板上「这根管子涂什么色」就对不上画面了。
+ * ⭐ 为什么两边共享同一份：材质只有一份 ⇒ 粗糙度/金属度改一次，两个 batch（直管、弯头）同时跟上；
+ *   合批是按 geometry+material 分桶的，共享材质不会把它们并成一个 batch（几何不同），draw call 仍是 2。
+ * ⚠️ DoubleSide 是必需的：直管是开口圆柱（无端面），从管口往里看要能看到内壁，否则管子里是黑的空洞。
+ */
+export function createPipeMaterial() {
+    return new MeshStandardMaterial({
+        color: 0xffffff,
+        roughness: 0.35,
+        metalness: 0.5,
+        side: DoubleSide,
+    });
+}
+/** 全库共享的那一份材质实例（InstancedChild 的 static material 必须是同一个对象才会同桶/同改） */
+export const pipeMaterial = createPipeMaterial();
+/** 管道默认颜色，取自参考稿 */
+export const PIPE_DEFAULT_COLOR = 0x4fc3f7;