three-base 2.0.172 → 2.0.175

package/MktMesh/panoTileStitcher.ts

@@ -1,5 +1,5 @@
 /*
- * @Description: 32 瓦片全景的「离屏拼合器」= **shader 逐格画进 WebGLRenderTarget**（本项目唯一一份拼合实现）。
+ * @Description: 9 瓦片全景的「离屏拼合器」= **shader 逐格画进 WebGLRenderTarget**（本项目唯一一份拼合实现）。
  *
  * 三道旨意叠成现在这一份：
  *   ① 2026-09-29：一张全景切多片（每片所有 GPU 都装得下），运行时离屏拼回若干张固定尺寸的「槽纹理」，
@@ -18,54 +18,66 @@
  *      ⇒ 旨②的 8×8=64 片 / 2×2 四槽 **作废**：改 **8×4=32 片 / 左右 2 槽**（槽纹理跟着变 4096² 正方形）。
  *      ⭐ 净效果：sampler 总数仍 16（硬顶）⇒ 同屏全景数 **4 → 8**；画质与单全景显存**分毫未动**；
  *         单全景下载片数 64 → 32（**减半**）。旧存档 64 条地址**不兼容**，皇上「有异常我会重传」。
+ *   ④ 2026-10-23（皇上旨，逐字）：「瓦片拆成 9 个了，每个瓦片的尺寸是 4096 * 2048 所有，全景的 RT 由原来的
+ *      2 个分成 3 个，每个 RT 的尺寸是 4096 * 6144，竖直排列 3 个瓦片」
+ *      ⇒ 改 **3×3=9 片 / 按列 3 槽**，每槽 = 原图一整列（横 1 格 × 竖 3 格）= **4096×6144**、与原图 1:1（不再缩小）。
+ *      ⚠️ 代价（皇上在「A/B/C/D」里点了 **A**）：sampler = 同屏景点数 × 3，硬顶 16 ⇒ **同屏全景点数 8 → 5**（5×3=15）。
+ *         单全景 RT 显存 170MB → **288MB**（含 mipmap ≈384MB）。旧存档 32 条地址**不兼容**，「有异常我会重传」。
  *
  * ⚠️ **仍然有 canvas，但只在上传切图那一步**（`src/views/MktMeshEdit/panoramaUpload.ts` 用 2D 画布把原图
- *    切成 32 个 JPEG 传 OSS）—— 那是**离线、一次性、产出的是数据**；运行时这条路上一个 canvas 都没有。
+ *    切成 9 个 JPEG 传 OSS）—— 那是**离线、一次性、产出的是数据**；运行时这条路上一个 canvas 都没有。
  *
  * ── 每帧的三道工序（旨②那两句话逐条落地，顺序固定）────────────────────────────────
- *   1. `_pumpDownloads()`：补发缺图的下载（每帧 ≤2 张、在册 ≤8、已解码待上传 ≤8）⇒ ⛔ 32 条 XHR 一起炸。
+ *   1. `_pumpDownloads()`：补发缺图的下载（每帧 ≤2 张、在册 ≤8、已解码待上传 ≤8）⇒ ⛔ 一批几十条 XHR 一起炸。
  *   2. `_drawPass()`：**只画「已经在 GPU 上的」瓦片**，一帧内画多少格都行（旨②「已经载入过的纹理，才可以
  *      一次性全部渲染到 RT 上面去」）。画完立刻释放那片 ⇒ 显存峰值 = 一格的量。
  *   3. `_uploadPass()`：**每帧至多一张**新纹理 `initTexture` 进 GPU（旨②「每一帧同样也是只载入一张新纹理
  *      到 GPU 里面去」）。这一趟**只上传、不画** ⇒ 上传与绘制永不落在同一拍（09-29 那句「两个大头别在同一
  *      帧」的延续），而且第 2 步天然只能画「上一帧及更早」传上去的图 ⇒ 每帧 = 1 上传 + 1 绘制（稳态）。
  *
- * ⚠️ 于是「一帧一片」从最旧版的 16 帧/组变成 **32 帧/组**（30ms/帧 ⇒ 全量到位约 1.0s，最旧版约 0.5s；
- *    10-06 白天那版 64 片是 64 帧/组 ≈ 1.9s，现砍半）。每格像素 1024²（旧 1024×512）。
- *    且因为下面那条「先喂 shader」的旨意，第一格画完墙上就有东西了，不必等 16 帧。
+ * ⚠️ 于是「一帧一片」的帧数随网格走：16 片 → 32 片（30ms/帧 ⇒ 全量到位约 1.0s）→ **9 片/组 = 9 帧**（约 0.27s，
+ *    10-23 旨）。每格像素 = `RT_STITCH_SLOT_W/1 × RT_STITCH_SLOT_H/3` = **4096×2048**（原图切出来那片多大就多大，一比一）。
+ *    且因为下面那条「先喂 shader」的旨意，第一格画完墙上就有东西了，不必等 9 帧。
  *
- * ⭐ 部分就绪就先喂（同日旨「1. 需要先喂给 shader」）：`peek()` 不再等一个槽的 16 格画满，
+ * ⭐ 部分就绪就先喂（同日旨「1. 需要先喂给 shader」）：`peek()` 不再等一个槽的 `cellsPerSlot` 格画满，
  *   **画过 ≥1 格就交出去**。为了保证交出去的那张 RT 里绝无未定义像素，RT 建好后的第一件事是
  *   整张涂成缺失灰（`_clearRt`）⇒ 观感 = 该象限从左上角起逐格显影，缺数据的格子一直是灰的。
  *
  * ── 画质四条（⛔ 改任何一条都是改画质，先请旨）──────────────────────────────
- *  1. **尺寸 / 格子几何**：槽 `RT_STITCH_SLOT_W/H` = **4096×4096 正方形**、每边 4 格、原图**横 8 × 竖 4** 片，
- *     全在 `./mktShader`（单一来源）。缩放比 (W/8)/1024 与 16 片时代 (W/4)/2048 **是同一个数**
- *     ⇒ 这次切细不涨不降清晰度。⛔ 槽必须是正方形：每槽现在覆盖「横 180° × 竖 180°」，
- *     沿用 4096×2048 会让纵向被压 2 倍（见 `RT_STITCH_SLOT_H` 那条注释）。
+ *  1. **尺寸 / 格子几何**：槽 `RT_STITCH_SLOT_W/H` = **4096×6144**、每槽「横 1 格 × 竖 3 格」、原图**横 3 × 竖 3** 片，
+ *     全在 `./mktShader`（单一来源）。⭐ 10-23 旨后格子尺寸 = 那片瓦片的尺寸 ⇒ **一比一**：11968×5984 那类原图
+ *     切 3×3 得 ~3989×1994 的片，铺进 4096×2048 的格子几乎不缩（缩放比 0.97，上一版 8×4 是 1.46 = 缩小）
+ *     ⇒ 单全景有效分辨率 33.5Mpx → **75.5Mpx**，是**升**画质，与「千万不要降低质量」红线同向。
+ *     ⛔ 不许把槽改回 4096² 正方形：那是上一版「每槽覆盖横 180°×竖 180°」的产物；现口径每槽只覆盖**横 120° × 竖 180°**，
+ *     宽高比 2:3 必须与「原图一整列」一致，否则格子被强行拉伸 = 几何挤歪。
  *  2. **色彩**：瓦片纹理 `colorSpace = SRGBColorSpace` ⇒ WebGL2 内部格式 `SRGB8_ALPHA8`，采样时硬件解码成
  *     linear；RT 纹理同样标 sRGB ⇒ 写入时硬件再编码回 sRGB。一进一出**逐字节还原**。
  *     ⚠️ 另一半证据在 three 里：写进非 XR 的 render target 时片元末尾的 `linearToOutputTexel` 恒按
  *     LinearSRGB（= 不转换），编码完全交给硬件 ⇒ ⛔ 我们的片元绝不 `#include <colorspace_fragment>`，
  *     也不带 tone mapping 的 chunk（那两处都会再转一遍 ⇒ 画面发白）。
  *  3. **摩尔纹**：两层都开 mipmap ——
- *     ① 瓦片纹理 `generateMipmaps` + `LinearMipmapLinearFilter`：一片原图 1488px 缩进 1024px 的格子是
- *        **缩小**，⛔ 单点双线性会采出锯齿（WebGL2 对 NPOT 也能生成 mipmap，three r163 起只支持 WebGL2）。
+ *     ① 瓦片纹理 `generateMipmaps` + `LinearMipmapLinearFilter`：10-23 旨后一片原图（~3989×1994）铺进 4096×2048
+ *        的格子是**一比一**，但墙面在远处仍会缩到格子以下 ⇒ ⛔ 单点双线性会采出锯齿，mipmap 照旧开
+ *        （WebGL2 对 NPOT 也能生成 mipmap，three r163 起只支持 WebGL2）。
  *     ② 槽 RT 标 `generateMipmaps`：three 每次渲染进 RT 后自己 `glGenerateMipmap`（`WebGLRenderer.js`
  *        `updateRenderTargetMipmap`）⇒ 与当年 CanvasTexture 上传后生成 mipmap 同一口径。
  *        ⚠️ 代价：每格一次（旧版每格也是一次），都在 GPU 上、不占主线程。
- *  4. **接缝**：槽内 4×4 = 16 格 ⇒ 一张槽内部的格子线从 1 横 1 竖变成 3 横 3 竖。治法 = 上传时每片向四边**多切**
+ *  4. **接缝**：槽内「横 1 × 竖 3」⇒ 一张槽内部的格子线是 **2 横 0 竖**（上一版 4096² 是 3 横 3 竖）；
+ *     槽与槽之间另有 u=1/3、u=2/3 两道**跨纹理**竖缝，那道治不了（见 `PanoTexMode` 说明②）。治法 = 上传时每片向四边**多切**
  *     `RT_STITCH_SEAM_MARGIN_PX` 像素、拼合时**只采中间那块**（`uSrcRect`）⇒ 边界插值拿得到真邻居像素，
  *     不再复制自己的边缘。⛔ 这条不许「顺手简化」成直接铺满格子：几何会挤歪，缝也还在。
  *     详见 `./mktShader` 里那三个 `rtStitch*` 纯函数 —— **上传侧与拼合侧必须共用同一份几何**。
  *
- * 资源账（⚠️ 如实记；10-06 晚改 8×4=32 片 / 左右 2 槽后重算）：
- *   - 常驻显存：2 槽 × (4096×**4096**×4B + mipmap≈33%) ≈ **170MB/全景** —— 与 16 片、64 片时代**一字不变**
- *     （合计像素相同，只是从「4 张 4096×2048」变成「2 张 4096×4096」）。
- *     ⚠️ 但同屏从 4 个全景变 **8 个** ⇒ 同屏 RT 显存 683MB → **1.33GB**；13 个全景全常驻 ≈ 2.2GB
- *     （上一轮已奉旨取消 LRU 淘汰 ⇒ 这些真会常驻，皇上已知情）。
- *   - 上传总量：32 片 × ~9.2MB ≈ 292MB/全景 ⇒ 总量不变、**片数减半**（64 片那版每片 4.6MB × 64）。
- *   - 瓦片纹理画完即弃 ⇒ 同时在册的只有「下载中 + 已解码待上传」那些，上限 8+8 片 ≈ 73MB CPU/拼合器。
+ * 资源账（⚠️ 如实记；10-23 旨改 3×3=9 片 / 按列 3 槽 / 4096×6144 后重算）：
+ *   - 常驻显存：3 槽 × (4096×**6144**×4B + mipmap≈33%) ≈ **384MB/全景**（不含 mipmap 288MB）
+ *     —— 上一版 2 槽 4096² 是 **170MB/全景** ⇒ 单全景变成 **2.26 倍**，代价来自「槽与原图一比一」那次**升分辨率**，
+ *     不是浪费：33.5Mpx → 75.5Mpx 的有效像素全在 RT 里。
+ *     ⚠️ 组**运行中不淘汰**（见文末那条旨）⇒ 13 张全景全常驻 ≈ **4.9GB**（上一版 2.2GB）。同屏景点数虽收到 5，
+ *     那只省 sampler 绑定、**不省显存**。⚠️ 这是本轮最大的风险项，已另记待皇上裁决（见「RT 不回收」）。
+ *   - 上传总量：同一张原图切完 ⇒ **总像素与 32 片那版逐字节同量**，只是片数 32 → 9、单片边长 ~2.7 倍
+ *     ⇒ 下载发起数减 72%、单请求变大。
+ *   - 瓦片纹理画完即弃 ⇒ 同时在册的只有「下载中 + 已解码待上传」那些，上限 8+8 片；
+ *     ⚠️ 每片解码位图 4096×2048×4B = **32MB**（上一版每片 8.5MB）⇒ 峰值 CPU 侧 ≈ **512MB**（原 ~136MB）。
  *
  * ⚠️ RT 是 GL 上下文私有资源：`pump(renderer)` 换 renderer 时整组作废（`_switchRenderer`），下一帧消费方
  *   照旧的 `ensure()` 重建（瓦片走浏览器 HTTP 缓存重新下载）。现况是**每个持有者一份拼合器 + 一个 renderer**
@@ -100,16 +112,14 @@ import { loadPanoTexture, releasePanoTexture } from "./panoBitmapTexture";
 import threeUtils from "../threeUtils";
 import {
     MISSING_TILE_GRAY,
-    RT_STITCH_CELLS_PER_SLOT,
-    RT_STITCH_SLOT_COUNT,
-    RT_STITCH_SLOT_H,
-    RT_STITCH_SLOT_TILES,
-    RT_STITCH_SLOT_W,
-    RT_STITCH_SLOT_GRID,
-    RT_STITCH_TILES_PER_BATCH,
     rtStitchBatchOf,
     rtStitchCellPos,
     rtStitchTileInset,
+    type TileLayout,
+    PANO_TILE_LAYOUT,
+    cellsPerSlotOf,
+    tilesPerBatchOf,
+    slotTilesOf,
 } from "./mktShader";
 
 /**
@@ -120,7 +130,7 @@ import {
  */
 const PANO_STITCH_UPLOADS_PER_FRAME = 1;
 
