s3m-three 0.4.23 → 0.4.25

package/src/analysis/skyline.ts

@@ -0,0 +1,125 @@
+/**
+ * 天际线：从一张「从相机看出去」的深度图，按列抽出天际线曲线。
+ *
+ * 为什么是「按列」：天际线在屏幕上就是每列最上面那个几何像素的轮廓。
+ * 所以不需要额外的几何体 —— 一次深度 pass + 一次逐列扫描就够了，
+ * 结果直接是一串（方位角，仰角），画成 2D 曲线比生成 3D 多边形便宜得多。
+ *
+ * 只做数学，不碰 WebGL：深度图由 `render/analysis/DepthPass` 产出。
+ */
+import { azimuthElevation, pixelToNdc, unpackRGBADepth, unprojectNdc } from './depth.js';
+import type { Vec3 } from './measure.js';
+
+export interface SkylineArgs {
+  /** RGBA8 深度图（three 的 RGBADepthPacking） */
+  rgba: ArrayLike<number>;
+  width: number;
+  height: number;
+  /** 视图投影矩阵的逆（列主序，与 `THREE.Matrix4.elements` 同序） */
+  inverseViewProj: ArrayLike<number>;
+  /** 相机在场景 ENU 里的位置 */
+  cameraPos: Vec3;
+  /**
+   * 背景判定阈值：深度 >= 它的像素视为天空（默认 0.9999）。
+   * 用 0.9999 而不是 1：远处地平线可能因为精度落在 0.99999 上。
+   */
+  skyDepth?: number;
+  /** 每隔多少列取一次（默认 1，即逐列） */
+  step?: number;
+}
+
+export interface SkylineResult {
+  /** 方位角（度，0 = 正北，顺时针），长度 = ceil(width / step) */
+  azimuths: Float32Array;
+  /** 对应列的仰角（度，0 = 水平） */
+  elevations: Float32Array;
+  /** 整条天际线的最大仰角（度） */
+  maxElevation: number;
+  /** 最小仰角（度）；全是天空时为 0 */
+  minElevation: number;
+  /** 没有几何、直通天空的列占比（0~1）—— 开敞度的最粗口径 */
+  openRatio: number;
+  /**
+   * 每列天际线在**屏幕上的位置**（归一化 0~1，左上角为原点），
+   * 布局是 `[x0, y0, x1, y1, …]`，长度 = `cols * 2`。
+   *
+   * 这是画「地图上的天际线」最直接的输入：深度图本来就是屏幕空间的东西，
+   * 换算成角度只是为了给人看，换算回去还会多一次投影误差。
+   * 归一化是为了让调用方按自己的画布尺寸缩放（捕获分辨率可以比画布小）。
+   */
+  screen: Float32Array;
+  /**
+   * 每列是否有几何（1 = 有，0 = 纯天空）。
+   *
+   * 画线时要在这里断开：把纯天空的列也连进去，线会横穿天空，
+   * 看起来像天际线突然掉到画面底部。
+   */
+  hasGeometry: Uint8Array;
+}
+
+/**
+ * 逐列取「最上面的几何像素」，反投影成世界坐标后换算成仰角，
+ * 同时记下该像素的归一化屏幕位置（给「在地图上描线」用）。
+ *
+ * 没有几何的列记 0°（地平线）并计入 `openRatio`，而不是记 -90°：
+ * 天际线曲线在地平线处收口，画图时不会突然掉到画面底部。
+ */
+export function skylineFromDepth(args: SkylineArgs): SkylineResult {
+  const { rgba, width, height, inverseViewProj, cameraPos } = args;
+  const skyDepth = args.skyDepth ?? 0.9999;
+  const step = Math.max(1, Math.floor(args.step ?? 1));
+  const cols = Math.ceil(width / step);
+
+  const azimuths = new Float32Array(cols);
+  const elevations = new Float32Array(cols);
+  const screen = new Float32Array(cols * 2);
+  const hasGeometry = new Uint8Array(cols);
+  let maxElevation = -90;
+  let minElevation = 90;
+  let open = 0;
+
+  for (let c = 0; c < cols; c++) {
+    const x = Math.min(width - 1, c * step);
+    let found = false;
+    for (let y = 0; y < height; y++) {
+      const off = (y * width + x) * 4;
+      const depth = unpackRGBADepth(rgba, off);
+      if (depth >= skyDepth) continue;
+
+      const [ndcX, ndcY] = pixelToNdc(x, y, width, height);
+      const p = unprojectNdc(ndcX, ndcY, depth, inverseViewProj);
+      const { azimuth, elevation } = azimuthElevation(cameraPos, p);
+      azimuths[c] = azimuth;
+      elevations[c] = elevation;
+      // 像素中心归一化：与捕获图同尺度，调用方乘自己的画布尺寸即可
+      screen[c * 2] = (x + 0.5) / width;
+      screen[c * 2 + 1] = (y + 0.5) / height;
+      hasGeometry[c] = 1;
+      if (elevation > maxElevation) maxElevation = elevation;
+      if (elevation < minElevation) minElevation = elevation;
+      found = true;
+      break;
+    }
+    if (!found) {
+      // 这一列没有几何：天际线落在水平线上
+      open++;
+      azimuths[c] = 0;
+      elevations[c] = 0;
+      screen[c * 2] = (x + 0.5) / width;
+      screen[c * 2 + 1] = 1; // 贴到画面底部，画线时按 hasGeometry 断开
+      hasGeometry[c] = 0;
+      if (0 > maxElevation) maxElevation = 0;
+      if (0 < minElevation) minElevation = 0;
+    }
+  }
+
+  return {
+    azimuths,
+    elevations,
+    maxElevation,
+    minElevation,
+    openRatio: cols > 0 ? open / cols : 0,
+    screen,
+    hasGeometry,
+  };
+}

