s3m-three 0.4.23 → 0.4.24

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

package/src/analysis/measure.ts

@@ -0,0 +1,119 @@
+/**
+ * 量算：距离 / 折线长 / 面积 / 高差。
+ *
+ * 全部是纯函数，输入输出都是**场景 ENU 米制坐标**（three 世界坐标），
+ * 不依赖 three、不依赖 WebGL，可以直接单测。
+ *
+ * 经纬度 ↔ ENU 的换算在 `S3MViewer` 里做（需要 `sceneAnchor` 与 `GeoAdapter`），
+ * 这一层只管算数 —— 这样投影口径变化不会污染数学。
+ */
+
+/** 场景 ENU 米制坐标（three 世界坐标） */
+export type Vec3 = [number, number, number];
+
+/** 经纬度 + 绝对高程（米） */
+export interface LngLatAlt {
+  lng: number;
+  lat: number;
+  /** 绝对高程（米），不是相对场景锚点的高度 */
+  altitude: number;
+}
+
+export function distance3D(a: Vec3, b: Vec3): number {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const dz = b[2] - a[2];
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+/** 水平距离（忽略高程差）—— 规划类口径常用 */
+export function distanceHorizontal(a: Vec3, b: Vec3): number {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/** 高差（有符号：b 比 a 高为正） */
+export function heightDifference(a: Vec3, b: Vec3): number {
+  return b[2] - a[2];
+}
+
+/** 折线长度（逐段求和）；点少于 2 个返回 0 */
+export function polylineLength(points: readonly Vec3[]): number {
+  let total = 0;
+  for (let i = 1; i < points.length; i++) total += distance3D(points[i - 1], points[i]);
+  return total;
+}
+
+/** 折线水平投影长度 */
+export function polylineLengthHorizontal(points: readonly Vec3[]): number {
+  let total = 0;
+  for (let i = 1; i < points.length; i++) total += distanceHorizontal(points[i - 1], points[i]);
+  return total;
+}
+
+/** 多边形周长（首尾自动闭合，不要重复传首点） */
+export function polygonPerimeter(points: readonly Vec3[]): number {
+  if (points.length < 2) return 0;
+  return polylineLength(points) + distance3D(points[points.length - 1], points[0]);
+}
+
+/**
+ * 多边形面积（Newell 法）。
+ *
+ * 对**共面**点给出真实面积；对起伏/不共面的点给出「投影到最佳拟合平面」的面积，
+ * 这也是绝大多数量算工具的口径。要水平投影面积用 `polygonAreaHorizontal`。
+ *
+ * 与点的绕向无关（取向量模长），所以不用担心用户顺时针还是逆时针点。
+ */
+export function polygonArea(points: readonly Vec3[]): number {
+  const n = points.length;
+  if (n < 3) return 0;
+  let nx = 0;
+  let ny = 0;
+  let nz = 0;
+  for (let i = 0; i < n; i++) {
+    const a = points[i];
+    const b = points[(i + 1) % n];
+    nx += (a[1] - b[1]) * (a[2] + b[2]);
+    ny += (a[2] - b[2]) * (a[0] + b[0]);
+    nz += (a[0] - b[0]) * (a[1] + b[1]);
+  }
+  return Math.sqrt(nx * nx + ny * ny + nz * nz) / 2;
+}
+
+/**
+ * 水平投影面积（鞋带公式，忽略高程）。
+ *
+ * 与 `polygonArea` 的区别：一个坡面上的矩形，`polygonArea` 给坡面真实面积，
+ * 这里给它在水平面上的投影面积。建筑面积/用地面积按后者算。
+ */
+export function polygonAreaHorizontal(points: readonly Vec3[]): number {
+  const n = points.length;
+  if (n < 3) return 0;
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    const a = points[i];
+    const b = points[(i + 1) % n];
+    sum += a[0] * b[1] - b[0] * a[1];
+  }
+  return Math.abs(sum) / 2;
+}
+
+/** 量算结果：一次给全三种口径，避免调用方自己再算一遍 */
+export interface MeasureResult {
+  /** 三维直线距离（米） */
+  distance3D: number;
+  /** 水平距离（米） */
+  distanceHorizontal: number;
+  /** 高差（米，有符号） */
+  heightDiff: number;
+}
+
+export function measureSegment(a: Vec3, b: Vec3): MeasureResult {
+  return {
+    distance3D: distance3D(a, b),
+    distanceHorizontal: distanceHorizontal(a, b),
+    heightDiff: heightDifference(a, b),
+  };
+}

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