three-base 2.0.172 → 2.0.180

package/MktMesh/boxLine2.ts

@@ -0,0 +1,222 @@
+/*
+ * @Description: 选中设备的包围盒高亮框 —— 皇上旨 2026-10-22「选中设备的时候，设备还需要有一个高亮的框，
+ *   你参考旁边 archives2026 项目」⇒ 整搬那边的 `srcWeb/pages/LargeScreen/component3d/BoxLine2.ts`
+ *   （12 条棱 fat-line：朝向相机那几棱**绿色实线**，被盒子自己挡住的那几棱**红色虚线**）。
+ *
+ * 为什么不直接用现成的 `EdgesGeometry + LineBasicMaterial`（也就是本仓旧版那圈细线）：
+ * - 旧那圈是 `GL_LINES`，`linewidth` 在 WebGL/ANGLE 下是**死旋钮** ⇒ 永远 1 像素，深色模型上几乎看不见
+ *   （仓内同族早已踩过：墙线/立方体边框 10-05、10-07 两旨都换成了 `LineSegments2 + LineMaterial`）。
+ * - fat-line 的粗细是**屏幕像素**（`worldUnits:false`）⇒ 远近一样粗，这正是「高亮框」要的效果。
+ *
+ * 遮挡那一刀怎么来的（照搬，⛔ 不是臣自己发明的判据）：八顶点各自从相机朝该角发一条射线，打这份**内嵌代理盒**
+ * —— 打得着 = 这条视线被盒子自己截住了 = 那个角在背面 ⇒ 凡是含背角的棱改用红色虚线材质。
+ * 代理盒本身 `alphaTest: 1.1` ⇒ 一个像素都不出、也不写深度，只当射线靶子用。
+ *
+ * ⚠️ 相对参考实现改了五处，每处都只为了贴合本仓：
+ *   ① 代理盒内缩量钳到「不小于原尺寸的 50%」（`_insetSize`）：那边设备都是米级大物件，`v - 0.1` 恒正；
+ *      本仓的模型槽可能是薄一片（画作/展牌）或 0.3 m 的占位方块，`v - 0.1` 会出负数拿到一份翻面的几何。
+ *   ② 整棵子树标 `userData.pickIgnored = true`：本仓编辑器拾取模型走 `intersectObjects(this.models, true)`
+ *      （递归打进槽本体），一个实心代理盒挂在槽下面会把「框内的空地」也点成选中这只槽 —— 旧版那圈细线是靠
+ *      `raycast = noop` 躲开的，这里换成标记，由 `_pickModel` 跳过（⛔ 类内部的遮挡射线不受影响，它打的是
+ *      自己那份 `boxMesh`，与本仓的拾取射线是两把尺）。
+ *   ③ 加 `dispose()`：本仓模型槽删除/换模型要释放那 12 份线段几何与两份 LineMaterial，否则删一只漏一份显存。
+ *   ④ 没搬那边那四颗 `setDepthTest` / `setLinewidth` / 两个 getter —— 在 archives2026 全仓 **0 处调用**
+ *      （而且那两个私有字段的初值 `false`/`1` 与两份材质真正用的 `depthTest:true`/`linewidth:2` 本来就不一致，
+ *      只有从没被调过才没露馅）。真正生效的就是下面材质构造里那两个数，⛔ 不留没人拧的旋钮。
+ *   ⑤ 12 条棱各自 `raycast = noop`：那边从不把线框交给射线，本仓的拾取射线会**递归**进槽子树打到它们，
+ *      而 `LineSegments2.raycast` 在 `worldUnits:false` 那一路要先读 `raycaster.camera`（编辑器那把没设）
+ *      ⇒ 先 `console.error` 再撞 `camera.projectionMatrix` 抛异常。详见 `createLine` 里那句注释。
+ */
+import {
+    BoxGeometry,
+    BufferGeometry,
+    Camera,
+    DoubleSide,
+    Group,
+    Material,
+    Mesh,
+    MeshBasicMaterial,
+    NormalBufferAttributes,
+    Raycaster,
+    Scene,
+    Vector2,
+    Vector3,
+    WebGLRenderer,
+} from "three";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
+import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/examples/jsm/lines/LineSegmentsGeometry.js";
+
+/** 朝向相机那几棱：绿色实线 */
+const FRONT_COLOR = 0x00ff00;
+/** 被盒子挡住的那几棱：红色虚线（dash/gap 各 5，与参考实现同档） */
+const BACK_COLOR = 0xff0000;
+/** 棱线粗细（屏幕像素，`worldUnits:false` ⇒ 远近一样粗） */
+const LINE_WIDTH_PX = 2;
+
+export default class BoxLine2 extends Mesh {
+    constructor() {
+        super();
+        // 拾取/射线都不该把高亮框算进来（见文件头 ⚠️②）；内部遮挡判据另打 `this.boxMesh`，不走这条
+        this.traverse((o) => { o.userData.pickIgnored = true; });
+    }
+
+    /** 控制台识别用（本仓约定：对象要能被认出来是谁的哪一份） */
+    type = "boxLine2";
+
+    frustumCulled = false;
+    size = new Vector3(1, 1, 1);
+
+    T1 = new Vector3(); T2 = new Vector3(); T3 = new Vector3(); T4 = new Vector3();
+    B1 = new Vector3(); B2 = new Vector3(); B3 = new Vector3(); B4 = new Vector3();
+
+    frontLineMaterial = new LineMaterial({
+        color: FRONT_COLOR,
+        worldUnits: false,
+        linewidth: LINE_WIDTH_PX,
+        depthTest: true,
+        resolution: new Vector2(1, 1),
+    });
+
+    backLineMaterial = new LineMaterial({
+        color: BACK_COLOR,
+        worldUnits: false,
+        dashed: true,
+        dashSize: 5,
+        gapSize: 5,
+        linewidth: LINE_WIDTH_PX,
+        depthTest: true,
+        resolution: new Vector2(1, 1),
+    });
+
+    createLine(name: string): LineSegments2 {
+        const segmentsGeometry = new LineSegmentsGeometry();
+        segmentsGeometry.setPositions([-0.5, 0, 0, 0.5, 0, 0]);
+        const line = new LineSegments2(segmentsGeometry, this.frontLineMaterial);
+        line.name = name;
+        line.renderOrder = 100;
+        // ⚠️ 本仓必改（参考那边没有这一行）：`LineSegments2.raycast` 在 `worldUnits:false` 那一路要读
+        //   `raycaster.camera`（屏幕空间投影），而编辑器拾取模型用的是 `intersectObjects(models, true)` 递归打到这里、
+        //   那把射线没设 camera ⇒ three 自己 `console.error` 之后紧接着碰 `camera.projectionMatrix` 直接抛 ⇒ 选中点不动。
+        //   线段本身不是「可点的东西」，置空最省事；那颗代理盒的 `raycast` 必须留着（遮挡判据打它）。
+        line.raycast = (): void => { };
+        line.computeLineDistances();
+        this.add(line);
+        return line;
+    }
+
+    T1_line = this.createLine("T1,T2");
+    T2_line = this.createLine("T2,T3");
+    T3_line = this.createLine("T3,T4");
+    T4_line = this.createLine("T4,T1");
+    M1_line = this.createLine("T1,B1");
+    M2_line = this.createLine("T2,B2");
+    M3_line = this.createLine("T3,B3");
+    M4_line = this.createLine("T4,B4");
+    B1_line = this.createLine("B1,B2");
+    B2_line = this.createLine("B2,B3");
+    B3_line = this.createLine("B3,B4");
+    B4_line = this.createLine("B4,B1");
+
+    /** 射线靶子（比框小一圈）：`alphaTest: 1.1` ⇒ 一个像素都不画，只给下面的遮挡判据打 */
+    boxMesh = (() => {
+        const boxGeometry = new BoxGeometry(1, 1, 1);
+        const boxMesh = new Mesh(boxGeometry, new MeshBasicMaterial({
+            color: "#ff0000", side: DoubleSide, wireframe: true, alphaTest: 1.1,
+        }));
+        boxMesh.name = "遮挡判据代理盒";
+        this.add(boxMesh);
+        return boxMesh;
+    })();
+
+    /** 代理盒单边内缩量：米级盒子照参考实现减 0.1；薄一片/占位方块那种小尺寸钳到自身的一半，⛔ 不出负数 */
+    private _insetSize(v: number): number {
+        return Math.max(v - 0.1, v * 0.5);
+    }
+
+    setSize(v: Vector3): void {
+        this.size.set(v.x, v.y, v.z);
+
+        this.boxMesh.geometry.dispose();
+        this.boxMesh.geometry = new BoxGeometry(
+            this._insetSize(v.x),
+            this._insetSize(v.y),
+            this._insetSize(v.z),
+        );
+
+        this.T1.set(v.x / -2, v.y / 2, v.z / -2);
+        this.T2.set(v.x / -2, v.y / 2, v.z / 2);
+        this.T3.set(v.x / 2, v.y / 2, v.z / 2);
+        this.T4.set(v.x / 2, v.y / 2, v.z / -2);
+        this.B1.set(v.x / -2, v.y / -2, v.z / -2);
+        this.B2.set(v.x / -2, v.y / -2, v.z / 2);
+        this.B3.set(v.x / 2, v.y / -2, v.z / 2);
+        this.B4.set(v.x / 2, v.y / -2, v.z / -2);
+
+        const lines: Array<{ line: LineSegments2; p1: Vector3; p2: Vector3 }> = [
+            { line: this.T1_line, p1: this.T1, p2: this.T2 },
+            { line: this.T2_line, p1: this.T2, p2: this.T3 },
+            { line: this.T3_line, p1: this.T3, p2: this.T4 },
+            { line: this.T4_line, p1: this.T4, p2: this.T1 },
+            { line: this.M1_line, p1: this.T1, p2: this.B1 },
+            { line: this.M2_line, p1: this.T2, p2: this.B2 },
+            { line: this.M3_line, p1: this.T3, p2: this.B3 },
+            { line: this.M4_line, p1: this.T4, p2: this.B4 },
+            { line: this.B1_line, p1: this.B1, p2: this.B2 },
+            { line: this.B2_line, p1: this.B2, p2: this.B3 },
+            { line: this.B3_line, p1: this.B3, p2: this.B4 },
+            { line: this.B4_line, p1: this.B4, p2: this.B1 },
+        ];
+
+        lines.forEach(({ line, p1, p2 }) => {
+            line.geometry.setPositions([p1.x, p1.y, p1.z, p2.x, p2.y, p2.z]);
+            line.computeLineDistances();
+        });
+    }
+
+    raycaster = new Raycaster();
+
+    onBeforeRender = (
+        renderer: WebGLRenderer, _scene: Scene, camera: Camera,
+        _geometry: BufferGeometry<NormalBufferAttributes>, _material: Material, _group: Group,
+    ): void => {
+        renderer.getSize(this.frontLineMaterial.resolution);
+        renderer.getSize(this.backLineMaterial.resolution);
+
+        const farVectorName: string[] = [];
+        const farVectorNames = ["T1", "T2", "T3", "T4", "B1", "B2", "B3", "B4"];
+        this.raycaster.ray.origin.copy(camera.position);
+
+        [this.T1, this.T2, this.T3, this.T4, this.B1, this.B2, this.B3, this.B4].forEach((v, i) => {
+            const direction = v.clone().applyMatrix4(this.matrixWorld).sub(camera.position);
+            this.raycaster.ray.direction.copy(direction).normalize();
+            this.raycaster.far = direction.length();
+            const intersect = this.raycaster.intersectObject(this.boxMesh);
+            if (intersect.length > 0) {
+                farVectorName.push(farVectorNames[i]);
+            }
+        });
+
+        [
+            this.T1_line, this.T2_line, this.T3_line, this.T4_line,
+            this.M1_line, this.M2_line, this.M3_line, this.M4_line,
+            this.B1_line, this.B2_line, this.B3_line, this.B4_line,
+        ].forEach((line) => {
+            const has = farVectorName.some((name) => line.name.includes(name));
+            line.material = has ? this.backLineMaterial : this.frontLineMaterial;
+        });
+    };
+
+    /** 释放：12 份线段几何 + 代理盒几何 + 两份 LineMaterial + 代理盒材质（模型槽删除/换框时调用） */
+    dispose(): void {
+        for (const line of [
+            this.T1_line, this.T2_line, this.T3_line, this.T4_line,
+            this.M1_line, this.M2_line, this.M3_line, this.M4_line,
+            this.B1_line, this.B2_line, this.B3_line, this.B4_line,
+        ]) line.geometry.dispose();
+        this.boxMesh.geometry.dispose();
+        (this.boxMesh.material as MeshBasicMaterial).dispose();
+        this.frontLineMaterial.dispose();
+        this.backLineMaterial.dispose();
+    }
+}

