s3m-three 0.4.23 → 0.4.25

package/dist/analysis/clipping.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 裁剪 / 剖切的纯数学部分：把「平面 / 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;
+}
+/** 过一个点、法线指向**保留侧**的平面 */
+export declare function planeFromPointNormal(normal: Vec3, point: Vec3): PlaneLike;
+/** 点是否在保留侧（含边界）；用于调试与单测 */
+export declare function isPointKept(planes: readonly PlaneLike[], p: Vec3): boolean;
+/** 平面裁剪：法线指向保留的一侧，切掉另一侧 */
+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 declare function planeClipping(opt: Omit<ClipPlaneOptions, 'type'>): PlaneLike[];
+export declare function boxClipping(opt: Omit<ClipBoxOptions, 'type'>): PlaneLike[];
+export declare function crossClipping(opt: Omit<ClipCrossOptions, 'type'>): PlaneLike[];
+/** 统一入口：把交互输入翻成半空间列表 */
+export declare function buildClipPlanes(opt: ClipOptions): PlaneLike[];
+//# sourceMappingURL=clipping.d.ts.map

package/dist/analysis/clipping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipping.d.ts","sourceRoot":"","sources":["../../src/analysis/clipping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,wCAAwC;AACxC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,IAAI,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAYD,0BAA0B;AAC1B,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,SAAS,CAGzE;AAED,2BAA2B;AAC3B,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAK1E;AAID,2BAA2B;AAC3B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,sBAAsB;IACtB,MAAM,EAAE,IAAI,CAAC;IACb,cAAc;IACd,KAAK,EAAE,IAAI,CAAC;CACb;AAED,qBAAqB;AACrB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,CAAC;IACZ,8BAA8B;IAC9B,CAAC,EAAE,IAAI,CAAC;IACR,CAAC,EAAE,IAAI,CAAC;CACT;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACd,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACd,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAI/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG,SAAS,EAAE,CAE9E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,SAAS,EAAE,CAoB1E;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG,SAAS,EAAE,CAS9E;AAED,wBAAwB;AACxB,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,EAAE,CAS7D"}

package/dist/analysis/clipping.js

