three-base 2.0.175 → 2.0.181

package/MktMesh/MktMesh.d.ts

@@ -2,6 +2,8 @@ import { BufferGeometry, Camera, Matrix4, Mesh, ShaderMaterial, Texture, Vector3
 import { type PanoTexMode } from "./mktShader";
 import { type PanoStitcher } from "./panoTileStitcher";
 import type { MktMeshData, MktTextureInfo, WallPoint, WallSide } from "./types";
+import { ImagePlane, type ImagePlaneData } from "./imagePlane";
+import { ModelSlot, type ModelSlotData } from "./modelSlot";
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures: MktTextureInfo[];
@@ -119,6 +121,18 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  必须与基类喂纹理处用同一个值，否则标记与地址不同源 ⇒ 整图被按 1/2 横向铺满球面（10-06 晚起纵向不分块，四槽时代是 1/4）。 */
     get panoTexMode(): PanoTexMode;
     private _tmpV3;
+    /**
+     * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
+     * ⇒ 移动/旋转/缩放这个展品时，墙 + 全景 + 平面图 + 模型一起走。
+     */
+    imagePlanes: ImagePlane[];
+    /** 模型槽层（同一棵子树，口径同上） */
+    models: ModelSlot[];
+    /**
+     * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不闪缺图灰；只随本对象 `dispose()` 释放。
+     */
+    private _imgTileLoader;
     constructor(opts?: {
         wallHeight?: number;
         wallClosed?: boolean;
@@ -295,12 +309,39 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     projectName: string;
     /** 注入项目名（导出 json 前调一次即可；导入时无须调——还原靠落盘地址自身的首段） */
     setProjectName(name: string): void;
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 */
+    addImagePlane(ip: ImagePlane): ImagePlane;
+    /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
+    removeImagePlane(ip: ImagePlane): void;
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    addModel(ms: ModelSlot): ModelSlot;
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾） */
+    removeModel(ms: ModelSlot): void;
+    /**
+     * 整层重建图片平面（`importData` 与预览那一路）。
+     * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
+     *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
+     */
+    setImagePlanes(datas: ImagePlaneData[]): void;
+    /**
+     * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
+     * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
+     *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     */
+    setModels(datas: ModelSlotData[], onEachLoad?: () => void): void;
+    /**
+     * 每帧把各颗平面那 4 张瓦片的纹理直采绑到材质（⭐ 10-22 晚旨：不走拼合器 RT）。
+     * 库里的**唯一驱动点**：持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次，⛔ 不许在调用方再抄一份循环。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元画缺图灰（皇上 10-26 收回默认图那条旨：「不要默认图, 没有加到位的时候 就显示深灰色」）。
+     */
+    feedImagePlaneTiles(): void;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData;
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
-     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
-    importData(data: MktMeshData, projName?: string): void;
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
+     *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
+    importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void;
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
     dispose(): this;
 }

package/MktMesh/MktMesh.js

@@ -16,14 +16,14 @@
  *     `panoSlotRoster.ts`；皇上旨 2026-10-03 起预览/发布与编辑器共用同一份算法 ⇒ 两边装同一批全景）。
  *     ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入），没注入才回落相机位置；
  *     中心变化或名册里有空格被补上人时加载新瓦片 → 设置 shader 的 8 个全景槽 panorama + textureMatrix；
- *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组）。
+ *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组 + ⭐ 10-26 旨起的平面图 / 模型两层）。
  *  5. ⚠️ 铁律：激活纹理（墙面上正在绘制的全景）的旋转/位置变化，必须立即同步到
  *     shader 的 textureMatrix uniform（见 setTexture），否则平面纹理不跟着全景球转。
  *
  * 说明：所有实例共享同一份 material（单一 panorama uniform），
  * 同一时刻只激活名册 0 号槽（中心）那一个纹理（全局共享单激活方案）。
  */
-import { BufferGeometry, BackSide, Float32BufferAttribute, Matrix4, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, } from "three";
+import { BufferGeometry, BackSide, Float32BufferAttribute, Matrix4, Mesh, Shape, ShapeGeometry, SRGBColorSpace, Vector3, Vector4, } from "three";
 import { createPlaceholderTexture, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT } from "./mktShader";
 import { MKT_PANO_MAX_SLOTS } from "./mktMappingShader";
 import { createMktFloorMappingShaderMaterial } from "./mktMappingShader";
@@ -45,6 +45,12 @@ import { subdivideCapTriangles, WALL_CAP_MAX_EDGE_M } from "./wallCapTessellate"
 // ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
 //    导出时剥域名（`exportData`）、导入时补回来（`importData`）——**各只有这一处**，⛔ 不许在别处另剥/另补。
 import { stripAssetHost, absAssetUrl } from "./assetUrl";
+// ⭐ 皇上旨 2026-10-26「按这个方案，把图片平面和模型一起搬进库里」：这两层（含每帧喂瓦片那条编排）
+//    原先各住在本站两个渲染器里一份 ⇒ 下游直接用包里的 `MktMesh` 时，存档里的 `images`/`models` 两键没人读。
+//    入库之后它们挂在 `MktMesh` **自己的子树**下，与墙同一棵变换 ⇒ 预览那三根 transform 滑杆搬得动整份展品。
+import { ImagePlane } from "./imagePlane";
+import { ModelSlot } from "./modelSlot";
+import { ImagePlaneTileLoader } from "./imageTileLoader";
 export default class MktMesh extends Mesh {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
     textures = [];
@@ -172,6 +178,18 @@ export default class MktMesh extends Mesh {
     }
     // 复用临时对象（避免每帧 new，降低 GC 压力）
     _tmpV3 = new Vector3();
+    /**
+     * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
+     * ⇒ 移动/旋转/缩放这个展品时，墙 + 全景 + 平面图 + 模型一起走。
+     */
+    imagePlanes = [];
+    /** 模型槽层（同一棵子树，口径同上） */
+    models = [];
+    /**
+     * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不闪缺图灰；只随本对象 `dispose()` 释放。
+     */
+    _imgTileLoader = new ImagePlaneTileLoader();
     constructor(opts = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -1008,6 +1026,105 @@ export default class MktMesh extends Mesh {
     setProjectName(name) {
         this.projectName = typeof name === "string" ? name : "";
     }
+    // ───────────── 平面图 / 模型两层（⭐ 皇上旨 2026-10-26「把图片平面和模型一起搬进库里」） ─────────────
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 */
+    addImagePlane(ip) {
+        this.imagePlanes.push(ip);
+        this.add(ip);
+        return ip;
+    }
+    /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
+    removeImagePlane(ip) {
+        const i = this.imagePlanes.indexOf(ip);
+        if (i >= 0)
+            this.imagePlanes.splice(i, 1);
+        this.remove(ip);
+        ip.dispose();
+    }
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    addModel(ms) {
+        this.models.push(ms);
+        this.add(ms);
+        return ms;
+    }
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾） */
+    removeModel(ms) {
+        const i = this.models.indexOf(ms);
+        if (i >= 0)
+            this.models.splice(i, 1);
+        this.remove(ms);
+        ms.dispose();
+    }
+    /**
+     * 整层重建图片平面（`importData` 与预览那一路）。
+     * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
+     *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
+     */
+    setImagePlanes(datas) {
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const d of datas) {
+            const ip = new ImagePlane(d.name);
+            ip.applyData(d);
+            this.imagePlanes.push(ip);
+            this.add(ip);
+        }
+    }
+    /**
+     * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
+     * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
+     *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     */
+    setModels(datas, onEachLoad) {
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        for (const d of datas) {
+            const ms = new ModelSlot(d.name);
+            ms.applyData(d);
+            this.models.push(ms);
+            this.add(ms);
+            if (d.url)
+                void ms.setModelUrl(d.url).then(() => onEachLoad && onEachLoad());
+        }
+    }
+    /**
+     * 每帧把各颗平面那 4 张瓦片的纹理直采绑到材质（⭐ 10-22 晚旨：不走拼合器 RT）。
+     * 库里的**唯一驱动点**：持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次，⛔ 不许在调用方再抄一份循环。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元画缺图灰（皇上 10-26 收回默认图那条旨：「不要默认图, 没有加到位的时候 就显示深灰色」）。
+     */
+    feedImagePlaneTiles() {
+        if (!this.imagePlanes.length)
+            return;
+        const zero = new Vector4(0, 0, 1, 1);
+        for (const ip of this.imagePlanes) {
+            const tiles = ip.tiles;
+            // ⛔ 旧存档 16 条地址（> 满批 4）直接不收 ⇒ 整张缺图灰，按 10-20 口径重传即可；空 tiles 同样
+            if (!tiles || tiles.length !== 4) {
+                ip.setTileTextures([null, null, null, null], [zero.clone(), zero.clone(), zero.clone(), zero.clone()]);
+                continue;
+            }
+            const texs = [null, null, null, null];
+            const insets = [zero.clone(), zero.clone(), zero.clone(), zero.clone()];
+            for (let i = 0; i < 4; i++) {
+                const url = tiles[i];
+                if (!url)
+                    continue;
+                this._imgTileLoader.preload(url);
+                const e = this._imgTileLoader.get(url);
+                if (!e || !e.tex)
+                    continue;
+                texs[i] = e.tex;
+                insets[i] = this._imgTileLoader.inset(e, i);
+            }
+            ip.setTileTextures(texs, insets);
+        }
+    }
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName) {
@@ -1030,11 +1147,29 @@ export default class MktMesh extends Mesh {
                 tiles: (t.tiles && t.tiles.length ? t.tiles.map((u) => stripAssetHost(u, pn)) : []),
                 matrix: t.matrix.toArray(),
             })),
+            // ⭐ 10-26 旨入库：这两层的地址与 `textures` 共用上面那一条剥域名口径（⛔ 不是另起一把尺），
+            //   其余字段（位置/旋转/宽高/瓦片数/落点面/原始包围盒）由各自的 `toData()` 逐字存。
+            images: this.imagePlanes.map((ip) => {
+                const d = ip.toData();
+                return {
+                    ...d,
+                    url: d.url ? stripAssetHost(d.url, pn) : "",
+                    tiles: d.tiles.length ? d.tiles.map((u) => stripAssetHost(u, pn)) : [],
+                };
+            }),
+            models: this.models.map((ms) => {
+                const d = ms.toData();
+                return { ...d, url: d.url ? stripAssetHost(d.url, pn) : "" };
+            }),
         };
     }
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
-     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
-    importData(data, projName) {
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
+     *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
+    importData(data, projName, onModelLoad) {
+        // ⭐ 10-08 旨的「补回域名」那颗项目名，10-26 旨之后全景/平面图/模型**三层共用同一个**（原来在 textures 的
+        //   map 里就地取，下面那两层也要用 ⇒ 提到方法开头，⛔ 不是第二处口径）。
+        const pn = typeof projName === "string" && projName ? projName : this.projectName;
         this.setWallPoints(data.wallPoints ?? [], {
             closed: data.wallClosed,
             height: data.wallHeight,
@@ -1049,7 +1184,6 @@ export default class MktMesh extends Mesh {
             //     （`/three-base_upload/…`）不必重存也能正常加载，不会被拼成 `https://host/https://host/…`
             //   · 19:53 旨后还要把 `{项目名}/x_0.jpg` **还原**成真身 OSS 地址（顶掉的上传目录要补回来），
             //     否则 json 里的地址指不回原图（图片裂）。`pn` 取入参、回落 `setProjectName` 注入的那个。
-            const pn = typeof projName === "string" && projName ? projName : this.projectName;
             const urlAbs = absAssetUrl(t.url, pn);
             return {
                 url: urlAbs,
@@ -1073,9 +1207,18 @@ export default class MktMesh extends Mesh {
                 this.panoFaceMapping[f] = imported[f];
             this.rebuildPanoIndexAttribute();
         }
+        // ⭐ 10-26 旨「把图片平面和模型一起搬进库里」的另一半：这两层也从**同一份 JSON** 里读，
+        //   地址在这一处补回域名（与上面 textures 同一条尺）⇒ 下游只调 `importData(整串)` 就全画出来。
+        //   旧存档没有这两个键 ⇒ 空数组 = 整层清空，与「墙 + 全景」那套逐字同口径。
+        this.setImagePlanes((data.images ?? []).map((d) => ({
+            ...d,
+            url: d.url ? absAssetUrl(d.url, pn) : "",
+            tiles: (d.tiles ?? []).map((u) => absAssetUrl(u, pn)),
+        })));
+        this.setModels((data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })), onModelLoad);
     }
     // ───────────────────────── 释放 ─────────────────────────
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
     dispose() {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
@@ -1086,6 +1229,19 @@ export default class MktMesh extends Mesh {
         this._texUploaded = new WeakSet(); // WeakSet 无 clear ⇒ 整只换掉
         this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
         this._ossSizeDepKeys.clear();
+        // ⭐ 10-26 旨入库的两层：子对象逐个 dispose，平面那 4 张瓦片的缓存**只在这里**整批清
+        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会闪缺图灰）。
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        this._imgTileLoader.clear();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder)

package/MktMesh/MktMesh.ts

@@ -16,7 +16,7 @@
  *     `panoSlotRoster.ts`；皇上旨 2026-10-03 起预览/发布与编辑器共用同一份算法 ⇒ 两边装同一批全景）。
  *     ⭐ 皇上旨 2026-10-07 第二十一道旨：锚点 = 外部控制器的中心点（`setRosterCenter` 注入），没注入才回落相机位置；
  *     中心变化或名册里有空格被补上人时加载新瓦片 → 设置 shader 的 8 个全景槽 panorama + textureMatrix；
- *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组）。
+ *  4. exportData / importData 支持导入导出（墙点位 + 纹理数组 + ⭐ 10-26 旨起的平面图 / 模型两层）。
  *  5. ⚠️ 铁律：激活纹理（墙面上正在绘制的全景）的旋转/位置变化，必须立即同步到
  *     shader 的 textureMatrix uniform（见 setTexture），否则平面纹理不跟着全景球转。
  *
@@ -39,6 +39,7 @@ import {
     SRGBColorSpace,
     Texture,
     Vector3,
+    Vector4,
 } from "three";
 import type { WebGLRenderer } from "three";
 import { createPlaceholderTexture, isPanoTexMode, mktPanoTiledFlag, mktPanoTexUrls, isRtStitchKey, rtStitchKeyParts, RT_STITCH_KEY_PREFIX, RT_STITCH_SLOT_COUNT, type PanoTexMode } from "./mktShader";
@@ -64,6 +65,12 @@ import { subdivideCapTriangles, WALL_CAP_MAX_EDGE_M } from "./wallCapTessellate"
 // ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
 //    导出时剥域名（`exportData`）、导入时补回来（`importData`）——**各只有这一处**，⛔ 不许在别处另剥/另补。
 import { stripAssetHost, absAssetUrl } from "./assetUrl";
+// ⭐ 皇上旨 2026-10-26「按这个方案，把图片平面和模型一起搬进库里」：这两层（含每帧喂瓦片那条编排）
+//    原先各住在本站两个渲染器里一份 ⇒ 下游直接用包里的 `MktMesh` 时，存档里的 `images`/`models` 两键没人读。
+//    入库之后它们挂在 `MktMesh` **自己的子树**下，与墙同一棵变换 ⇒ 预览那三根 transform 滑杆搬得动整份展品。
+import { ImagePlane, type ImagePlaneData } from "./imagePlane";
+import { ModelSlot, type ModelSlotData } from "./modelSlot";
+import { ImagePlaneTileLoader } from "./imageTileLoader";
 
 export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理列表（每个纹理的 url + 世界矩阵） */
@@ -197,6 +204,19 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     // 复用临时对象（避免每帧 new，降低 GC 压力）
     private _tmpV3: Vector3 = new Vector3();
 
+    /**
+     * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
+     * ⇒ 移动/旋转/缩放这个展品时，墙 + 全景 + 平面图 + 模型一起走。
+     */
+    imagePlanes: ImagePlane[] = [];
+    /** 模型槽层（同一棵子树，口径同上） */
+    models: ModelSlot[] = [];
+    /**
+     * 那 4 张瓦片的下载/解码缓存。⭐ 与全景 `_texCache` 同一条旨（10-02「纹理都缓存在对象里面，执行 dispose 时才销毁」）
+     * ⇒ 切工程**不**清它，回来那一圈直接命中缓存、不闪缺图灰；只随本对象 `dispose()` 释放。
+     */
+    private _imgTileLoader = new ImagePlaneTileLoader();
+
     constructor(opts: { wallHeight?: number; wallClosed?: boolean } = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -1035,6 +1055,107 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this.projectName = typeof name === "string" ? name : "";
     }
 
+    // ───────────── 平面图 / 模型两层（⭐ 皇上旨 2026-10-26「把图片平面和模型一起搬进库里」） ─────────────
+
+    /** 单颗图片平面入层（编辑态双击落点用）：进数组 + 挂进本对象子树 */
+    addImagePlane(ip: ImagePlane): ImagePlane {
+        this.imagePlanes.push(ip);
+        this.add(ip);
+        return ip;
+    }
+
+    /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
+    removeImagePlane(ip: ImagePlane): void {
+        const i = this.imagePlanes.indexOf(ip);
+        if (i >= 0) this.imagePlanes.splice(i, 1);
+        this.remove(ip);
+        ip.dispose();
+    }
+
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    addModel(ms: ModelSlot): ModelSlot {
+        this.models.push(ms);
+        this.add(ms);
+        return ms;
+    }
+
+    /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾） */
+    removeModel(ms: ModelSlot): void {
+        const i = this.models.indexOf(ms);
+        if (i >= 0) this.models.splice(i, 1);
+        this.remove(ms);
+        ms.dispose();
+    }
+
+    /**
+     * 整层重建图片平面（`importData` 与预览那一路）。
+     * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
+     *   ⛔ 本方法里不许再补一遍，也⛔ 不许在调用方各自补。
+     */
+    setImagePlanes(datas: ImagePlaneData[]): void {
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const d of datas) {
+            const ip = new ImagePlane(d.name);
+            ip.applyData(d);
+            this.imagePlanes.push(ip);
+            this.add(ip);
+        }
+    }
+
+    /**
+     * 整层重建模型槽（`importData` 与预览那一路），地址口径的要求同 `setImagePlanes`。
+     * ⚠️ GLB 逐只**异步取、不 await**（十几只串一条队会把载入卡死），每只落地那一刻各回调一次 `onEachLoad`：
+     *   预览每帧真画 ⇒ 不传；编辑器是按需渲染 ⇒ 传一个「标脏」的钩子，否则模型挂上来屏幕不动。
+     */
+    setModels(datas: ModelSlotData[], onEachLoad?: () => void): void {
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        for (const d of datas) {
+            const ms = new ModelSlot(d.name);
+            ms.applyData(d);
+            this.models.push(ms);
+            this.add(ms);
+            if (d.url) void ms.setModelUrl(d.url).then(() => onEachLoad && onEachLoad());
+        }
+    }
+
+    /**
+     * 每帧把各颗平面那 4 张瓦片的纹理直采绑到材质（⭐ 10-22 晚旨：不走拼合器 RT）。
+     * 库里的**唯一驱动点**：持有渲染循环的那一方（编辑态 / 预览 / 下游）每帧调一次，⛔ 不许在调用方再抄一份循环。
+     * 还没下载完/缺格的那一格绑 null ⇒ 片元画缺图灰（皇上 10-26 收回默认图那条旨：「不要默认图, 没有加到位的时候 就显示深灰色」）。
+     */
+    feedImagePlaneTiles(): void {
+        if (!this.imagePlanes.length) return;
+        const zero = new Vector4(0, 0, 1, 1);
+        for (const ip of this.imagePlanes) {
+            const tiles = ip.tiles;
+            // ⛔ 旧存档 16 条地址（> 满批 4）直接不收 ⇒ 整张缺图灰，按 10-20 口径重传即可；空 tiles 同样
+            if (!tiles || tiles.length !== 4) {
+                ip.setTileTextures([null, null, null, null], [zero.clone(), zero.clone(), zero.clone(), zero.clone()]);
+                continue;
+            }
+            const texs: (Texture | null)[] = [null, null, null, null];
+            const insets: Vector4[] = [zero.clone(), zero.clone(), zero.clone(), zero.clone()];
+            for (let i = 0; i < 4; i++) {
+                const url = tiles[i];
+                if (!url) continue;
+                this._imgTileLoader.preload(url);
+                const e = this._imgTileLoader.get(url);
+                if (!e || !e.tex) continue;
+                texs[i] = e.tex;
+                insets[i] = this._imgTileLoader.inset(e, i);
+            }
+            ip.setTileTextures(texs, insets);
+        }
+    }
+
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData {
@@ -1057,12 +1178,30 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
                 tiles: (t.tiles && t.tiles.length ? t.tiles.map((u) => stripAssetHost(u, pn)) : []) as string[],
                 matrix: t.matrix.toArray(),
             })),
+            // ⭐ 10-26 旨入库：这两层的地址与 `textures` 共用上面那一条剥域名口径（⛔ 不是另起一把尺），
+            //   其余字段（位置/旋转/宽高/瓦片数/落点面/原始包围盒）由各自的 `toData()` 逐字存。
+            images: this.imagePlanes.map((ip) => {
+                const d = ip.toData();
+                return {
+                    ...d,
+                    url: d.url ? stripAssetHost(d.url, pn) : "",
+                    tiles: d.tiles.length ? d.tiles.map((u) => stripAssetHost(u, pn)) : [],
+                };
+            }),
+            models: this.models.map((ms) => {
+                const d = ms.toData();
+                return { ...d, url: d.url ? stripAssetHost(d.url, pn) : "" };
+            }),
         };
     }
 
     /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
