s3m-three 0.4.22 → 0.4.24

package/docs/API.md

@@ -172,10 +172,11 @@ new S3MViewer(options?: S3MViewerOptions)
 | （随 `useWorker`）DXT 压缩直传 | 自动 | 自动 | 宿主 GL 同时支持 `WEBGL_compressed_texture_s3tc`(+srgb) 时，dxt1/dxt5（含 CRN 转码产物）不解码直接 `CompressedTexture` 上传，显存与上传带宽降为 1/4~1/8；块长与 4×4 对齐公式不符、flipY 图集、移动端无扩展时自动回退 RGBA 解码 |
 | `lodRangeScale` | `number` | `1.0` | LOD 切换距离缩放系数，> 1 更倾向保留粗模，< 1 提前细化 |
 | `lodPixelRatioCap` | `number` | `Infinity` | LOD 判定屏幕高度的 **DPR 上限**（不截断）。默认按 `canvasHeight` 物理像素算，与官方 `calcPixFromCam` 同口径；3x DPR 手机上由此会多细化、多拉瓦片，传 `2` 即按「CSS 高度 × 2」截断 |
-| `anisotropyCap` | `number` | `Infinity` | 各向异性过滤上限（不封顶 = 取 GPU 最大值，通常 16）。移动端封到 4 / 8 肉眼通常无差，采样成本明显下降。只影响之后创建的纹理 |
-| `maxTextureSize` | `number` | `Infinity` | 纹理长边像素上限（不限制）。非图集的 RGBA / WebP 产物按 2× 盒式滤波减半到上限内；DXT 压缩直传与图集不受影响 |
+| `anisotropyCap` | `number` | `Infinity` | 各向异性过滤上限（不封顶 = 取 GPU 最大值，通常 16）。移动端封到 4 / 8 肉眼通常无差，采样成本明显下降。**图层级**：运行时 `setAnisotropyCap()` 会立刻应用到已上传纹理（改采样参数 + 重传，不重解码、不重载瓦片），图集纹理恒为 1 |
+| `maxTextureSize` | `number` | `Infinity` | 纹理长边像素上限（不限制）。非图集的 RGBA / WebP 产物按 2× 盒式滤波减半到上限内；DXT 压缩直传与图集不受影响。**图层级**，但只影响之后解码的纹理（已解码的不重解） |
 | `maxImageCache` | `number` | `128` | 纹理缓存条数上限。一条 = 一张已解码的瓦片纹理，1024² RGBA 约 4MB，128 条即约 512MB 显存；低端设备 32~48。LRU，降下来下次淘汰时释放 |
 | `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。**图层级**：同页多个图层各用各的，互不覆盖；不传则跟随模块级默认（`setMaterialQuality`）。只影响之后创建的材质 |
+| `colorPipeline` | `'linear' \| 'direct'` | `'linear'` | 颜色管线。`direct` = 官方 iClient3D 的 sRGB 直乘（同时关掉纹理解码），`lightingPreset: 'supermap'` 会选它。**图层级**：同页多图层各用各的；已加载瓦片可运行时 `setColorPipeline(q, { duration })` 走 fade-through 平滑切过去（重建材质 + 重传纹理，不重下瓦片） |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 可选的 iServer 数据服务配置，配了才能用 `colorByField()` 等便利方法；不配就自己取数 + `setFeaturesStyle()`，见[业务字段](#业务字段锚点在库内对应关系在外部) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
@@ -311,10 +312,30 @@ await viewer.setEnvironment('/env/city_2k.hdr', 1.0); // 等距柱状图（2:1
 - **不传 = 不覆盖**（内部用 `-1` 当哨兵），保持数据自身的口径：`metalness` 恒 0，
   `roughness` 由 S3M 的 `shininess` 映射（常见 0.95）。
 - 只有 `materialQuality: 'pbr'`（默认）支持；`'lambert'` 模板里没有这两个 chunk，注入是 no-op。
+- **图层级**：两个 uniform 是每个 viewer 自己的一份，同页多个图层互不影响。
+- 过渡起点取数据侧常见值（`roughness` ≈ 0.95、`metalness` = 0），不是 0 —— 否则
+  `setStyle({ roughness: 0.2 }, { duration })` 会先跳到 0 再爬回来。
 - ⚠️ 金属几乎没有漫反射，**没有环境贴图时 `metalness` 一高就整片发黑**，只剩平行光的
   高光点。先 `setEnvironment()` 挂一张等距柱状图（内部会转成 PMREM 预滤波），
   强度由 `scene.environmentIntensity` 控制。
 
+### 颜色管线（`linear` / `direct`）与过渡
+
+```ts
+new S3MLayer({ colorPipeline: 'direct' });          // 建图层时定档（图层级）
+await layer.setColorPipeline('direct', { duration: 400 });  // 运行时平滑切
+```
+
+- `'direct'` = 官方 iClient3D 的 sRGB 直乘管线（贴图字节值不解码 → 常数 Lambert 直乘
+  → 输出前抵消 OETF），`lightingPreset: 'supermap'` 会同时选它并把各向异性收回 1。
+- 切换牵扯三样东西：材质宏（换 program）、纹理 `colorSpace`（重传）、各向异性档位。
+  **都不需要重新下载瓦片** —— 改完 `needsUpdate` 重传一次像素即可。
+- `duration > 0` 走 fade-through：压暗（`uFade` 到 0.35）→ 同一帧里换管线 → 亮回来。
+  不做逐像素混合：两条管线的差异有一部分在采样端（硬件 sRGB 解码 vs 原始字节），
+  要混合就得让贴图恒为原始字节并在片元里手动解码，那会改掉默认路径的采样数学。
+- 同页多个图层各持自己的管线，`setColorPipeline` 只影响本层。
+- `setAnisotropyCap()` 同样即时生效（改采样参数 + 重传），不再"只影响之后创建的纹理"。
+
 ### 单体样式与状态
 
 ```ts