package/src/analysis/viewshed.ts

@@ -0,0 +1,160 @@
+/**
+ * 360° 可视域：地面栅格版。
+ *
+ * 思路与「从观察点做阴影贴图」一致，但**判定在 CPU 上做**：
+ * GPU 只负责产出一个 `方向 → 最近遮挡距离` 的采样函数（6 面立方体深度图），
+ * 这里拿它在观察点周围的地面网格上逐格比较距离。
+ *
+ * 为什么不在片元里逐像素判定（建筑立面着色版）：
+ * 那要把立方体深度注入到每种材质（pbr / lambert / 棱线 / 点云 / 泼溅）的 shader 里，
+ * 成本和风险高一个量级；地面栅格版能覆盖绝大多数规划类需求，且结果可以直接
+ * 当成一张贴图/热力图叠在地面上。
+ *
+ * 纯数学，不碰 WebGL：采样函数由 `render/analysis/DepthPass` 提供，单测里用假的。
+ */
+import { unpackRGBADepth } from './depth.js';
+import type { Vec3 } from './measure.js';
+
+export interface ViewshedOptions {
+  /** 分析半径（米） */
+  radius: number;
+  /** 栅格边长（格数，默认 96；96² = 9216 个采样点，CPU 侧约 1~3 ms） */
+  grid?: number;
+  /**
+   * 遮挡容差（米，默认 0.5）。
+   *
+   * 采样点到观察点的距离要**小于等于**该方向上的遮挡距离才算可见；
+   * 留一点容差是为了吸收深度图的离散化误差与地面自身的起伏。
+   */
+  bias?: number;
+  /** 地面高程（场景 ENU 的 z，默认 0） */
+  groundZ?: number;
+}
+
+export interface ViewshedResult {
+  /**
+   * `grid × grid` 的可见性，行优先（`y * grid + x`）：
+   * `1` = 可见，`0` = 被遮挡，`-1` = 超出半径或没有数据。
+   */
+  raster: Float32Array;
+  grid: number;
+  /** 栅格左下角（场景 ENU 米） */
+  minX: number;
+  minY: number;
+  /** 每格边长（米） */
+  cellSize: number;
+  /** 有效格子里可见的比例（0~1） */
+  visibleRatio: number;
+}
+
+/**
+ * @param origin 观察点（场景 ENU 米，已含眼高）
+ * @param sampleDistance 沿单位方向取「最近的遮挡距离」；该方向没有几何时返回 `Infinity`
+ */
+export function computeViewshed(
+  origin: Vec3,
+  sampleDistance: (dir: Vec3) => number,
+  opts: ViewshedOptions
+): ViewshedResult {
+  const radius = Math.max(1e-3, opts.radius);
+  const grid = Math.max(2, Math.floor(opts.grid ?? 96));
+  const bias = Math.max(0, opts.bias ?? 0.5);
+  const groundZ = opts.groundZ ?? 0;
+
+  const cellSize = (radius * 2) / grid;
+  const minX = origin[0] - radius;
+  const minY = origin[1] - radius;
+  const raster = new Float32Array(grid * grid);
+
+  let visible = 0;
+  let counted = 0;
+
+  for (let iy = 0; iy < grid; iy++) {
+    const wy = minY + (iy + 0.5) * cellSize;
+    for (let ix = 0; ix < grid; ix++) {
+      const wx = minX + (ix + 0.5) * cellSize;
+      const dx = wx - origin[0];
+      const dy = wy - origin[1];
+      const dz = groundZ - origin[2];
+      const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      const idx = iy * grid + ix;
+
+      if (dist > radius || dist < 1e-6) {
+        raster[idx] = -1;
+        continue;
+      }
+
+      const dir: Vec3 = [dx / dist, dy / dist, dz / dist];
+      const blockedAt = sampleDistance(dir);
+      const ok = dist <= blockedAt + bias;
+      raster[idx] = ok ? 1 : 0;
+      counted++;
+      if (ok) visible++;
+    }
+  }
+
+  return {
+    raster,
+    grid,
+    minX,
+    minY,
+    cellSize,
+    visibleRatio: counted > 0 ? visible / counted : 0,
+  };
+}
+
+/**
+ * 从 6 面立方体深度图构造 `sampleDistance`。
+ *
+ * 立方体每个面是 `size × size` 的 RGBA8，存的是 `距离 / maxDist` 的打包值
+ * （打包方式同 three 的 `packDepthToRGBA`，与 `RGBADepthPacking` 一致）。
+ * 采样用最近邻 —— 可视域本身是栅格化的，插值不会让结果更准。
+ *
+ * 面序与 three 的 `WebGLCubeRenderTarget` / `CubeCamera` 一致：
+ * `+x, -x, +y, -y, +z, -z`。
+ */
+export function makeCubeDistanceSampler(
+  faces: readonly (ArrayLike<number> | null | undefined)[],
+  size: number,
+  maxDist: number
+): (dir: Vec3) => number {
+  return (dir) => {
+    const [x, y, z] = dir;
+    const ax = Math.abs(x);
+    const ay = Math.abs(y);
+    const az = Math.abs(z);
+
+    // 主轴决定落在哪个面：|x| 最大 → ±x 面，依此类推
+    let faceIndex: number;
+    let u: number;
+    let v: number;
+    if (ax >= ay && ax >= az) {
+      faceIndex = x >= 0 ? 0 : 1;
+      const d = ax;
+      // three 的立方体面约定：+x 面 u = -z/d, v = -y/d
+      u = x >= 0 ? -z / d : z / d;
+      v = -y / d;
+    } else if (ay >= az) {
+      faceIndex = y >= 0 ? 2 : 3;
+      const d = ay;
+      u = x / d;
+      v = y >= 0 ? z / d : -z / d;
+    } else {
+      faceIndex = z >= 0 ? 4 : 5;
+      const d = az;
+      // 面朝向相反时 u 轴也翻向，否则 -z 面会左右镜像（可视域会镜像到错误一侧）
+      u = z >= 0 ? x / d : -x / d;
+      v = -y / d;
+    }
+
+    const face = faces[faceIndex];
+    if (!face) return Infinity;
+    const px = Math.min(size - 1, Math.max(0, Math.floor(((u + 1) / 2) * size)));
+    const py = Math.min(size - 1, Math.max(0, Math.floor(((v + 1) / 2) * size)));
+    const d = unpackRGBADepth(face, (py * size + px) * 4);
+    // 打包值是归一化距离：1 = 远平面（该方向没有几何）。three 的 pack 对 v>=1
+    // 直接返回全白，解包正好是 1.0，所以阈值取 0.9999 就够。
+    if (d >= 0.9999) return Infinity;
+    return d * maxDist;
+  };
+}