package/MktMesh/imagePlane.d.ts

@@ -0,0 +1,60 @@
+import { Mesh, MeshBasicMaterial, PlaneGeometry, Texture, Vector4 } from "three";
+/**
+ * 皇上旨 2026-10-23「添加的平面 有点隐隐的 边框, 你在代码里面写一下, 把边框的那一点点 discrad 掉」。
+ * 整张图**外圈**这一条 UV 余量在片元里一刀 `discard` 掉 —— 边框那一圈来自裁片留下的描边/柔边像素
+ * （`alphaTest` 砍不到它：那圈像素的 alpha 高于阈值 —— 0.2 / 0.9 / 0.3 这几档都留得住它，只是颜色比内容浅，于是画成实心的一圈浅边）。
+ * 只切外圈：内部那 2×2 拼缝归每片自己的 inset 采样窗口管，两把刀互不重叠。
+ * ⚠️ 这一档是**比例**不是毫米：默认平面 2×1.5 m ⇒ 横着每边切 8 mm、竖着每边切 6 mm。尺只许写在这一处。
+ */
+export declare const IMAGE_PLANE_EDGE_CLIP_UV = 0.004;
+/** 图片平面的持久化数据（进 exportData / importData） */
+export interface ImagePlaneData {
+    name?: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    width: number;
+    height: number;
+    /** 原图地址（上传后返回的 origin URL，缩略图展示用） */
+    url: string;
+    /** 瓦片地址（行优先、图像左上起；张数 = 库里 `IMAGE_TILE_GRID` 的 cols×rows，10-21 旨 = 2×2=4） */
+    tiles: string[];
+    /** 原图自然像素宽（瓦片纹理实际像素，算 inset 采样窗口需要） */
+    naturalW?: number;
+    /** 原图自然像素高 */
+    naturalH?: number;
+}
+export declare class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
+    private _originalColor;
+    private _uTiles;
+    private _uInset;
+    private _uValid;
+    private _data;
+    constructor(name?: string);
+    get imageWidth(): number;
+    get imageHeight(): number;
+    setPlaneSize(w: number, h: number): void;
+    setPlaneData(d: Pick<ImagePlaneData, "url" | "tiles" | "naturalW" | "naturalH">): void;
+    get tiles(): string[];
+    get url(): string;
+    get naturalW(): number | undefined;
+    get naturalH(): number | undefined;
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    setTileTextures(texs: (Texture | null)[], insets: Vector4[]): void;
+    highlight(): void;
+    restoreColor(): void;
+    toData(): ImagePlaneData;
+    applyData(d: ImagePlaneData): void;
+    dispose(): void;
+}
+export declare const IMAGE_PLANE_DEFAULTS: {
+    width: number;
+    height: number;
+};