-     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
-    importData(data: MktMeshData, projName?: string): void {
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址
+     *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
+    importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void {
+        // ⭐ 10-08 旨的「补回域名」那颗项目名，10-26 旨之后全景/平面图/模型**三层共用同一个**（原来在 textures 的
+        //   map 里就地取，下面那两层也要用 ⇒ 提到方法开头，⛔ 不是第二处口径）。
+        const pn = typeof projName === "string" && projName ? projName : this.projectName;
         this.setWallPoints(data.wallPoints ?? [], {
             closed: data.wallClosed,
             height: data.wallHeight,
@@ -1078,7 +1217,6 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
                 //     （`/three-base_upload/…`）不必重存也能正常加载，不会被拼成 `https://host/https://host/…`
                 //   · 19:53 旨后还要把 `{项目名}/x_0.jpg` **还原**成真身 OSS 地址（顶掉的上传目录要补回来），
                 //     否则 json 里的地址指不回原图（图片裂）。`pn` 取入参、回落 `setProjectName` 注入的那个。
-                const pn = typeof projName === "string" && projName ? projName : this.projectName;
                 const urlAbs = absAssetUrl(t.url as string, pn);
                 return {
                     url: urlAbs,
@@ -1102,11 +1240,25 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             for (let f = 0; f < restore; f++) this.panoFaceMapping[f] = imported[f];
             this.rebuildPanoIndexAttribute();
         }
+        // ⭐ 10-26 旨「把图片平面和模型一起搬进库里」的另一半：这两层也从**同一份 JSON** 里读，
+        //   地址在这一处补回域名（与上面 textures 同一条尺）⇒ 下游只调 `importData(整串)` 就全画出来。
+        //   旧存档没有这两个键 ⇒ 空数组 = 整层清空，与「墙 + 全景」那套逐字同口径。
+        this.setImagePlanes(
+            (data.images ?? []).map((d) => ({
+                ...d,
+                url: d.url ? absAssetUrl(d.url, pn) : "",
+                tiles: (d.tiles ?? []).map((u) => absAssetUrl(u, pn)),
+            }))
+        );
+        this.setModels(
+            (data.models ?? []).map((d) => ({ ...d, url: d.url ? absAssetUrl(d.url, pn) : "" })),
+            onModelLoad
+        );
     }
 
     // ───────────────────────── 释放 ─────────────────────────
 
-    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、几何、材质 */
+    /** 释放 GPU 资源：瓦片缓存（**只有这里**清，皇上旨 2026-10-02）、拼合器、平面图/模型两层、几何、材质 */
     dispose(): this {
         // ⚠️ rt 虚拟键从不进 `_texCache`（拼合槽纹理由 `_stitcher` 自己持有并释放），这里清的都是本类下载的 Texture。
         // ⭐ 甲（2026-10-05）：`releasePanoTexture` 除 `dispose()` 外还要 `ImageBitmap.close()` —— 位图的原生内存
@@ -1116,6 +1268,19 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this._texUploaded = new WeakSet(); // WeakSet 无 clear ⇒ 整只换掉
         this._uploadQueued.clear(); // 排队项即便回调仍触发，也会因 `!this._uploadQueued.delete(tex)` 早退
         this._ossSizeDepKeys.clear();
+        // ⭐ 10-26 旨入库的两层：子对象逐个 dispose，平面那 4 张瓦片的缓存**只在这里**整批清
+        //   （与上面 `_texCache` 同一条旨 ⇒ 切工程不重建这一份、也就不会闪缺图灰）。
+        for (const ip of this.imagePlanes) {
+            this.remove(ip);
+            ip.dispose();
+        }
+        this.imagePlanes = [];
+        for (const ms of this.models) {
+            this.remove(ms);
+            ms.dispose();
+        }
+        this.models = [];
+        this._imgTileLoader.clear();
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder) this._placeholder.dispose();

package/MktMesh/boxLine2.d.ts

@@ -0,0 +1,42 @@
+import { BoxGeometry, BufferGeometry, Camera, Group, Material, Mesh, MeshBasicMaterial, NormalBufferAttributes, Raycaster, Scene, Vector3, WebGLRenderer } from "three";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
+import { LineSegments2 } from "three/examples/jsm/lines/LineSegments2.js";
+export default class BoxLine2 extends Mesh {
+    constructor();
+    /** 控制台识别用（本仓约定：对象要能被认出来是谁的哪一份） */
+    type: string;
+    frustumCulled: boolean;
+    size: Vector3;
+    T1: Vector3;
+    T2: Vector3;
+    T3: Vector3;
+    T4: Vector3;
+    B1: Vector3;
+    B2: Vector3;
+    B3: Vector3;
+    B4: Vector3;
+    frontLineMaterial: LineMaterial;
+    backLineMaterial: LineMaterial;
+    createLine(name: string): LineSegments2;
+    T1_line: LineSegments2;
+    T2_line: LineSegments2;
+    T3_line: LineSegments2;
+    T4_line: LineSegments2;
+    M1_line: LineSegments2;
+    M2_line: LineSegments2;
+    M3_line: LineSegments2;
+    M4_line: LineSegments2;
+    B1_line: LineSegments2;
+    B2_line: LineSegments2;
+    B3_line: LineSegments2;
+    B4_line: LineSegments2;
+    /** 射线靶子（比框小一圈）：`alphaTest: 1.1` ⇒ 一个像素都不画，只给下面的遮挡判据打 */
+    boxMesh: Mesh<BoxGeometry, MeshBasicMaterial, import("three").Object3DEventMap>;
+    /** 代理盒单边内缩量：米级盒子照参考实现减 0.1；薄一片/占位方块那种小尺寸钳到自身的一半，⛔ 不出负数 */
+    private _insetSize;
+    setSize(v: Vector3): void;
+    raycaster: Raycaster;
+    onBeforeRender: (renderer: WebGLRenderer, _scene: Scene, camera: Camera, _geometry: BufferGeometry<NormalBufferAttributes>, _material: Material, _group: Group) => void;
+    /** 释放：12 份线段几何 + 代理盒几何 + 两份 LineMaterial + 代理盒材质（模型槽删除/换框时调用） */
+    dispose(): void;
+}