-/** 每帧最多发起几张下载（32 片一批，⛔ 不加以限制就是一帧甩 32 条 XHR + 32 次解码） */
+/** 每帧最多发起几张下载（10-23 起一批 9 片，⛔ 不加以限制就是一帧甩 9 条 XHR + 9 次 800 万像素解码） */
 const PANO_STITCH_DOWNLOADS_PER_FRAME = 2;
 
 /** 「下载中」的片数上限（跨所有批次） */
@@ -185,15 +195,23 @@ interface TileRec {
     uploaded: boolean;
 }
 
-/** 一个 32 瓦片批次（= 一个全景点）的拼合组 */
+/** 一个瓦片批次的拼合组（⛔ 名字仍叫 StitchGroup，不改对外接口 —— 只是多了 layout） */
 interface StitchGroup {
-    /** 32 张瓦片地址（原图 **横 8 × 竖 4 行优先**、图像左上起；不足 32 条补空串占位 ⇒ 缺格涂灰） */
+    /** 布局（⛔ 由 `ensure` 传入；全景 = PANO_TILE_LAYOUT，图片平面 = imageTileLayout(…)） */
+    layout: TileLayout;
+    /** 该布局下槽 slot 使用哪些瓦片下标（预计算 `slotTilesOf(layout)` ⇒ 每帧三道工序反复用，不再每帧现算） */
+    slotTiles: number[][];
+    /** 该布局一批几条地址（补空串占位到此长度） */
+    tileCount: number;
+    /** 该布局每槽几格（cell < cellsPerSlot） */
+    cellsPerSlot: number;
+    /** 瓦片地址数组（图像左上起行优先） */
     urls: string[];
-    /** `RT_STITCH_SLOT_COUNT`(2) 个槽的渲染目标（懒建；`rt.texture` 就是交给 shader 的那张槽纹理） */
+    /** layout.slotCount 个槽的渲染目标（懒建） */
     rts: (WebGLRenderTarget | null)[];
-    /** 每槽一个 16 位掩码：bit `cell` = 1 ⇒ 这一格已画进 RT（**允许跳着画**：谁先到就上谁） */
+    /** 每槽一个位掩码：bit `cell` = 1 ⇒ 这一格已画进 RT */
     drawn: number[];
-    /** 每槽已画格数（= 掩码的 popcount，省得每帧数） */
+    /** 每槽已画格数（= 掩码 popcount） */
     drawnCount: number[];
     /** 还剩几槽没画满 */
     pending: number;
@@ -204,8 +222,10 @@ interface StitchGroup {
  * 10-06 之前它是「两份实现共用一份接口」里的 canvas 那一份 ⇒ 那份已奉旨删除，接口留在原地当文档。
  */
 export interface PanoStitcher {
-    /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做） */
-    ensure(urls: string[]): void;
+    /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
+     *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 3×3 / 3 槽 / 4096×6144，10-23 旨）；
+     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。 */
+    ensure(urls: string[], layout?: TileLayout): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
      * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
@@ -270,7 +290,8 @@ private _uploadQueued: Set<TileRec> = new Set();
         depthWrite: false,
         blending: NoBlending,
     });
-    /** 几何是 2×2（铺满正交相机的 [-1,1]²），每格只把它缩到 1/4 再挪过去 ⇒ 一格 = 槽的 1/16 */
+    /** 几何是 2×2（铺满正交相机的 [-1,1]²），每格按 `1/slotCellCols × 1/slotCellRows` 缩放再挪过去
+     *  ⇒ 全景一格 = 槽的 1/3（横 1 竖 3，10-23 旨），图片平面一格 = 1/4（横 2 竖 2） */
     private _quad: Mesh<PlaneGeometry, ShaderMaterial> = new Mesh(new PlaneGeometry(2, 2), this._mat);
     /** 缺格那一路 `uMap` 也要有个合法纹理可绑（1×1，从不真采样） */
     private _blank: DataTexture = new DataTexture(new Uint8Array([0, 0, 0, 255]), 1, 1);
@@ -284,28 +305,36 @@ private _uploadQueued: Set<TileRec> = new Set();
     }
 
     /** 确保批次已建组、加载已发起。幂等：同批已在册 ⇒ 直接返回（一片瓦片终身只下载、只解码一次）。
-     *  ⭐ 09-29 晚旨「不足的涂灰」+ 10-06 晚旨「8×4 = 32 片」：1~32 条皆可入组，内部补空串占位到 32；
+     *  ⭐ 09-29 晚旨「不足的涂灰」+ 10-23 旨「3×3 = 9 片」：1~9 条皆可入组，内部补空串占位到 9；
      *  空串 / 死链的格子拼合时涂灰（一眼看出该全景数据不全）。
-     *  ⛔ 旧版 16 条（4×4）与 64 条（8×8）的数据**都不做兼容**（皇上「无须兼容正常使用, 有异常我会重传」）：
-     *  64 条会在上一行被判超限直接丢弃；真喂进来的短数据只占前几格 + 其余涂灰，那是**故意**让数据不全看得见。
-     *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null,null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls: string[]): void {
-        if (!urls || urls.length === 0 || urls.length > RT_STITCH_TILES_PER_BATCH) return;
+     *  ⛔ 旧版 16 条（4×4）、32 条（8×4）与 64 条（8×8）的数据**都不做兼容**（皇上「无须兼容正常使用, 有异常我会重传」）：
+     *  超 9 条会在上一行被判超限直接丢弃；真喂进来的短数据只占前几格 + 其余涂灰，那是**故意**让数据不全看得见。
+     *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null,null]` —— 槽数再变会漏改）。 */
+    ensure(urls: string[], layout?: TileLayout): void {
+        const L = layout ?? PANO_TILE_LAYOUT;
+        const maxTiles = tilesPerBatchOf(L);
+        if (!urls || urls.length === 0 || urls.length > maxTiles) return;
         const u = urls.slice();
-        while (u.length < RT_STITCH_TILES_PER_BATCH) u.push("");
+        while (u.length < maxTiles) u.push("");
         const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch)) return; // ⭐ 已建组：什么都不做（绝不重建 ⇒ 永不二次解码）