package/MktMesh/imagePlane.js

@@ -0,0 +1,158 @@
+/*
+ * @Description: 图片平面元素 —— 皇上旨 2026-10-20「先添加一个平面, 再给这个平面上传图片,
+ *   上传的这个图切成 4*4=16 片, 加载的时候也是一帧载入一片」→ 2026-10-21 改口「切成 2*2=4 份，
+ *   不用切成 16 份了」。片数只在库里那一个 `IMAGE_TILE_GRID` 常数上，本文件⛔ 不写数字。
+ *
+ * 设计：
+ * - 独立 Mesh（非 InstancedChild）：每张图片各有自己的 4 张瓦片纹理 ⇒ 材质实例不可共用，不合批。
+ * - 材质 MeshBasicMaterial + FrontSide（皇上旨 2026-10-22「添加的平面图片元素只要单面可见就行了，双面不需要」）：
+ *   平面本身不承受光照（贴图内容自带明暗）。单面 ⇒ 背面既不画也打不中（three 的射线拾取按材质 side 剔背面，
+ *   `node_modules/three/src/objects/Mesh.js:343`），与渲染共用同一条式子 ⇒ 站在这一面的反面既看不见也选不中。
+ * - 几何 PlaneGeometry(width, height)，原点在平面中心；position.y 由调用者设定（通常 height/2 让底部落地）。
+ * - ⭐ 2026-10-22 晚旨：纹理**不走拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，片元按 UV 象限选片 +
+ *   用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。材质用 onBeforeCompile 打补丁，
+ *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰、逐张就绪逐张显影。
+ * - UV 标准 [0,1]²（PlaneGeometry 自带），4 张瓦片按 2×2 象限铺满 ⇒ 不需要投影 shader，也不需要离屏 RT。
+ */
+import { Color, DataTexture, FrontSide, Mesh, MeshBasicMaterial, PlaneGeometry, RGBAFormat, Vector4, } from "three";
+/*
+ * ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
+ * 片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
+ * 占位 1×1 灰纹理：sampler 必须绑定有效纹理（未就绪片绑定它、但片元 `uValid` 为 0 时不采样它）。
+ */
+const PLACEHOLDER_TEX = (() => {
+    const t = new DataTexture(new Uint8Array([204, 204, 204, 255]), 1, 1, RGBAFormat);
+    t.needsUpdate = true;
+    return t;
+})();
+const ZERO_INSET = new Vector4(0, 0, 1, 1);
+/**
+ * 皇上旨 2026-10-23「添加的平面 有点隐隐的 边框, 你在代码里面写一下, 把边框的那一点点 discrad 掉」。
+ * 整张图**外圈**这一条 UV 余量在片元里一刀 `discard` 掉 —— 边框那一圈来自裁片留下的描边/柔边像素
+ * （`alphaTest` 砍不到它：那圈像素的 alpha 高于阈值 —— 0.2 / 0.9 / 0.3 这几档都留得住它，只是颜色比内容浅，于是画成实心的一圈浅边）。
+ * 只切外圈：内部那 2×2 拼缝归每片自己的 inset 采样窗口管，两把刀互不重叠。
+ * ⚠️ 这一档是**比例**不是毫米：默认平面 2×1.5 m ⇒ 横着每边切 8 mm、竖着每边切 6 mm。尺只许写在这一处。
+ */
+export const IMAGE_PLANE_EDGE_CLIP_UV = 0.004;
+const EDGE_MAX_UV = 1 - IMAGE_PLANE_EDGE_CLIP_UV;
+/** 片元打补丁：4 张瓦片按 UV 象限选片，缺图那片显示灰（与旧缺失灰同一观感）。索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
+const IMG_PLANE_MAP_FRAG = `
+    if ( vUv.x < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.x > ${EDGE_MAX_UV} || vUv.y < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.y > ${EDGE_MAX_UV} ) discard;
+    vec4 imgTexel = vec4(0.8, 0.8, 0.8, 1.0); // 缺图灰
+    vec2 cell = floor(vUv * 2.0);
+    vec2 local = fract(vUv * 2.0);
+    if (cell.y >= 0.5 && cell.x < 0.5) {
+        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); }
+    } else if (cell.y >= 0.5 && cell.x >= 0.5) {
+        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); }
+    } else if (cell.y < 0.5 && cell.x < 0.5) {
+        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); }
+    } else {
+        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); }
+    }
+    diffuseColor *= imgTexel;
+`;
+const DEFAULT_WIDTH = 2;
+const DEFAULT_HEIGHT = 1.5;
+const HIGHLIGHT_COLOR = "#ffd24a";
+export class ImagePlane extends Mesh {
+    _originalColor = "#ffffff";
+    _uTiles;
+    _uInset;
+    _uValid;
+    _data = {
+        url: "",
+        tiles: [],
+    };
+    constructor(name) {
+        const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
+        const mat = new MeshBasicMaterial({
+            color: new Color("#ffffff"),
+            side: FrontSide,
+            // 皇上旨 2026-10-21「平面的材质需要设置 alphaTest = 0.2」⇒ 同日 10-23 两次改口（先 0.9、后 **0.3**）：
+            // alpha 不足阈值的像素丢弃，其余实心。0.9 那一档会把图上半透的内容也切掉，现停在 0.3。
+            // ⛔ 这个构造里不许再写「走半透明通道」与「不透明度数值」那两行：皇上 10-22 点名「没有说过要设置透明度」，
+            //   那是臣 10-21 建这个类时擅自加的（没问过），当日整条删除。平面恒走不透明通道，
+            //   要「透」只能靠 alphaTest 这一刀切掉。
+            alphaTest: 0.3,
+        });
+        // ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
+        //   片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
+        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰。
+        mat.defines = { USE_UV: "" };
+        const uTiles = { value: [PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX] };
+        const uInset = { value: [ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone()] };
+        const uValid = { value: [0, 0, 0, 0] };
+        mat.onBeforeCompile = (shader) => {
+            shader.uniforms.uTiles = uTiles;
+            shader.uniforms.uInset = uInset;
+            shader.uniforms.uValid = uValid;
+            shader.fragmentShader = shader.fragmentShader
+                .replace("#include <common>", `#include <common>
+                    uniform sampler2D uTiles[4];
+                    uniform vec4 uInset[4];
+                    uniform float uValid[4];`)
+                .replace("#include <map_fragment>", IMG_PLANE_MAP_FRAG);
+        };
+        super(geo, mat);
+        this._uTiles = uTiles;
+        this._uInset = uInset;
+        this._uValid = uValid;
+        this.name = name || "图片平面";
+    }
+    get imageWidth() { return this.geometry.parameters.width; }
+    get imageHeight() { return this.geometry.parameters.height; }
+    setPlaneSize(w, h) {
+        this.geometry.dispose();
+        this.geometry = new PlaneGeometry(w, h);
+    }
+    setPlaneData(d) {
+        this._data = { url: d.url, tiles: d.tiles, naturalW: d.naturalW, naturalH: d.naturalH };
+    }
+    get tiles() { return this._data.tiles; }
+    get url() { return this._data.url; }
+    get naturalW() { return this._data.naturalW; }
+    get naturalH() { return this._data.naturalH; }
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    setTileTextures(texs, insets) {
+        for (let i = 0; i < 4; i++) {
+            const t = texs[i] || null;
+            this._uTiles.value[i] = t || PLACEHOLDER_TEX;
+            if (insets[i])
+                this._uInset.value[i].copy(insets[i]);
+            this._uValid.value[i] = t ? 1 : 0;
+        }
+    }
+    highlight() {
+        this.material.color.set(HIGHLIGHT_COLOR);
+    }
+    restoreColor() {
+        this.material.color.set(this._originalColor);
+    }
+    toData() {
+        return {
+            name: this.name || undefined,
+            position: { x: this.position.x, y: this.position.y, z: this.position.z },
+            rotation: { x: this.rotation.x, y: this.rotation.y, z: this.rotation.z },
+            width: this.imageWidth,
+            height: this.imageHeight,
+            url: this._data.url,
+            tiles: this._data.tiles,
+            naturalW: this._data.naturalW,
+            naturalH: this._data.naturalH,
+        };
+    }
+    applyData(d) {
+        if (d.name)
+            this.name = d.name;
+        this.position.set(d.position.x, d.position.y, d.position.z);
+        this.rotation.set(d.rotation.x, d.rotation.y, d.rotation.z);
+        this.setPlaneSize(d.width, d.height);
+        this._data = { url: d.url, tiles: d.tiles || [], naturalW: d.naturalW, naturalH: d.naturalH };
+    }
+    dispose() {
+        this.geometry.dispose();
+        this.material.dispose();
+    }
+}
+export const IMAGE_PLANE_DEFAULTS = { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT };

package/MktMesh/imagePlane.ts

@@ -0,0 +1,203 @@
+/*
+ * @Description: 图片平面元素 —— 皇上旨 2026-10-20「先添加一个平面, 再给这个平面上传图片,
+ *   上传的这个图切成 4*4=16 片, 加载的时候也是一帧载入一片」→ 2026-10-21 改口「切成 2*2=4 份，
+ *   不用切成 16 份了」。片数只在库里那一个 `IMAGE_TILE_GRID` 常数上，本文件⛔ 不写数字。
+ *
+ * 设计：
+ * - 独立 Mesh（非 InstancedChild）：每张图片各有自己的 4 张瓦片纹理 ⇒ 材质实例不可共用，不合批。
+ * - 材质 MeshBasicMaterial + FrontSide（皇上旨 2026-10-22「添加的平面图片元素只要单面可见就行了，双面不需要」）：
+ *   平面本身不承受光照（贴图内容自带明暗）。单面 ⇒ 背面既不画也打不中（three 的射线拾取按材质 side 剔背面，
+ *   `node_modules/three/src/objects/Mesh.js:343`），与渲染共用同一条式子 ⇒ 站在这一面的反面既看不见也选不中。
+ * - 几何 PlaneGeometry(width, height)，原点在平面中心；position.y 由调用者设定（通常 height/2 让底部落地）。
+ * - ⭐ 2026-10-22 晚旨：纹理**不走拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，片元按 UV 象限选片 +
+ *   用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。材质用 onBeforeCompile 打补丁，
+ *   注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰、逐张就绪逐张显影。
+ * - UV 标准 [0,1]²（PlaneGeometry 自带），4 张瓦片按 2×2 象限铺满 ⇒ 不需要投影 shader，也不需要离屏 RT。
+ */
+import {
+    Color,
+    DataTexture,
+    FrontSide,
+    Mesh,
+    MeshBasicMaterial,
+    PlaneGeometry,
+    RGBAFormat,
+    Texture,
+    Vector4,
+} from "three";
+
+/*
+ * ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
+ * 片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
+ * 占位 1×1 灰纹理：sampler 必须绑定有效纹理（未就绪片绑定它、但片元 `uValid` 为 0 时不采样它）。
+ */
+const PLACEHOLDER_TEX: Texture = (() => {
+    const t = new DataTexture(new Uint8Array([204, 204, 204, 255]), 1, 1, RGBAFormat);
+    t.needsUpdate = true;
+    return t;
+})();
+const ZERO_INSET = new Vector4(0, 0, 1, 1);
+
+/**
+ * 皇上旨 2026-10-23「添加的平面 有点隐隐的 边框, 你在代码里面写一下, 把边框的那一点点 discrad 掉」。
+ * 整张图**外圈**这一条 UV 余量在片元里一刀 `discard` 掉 —— 边框那一圈来自裁片留下的描边/柔边像素
+ * （`alphaTest` 砍不到它：那圈像素的 alpha 高于阈值 —— 0.2 / 0.9 / 0.3 这几档都留得住它，只是颜色比内容浅，于是画成实心的一圈浅边）。
+ * 只切外圈：内部那 2×2 拼缝归每片自己的 inset 采样窗口管，两把刀互不重叠。
+ * ⚠️ 这一档是**比例**不是毫米：默认平面 2×1.5 m ⇒ 横着每边切 8 mm、竖着每边切 6 mm。尺只许写在这一处。
+ */
+export const IMAGE_PLANE_EDGE_CLIP_UV = 0.004;
+const EDGE_MAX_UV = 1 - IMAGE_PLANE_EDGE_CLIP_UV;
+
+/** 片元打补丁：4 张瓦片按 UV 象限选片，缺图那片显示灰（与旧缺失灰同一观感）。索引用字面量 0..3 ⇒ GLSL ES 1.00 合法。 */
+const IMG_PLANE_MAP_FRAG = `
+    if ( vUv.x < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.x > ${EDGE_MAX_UV} || vUv.y < ${IMAGE_PLANE_EDGE_CLIP_UV} || vUv.y > ${EDGE_MAX_UV} ) discard;
+    vec4 imgTexel = vec4(0.8, 0.8, 0.8, 1.0); // 缺图灰
+    vec2 cell = floor(vUv * 2.0);
+    vec2 local = fract(vUv * 2.0);
+    if (cell.y >= 0.5 && cell.x < 0.5) {
+        if (uValid[0] > 0.5) { vec4 ins = uInset[0]; imgTexel = texture2D(uTiles[0], mix(ins.xy, ins.zw, local)); }
+    } else if (cell.y >= 0.5 && cell.x >= 0.5) {
+        if (uValid[1] > 0.5) { vec4 ins = uInset[1]; imgTexel = texture2D(uTiles[1], mix(ins.xy, ins.zw, local)); }
+    } else if (cell.y < 0.5 && cell.x < 0.5) {
+        if (uValid[2] > 0.5) { vec4 ins = uInset[2]; imgTexel = texture2D(uTiles[2], mix(ins.xy, ins.zw, local)); }
+    } else {
+        if (uValid[3] > 0.5) { vec4 ins = uInset[3]; imgTexel = texture2D(uTiles[3], mix(ins.xy, ins.zw, local)); }
+    }
+    diffuseColor *= imgTexel;
+`;
+
+/** 图片平面的持久化数据（进 exportData / importData） */
+export interface ImagePlaneData {
+    name?: string;
+    position: { x: number; y: number; z: number };
+    rotation: { x: number; y: number; z: number };
+    width: number;
+    height: number;
+    /** 原图地址（上传后返回的 origin URL，缩略图展示用） */
+    url: string;
+    /** 瓦片地址（行优先、图像左上起；张数 = 库里 `IMAGE_TILE_GRID` 的 cols×rows，10-21 旨 = 2×2=4） */
+    tiles: string[];
+    /** 原图自然像素宽（瓦片纹理实际像素，算 inset 采样窗口需要） */
+    naturalW?: number;
+    /** 原图自然像素高 */
+    naturalH?: number;
+}
+
+const DEFAULT_WIDTH = 2;
+const DEFAULT_HEIGHT = 1.5;
+const HIGHLIGHT_COLOR = "#ffd24a";
+
+export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
+    private _originalColor: string = "#ffffff";
+    private _uTiles!: { value: Texture[] };
+    private _uInset!: { value: Vector4[] };
+    private _uValid!: { value: number[] };
+    private _data: Omit<ImagePlaneData, "position" | "rotation" | "width" | "height"> = {
+        url: "",
+        tiles: [],
+    };
+
+    constructor(name?: string) {
+        const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
+        const mat = new MeshBasicMaterial({
+            color: new Color("#ffffff"),
+            side: FrontSide,
+            // 皇上旨 2026-10-21「平面的材质需要设置 alphaTest = 0.2」⇒ 同日 10-23 两次改口（先 0.9、后 **0.3**）：
+            // alpha 不足阈值的像素丢弃，其余实心。0.9 那一档会把图上半透的内容也切掉，现停在 0.3。
+            // ⛔ 这个构造里不许再写「走半透明通道」与「不透明度数值」那两行：皇上 10-22 点名「没有说过要设置透明度」，
+            //   那是臣 10-21 建这个类时擅自加的（没问过），当日整条删除。平面恒走不透明通道，
+            //   要「透」只能靠 alphaTest 这一刀切掉。
+            alphaTest: 0.3,
+        });
+        // ⭐ 2026-10-22 晚旨：图片平面**不用拼合器 RT**，直接把上传切好的 4 张瓦片纹理绑到材质，
+        //   片元按 UV 象限选片 + 用每片 `rtStitchTileInset` 窗口采样（与上传切片共用同一份几何 ⇒ 接缝不回潮）。
+        //   材质打补丁（onBeforeCompile）注入 4 个 sampler + 每片 inset + 就绪标志；缺失那片显示灰。
+        mat.defines = { USE_UV: "" };
+        const uTiles = { value: [PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX, PLACEHOLDER_TEX] as Texture[] };
+        const uInset = { value: [ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone(), ZERO_INSET.clone()] };
+        const uValid = { value: [0, 0, 0, 0] };
+        mat.onBeforeCompile = (shader) => {
+            shader.uniforms.uTiles = uTiles;
+            shader.uniforms.uInset = uInset;
+            shader.uniforms.uValid = uValid;
+            shader.fragmentShader = shader.fragmentShader
+                .replace(
+                    "#include <common>",
+                    `#include <common>
+                    uniform sampler2D uTiles[4];
+                    uniform vec4 uInset[4];
+                    uniform float uValid[4];`
+                )
+                .replace("#include <map_fragment>", IMG_PLANE_MAP_FRAG);
+        };
+        super(geo, mat);
+        this._uTiles = uTiles;
+        this._uInset = uInset;
+        this._uValid = uValid;
+        this.name = name || "图片平面";
+    }
+
+    get imageWidth(): number { return (this.geometry as PlaneGeometry).parameters.width; }
+    get imageHeight(): number { return (this.geometry as PlaneGeometry).parameters.height; }
+
+    setPlaneSize(w: number, h: number): void {
+        this.geometry.dispose();
+        this.geometry = new PlaneGeometry(w, h);
+    }
+
+    setPlaneData(d: Pick<ImagePlaneData, "url" | "tiles" | "naturalW" | "naturalH">): void {
+        this._data = { url: d.url, tiles: d.tiles, naturalW: d.naturalW, naturalH: d.naturalH };
+    }
+
+    get tiles(): string[] { return this._data.tiles; }
+    get url(): string { return this._data.url; }
+    get naturalW(): number | undefined { return this._data.naturalW; }
+    get naturalH(): number | undefined { return this._data.naturalH; }
+
+    /** 把上传切好的 4 张瓦片纹理 + 每片 inset 绑到材质（缺图那片传 null ⇒ 显示灰）。uTiles 用持久对象引用 ⇒ 改 value 实时生效 */
+    setTileTextures(texs: (Texture | null)[], insets: Vector4[]): void {
+        for (let i = 0; i < 4; i++) {
+            const t = texs[i] || null;
+            this._uTiles.value[i] = t || PLACEHOLDER_TEX;
+            if (insets[i]) this._uInset.value[i].copy(insets[i]);
+            this._uValid.value[i] = t ? 1 : 0;
+        }
+    }
+
+    highlight(): void {
+        this.material.color.set(HIGHLIGHT_COLOR);
+    }
+
+    restoreColor(): void {
+        this.material.color.set(this._originalColor);
+    }
+
+    toData(): ImagePlaneData {
+        return {
+            name: this.name || undefined,
+            position: { x: this.position.x, y: this.position.y, z: this.position.z },
+            rotation: { x: this.rotation.x, y: this.rotation.y, z: this.rotation.z },
+            width: this.imageWidth,
+            height: this.imageHeight,
+            url: this._data.url,
+            tiles: this._data.tiles,
+            naturalW: this._data.naturalW,
+            naturalH: this._data.naturalH,
+        };
+    }
+
+    applyData(d: ImagePlaneData): void {
+        if (d.name) this.name = d.name;
+        this.position.set(d.position.x, d.position.y, d.position.z);
+        this.rotation.set(d.rotation.x, d.rotation.y, d.rotation.z);
+        this.setPlaneSize(d.width, d.height);
+        this._data = { url: d.url, tiles: d.tiles || [], naturalW: d.naturalW, naturalH: d.naturalH };
+    }
+
+    dispose(): void {
+        this.geometry.dispose();
+        this.material.dispose();
+    }
+}
+
+export const IMAGE_PLANE_DEFAULTS = { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT };

package/MktMesh/imageTileLoader.d.ts

@@ -0,0 +1,19 @@
+import { Texture, Vector4 } from "three";
+interface TileEntry {
+    tex: Texture | null;
+    w: number;
+    h: number;
+}
+export declare class ImagePlaneTileLoader {
+    private cache;
+    private inflight;
+    /** 触发某张瓦片下载 + 解码（已缓存 / 在途则跳过）；完成后填入 cache，下一帧 feed 即取到 */
+    preload(url: string): void;
+    /** 取已就绪的瓦片（未就绪返回 null） */
+    get(url: string): TileEntry | null;
+    /** 第 i 片（行优先、图像左上起）的采样窗口；瓦片未就绪时返回整张 [0,0,1,1] */
+    inset(entry: TileEntry, i: number): Vector4;
+    /** 释放本 loader 持有的全部瓦片纹理（项目重置 / 卸载场景时调用；⛔ 不关共享占位纹理） */
+    clear(): void;
+}
+export {};