s3m-three 0.4.22 → 0.4.24

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

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/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/DatasetManager.ts

@@ -13,6 +13,7 @@ import type { AuthenticateFn } from '../core/AuthFetch.js';
 import type { Anchor } from '../core/types.js';
 import type { UnsupportedPolicy } from '../core/degradations.js';
 import { worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
+import type { TextureCreateOptions } from './TextureFactory.js';
 
 export type DatasetAlignment = 'origin' | 'bottom' | 'top' | 'center';
 
@@ -118,6 +119,23 @@ export class DatasetManager {
     }
   }
 
+  /**
+   * 图层级渲染 profile 默认值（颜色管线 / 纹理参数）。
+   * 与 `defaultMaterialQuality` 不同，它没有数据集级覆盖 —— 管线和纹理解码是
+   * 图层级的观感设定，逐数据集混着来只会让同一屏出现两套色彩空间。
+   */
+  defaultColorPipeline: 'linear' | 'direct' | undefined = undefined;
+  defaultTextureOptions: TextureCreateOptions | undefined = undefined;
+
+  /** 图层 profile 变更：同步给已存在的数据集（之后加载的瓦片才用新参数） */
+  setRenderProfile(p: { colorPipeline?: 'linear' | 'direct'; textureOptions?: TextureCreateOptions }): void {
+    if (p.colorPipeline !== undefined) this.defaultColorPipeline = p.colorPipeline;
+    if (p.textureOptions !== undefined) this.defaultTextureOptions = p.textureOptions;
+    for (const entry of this.datasets.values()) {
+      entry.tileset?.setRenderProfile(p);
+    }
+  }
+
   get(id: string): S3MDatasetEntry | undefined {
     return this.datasets.get(id);
   }
@@ -250,6 +268,9 @@ export class DatasetManager {
       polygonOffset: ds.polygonOffset,
       // 数据集 > 图层 > 模块级默认（undefined 一路传下去，由 createStyledMaterial 回落）
       materialQuality: ds.materialQuality ?? this.defaultMaterialQuality,
+      // 颜色管线 / 纹理参数只有图层级（见 setRenderProfile 注释）
+      colorPipeline: this.defaultColorPipeline,
+      textureOptions: this.defaultTextureOptions,
       useWorker: ds.useWorker,
       authenticate: ds.authenticate ?? authenticate,
       unsupported: ds.unsupported,

package/src/render/GeometryBuilder.ts

@@ -13,6 +13,7 @@
  */
 import * as THREE from 'three';
 import { createTexture } from './TextureFactory.js';
+import type { TextureCreateOptions } from './TextureFactory.js';
 import { createSharedUniforms, createStyledMaterial } from './StyleMaterial.js';
 import { isTransparentMaterial, minVertexAlpha } from './materialAlpha.js';
 import type { StyledMaterial } from './StyleMaterial.js';
@@ -367,6 +368,16 @@ export interface BuildTileOptions {
    * 由 `S3MTileset` 从图层 / 数据集一路带下来，所以同页多个图层可以各用各的。
    */
   materialQuality?: 'pbr' | 'lambert';
+  /**
+   * 颜色管线，透传给 `createStyledMaterial`。不传 = 读模块级默认。
+   * 由 `S3MTileset` 从图层的渲染 profile 带下来。
+   */
+  colorPipeline?: 'linear' | 'direct';
+  /**
+   * 纹理创建参数（sRGB 解码 / 尺寸上限 / 各向异性上限），透传给 `createTexture`。
+   * 不传 = 各自读模块级默认。同样由图层的渲染 profile 带下来。
+   */
+  textureOptions?: TextureCreateOptions;
 }
 
 export interface BuildTileResult {
@@ -426,7 +437,7 @@ export async function buildTileObjects(
       if (prevPixels >= (tex.width ?? 0) * (tex.height ?? 0)) continue;
       textureByCode.delete(key);
     }
-    const { texture, decoded } = await createTexture(tex);
+    const { texture, decoded } = await createTexture(tex, options.textureOptions);
     if (texture) {
       textureByCode.set(key, texture);
       usedTextureKeys.push(key);
@@ -550,6 +561,7 @@ export async function buildTileObjects(
       secMap,
       // 图层 / 数据集的档位；undefined 时 createStyledMaterial 自己回落到模块级默认
       materialQuality: options.materialQuality,
+      colorPipeline: options.colorPipeline,
     });
     // 用户配置的深度偏移（共面摩尔纹 / 重合面归属的人工定序，见 BuildTileOptions 注释）
     if (options.polygonOffset) {