+        if (this._groups.has(batch)) return;
+        const slotCount = L.slotCount;
+        const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
+            layout: L,
+            slotTiles: slotTilesOf(L),
+            tileCount: maxTiles,
+            cellsPerSlot,
             urls: u,
-            rts: Array.from({ length: RT_STITCH_SLOT_COUNT }, () => null),
-            drawn: Array.from({ length: RT_STITCH_SLOT_COUNT }, () => 0),
-            drawnCount: Array.from({ length: RT_STITCH_SLOT_COUNT }, () => 0),
-            pending: RT_STITCH_SLOT_COUNT,
+            rts: Array.from({ length: slotCount }, () => null),
+            drawn: Array.from({ length: slotCount }, () => 0),
+            drawnCount: Array.from({ length: slotCount }, () => 0),
+            pending: slotCount,
         });
         this._stamp++;
     }
 
-    /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 16 格画满）。
+    /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {
         const g = this._groups.get(batch);
@@ -398,13 +427,13 @@ private _uploadQueued: Set<TileRec> = new Set();
         let budget = PANO_STITCH_DOWNLOADS_PER_FRAME;
         for (const g of this._groups.values()) {
             if (budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
-            for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
-                const ids = RT_STITCH_SLOT_TILES[slot];
-                for (let cell = 0; cell < RT_STITCH_CELLS_PER_SLOT; cell++) {
-                    if (g.drawn[slot] & (1 << cell)) continue; // 画过的格子那片早释放了，不用再来
+            for (let slot = 0; slot < g.layout.slotCount; slot++) {
+                const ids = g.slotTiles[slot];
+                for (let cell = 0; cell < g.cellsPerSlot; cell++) {
+                    if (g.drawn[slot] & (1 << cell)) continue;
                     const url = g.urls[ids[cell]];
-                    if (!url || this._dead.has(url)) continue; // 缺格 / 死链：涂灰那一路，不需要纹理
-                    if (this._texs.has(url)) continue; // 已在册（下载中或已解码）⇒ ⛔ 发第二遍
+                    if (!url || this._dead.has(url)) continue;
+                    if (this._texs.has(url)) continue;
                     this._loadTile(url);
                     inflight++;
                     if (--budget <= 0 || inflight >= PANO_STITCH_MAX_INFLIGHT || decoded >= PANO_STITCH_MAX_DECODED_AHEAD) return;
@@ -419,20 +448,20 @@ private _uploadQueued: Set<TileRec> = new Set();
     private _drawPass(renderer: WebGLRenderer): void {
         for (const g of this._groups.values()) {
             if (g.pending <= 0) continue;
-            for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
-                if (g.drawnCount[slot] >= RT_STITCH_CELLS_PER_SLOT) continue;
-                const ids = RT_STITCH_SLOT_TILES[slot];
-                for (let cell = 0; cell < RT_STITCH_CELLS_PER_SLOT; cell++) {
+            for (let slot = 0; slot < g.layout.slotCount; slot++) {
+                if (g.drawnCount[slot] >= g.cellsPerSlot) continue;
+                const ids = g.slotTiles[slot];
+                for (let cell = 0; cell < g.cellsPerSlot; cell++) {
                     if (g.drawn[slot] & (1 << cell)) continue;
                     const url = g.urls[ids[cell]];
                     if (!url || this._dead.has(url)) {
-                        this._stitchCell(renderer, g, slot, cell, null); // 缺格：涂灰，不占任何预算
+                        this._stitchCell(renderer, g, slot, cell, null);
                         continue;
                     }
                     const rec = this._texs.get(url);
-                    if (!rec || !rec.tex || !rec.uploaded) continue; // 还没上 GPU：等下一帧（工序 3 会排它）
+                    if (!rec || !rec.tex || !rec.uploaded) continue;
                     this._stitchCell(renderer, g, slot, cell, rec.tex);
-                    this._dropTile(url); // 一格只用这一片 ⇒ 画完即弃（显存峰值 = 一格）
+                    this._dropTile(url);
                 }
             }
         }
@@ -456,27 +485,22 @@ private _uploadQueued: Set<TileRec> = new Set();
      *      与 `_drawPass` 天然错开（上传与绘制不落同一拍，正是 09-29「两个大头别在同一帧」的延续）。
      */
     private _uploadPass(renderer: WebGLRenderer): void {
-        // ⛔⛔ 队列里已有待上传项 ⇒ **本次直接不排**。
-        //   这一句是本改法的关键闸门：若只靠下面 `has(rec)` 跳过「同一片」，遍历会**继续往下找下一片**
-        //   于是 pump 几次就把多张全排进队列（13 全景 × 32 片 = 416 项 ⇒ workList 膨胀、`includes` 退化成 O(n)、
-        //   队尾那张要等几百帧才传完）。先判「队列非空就收手」⇒ 队列恒 ≤2 项（一占位+一真活），延迟最低。
         if (this._uploadQueued.size > 0) return;
         for (const g of this._groups.values()) {
             if (g.pending <= 0) continue;
-            for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
-                const ids = RT_STITCH_SLOT_TILES[slot];
-                for (let cell = 0; cell < RT_STITCH_CELLS_PER_SLOT; cell++) {
+            for (let slot = 0; slot < g.layout.slotCount; slot++) {
+                const ids = g.slotTiles[slot];
+                for (let cell = 0; cell < g.cellsPerSlot; cell++) {
                     if (g.drawn[slot] & (1 << cell)) continue;
                     const url = g.urls[ids[cell]];
                     if (!url || this._dead.has(url)) continue;
                     const rec = this._texs.get(url);
                     if (!rec || !rec.tex || rec.uploaded) continue;
-                    // ⛔ 已在队列里 ⇒ 跳过（`addWork` 按引用判重对「新闭包」无效 ⇒ 必须自备 Set，见 `_uploadQueued`）
                     if (this._uploadQueued.has(rec)) continue;
                     this._uploadQueued.add(rec);
-                    threeUtils.addWork(() => {}); // 占一格（什么都不干），把真活推到下一个 tick
+                    threeUtils.addWork(() => {});
                     threeUtils.addWork(() => this._uploadTile(rec));
-                    return; // ⛔ 本次 pump 只排一张：其余名额留给下一帧的队列，绝不在这一帧再排第二张
+                    return;
                 }
             }
         }
@@ -493,8 +517,9 @@ private _uploadQueued: Set<TileRec> = new Set();
         if (!renderer || !rec.tex) return;
         try {
             renderer.initTexture(rec.tex);
-        } catch (e) {
-            console.warn("[PanoTileStitcher] 瓦片预上传失败，交给绘制那一帧自己上传：", e);
+        } catch {
+            // 皇上旨 2026-10-12「日志都去掉」⇒ 不再出声；下面照记 `uploaded = true`，
+            // 最坏退回绘制那一帧自己上传。
         }
         rec.uploaded = true;
         this._stamp++;
@@ -502,24 +527,26 @@ private _uploadQueued: Set<TileRec> = new Set();
 
     // ───────────────────────── 内部：单格绘制 ─────────────────────────
 
-    /** 画一格：把那片瓦片的**中间那块**铺进该槽第 `cell` 格（16 格里的一格）。
-     *  ⚠️⚠️ `autoClear` 必须关掉：three 每次 `render()` 默认清屏，而这里**同一张 RT 要连画 16 帧**，
+    /** 画一格：把那片瓦片的**中间那块**铺进该槽第 `cell` 格（每槽 `slotCellCols × slotCellRows` 格里的一格，
+     *  10-23 旨后全景是「横 1 × 竖 3」= 3 格、图片平面是 2×2 = 4 格）。
+     *  ⚠️⚠️ `autoClear` 必须关掉：three 每次 `render()` 默认清屏，而这里**同一张 RT 要连画 cellsPerSlot 帧**，
      *     清一次就把前面画好的格子抹了 ⇒ 槽纹理只剩最后一格。清屏交给我们自己（见 `_clearRt`）。 */
     private _stitchCell(renderer: WebGLRenderer, g: StitchGroup, slot: number, cell: number, tex: Texture | null): void {
         const rt = this._ensureRt(renderer, g, slot);
-        const tileIdx = RT_STITCH_SLOT_TILES[slot][cell];
-        const [cc, rr] = rtStitchCellPos(cell);
-        // 正交相机铺满 [-1,1]²：quad 缩到 1/4 ⇒ 占一格；`rtStitchCellPos` 是**图像方向**的 [列, 行]，
-        // GL 的 y 向上 ⇒ 图像第一行落在 RT 的上半（v=1），故 y 取反。
-        this._quad.scale.set(1 / RT_STITCH_SLOT_GRID, 1 / RT_STITCH_SLOT_GRID, 1);
+        const tileIdx = g.slotTiles[slot][cell];
+        const [cc, rr] = rtStitchCellPos(cell, g.layout.slotCellCols);
+        // ⚠️ 横竖**分轴**缩放/摆位（旧的单一 `slotGrid` 方形假设整条作废）：10-23 旨一槽 = 原图一整列 ⇒ 1 横 3 竖
+        const cw = g.layout.slotCellCols;
+        const ch = g.layout.slotCellRows;
+        this._quad.scale.set(1 / cw, 1 / ch, 1);
         this._quad.position.set(
-            (2 * cc + 1) / RT_STITCH_SLOT_GRID - 1,
-            1 - (2 * rr + 1) / RT_STITCH_SLOT_GRID,
+            (2 * cc + 1) / cw - 1,
+            1 - (2 * rr + 1) / ch,
             0,
         );
         this._mat.uniforms.uMap.value = tex ?? this._blank;
         this._mat.uniforms.uMissing.value = tex ? 0 : 1;
-        const rect = tex ? rtStitchTileInset(tileIdx, texW(tex), texH(tex)) : null;
+        const rect = tex ? rtStitchTileInset(tileIdx, texW(tex), texH(tex), g.layout) : null;
         const uv = this._mat.uniforms.uSrcRect.value as Vector4;
         if (rect) uv.set(rect[0], rect[1], rect[2], rect[3]);
         else uv.set(0, 0, 1, 1);
@@ -527,7 +554,7 @@ private _uploadQueued: Set<TileRec> = new Set();
         g.drawn[slot] |= 1 << cell;
         g.drawnCount[slot]++;
         this._stamp++;
-        if (g.drawnCount[slot] >= RT_STITCH_CELLS_PER_SLOT) g.pending--;
+        if (g.drawnCount[slot] >= g.cellsPerSlot) g.pending--;
         if (g.pending <= 0) this._releaseGroupWanted(g);
     }
 
@@ -627,12 +654,14 @@ private _uploadQueued: Set<TileRec> = new Set();
         this._dead.clear();
     }
 
-    /** 懒建某槽的渲染目标：4096×4096 RGBA8 + sRGB + mipmap，并**立刻整张涂缺失灰**
-     *  （⛔ 未定义像素不许进 shader：`peek()` 现在画过 1 格就交出去）。 */
+    /** 懒建某槽的渲染目标：尺寸取自 `g.layout.rtW/rtH`（全景档 = **4096×6144**，10-23 旨）、RGBA8 + sRGB + mipmap，
+     *  并**立刻整张涂缺失灰**（⛔ 未定义像素不许进 shader：`peek()` 现在画过 1 格就交出去）。
+     *  ⚠️ 6144 这个数受本机 `MAX_TEXTURE_SIZE` / 最大渲染目标尺寸约束（ANGLE/D3D11 的 11_0 是 16384，远超；
+     *     只有老 Intel 集显才可能卡 4096 —— 真建不出来 three 会报 `GL_INVALID_VALUE`，届时墙上整片缺失灰）。 */
     private _ensureRt(renderer: WebGLRenderer, g: StitchGroup, slot: number): WebGLRenderTarget {
         const exist = g.rts[slot];
         if (exist) return exist;
-        const rt = new WebGLRenderTarget(RT_STITCH_SLOT_W, RT_STITCH_SLOT_H, {
+        const rt = new WebGLRenderTarget(g.layout.rtW, g.layout.rtH, {
             wrapS: ClampToEdgeWrapping,
             wrapT: ClampToEdgeWrapping,
             minFilter: LinearMipmapLinearFilter,
@@ -667,7 +696,7 @@ private _uploadQueued: Set<TileRec> = new Set();
 
     /** 释放一组的全部 GPU 资源：2 张 RT + 还没画掉的瓦片纹理 */
     private _dropGroupGpu(g: StitchGroup): void {
-        for (let slot = 0; slot < RT_STITCH_SLOT_COUNT; slot++) {
+        for (let slot = 0; slot < g.layout.slotCount; slot++) {
             const rt = g.rts[slot];
             if (rt) rt.dispose();
             g.rts[slot] = null;

package/PipeMesh/PipeJoint.d.ts

@@ -0,0 +1,22 @@
+import { SphereGeometry } from "three";
+import InstancedChild from "../instanced/InstancedChild";
+/**
+ * 拐角补角球实例：**直径 1** 的单位球（半径 0.5，与直管半径同量级）。
+ *
+ * ⭐ 为什么必须有它：直管是开口圆柱（`CylinderGeometry(0.5, 0.5, 1, 48, 1, true)`），两段斜管
+ *   在拐角处端面是斜的、只有轴线相交 ⇒ 夹角外侧必然露一个楔形缺口。球心压在控制点上、
+ *   缩放 = 直径 ⇒ 球面正好把缺口盖满；球与管同径，共线时完全看不出来。
+ *
+ * 姿态无所谓（球各向同性），所以只写 position / scale，不碰 quaternion —— 比 PipeBend 那套
+ * 三列基向量简单一整个量级，也正是「最简单的方案」想要的。
+ */
+export default class PipeJoint extends InstancedChild {
+    static geometry: SphereGeometry;
+    static material: import("three").MeshStandardMaterial;
+    /** 控制台取证用：对应第几个控制点（由 PipeMesh 容器在 rebuild 时写入） */
+    partIndex: number;
+    constructor();
+    /** 落到某个拐角：球心 + 直径缩放 */
+    applyAt(center: [number, number, number], diameter: number): void;
+    setPartIndex(i: number): void;
+}

package/PipeMesh/PipeJoint.js

@@ -0,0 +1,33 @@
+import { SphereGeometry } from "three";
+import InstancedChild from "../instanced/InstancedChild";
+import { pipeMaterial } from "./pipeMaterial";
+/**
+ * 拐角补角球实例：**直径 1** 的单位球（半径 0.5，与直管半径同量级）。
+ *
+ * ⭐ 为什么必须有它：直管是开口圆柱（`CylinderGeometry(0.5, 0.5, 1, 48, 1, true)`），两段斜管
+ *   在拐角处端面是斜的、只有轴线相交 ⇒ 夹角外侧必然露一个楔形缺口。球心压在控制点上、
+ *   缩放 = 直径 ⇒ 球面正好把缺口盖满；球与管同径，共线时完全看不出来。
+ *
+ * 姿态无所谓（球各向同性），所以只写 position / scale，不碰 quaternion —— 比 PipeBend 那套
+ * 三列基向量简单一整个量级，也正是「最简单的方案」想要的。
+ */
+export default class PipeJoint extends InstancedChild {
+    static geometry = new SphereGeometry(0.5, 32, 16);
+    static material = pipeMaterial;
+    /** 控制台取证用：对应第几个控制点（由 PipeMesh 容器在 rebuild 时写入） */
+    partIndex = -1;
+    constructor() {
+        super();
+        this.type = "PipeJoint";
+        this.name = "PipeJoint";
+    }
+    /** 落到某个拐角：球心 + 直径缩放 */
+    applyAt(center, diameter) {
+        this.position.set(center[0], center[1], center[2]);
+        this.scale.setScalar(diameter);
+    }
+    setPartIndex(i) {
+        this.partIndex = i;
+        this.name = `PipeJoint[${i}]`;
+    }
+}

package/PipeMesh/PipeJoint.ts

@@ -0,0 +1,38 @@
+import { SphereGeometry } from "three";
+import InstancedChild from "../instanced/InstancedChild";
+import { pipeMaterial } from "./pipeMaterial";
+
+/**
+ * 拐角补角球实例：**直径 1** 的单位球（半径 0.5，与直管半径同量级）。
+ *
+ * ⭐ 为什么必须有它：直管是开口圆柱（`CylinderGeometry(0.5, 0.5, 1, 48, 1, true)`），两段斜管
+ *   在拐角处端面是斜的、只有轴线相交 ⇒ 夹角外侧必然露一个楔形缺口。球心压在控制点上、
+ *   缩放 = 直径 ⇒ 球面正好把缺口盖满；球与管同径，共线时完全看不出来。
+ *
+ * 姿态无所谓（球各向同性），所以只写 position / scale，不碰 quaternion —— 比 PipeBend 那套
+ * 三列基向量简单一整个量级，也正是「最简单的方案」想要的。
+ */
+export default class PipeJoint extends InstancedChild {
+    static geometry = new SphereGeometry(0.5, 32, 16);
+    static material = pipeMaterial;
+
+    /** 控制台取证用：对应第几个控制点（由 PipeMesh 容器在 rebuild 时写入） */
+    partIndex: number = -1;
+
+    constructor() {
+        super();
+        (this as { type: string }).type = "PipeJoint";
+        this.name = "PipeJoint";
+    }
+
+    /** 落到某个拐角：球心 + 直径缩放 */
+    applyAt(center: [number, number, number], diameter: number): void {
+        this.position.set(center[0], center[1], center[2]);
+        this.scale.setScalar(diameter);
+    }
+
+    setPartIndex(i: number): void {
+        this.partIndex = i;
+        this.name = `PipeJoint[${i}]`;
+    }
+}

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;
 }