@@ -0,0 +1,69 @@
+function normalize(v) {
+    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, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/** 过一个点、法线指向**保留侧**的平面 */
+export function planeFromPointNormal(normal, point) {
+    const n = normalize(normal);
+    return { normal: n, constant: -dot(n, point) };
+}
+/** 点是否在保留侧（含边界）；用于调试与单测 */
+export function isPointKept(planes, p) {
+    for (const pl of planes) {
+        if (dot(pl.normal, p) + pl.constant < 0)
+            return false;
+    }
+    return true;
+}
+/* ------------------------------------------------------------------ 生成 */
+export function planeClipping(opt) {
+    return [planeFromPointNormal(opt.normal, opt.point)];
+}
+export function boxClipping(opt) {
+    const min = [
+        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 = [
+        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) {
+    const planes = [
+        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) {
+    switch (opt.type) {
+        case 'plane':
+            return planeClipping(opt);
+        case 'box':
+            return boxClipping(opt);
+        case 'cross':
+            return crossClipping(opt);
+    }
+}
+//# sourceMappingURL=clipping.js.map

package/dist/analysis/clipping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipping.js","sourceRoot":"","sources":["../../src/analysis/clipping.ts"],"names":[],"mappings":"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"}

package/dist/analysis/depth.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 深度图回读的数学部分：解包 + 反投影。
+ *
+ * GPU 那边只能把深度渲染成 RGBA8（three 的 `RGBADepthPacking`），
+ * 回读到 CPU 后要还原成 0~1 的窗口深度，再反投影成世界坐标 —— 这两步都在这里，
+ * 与 WebGL 无关，可以用构造出来的矩阵直接单测。
+ *
+ * 打包/解包的常数照抄 three 的 `packing.glsl.js`，不要自己改：
+ * 改一个常数，回读出来的深度就会整体偏移，而画面看起来完全正常。
+ */
+import type { Vec3 } from './measure.js';
+/**
+ * 把 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 declare function packRGBADepth(depth: number): [number, number, number, number];
+/**
+ * 解包：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 declare function unpackRGBADepth(rgba: ArrayLike<number>, offset?: number): number;
+/**
+ * NDC + 窗口深度 → 世界坐标。
+ *
+ * @param ndcX -1~1（屏幕左侧到右侧）
+ * @param ndcY -1~1（屏幕底部到顶部；注意与像素行号反向）
+ * @param depth01 0~1 的窗口深度
+ * @param inverseViewProj 视图投影矩阵的逆（列主序 16 元，与 `THREE.Matrix4.elements` 同序）
+ */
+export declare function unprojectNdc(ndcX: number, ndcY: number, depth01: number, inverseViewProj: ArrayLike<number>): Vec3;
+/** 像素坐标（左上角为 0,0）→ NDC */
+export declare function pixelToNdc(px: number, py: number, width: number, height: number): [number, number];
+/**
+ * 把「观察点 → 目标点」拆成方位角 / 仰角（度）。
+ *
+ * 方位角：0 = 正北，顺时针增大（与地图 bearing 一致），ENU 下 x 向东、y 向北。
+ * 仰角：0 = 水平，正值向上，负值向下。
+ */
+export declare function azimuthElevation(from: Vec3, to: Vec3): {
+    azimuth: number;
+    elevation: number;
+    distance: number;
+};
+//# sourceMappingURL=depth.d.ts.map

package/dist/analysis/depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth.d.ts","sourceRoot":"","sources":["../../src/analysis/depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAWzC;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAiB7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,SAAI,GAAG,MAAM,CAW3E;AAQD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,SAAS,CAAC,MAAM,CAAC,GACjC,IAAI,CASN;AAED,0BAA0B;AAC1B,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAElG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,IAAI,GACP;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAS1D"}

package/dist/analysis/depth.js

@@ -0,0 +1,99 @@
+/** 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) {
+    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) => 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, offset = 0) {
+    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) {
+    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, ndcY, depth01, inverseViewProj) {
+    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, py, width, height) {
+    return [((px + 0.5) / width) * 2 - 1, 1 - ((py + 0.5) / height) * 2];
+}
+/**
+ * 把「观察点 → 目标点」拆成方位角 / 仰角（度）。
+ *
+ * 方位角：0 = 正北，顺时针增大（与地图 bearing 一致），ENU 下 x 向东、y 向北。
+ * 仰角：0 = 水平，正值向上，负值向下。
+ */
+export function azimuthElevation(from, to) {
+    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 };
+}
+//# sourceMappingURL=depth.js.map

package/dist/analysis/depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth.js","sourceRoot":"","sources":["../../src/analysis/depth.ts"],"names":[],"mappings":"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"}

package/dist/analysis/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 三维空间分析内核（宿主无关、不依赖 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';
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/analysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,WAAW,GACZ,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/analysis/index.js

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

package/dist/analysis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,wBAAwB,EACxB,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AASvB,6DAA6D;AAC7D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}

package/dist/analysis/lineOfSight.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 通视分析（单条视线）。
+ *
+ * 求交本体由调用方注入 —— 内核只负责「沿视线找第一个遮挡、算可见比例」，
+ * 这样不依赖 three，也能在单测里用解析几何伪造求交结果。
+ *
+ * 场景里实际用的求交是 `THREE.Raycaster` 打全部 pickable mesh（与
+ * `PickService.drillPick` 同一条路径），由 `S3MViewer.lineOfSight` 装配。
+ */
+import { 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 declare function lineOfSight(from: Vec3, to: Vec3, cast: RayCast, opts?: LineOfSightOptions): LineOfSightResult;
+//# sourceMappingURL=lineOfSight.d.ts.map

package/dist/analysis/lineOfSight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineOfSight.d.ts","sourceRoot":"","sources":["../../src/analysis/lineOfSight.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AAErD,6BAA6B;AAC7B,MAAM,WAAW,MAAM;IACrB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,0BAA0B;IAC1B,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,IAAI,EACR,IAAI,EAAE,OAAO,EACb,IAAI,GAAE,kBAAuB,GAC5B,iBAAiB,CAyCnB"}

package/dist/analysis/lineOfSight.js

@@ -0,0 +1,56 @@
+/**
+ * 通视分析（单条视线）。
+ *
+ * 求交本体由调用方注入 —— 内核只负责「沿视线找第一个遮挡、算可见比例」，
+ * 这样不依赖 three，也能在单测里用解析几何伪造求交结果。
+ *
+ * 场景里实际用的求交是 `THREE.Raycaster` 打全部 pickable mesh（与
+ * `PickService.drillPick` 同一条路径），由 `S3MViewer.lineOfSight` 装配。
+ */
+import { distance3D } from './measure.js';
+/**
+ * 计算两点之间的通视情况。
+ *
+ * @param from 起点（场景 ENU 米）
+ * @param to 终点
+ * @param cast 射线求交函数
+ */
+export function lineOfSight(from, to, cast, opts = {}) {
+    const total = distance3D(from, to);
+    if (total <= 1e-6) {
+        return { visible: true, distance: 0, blockedDistance: null, blockedPoint: null, visibleRatio: 1 };
+    }
+    const dir = [
+        (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 = [
+        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 };
+}
+//# sourceMappingURL=lineOfSight.js.map

package/dist/analysis/lineOfSight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineOfSight.js","sourceRoot":"","sources":["../../src/analysis/lineOfSight.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAa,MAAM,cAAc,CAAC;AA+CrD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,IAAU,EACV,EAAQ,EACR,IAAa,EACb,OAA2B,EAAE;IAE7B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IACpG,CAAC;IAED,MAAM,GAAG,GAAS;QAChB,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK;QACzB,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK;QACzB,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK;KAC1B,CAAC;IAEF,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;IACzD,0BAA0B;IAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,SAAS,EAAE,KAAK,GAAG,GAAG,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAS;QACnB,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW;QAC9B,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW;QAC9B,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW;KAC/B,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;IAE1C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,GAAG,KAAK,EAAE,CAAC;QAChC,2BAA2B;QAC3B,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC;QACpE,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,KAAK;YACf,eAAe;YACf,YAAY,EAAE,GAAG,CAAC,KAAK,IAAI;gBACzB,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,eAAe;gBAClC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,eAAe;gBAClC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,eAAe;aACnC;YACD,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,CAAC;SAChE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AACxG,CAAC"}

package/dist/analysis/measure.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 量算：距离 / 折线长 / 面积 / 高差。
+ *
+ * 全部是纯函数，输入输出都是**场景 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 declare function distance3D(a: Vec3, b: Vec3): number;
+/** 水平距离（忽略高程差）—— 规划类口径常用 */
+export declare function distanceHorizontal(a: Vec3, b: Vec3): number;
+/** 高差（有符号：b 比 a 高为正） */
+export declare function heightDifference(a: Vec3, b: Vec3): number;
+/** 折线长度（逐段求和）；点少于 2 个返回 0 */
+export declare function polylineLength(points: readonly Vec3[]): number;
+/** 折线水平投影长度 */
+export declare function polylineLengthHorizontal(points: readonly Vec3[]): number;
+/** 多边形周长（首尾自动闭合，不要重复传首点） */
+export declare function polygonPerimeter(points: readonly Vec3[]): number;
+/**
+ * 多边形面积（Newell 法）。
+ *
+ * 对**共面**点给出真实面积；对起伏/不共面的点给出「投影到最佳拟合平面」的面积，
+ * 这也是绝大多数量算工具的口径。要水平投影面积用 `polygonAreaHorizontal`。
+ *
+ * 与点的绕向无关（取向量模长），所以不用担心用户顺时针还是逆时针点。
+ */
+export declare function polygonArea(points: readonly Vec3[]): number;
+/**
+ * 水平投影面积（鞋带公式，忽略高程）。
+ *
+ * 与 `polygonArea` 的区别：一个坡面上的矩形，`polygonArea` 给坡面真实面积，
+ * 这里给它在水平面上的投影面积。建筑面积/用地面积按后者算。
+ */
+export declare function polygonAreaHorizontal(points: readonly Vec3[]): number;
+/** 量算结果：一次给全三种口径，避免调用方自己再算一遍 */
+export interface MeasureResult {
+    /** 三维直线距离（米） */
+    distance3D: number;
+    /** 水平距离（米） */
+    distanceHorizontal: number;
+    /** 高差（米，有符号） */
+    heightDiff: number;
+}
+export declare function measureSegment(a: Vec3, b: Vec3): MeasureResult;
+//# sourceMappingURL=measure.d.ts.map

package/dist/analysis/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../../src/analysis/measure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8BAA8B;AAC9B,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,oBAAoB;AACpB,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAKnD;AAED,4BAA4B;AAC5B,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAI3D;AAED,wBAAwB;AACxB,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAEzD;AAED,6BAA6B;AAC7B,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,CAI9D;AAED,eAAe;AACf,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,CAIxE;AAED,4BAA4B;AAC5B,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,CAGhE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,CAc3D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,CAUrE;AAED,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,aAAa,CAM9D"}

package/dist/analysis/measure.js

@@ -0,0 +1,95 @@
+/**
+ * 量算：距离 / 折线长 / 面积 / 高差。
+ *
+ * 全部是纯函数，输入输出都是**场景 ENU 米制坐标**（three 世界坐标），
+ * 不依赖 three、不依赖 WebGL，可以直接单测。
+ *
+ * 经纬度 ↔ ENU 的换算在 `S3MViewer` 里做（需要 `sceneAnchor` 与 `GeoAdapter`），
+ * 这一层只管算数 —— 这样投影口径变化不会污染数学。
+ */
+export function distance3D(a, b) {
+    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, b) {
+    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, b) {
+    return b[2] - a[2];
+}
+/** 折线长度（逐段求和）；点少于 2 个返回 0 */
+export function polylineLength(points) {
+    let total = 0;
+    for (let i = 1; i < points.length; i++)
+        total += distance3D(points[i - 1], points[i]);
+    return total;
+}
+/** 折线水平投影长度 */
+export function polylineLengthHorizontal(points) {
+    let total = 0;
+    for (let i = 1; i < points.length; i++)
+        total += distanceHorizontal(points[i - 1], points[i]);
+    return total;
+}
+/** 多边形周长（首尾自动闭合，不要重复传首点） */
+export function polygonPerimeter(points) {
+    if (points.length < 2)
+        return 0;
+    return polylineLength(points) + distance3D(points[points.length - 1], points[0]);
+}
+/**
+ * 多边形面积（Newell 法）。
+ *
+ * 对**共面**点给出真实面积；对起伏/不共面的点给出「投影到最佳拟合平面」的面积，
+ * 这也是绝大多数量算工具的口径。要水平投影面积用 `polygonAreaHorizontal`。
+ *
+ * 与点的绕向无关（取向量模长），所以不用担心用户顺时针还是逆时针点。
+ */
+export function polygonArea(points) {
+    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) {
+    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 function measureSegment(a, b) {
+    return {
+        distance3D: distance3D(a, b),
+        distanceHorizontal: distanceHorizontal(a, b),
+        heightDiff: heightDifference(a, b),
+    };
+}
+//# sourceMappingURL=measure.js.map