@@ -389,6 +410,106 @@ getFeatureBounds(smid: number): [[number, number], [number, number]] | null
 
 拾取走 GPU：把「物体编号 + batchId」编码成 RGBA 渲染到 **1×1** 离屏目标再读那一个像素——viewport 仍是整块画布、原点平移到点击点，于是整幅画面按原样光栅化，只有点击点那一格落在目标上。代价与三角面数无关，且天然只命中最前面的可见面。
 
+### 三维空间分析（量算 / 通视 / 裁剪）
+
+```ts
+measureDistance(a: LngLatAlt, b: LngLatAlt): { distance3D; distanceHorizontal; heightDiff }
+measurePolyline(points: LngLatAlt[]): { length3D; lengthHorizontal }
+measurePolygon(points: LngLatAlt[]): { area3D; areaHorizontal; perimeter }
+
+lineOfSight(a: LngLatAlt, b: LngLatAlt, opts?): {
+  visible: boolean; distance: number; blockedDistance: number | null;
+  blockedPoint: [number, number, number] | null; visibleRatio: number;
+}
+
+setClipping(opt: ClipOptions | null): void      // 平面 / Box / 十字
+readonly clipping: ClipOptions | null
+
+skyline(opts?: { width?; height?; step? }): SkylineResult | null
+viewshed(opts: { origin: LngLatAlt; radius: number; grid?; eyeHeight?; size? }): ViewshedResult | null
+```
+
+- 入参是**经纬度 + 绝对高程**，直接用 `pickPosition(x, y)` 的返回值；交互（取点、拖拽、标签、撤销）属于应用层，不进库。
+- 纯数学部分（距离 / 面积 / 通视判定 / 半空间生成）导出在 `s3m-three` 根上，**不依赖 WebGL**，可以在 Worker 或服务端复用。
+- 面积有两套口径：`area3D` 是坡面真实面积（Newell 法），`areaHorizontal` 是水平投影（鞋带公式）。建筑面积、用地面积按后者。
+- `lineOfSight` 走 CPU 射线求交（`Raycaster` 打全部 pickable mesh），几十万面是几十毫秒量级，适合点击式查询；要拖拽时逐帧刷新得等深度图批量采样版本。
+- 裁剪是**图层级**的（每个 `S3MLayer` 一个 `WebGLRenderer`，平面挂在它的 `clippingPlanes` 上），同页其它图层不受影响。传 `null` 取消。
+- **两个已知边界**：① 只做「切掉」不做**封口**，剖开后看到的是空壳/背面；② 半空间求交只能表达凸区域，凹多边形裁剪需要多组并集，three 的 `clippingPlanes` 表达不了。
+- **分析范围只包含 S3M 场景里的几何**：MapLibre 底图地形与 MVT 建筑不在这个场景里，不参与遮挡判断。
+
+**天际线 / 360° 可视域**（P1）走的是「一次离屏深度 pass + CPU 归约」：
+
+- `skyline()`：用当前视角渲染一张 `RGBADepthPacking` 深度图，按列取最上面的几何像素，
+  反投影成（方位角, 仰角）。一次调用 = 一趟额外渲染 + 一次全图回读，**不要每帧调**，
+  相机停下后算一次。精度由 `width` 决定（640 宽 ≈ 0.56°/列）。
+- 结果里除了角度，还有 `screen`（每列天际线像素的**归一化屏幕坐标** `[x0,y0,x1,y1,…]`）
+  和 `hasGeometry`（纯天空列）。要在**地图上描天际线**，直接用这两个：
+  深度图本来就是屏幕空间的产物，换算成角度只为读数，画线再投影一次反而多一层误差。
+  `hasGeometry = 0` 的列必须断开，否则线会横穿天空掉到画面底部。
+- 天际线绑定位姿：镜头一动就作废，应用层要在 `movestart` 清掉、`moveend` 按需重算。
+- `viewshed()`：从观察点朝 6 个方向各渲染一次「到观察点的距离」，再在 CPU 上对
+  地面网格逐格比较，返回 `raster`（1 可见 / 0 遮挡 / -1 无效）。一次调用 = 6 趟渲染 + 6 次回读，
+  成本明显更高，只在点击/松手时算。
+- 两者都**不做建筑立面逐像素着色**（那要把立方体深度注入每种材质的 shader）。
+- 已知限制：`overrideMaterial` 换材质时**实例化网格（点云/树木）不参与遮挡**。
+
+#### 分析范围：只含 S3M 场景，底图内容要外围自己补
+
+`skyline()` / `viewshed()` / `lineOfSight()` 都只看 **S3M 场景里的几何**：
+
+- MapLibre 的 `fill-extrusion` 建筑、terrain 地形不在 three 场景里，**不参与遮挡**；
+- raster 底图本来就没有高度，没什么可参与；
+- 也**读不到** MapLibre 的深度：自定义图层画在主 framebuffer 里，帧内拿不出来；而深度 pass 用的是自己的 FBO + `overrideMaterial`，两套深度不共享。
+
+要「整座城市的天际线」，只能**复制一份几何**进来。这一步属于外围，库提供两个必要的原语：
+`lngLatToPoint()`（经纬度 → 场景 ENU）和 `include`（只参与这一趟深度渲染的额外几何）。
+
+```ts
+// 1) 从底图矢量源取当前视野的建筑（高度字段各家不同，见下面的坑）
+const feats = map.querySourceFeatures('openmaptiles', { sourceLayer: 'building' });
+
+// 2) 轮廓 → 场景 ENU → 挤出
+const proxy = new THREE.Group();
+for (const f of feats) {
+  const h = Number(f.properties.render_height ?? f.properties.height ?? 0);
+  if (!(h > 0)) continue;
+  const shape = new THREE.Shape(
+    f.geometry.coordinates[0].map(([lng, lat]) => {
+      const p = layer.lngLatToPoint({ lng, lat, altitude: 0 });
+      return new THREE.Vector2(p[0], p[1]);
+    })
+  );
+  proxy.add(new THREE.Mesh(new THREE.ExtrudeGeometry(shape, { depth: h, bevelEnabled: false })));
+}
+
+// 3) 只喂给这一趟深度渲染：不进主渲染，不会和 MapLibre 重复画
+const r = layer.skyline({ width: 1280, height: 720, include: [proxy] });
+```
+
+`include` 的语义：对象在采集期间临时挂进 viewer 场景，采集完立刻摘掉
+（已经有 parent 的会被跳过）。`viewshed()` 同样支持这个参数。
+
+**三个坑**：
+
+1. **高度字段口径不统一** —— `render_height`（OpenMapTiles）/ `height`（OSM 原始）/ `building:levels × 3`，
+   要和底图样式里 `fill-extrusion-height` 的表达式保持一致，否则会出现「分析里有一栋、画面上没有」。
+2. **要素会重复** —— `querySourceFeatures` 返回当前视野内所有已加载瓦片的要素，跨瓦片边界的建筑会出现多次，
+   需要按 id 或几何去重，否则代理几何叠在一起（对天际线无害，对统计有害）。
+3. **代理 ≠ 画面** —— 底图如果用了 `fill-extrusion-height` 插值或 terrain 抬升，代理和实际渲染会有偏差；
+   要完全一致，就得让底图建筑也由自己渲染，那已经超出「分析」的范围了。
+
+`demo/analysis.html` 里有可运行的例子：「含底图天际线」（只喂分析）+「显示代理」（把代理塞进画面看效果）。
+
+```ts
+type ClipOptions =
+  | { type: 'plane'; normal: [number, number, number]; point: [number, number, number] }
+  | { type: 'box'; a: [number, number, number]; b: [number, number, number] }
+  | { type: 'cross'; center: [number, number, number]; keepX: 1 | -1; keepY: 1 | -1;
+      horizontal?: boolean; keepZ?: 1 | -1 };
+```
+
+法线一律指向**保留侧**（与 three 的 `Plane` 口径一致：`normal·p + constant >= 0` 保留）。
+
 ### LOD 与统计
 
 ```ts
@@ -400,7 +521,7 @@ setMaxTriangles(n: number, datasetId?: string): void   // Infinity = 不限制
 readonly maxTriangles: number
 setMaxMemory(bytes: number, datasetId?: string): void  // 显存字节上限，Infinity = 不限制（默认）
 readonly maxMemory: number
-setAnisotropyCap(cap: number): void           // Infinity = 取 GPU 最大值（默认）
+setAnisotropyCap(cap: number): void           // Infinity = 取 GPU 最大值（默认）；即时应用到已上传纹理
 readonly anisotropyCap: number
 setMaxTextureSize(n: number): void            // Infinity = 不限制（默认）
 readonly maxTextureSize: number

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {

package/src/analysis/clipping.ts

@@ -0,0 +1,135 @@
+/**
+ * 裁剪 / 剖切的纯数学部分：把「平面 / Box / 十字」三种交互输入翻译成一组半空间。
+ *
+ * 与 three 的 `THREE.Plane` 同构（`normal` 单位化，`constant = -normal·point`），
+ * 判据是 three 的口径：`normal·p + constant >= 0` 的片元**保留**，否则丢弃。
+ * 所以这里的法线一律朝「保留侧」。
+ *
+ * 不依赖 three，`S3MViewer.setClipping` 再把结果转成 `THREE.Plane` 挂到
+ * `renderer.clippingPlanes`（每个图层一个 renderer，天然图层级）。
+ *
+ * 已知边界：
+ * - 半空间求交只能表达**凸**区域，凹多边形要多组并集（three 的 clippingPlanes
+ *   是「全部满足才保留」，做不到并集），见 `docs/API.md` 的说明；
+ * - 不做封口：剖切后看到的是背面/空壳，封口要靠 stencil 或背面重绘，不在这一层。
+ */
+import type { Vec3 } from './measure.js';
+
+/** 与 `THREE.Plane` 同构：`normal` 必须单位化 */
+export interface PlaneLike {
+  normal: Vec3;
+  constant: number;
+}
+
+function normalize(v: Vec3): Vec3 {
+  const len = Math.hypot(v[0], v[1], v[2]);
+  if (len < 1e-9) return [0, 0, 1];
+  return [v[0] / len, v[1] / len, v[2] / len];
+}
+
+function dot(a: Vec3, b: Vec3): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+/** 过一个点、法线指向**保留侧**的平面 */
+export function planeFromPointNormal(normal: Vec3, point: Vec3): PlaneLike {
+  const n = normalize(normal);
+  return { normal: n, constant: -dot(n, point) };
+}
+
+/** 点是否在保留侧（含边界）；用于调试与单测 */
+export function isPointKept(planes: readonly PlaneLike[], p: Vec3): boolean {
+  for (const pl of planes) {
+    if (dot(pl.normal, p) + pl.constant < 0) return false;
+  }
+  return true;
+}
+
+/* ------------------------------------------------------------------ 输入形态 */
+
+/** 平面裁剪：法线指向保留的一侧，切掉另一侧 */
+export interface ClipPlaneOptions {
+  type: 'plane';
+  /** 指向保留侧的法线（不必单位化） */
+  normal: Vec3;
+  /** 平面过的一个点 */
+  point: Vec3;
+}
+
+/** Box 裁剪：保留盒内的部分 */
+export interface ClipBoxOptions {
+  type: 'box';
+  /** 对角点（顺序无所谓，内部会取 min/max） */
+  a: Vec3;
+  b: Vec3;
+}
+
+/**
+ * 十字剖切：用两个竖直面切掉一个象限，露出两个互相垂直的剖面。
+ *
+ * `keepX` / `keepY` 指保留哪个方向：`1` 保留 +x 侧，`-1` 保留 -x 侧。
+ * 加 `horizontal: true` 再多一个水平面，变成「切掉一个角」的三面剖切。
+ */
+export interface ClipCrossOptions {
+  type: 'cross';
+  center: Vec3;
+  keepX: 1 | -1;
+  keepY: 1 | -1;
+  /** 是否再叠一个水平面（在 center.z 处切掉上方），默认 false */
+  horizontal?: boolean;
+  /** 水平面保留哪一侧：`1` 保留上方，`-1` 保留下方，默认 -1 */
+  keepZ?: 1 | -1;
+}
+
+export type ClipOptions = ClipPlaneOptions | ClipBoxOptions | ClipCrossOptions;
+
+/* ------------------------------------------------------------------ 生成 */
+
+export function planeClipping(opt: Omit<ClipPlaneOptions, 'type'>): PlaneLike[] {
+  return [planeFromPointNormal(opt.normal, opt.point)];
+}
+
+export function boxClipping(opt: Omit<ClipBoxOptions, 'type'>): PlaneLike[] {
+  const min: Vec3 = [
+    Math.min(opt.a[0], opt.b[0]),
+    Math.min(opt.a[1], opt.b[1]),
+    Math.min(opt.a[2], opt.b[2]),
+  ];
+  const max: Vec3 = [
+    Math.max(opt.a[0], opt.b[0]),
+    Math.max(opt.a[1], opt.b[1]),
+    Math.max(opt.a[2], opt.b[2]),
+  ];
+  // 六个面，法线一律朝盒内 —— 六个半空间求交就是「盒内」
+  return [
+    { normal: [1, 0, 0], constant: -min[0] },
+    { normal: [-1, 0, 0], constant: max[0] },
+    { normal: [0, 1, 0], constant: -min[1] },
+    { normal: [0, -1, 0], constant: max[1] },
+    { normal: [0, 0, 1], constant: -min[2] },
+    { normal: [0, 0, -1], constant: max[2] },
+  ];
+}
+
+export function crossClipping(opt: Omit<ClipCrossOptions, 'type'>): PlaneLike[] {
+  const planes: PlaneLike[] = [
+    planeFromPointNormal([opt.keepX, 0, 0], opt.center),
+    planeFromPointNormal([0, opt.keepY, 0], opt.center),
+  ];
+  if (opt.horizontal) {
+    planes.push(planeFromPointNormal([0, 0, opt.keepZ ?? -1], opt.center));
+  }
+  return planes;
+}
+
+/** 统一入口：把交互输入翻成半空间列表 */
+export function buildClipPlanes(opt: ClipOptions): PlaneLike[] {
+  switch (opt.type) {
+    case 'plane':
+      return planeClipping(opt);
+    case 'box':
+      return boxClipping(opt);
+    case 'cross':
+      return crossClipping(opt);
+  }
+}

package/src/analysis/depth.ts

@@ -0,0 +1,126 @@
+/**
+ * 深度图回读的数学部分：解包 + 反投影。
+ *
+ * GPU 那边只能把深度渲染成 RGBA8（three 的 `RGBADepthPacking`），
+ * 回读到 CPU 后要还原成 0~1 的窗口深度，再反投影成世界坐标 —— 这两步都在这里，
+ * 与 WebGL 无关，可以用构造出来的矩阵直接单测。
+ *
+ * 打包/解包的常数照抄 three 的 `packing.glsl.js`，不要自己改：
+ * 改一个常数，回读出来的深度就会整体偏移，而画面看起来完全正常。
+ */
+import type { Vec3 } from './measure.js';
+
+/** three: `PackUpscale = 256 / 255` */
+const PACK_UPSCALE = 256 / 255;
+/** three: `UnpackDownscale = 255 / 256` */
+const UNPACK_DOWNSCALE = 255 / 256;
+/** three: `ShiftRight8 = 1 / 256` */
+const SHIFT_RIGHT_8 = 1 / 256;
+/** three: `PackFactors = (1, 256, 65536, 16777216)` */
+const PACK_FACTOR_A = 16777216;
+
+/**
+ * 把 0~1 的深度按 three 的 `RGBADepthPacking` 打包成 4 个字节（0~255）。
+ *
+ * 严格照抄 `packing.glsl.js` 的 `packDepthToRGBA`，**不要凭直觉改**：
+ * - `v <= 0` 返回全黑、`v >= 1` 返回**全白**（这两条特判是精度链条的一部分，
+ *   也正好让「远平面」和「清屏白」解包出来都是 1.0，背景判定因此简单）；
+ * - 中间值是 `modf` 链拆出来的 32 位定点，通道顺序是 (粗 → 细) 的 r/g/b/a。
+ *
+ * 精度：解包误差约 1e-5（受 g 通道 8 位量化限制），换算成 141m 处的位置误差约 0.2m。
+ */
+export function packRGBADepth(depth: number): [number, number, number, number] {
+  const v = Math.min(1, Math.max(0, depth));
+  if (v <= 0) return [0, 0, 0, 0];
+  if (v >= 1) return [255, 255, 255, 255];
+
+  const af = modf(v * PACK_FACTOR_A);
+  const b = modf(af.int * SHIFT_RIGHT_8);
+  const g = modf(b.int * SHIFT_RIGHT_8);
+
+  const toByte = (x: number): number => Math.max(0, Math.min(255, Math.round(x * 255)));
+  return [
+    // r = floor(v*256)/255 —— 乘回 255 就是整数本身
+    toByte(g.int / 255),
+    toByte(g.frac * PACK_UPSCALE),
+    toByte(b.frac * PACK_UPSCALE),
+    toByte(af.frac),
+  ];
+}
+
+/**
+ * 解包：RGBA 四个字节 → 0~1 的窗口深度（0 = 近平面，1 = 远平面 / 背景）。
+ *
+ * 与 `packing.glsl.js` 的 `unpackRGBAToDepth` 同式：
+ * `dot(rgba, (UnpackDownscale/1, UnpackDownscale/256, UnpackDownscale/65536, 1/2^24))`。
+ *
+ * @param rgba 回读出来的像素缓冲
+ * @param offset 字节偏移（第 i 个像素就是 i*4）
+ */
+export function unpackRGBADepth(rgba: ArrayLike<number>, offset = 0): number {
+  const r = rgba[offset]! / 255;
+  const g = rgba[offset + 1]! / 255;
+  const b = rgba[offset + 2]! / 255;
+  const a = rgba[offset + 3]! / 255;
+  return (
+    r * UNPACK_DOWNSCALE +
+    g * (UNPACK_DOWNSCALE / 256) +
+    b * (UNPACK_DOWNSCALE / 65536) +
+    a / PACK_FACTOR_A
+  );
+}
+
+/** GLSL `modf`：返回小数部分，整数部分写进 `int` */
+function modf(x: number): { frac: number; int: number } {
+  const int = Math.floor(x);
+  return { frac: x - int, int };
+}
+
+/**
+ * NDC + 窗口深度 → 世界坐标。
+ *
+ * @param ndcX -1~1（屏幕左侧到右侧）
+ * @param ndcY -1~1（屏幕底部到顶部；注意与像素行号反向）
+ * @param depth01 0~1 的窗口深度
+ * @param inverseViewProj 视图投影矩阵的逆（列主序 16 元，与 `THREE.Matrix4.elements` 同序）
+ */
+export function unprojectNdc(
+  ndcX: number,
+  ndcY: number,
+  depth01: number,
+  inverseViewProj: ArrayLike<number>
+): Vec3 {
+  const z = depth01 * 2 - 1;
+  const m = inverseViewProj;
+  const x = m[0]! * ndcX + m[4]! * ndcY + m[8]! * z + m[12]!;
+  const y = m[1]! * ndcX + m[5]! * ndcY + m[9]! * z + m[13]!;
+  const zz = m[2]! * ndcX + m[6]! * ndcY + m[10]! * z + m[14]!;
+  const w = m[3]! * ndcX + m[7]! * ndcY + m[11]! * z + m[15]!;
+  const iw = Math.abs(w) > 1e-12 ? 1 / w : 1;
+  return [x * iw, y * iw, zz * iw];
+}
+
+/** 像素坐标（左上角为 0,0）→ NDC */
+export function pixelToNdc(px: number, py: number, width: number, height: number): [number, number] {
+  return [((px + 0.5) / width) * 2 - 1, 1 - ((py + 0.5) / height) * 2];
+}
+
+/**
+ * 把「观察点 → 目标点」拆成方位角 / 仰角（度）。
+ *
+ * 方位角：0 = 正北，顺时针增大（与地图 bearing 一致），ENU 下 x 向东、y 向北。
+ * 仰角：0 = 水平，正值向上，负值向下。
+ */
+export function azimuthElevation(
+  from: Vec3,
+  to: Vec3
+): { azimuth: number; elevation: number; distance: number } {
+  const dx = to[0] - from[0];
+  const dy = to[1] - from[1];
+  const dz = to[2] - from[2];
+  const horizontal = Math.hypot(dx, dy);
+  const distance = Math.hypot(horizontal, dz);
+  const azimuth = ((Math.atan2(dx, dy) * 180) / Math.PI + 360) % 360;
+  const elevation = (Math.atan2(dz, horizontal) * 180) / Math.PI;
+  return { azimuth, elevation, distance };
+}

package/src/analysis/index.ts

@@ -0,0 +1,47 @@
+/**
+ * 三维空间分析内核（宿主无关、不依赖 WebGL）。
+ *
+ * 分工：
+ * - 本目录只做**纯数学**：量算、通视判定、裁剪半空间生成。可以直接单测。
+ * - 需要 GPU 的部分（贴地采样、天际线、可视域、阴影）在 `render/` 下，
+ *   复用 `Picker` 的离屏 pass 与状态恢复。
+ * - 交互（取点、拖拽、标签绘制）属于应用层，不进这个包。
+ */
+export {
+  distance3D,
+  distanceHorizontal,
+  heightDifference,
+  polylineLength,
+  polylineLengthHorizontal,
+  polygonPerimeter,
+  polygonArea,
+  polygonAreaHorizontal,
+  measureSegment,
+} from './measure.js';
+export type { Vec3, LngLatAlt, MeasureResult } from './measure.js';
+
+export { lineOfSight } from './lineOfSight.js';
+export type { RayHit, RayCast, LineOfSightOptions, LineOfSightResult } from './lineOfSight.js';
+
+export {
+  planeFromPointNormal,
+  isPointKept,
+  planeClipping,
+  boxClipping,
+  crossClipping,
+  buildClipPlanes,
+} from './clipping.js';
+export type {
+  PlaneLike,
+  ClipPlaneOptions,
+  ClipBoxOptions,
+  ClipCrossOptions,
+  ClipOptions,
+} from './clipping.js';
+
+/* 深度图回读（P1：天际线 / 可视域的数学部分，GL 在 render/analysis/DepthPass） */
+export { packRGBADepth, unpackRGBADepth, unprojectNdc, pixelToNdc, azimuthElevation } from './depth.js';
+export { skylineFromDepth } from './skyline.js';
+export type { SkylineArgs, SkylineResult } from './skyline.js';
+export { computeViewshed, makeCubeDistanceSampler } from './viewshed.js';
+export type { ViewshedOptions, ViewshedResult } from './viewshed.js';

package/src/analysis/lineOfSight.ts

@@ -0,0 +1,110 @@
+/**
+ * 通视分析（单条视线）。
+ *
+ * 求交本体由调用方注入 —— 内核只负责「沿视线找第一个遮挡、算可见比例」，
+ * 这样不依赖 three，也能在单测里用解析几何伪造求交结果。
+ *
+ * 场景里实际用的求交是 `THREE.Raycaster` 打全部 pickable mesh（与
+ * `PickService.drillPick` 同一条路径），由 `S3MViewer.lineOfSight` 装配。
+ */
+import { distance3D, type Vec3 } from './measure.js';
+
+/** 一次射线求交的结果：只关心「最近的交点距离」 */
+export interface RayHit {
+  /** 沿射线的距离（米） */
+  distance: number;
+  /** 交点位置（可选，用于画遮挡点标记） */
+  point?: Vec3;
+}
+
+/**
+ * 射线求交函数。
+ *
+ * @param origin 起点（场景 ENU 米）
+ * @param dir 单位方向
+ * @param maxDistance 只关心这个距离内的交点，超出可以返回 null（实现可据此提前剪枝）
+ */
+export type RayCast = (origin: Vec3, dir: Vec3, maxDistance: number) => RayHit | null;
+
+export interface LineOfSightOptions {
+  /**
+   * 起点外推距离（米，默认 0.05）。
+   *
+   * 从建筑表面起步时，起点就落在三角面上，浮点误差会让射线立刻打中自己所在的
+   * 那个三角面，于是「永远不可见」。沿视线方向先推一小段再求交即可避开。
+   */
+  originOffset?: number;
+  /**
+   * 终点内缩距离（米，默认 0.05）。同理：终点若贴在目标表面，不要把目标自身
+   * 当成遮挡物。
+   */
+  targetOffset?: number;
+}
+
+export interface LineOfSightResult {
+  /** 起终点之间是否通视 */
+  visible: boolean;
+  /** 起点到终点的直线距离（米） */
+  distance: number;
+  /** 第一个遮挡点距起点的距离（米）；通视时为 null */
+  blockedDistance: number | null;
+  /** 第一个遮挡点的位置；通视时为 null */
+  blockedPoint: Vec3 | null;
+  /** 可见段占全长的比例（0~1，1 = 完全通视）—— 直接用来画「绿段 / 红段」 */
+  visibleRatio: number;
+}
+
+/**
+ * 计算两点之间的通视情况。
+ *
+ * @param from 起点（场景 ENU 米）
+ * @param to 终点
+ * @param cast 射线求交函数
+ */
+export function lineOfSight(
+  from: Vec3,
+  to: Vec3,
+  cast: RayCast,
+  opts: LineOfSightOptions = {}
+): LineOfSightResult {
+  const total = distance3D(from, to);
+  if (total <= 1e-6) {
+    return { visible: true, distance: 0, blockedDistance: null, blockedPoint: null, visibleRatio: 1 };
+  }
+
+  const dir: Vec3 = [
+    (to[0] - from[0]) / total,
+    (to[1] - from[1]) / total,
+    (to[2] - from[2]) / total,
+  ];
+
+  const startOffset = Math.max(0, opts.originOffset ?? 0.05);
+  const endOffset = Math.max(0, opts.targetOffset ?? 0.05);
+  // 两端各缩一点；太短的视线就不缩了，免得区间翻负
+  const shrink = Math.min(startOffset + endOffset, total * 0.5);
+  const origin: Vec3 = [
+    from[0] + dir[0] * startOffset,
+    from[1] + dir[1] * startOffset,
+    from[2] + dir[2] * startOffset,
+  ];
+  const limit = Math.max(0, total - shrink);
+
+  const hit = cast(origin, dir, limit);
+  if (hit && hit.distance < limit) {
+    // 距离要把起点外推量加回去，才是「从真实起点算起」
+    const blockedDistance = Math.min(total, hit.distance + startOffset);
+    return {
+      visible: false,
+      distance: total,
+      blockedDistance,
+      blockedPoint: hit.point ?? [
+        from[0] + dir[0] * blockedDistance,
+        from[1] + dir[1] * blockedDistance,
+        from[2] + dir[2] * blockedDistance,
+      ],
+      visibleRatio: Math.max(0, Math.min(1, blockedDistance / total)),
+    };
+  }
+
+  return { visible: true, distance: total, blockedDistance: null, blockedPoint: null, visibleRatio: 1 };
+}