package/src/core/DXTTextureDecode.ts

@@ -2,10 +2,13 @@
  * DXT1 / DXT3 / DXT5 纹理解码（squish 算法的 JS 移植）
  *
  * 来源：SuperMap iClient3D S3M SDK（Apache-2.0）。
- * 迁移到 TS 时做了两件事，算法本身未改：
+ * 迁移到 TS 时做了三件事，算法本身未改：
  *   1. 补齐类型；
  *   2. 修掉 `DecompressAlphaDxt3` 里把 `block` 误写成未定义全局 `bytes` 的笔误
- *      （DXT3 纹理此前会直接 ReferenceError）。
+ *      （DXT3 纹理此前会直接 ReferenceError）；
+ *   3. 修掉 `DecompressImage565` 的两处 flipY 笔误（见下方函数内注释：
+ *      块行下标少减 1 让 format ≤ 11 的 DXT1 顶部块行整行变黑；块内 4 行
+ *      没倒着写，导致行序和 `DecompressImage` 主路径对不上）。
  */
 
 const kDxt1 = 1 << 0;
@@ -158,7 +161,13 @@ function DecompressImage565(rgb565: Uint16Array, width: number, height: number,
   const blockHeight = height / 4;
   for (let blockY = 0; blockY < blockHeight; blockY++) {
     for (let blockX = 0; blockX < blockWidth; blockX++) {
-      i = 4 * ((blockHeight - blockY) * blockWidth + blockX);
+      // flipY 分两级做，才和 DecompressImage 的 height - 1 - sy 真正同口径：
+      //   ① 块行倒着取（blockHeight - 1 - blockY）；
+      //   ② 块内 4 行也倒着写（下面 dstI 从块底行起、逐行 -= width）。
+      // 只做 ① 会变成「块带倒序、带内行正序」的错位图，和主路径对不上。
+      // 写成 blockHeight - blockY 则会让 blockY=0 读到数组界外（Uint16Array 越界读
+      // 得 undefined，位运算后归 0），顶部块行解成全黑、其余块行整体错位一行。
+      i = 4 * ((blockHeight - 1 - blockY) * blockWidth + blockX);
       c[0] = blocks[i];
       c[1] = blocks[i + 1];
       r0 = c[0] & 0x1f;
@@ -172,23 +181,24 @@ function DecompressImage565(rgb565: Uint16Array, width: number, height: number,
       c[2] = ((5 * r0 + 3 * r1) >> 3) | (((5 * g0 + 3 * g1) >> 3) & 0x7e0) | (((5 * b0 + 3 * b1) >> 3) & 0xf800);
       c[3] = ((5 * r1 + 3 * r0) >> 3) | (((5 * g1 + 3 * g0) >> 3) & 0x7e0) | (((5 * b1 + 3 * b0) >> 3) & 0xf800);
       m = blocks[i + 2];
-      dstI = blockY * 4 * width + blockX * 4;
+      // 块内第 0 行写到块底行，逐行往上走 —— 逐行 flipY
+      dstI = (blockY * 4 + 3) * width + blockX * 4;
       dst[dstI] = c[m & 0x3];
       dst[dstI + 1] = c[(m >> 2) & 0x3];
       dst[dstI + 2] = c[(m >> 4) & 0x3];
       dst[dstI + 3] = c[(m >> 6) & 0x3];
-      dstI += width;
+      dstI -= width;
       dst[dstI] = c[(m >> 8) & 0x3];
       dst[dstI + 1] = c[(m >> 10) & 0x3];
       dst[dstI + 2] = c[(m >> 12) & 0x3];
       dst[dstI + 3] = c[(m >> 14) & 0x3];
       m = blocks[i + 3];
-      dstI += width;
+      dstI -= width;
       dst[dstI] = c[m & 0x3];
       dst[dstI + 1] = c[(m >> 2) & 0x3];
       dst[dstI + 2] = c[(m >> 4) & 0x3];
       dst[dstI + 3] = c[(m >> 6) & 0x3];
-      dstI += width;
+      dstI -= width;
       dst[dstI] = c[(m >> 8) & 0x3];
       dst[dstI + 1] = c[(m >> 10) & 0x3];
       dst[dstI + 2] = c[(m >> 12) & 0x3];

package/src/index.ts

@@ -138,6 +138,11 @@ export { setMaterialQuality, getMaterialQuality } from './render/StyleMaterial.j
 
 export { Picker } from './render/Picker.js';
 export { GpuEdgePass } from './render/GpuEdgePass.js';
+
+/* 三维空间分析内核：纯数学，不依赖 WebGL，可单独用于服务端 / Worker */
+export * from './analysis/index.js';
+export { captureSkylineDepth, captureRadialCube, buildCubeCameras, CUBE_FACES } from './render/analysis/DepthPass.js';
+export type { DepthCaptureContext, SkylineCapture } from './render/analysis/DepthPass.js';
 export type { GpuEdgeParams } from './render/GpuEdgePass.js';
 export type { PickHit } from './render/Picker.js';
 

package/src/render/S3MViewer.ts

@@ -70,7 +70,30 @@ import type { DegradationKind, UnsupportedPolicy } from '../core/degradations.js
 import { Picker } from './Picker.js';
 import { GpuEdgePass } from './GpuEdgePass.js';
 import { Animator } from '../anim/Animator.js';
-import type { Channel, TransitionOptions } from '../anim/Animator.js';
+import {
+  buildClipPlanes,
+  lineOfSight as computeLineOfSight,
+  measureSegment,
+  polygonArea,
+  polygonAreaHorizontal,
+  polygonPerimeter,
+  polylineLength,
+  polylineLengthHorizontal,
+} from '../analysis/index.js';
+import type {
+  ClipOptions,
+  LineOfSightOptions,
+  LineOfSightResult,
+  LngLatAlt,
+  MeasureResult,
+  SkylineResult,
+  Vec3,
+  ViewshedResult,
+} from '../analysis/index.js';
+import { skylineFromDepth } from '../analysis/skyline.js';
+import { computeViewshed, makeCubeDistanceSampler } from '../analysis/viewshed.js';
+import { captureRadialCube, captureSkylineDepth } from './analysis/DepthPass.js';
+import type { DepthCaptureContext } from './analysis/DepthPass.js';import type { Channel, TransitionOptions } from '../anim/Animator.js';
 import { Path } from '../anim/Path.js';
 import type { EasingFn, EasingName } from '../anim/easing.js';
 import type { LineSharedUniforms, ThickLineMaterial } from './EdgeLines.js';
@@ -88,7 +111,7 @@ import type {
   StyleUniforms,
 } from '../core/types.js';
 
-import { lngLatFromWorld, type GeoAdapter } from './GeoAdapter.js';
+import { lngLatFromWorld, worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
 
 import {
   DatasetManager,
@@ -282,6 +305,8 @@ export class S3MViewer {
   private _colorPipeline: ColorPipeline | undefined;
   /** fade-through 编排的代次：中途再切一次，旧编排作废（与 setMode 同一套） */
   private _pipelineGen = 0;
+  /** 当前裁剪配置；renderer 就绪前后都要能设，所以单独存一份（见 `_applyClipping`） */
+  private _clip: ClipOptions | null = null;
   /** 单体样式、专题着色与状态纹理管理器 */
   private readonly _featureStyleManager: FeatureStyleManager;
   /** GPU 路径动画管理器 */
@@ -566,6 +591,8 @@ export class S3MViewer {
     this.renderer = this._createRenderer(canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy(), this.options.anisotropyCap ?? Infinity);
     this._syncTextureCapabilities(gl);
+    // 裁剪是构造期就能设的（还没 mount 时 `_applyClipping` 会先跳过），这里补挂一次
+    this._applyClipping();
 
     this.scene = new THREE.Scene();
     this.scene.add(this.groundManager.group);
@@ -608,6 +635,8 @@ export class S3MViewer {
     this.renderer = this._createRenderer(this.canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy(), this.options.anisotropyCap ?? Infinity);
     this._syncTextureCapabilities(gl);
+    // 新 renderer 的 clippingPlanes 是空的，裁剪状态要重新挂上去
+    this._applyClipping();
     this.picker?.dispose();
     this.picker = new Picker(this.renderer);
     // GPU 描边的 RT / 材质绑定在旧上下文上，整体丢弃，下一帧按需重建
@@ -2446,6 +2475,208 @@ export class S3MViewer {
     return this._picks.getFeatureBounds(smid);
   }
 
+  /* -------------------------------------------------------------- 三维空间分析 */
+
+  /**
+   * 经纬度 + 高程 → 场景 ENU 米制坐标。
+   *
+   * 场景锚点可能还没就绪（没加数据集），此时按世界原点处理 —— 量算 API 会因此
+   * 给出「以原点为基准」的结果，但不会抛错。真实使用里锚点在 addDataset 之后必然存在。
+   */
+  private _sceneFromLngLat(p: LngLatAlt): Vec3 {
+    const anchor = this.sceneAnchor;
+    if (!anchor) return [0, 0, 0];
+    const s = anchor.meterInMercator;
+    const w = worldFromLngLat(this.geo, p.lng, p.lat, p.altitude);
+    // 注意 y 取反：three 的 y 向上，墨卡托 y 向下（与 PickService.pickPosition 互逆）
+    return [(w.x - anchor.x) / s, -(w.y - anchor.y) / s, p.altitude - (anchor.altitude ?? 0)];
+  }
+
+  /**
+   * 经纬度 + 绝对高程 → 场景 ENU 米制坐标。
+   *
+   * 外围要做「分析代理几何」（底图建筑挤出）、或者在 three 里画自定义标注时，
+   * 都得先把经纬度落到这个坐标系里 —— 场景的 ENU 原点在 `sceneAnchor`，
+   * 不是经纬度，所以必须走这个换算。
+   */
+  lngLatToPoint(p: LngLatAlt): Vec3 {
+    return this._sceneFromLngLat(p);
+  }
+
+  /** 场景 ENU 米制坐标 → 经纬度 + 绝对高程（`pointToLngLat` 的逆） */
+  pointToLngLat(v: Vec3): LngLatAlt {
+    return this._lngLatFromScene(v);
+  }
+
+  /** 场景 ENU 米制坐标 → 经纬度 + 绝对高程 */
+  private _lngLatFromScene(v: Vec3): LngLatAlt {
+    const anchor = this.sceneAnchor;
+    if (!anchor) return { lng: 0, lat: 0, altitude: v[2] };
+    const s = anchor.meterInMercator;
+    const [lng, lat] = lngLatFromWorld(this.geo, v[0] * s + anchor.x, -v[1] * s + anchor.y);
+    return { lng, lat, altitude: v[2] + (anchor.altitude ?? 0) };
+  }
+
+  /**
+   * 两点量算：三维距离 / 水平距离 / 高差。
+   *
+   * 输入是经纬度 + 绝对高程（`pickPosition` 的返回值直接能用），
+   * 内部换算到 ENU 米再算，所以不会受投影单位影响。
+   */
+  measureDistance(a: LngLatAlt, b: LngLatAlt): MeasureResult {
+    return measureSegment(this._sceneFromLngLat(a), this._sceneFromLngLat(b));
+  }
+
+  /** 折线长度（三维 + 水平投影两套口径） */
+  measurePolyline(points: readonly LngLatAlt[]): { length3D: number; lengthHorizontal: number } {
+    const scene = points.map((p) => this._sceneFromLngLat(p));
+    return { length3D: polylineLength(scene), lengthHorizontal: polylineLengthHorizontal(scene) };
+  }
+
+  /**
+   * 多边形量算：坡面真实面积 / 水平投影面积 / 周长。
+   *
+   * 建筑面积、用地面积按 `areaHorizontal` 算；坡面覆盖面积按 `area3D`。
+   */
+  measurePolygon(points: readonly LngLatAlt[]): {
+    area3D: number;
+    areaHorizontal: number;
+    perimeter: number;
+  } {
+    const scene = points.map((p) => this._sceneFromLngLat(p));
+    return {
+      area3D: polygonArea(scene),
+      areaHorizontal: polygonAreaHorizontal(scene),
+      perimeter: polygonPerimeter(scene),
+    };
+  }
+
+  /**
+   * 通视分析：两点之间是否被已加载的 S3M 几何挡住。
+   *
+   * 走 CPU 射线求交（`Raycaster` 打全部 pickable mesh），几十万面量级是几十毫秒，
+   * 适合点击式查询；要拖拽时逐帧刷新，得等深度图版本的批量采样。
+   *
+   * 注意范围：**只认 S3M 场景里的几何**。MapLibre 底图地形与 MVT 建筑不在这个场景里，
+   * 它们不参与遮挡（见 `docs/API.md` 的「分析范围」）。
+   */
+  lineOfSight(a: LngLatAlt, b: LngLatAlt, opts: LineOfSightOptions = {}): LineOfSightResult {
+    const from = this._sceneFromLngLat(a);
+    const to = this._sceneFromLngLat(b);
+    return computeLineOfSight(from, to, (origin, dir, maxDistance) => {
+      const hit = this._picks.raycastDistance(origin, dir, maxDistance);
+      if (!hit) return null;
+      return { distance: hit.distance, point: hit.point };
+    }, opts);
+  }
+
+  /**
+   * 裁剪 / 剖切（平面、Box、十字）。
+   *
+   * 平面列表挂在**本图层的 renderer** 上（每个 `S3MLayer` 一个 `WebGLRenderer`），
+   * 所以天然是图层级：同页别的图层不受影响。传 `null` 取消裁剪。
+   *
+   * 已知边界：只做「切掉」，不做**封口**——剖开后看到的是空壳/背面；
+   * 凹多边形裁剪需要多组半空间并集，three 的 `clippingPlanes` 表达不了（只能凸）。
+   */
+  setClipping(opt: ClipOptions | null): void {
+    this._clip = opt;
+    this._applyClipping();
+    this._requestRepaint();
+  }
+
+  /** 当前裁剪配置（`null` = 未裁剪） */
+  get clipping(): ClipOptions | null {
+    return this._clip;
+  }
+
+  private _applyClipping(): void {
+    const r = this.renderer;
+    if (!r) return; // mount 前先记着，`_createRenderer` 之后会补一次
+    if (!this._clip) {
+      r.clippingPlanes = [];
+      return;
+    }
+    r.clippingPlanes = buildClipPlanes(this._clip).map(
+      (p) => new THREE.Plane(new THREE.Vector3(p.normal[0], p.normal[1], p.normal[2]), p.constant)
+    );
+  }
+
+  /** 分析用的离屏采集上下文（renderer / scene / camera 都可能在 mount 前为空） */
+  private _depthCtx(): DepthCaptureContext {
+    return {
+      renderer: () => this.renderer,
+      scene: () => this.scene,
+      camera: () => this.camera,
+    };
+  }
+
+  /**
+   * 天际线分析：用当前视角渲染一张深度图，按列抽出「方位角 → 仰角」曲线。
+   *
+   * 一次调用 = 一趟额外渲染 + 一次全图回读，**不要每帧调**。
+   * 典型用法是相机停下来（`moveend`）后算一次。
+   *
+   * @param opts.width 采集分辨率（默认 640）。精度由它决定：
+   *   640 宽 ≈ 0.56°/列，1280 宽 ≈ 0.28°/列。
+   */
+  skyline(opts: {
+    width?: number;
+    height?: number;
+    step?: number;
+    /** 额外参与遮挡的代理几何（底图建筑 / 地形网格），只在这一趟深度渲染里存在 */
+    include?: readonly THREE.Object3D[];
+  } = {}): SkylineResult | null {
+    const cap = captureSkylineDepth(
+      this._depthCtx(),
+      opts.width ?? 640,
+      opts.height ?? 360,
+      opts.include
+    );
+    if (!cap) return null;
+    return skylineFromDepth({
+      rgba: cap.rgba,
+      width: cap.width,
+      height: cap.height,
+      inverseViewProj: cap.inverseViewProj,
+      cameraPos: cap.cameraPos,
+      step: opts.step,
+    });
+  }
+
+  /**
+   * 360° 可视域（地面栅格版）：从观察点朝 6 个方向各渲染一次深度，
+   * 再在 CPU 上对地面网格逐格判定可见性。
+   *
+   * 一次调用 = 6 趟额外渲染 + 6 次回读，成本明显高于天际线，
+   * 只在点击/松手时算。返回的 `raster` 可以直接当贴图画在地面上。
+   */
+  viewshed(opts: {
+    /** 观察点（经纬度 + 地面高程；眼高由 `eyeHeight` 另加） */
+    origin: LngLatAlt;
+    /** 分析半径（米） */
+    radius: number;
+    /** 栅格边长（默认 96） */
+    grid?: number;
+    /** 眼高（米，默认 1.7） */
+    eyeHeight?: number;
+    /** 立方体深度图分辨率（默认 128；越大边缘越准，回读越慢） */
+    size?: number;
+    /** 额外参与遮挡的代理几何（底图建筑 / 地形网格），只在这一趟深度渲染里存在 */
+    include?: readonly THREE.Object3D[];
+  }): ViewshedResult | null {
+    const eye = opts.eyeHeight ?? 1.7;
+    const origin = this._sceneFromLngLat({ ...opts.origin, altitude: opts.origin.altitude + eye });
+    const size = opts.size ?? 128;
+    const faces = captureRadialCube(this._depthCtx(), origin, size, opts.radius, opts.include);
+    if (!faces) return null;
+    return computeViewshed(origin, makeCubeDistanceSampler(faces, size, opts.radius), {
+      radius: opts.radius,
+      grid: opts.grid,
+      groundZ: 0,
+    });
+  }
+
   /** @internal 见 viewer/PickService.ts */
   _intersectMeshAtRay(mesh: THREE.Mesh, ray: THREE.Ray, instanceIndex?: number): THREE.Vector3 | null {
     return this._picks.intersectMeshAtRay(mesh, ray, instanceIndex);