@soonspacejs/plugin-tiles 2.14.29 → 2.14.30

package/dist/terrain-tiles-renderer/types.d.ts

@@ -0,0 +1,295 @@
+import { WMTSTileMatrixSet, WMTSLayer } from 'um-3d-tiles-renderer/src/three/plugins/loaders/WMTSCapabilitiesLoader';
+import { Matrix4 } from 'three';
+/**
+ * Cesium Ion 地形配置
+ */
+export interface ICesiumIonOptions {
+    /** Cesium Ion API Token */
+    apiToken: string;
+    /** Asset ID，默认 '1' (Cesium World Terrain) */
+    assetId?: string;
+    /** 是否自动刷新 Token，默认 true */
+    autoRefreshToken?: boolean;
+}
+/**
+ * 重定向配置（将地球某点移动到场景原点）
+ */
+export interface IReorientationOptions {
+    /** 经度 */
+    lon: number;
+    /** 纬度 */
+    lat: number;
+    /** 高度，默认 0.1 */
+    height?: number;
+}
+/**
+ * Alpha 裁剪模式
+ * - alphaTest: 使用 alphaTest 进行硬边裁剪，不需要深度排序（推荐用于 mask）
+ * - transparent: 使用透明混合（可能需要深度排序）
+ * - alphaToCoverage: 使用 alphaToCoverage（需要 MSAA，效果较平滑）
+ */
+export type AlphaClipMode = 'alphaTest' | 'transparent' | 'alphaToCoverage';
+/**
+ * TerrainTilesRenderer 配置选项
+ */
+export interface ITerrainTilesRendererOptions {
+    /**
+     * 基础地形 URL
+     * - 默认使用内置的地形服务
+     */
+    baseUrl?: string;
+    /**
+     * 影像叠加层 URL
+     * - 默认使用 OpenStreetMap
+     * - 设置为 false 可禁用影像叠加层
+     */
+    imageryUrl?: string | false;
+    /**
+     * 重定向配置
+     * - 将地球上指定经纬度的点移动到场景原点
+     * - 默认 { lon: 120, lat: 30 }
+     */
+    reorientation?: IReorientationOptions | false;
+    /**
+     * 是否使用自定义材质（MeshBasicMaterial）
+     * - 默认 true
+     */
+    useCustomMaterial?: boolean;
+    /**
+     * 最大深度，默认 20
+     */
+    maxDepth?: number;
+    /**
+     * 误差目标，默认 1
+     */
+    errorTarget?: number;
+    /**
+     * Alpha 裁剪模式
+     * - 用于支持 GeoJSON mask 功能
+     * - 默认 'alphaTest'
+     */
+    alphaClipMode?: AlphaClipMode;
+}
+/**
+ * Overlay 基础配置
+ */
+export interface IOverlayBaseOptions {
+    /** 唯一标识符 */
+    id: string;
+    /** 颜色 */
+    color?: number | string;
+    /** 透明度 */
+    opacity?: number;
+    /** 层级顺序（数值越大越靠上），默认按添加顺序 */
+    order?: number;
+}
+/**
+ * GeoJSON Overlay 配置
+ */
+export interface IGeoJSONOverlayOptions extends IOverlayBaseOptions {
+    /** GeoJSON 文件 URL 或 GeoJSON 数据对象 */
+    url?: string;
+    geojson?: object;
+    /** 填充样式 */
+    fillStyle?: string;
+    /** 描边样式: 颜色设置参考  https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/strokeStyle*/
+    strokeStyle?: string;
+    /** 描边宽度 */
+    strokeWidth?: number;
+}
+/**
+ * Cesium Ion Overlay 配置
+ */
+export interface ICesiumIonOverlayOptions extends IOverlayBaseOptions {
+    /** Cesium Ion 资源 ID */
+    assetId: string;
+    /** Cesium Ion API Token */
+    apiToken: string;
+    /** 是否自动刷新 Token */
+    autoRefreshToken?: boolean;
+}
+/**
+ * TMS Tiles Overlay 配置
+ */
+export interface ITMSTilesOverlayOptions extends IOverlayBaseOptions {
+    /** TMS 服务 URL */
+    url: string;
+}
+/**
+ * XYZ Tiles Overlay 配置
+ */
+export interface IXYZTilesOverlayOptions extends IOverlayBaseOptions {
+    /** XYZ 服务 URL */
+    url: string;
+}
+/**
+ * URL Template Overlay 配置
+ *
+ * 支持的 URL 模板变量:
+ * - `{z}` - 缩放级别
+ * - `{x}` - 瓦片 X 坐标
+ * - `{y}` - 瓦片 Y 坐标
+ * - `{s}` - 子域名（从 subdomains 列表轮换）
+ * - `{reverseX}` - 从东向西的瓦片 X
+ * - `{reverseY}` - 从底部向上的瓦片 Y（TMS 风格）
+ * - `{reverseZ}` - 反转的缩放级别
+ * - `{westDegrees}`, `{southDegrees}`, `{eastDegrees}`, `{northDegrees}` - 瓦片边界框（度）
+ * - `{westProjected}`, `{southProjected}`, `{eastProjected}`, `{northProjected}` - 瓦片边界框（投影坐标）
+ * - `{width}`, `{height}` - 瓦片像素尺寸
+ */
+export interface IUrlTemplateOverlayOptions extends IOverlayBaseOptions {
+    /**
+     * URL 模板，支持上述变量
+     * 例如: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
+     */
+    url: string;
+    /**
+     * 子域名列表，用于 {s} 占位符轮换
+     * 可以是字符串（每个字符是一个子域）或字符串数组
+     * 默认: 'abc'
+     */
+    subdomains?: string | string[];
+    /**
+     * 缩放级别数量，或每级配置对象数组
+     * 默认: 20
+     */
+    levels?: number | object[];
+    /**
+     * 瓦片像素尺寸
+     * 默认: 256
+     */
+    tileDimension?: number;
+    /**
+     * 投影标识符
+     * 支持: 'EPSG:3857' (Web Mercator) 或 'EPSG:4326' (WGS84)
+     * 默认: 'EPSG:3857'
+     */
+    projection?: 'EPSG:3857' | 'EPSG:4326';
+    /**
+     * 内容边界框（度）[west, south, east, north]
+     * 如果为 null，则使用完整投影范围
+     */
+    contentBoundingBox?: [number, number, number, number] | null;
+    /**
+     * 自定义模板变量
+     * 每个键映射到静态字符串或函数 (x, y, level) => value
+     */
+    customTags?: Record<string, string | ((x: number, y: number, level: number) => string)> | null;
+}
+/**
+ * WMS Tiles Overlay 配置
+ */
+export interface IWMSTilesOverlayOptions extends IOverlayBaseOptions {
+    /** WMS 服务基础 URL */
+    url: string;
+    /** 图层名称 */
+    layer: string;
+    /** 样式 */
+    styles?: string;
+    /** 坐标系 */
+    crs?: string;
+    /** 图片格式 */
+    format?: string;
+    /** 瓦片尺寸 */
+    tileDimension?: number;
+}
+/**
+ * WMTS Tiles Overlay 配置
+ */
+export interface IWMTSTilesOverlayOptions extends IOverlayBaseOptions {
+    /** WMTS 服务 URL */
+    url: string;
+    /** 图层标识符 */
+    layer?: WMTSLayer | string | null;
+    /** 维度 */
+    dimensions?: {
+        [key: string]: any;
+    } | null;
+    /** 瓦片矩阵集 */
+    tileMatrixSet?: WMTSTileMatrixSet | string | null;
+    /** 样式 */
+    style?: string;
+    /** 帧 */
+    frame?: Matrix4 | null;
+}
+/**
+ * Overlay 类型枚举
+ */
+export declare enum OverlayType {
+    GEOJSON = "geojson",
+    CESIUM_ION = "cesiumIon",
+    TMS = "tms",
+    XYZ = "xyz",
+    WMS = "wms",
+    WMTS = "wmts",
+    URL_TEMPLATE = "urlTemplate"
+}
+/**
+ * Overlay 存储项
+ */
+export interface IOverlayItem<T = any> {
+    id: string;
+    type: OverlayType;
+    options: T;
+    instance: any;
+}
+/**
+ * 地形源类型
+ */
+export declare enum TerrainType {
+    /** 量化网格地形（layer.json 格式） */
+    QUANTIZED_MESH = "quantizedMesh",
+    /** Cesium Ion 地形 */
+    CESIUM_ION = "cesiumIon"
+}
+/**
+ * 量化网格地形配置
+ */
+export interface IQuantizedMeshTerrainOptions {
+    /** 地形服务 URL */
+    url: string;
+}
+/**
+ * 地形源基础配置
+ */
+export interface ITerrainSourceBase {
+    /** 唯一标识符 */
+    id: string;
+}
+/**
+ * 量化网格地形源
+ */
+export interface IQuantizedMeshTerrainSource extends ITerrainSourceBase {
+    type: TerrainType.QUANTIZED_MESH;
+    options: IQuantizedMeshTerrainOptions;
+}
+/**
+ * Cesium Ion 地形源
+ */
+export interface ICesiumIonTerrainSource extends ITerrainSourceBase {
+    type: TerrainType.CESIUM_ION;
+    options: ICesiumIonOptions;
+}
+/**
+ * 地形源联合类型
+ */
+export type ITerrainSource = IQuantizedMeshTerrainSource | ICesiumIonTerrainSource;
+/**
+ * 地形源存储项
+ */
+export interface ITerrainItem {
+    id: string;
+    type: TerrainType;
+    source: ITerrainSource;
+}
+/**
+ * 地形配置（用于 setTerrain）
+ */
+export type ITerrainConfig = {
+    id: string;
+    type: TerrainType.QUANTIZED_MESH;
+    url: string;
+} | {
+    id: string;
+    type: TerrainType.CESIUM_ION;
+} & ICesiumIonOptions;

package/dist/tiles-renderer/TilesRenderer.d.ts

@@ -0,0 +1,120 @@
+import { Object3D } from 'three';
+import { TilesRenderer as TilesInstance } from 'um-3d-tiles-renderer';
+import { TilesFadePlugin, UpdateOnChangePlugin, ReorientationPlugin } from 'um-3d-tiles-renderer/plugins';
+import { default as SoonSpace } from 'soonspacejs';
+import { IReorientationOptions } from '..';
+export declare const MaterialType: {
+    readonly DEFAULT: 0;
+    readonly GRADIENT: 1;
+    readonly TOPOGRAPHIC_LINES: 2;
+    readonly LIGHTING: 3;
+};
+export type MaterialTypeValue = (typeof MaterialType)[keyof typeof MaterialType];
+export interface ITilesRendererBaseOptions {
+    /** 重定向配置 */
+    reorientation?: IReorientationOptions;
+    /**
+     * 是否使用自定义材质（MeshBasicMaterial）
+     * - 默认 false
+     */
+    useCustomMaterial?: boolean;
+    /**
+     * 是否自动将模型居中到原点
+     * - 默认 true
+     */
+    autoCenter?: boolean;
+    /**
+     * 最大深度，默认 20
+     */
+    maxDepth?: number;
+    /**
+     * 误差目标，默认 2
+     */
+    errorTarget?: number;
+    /**
+     * 内部使用：由 TilesRendererManager 管理时设为 true
+     * @internal
+     */
+    _managedByPlugin?: boolean;
+}
+export interface ITilesRendererOptions extends ITilesRendererBaseOptions {
+    /** 3D Tiles 地址 */
+    url: string;
+}
+export interface ICesiumIonOptions extends ITilesRendererBaseOptions {
+    /** Cesium Ion API Token */
+    apiToken: string;
+    /** Asset ID*/
+    assetId: string;
+    /** 是否自动刷新 Token，默认 true */
+    autoRefreshToken?: boolean;
+}
+export declare class TilesRenderer {
+    readonly ssp: SoonSpace;
+    tiles: TilesInstance;
+    tilesFadePlugin: TilesFadePlugin;
+    updateOnChangePlugin: UpdateOnChangePlugin;
+    reorientationPlugin?: ReorientationPlugin;
+    options: ITilesRendererOptions | ICesiumIonOptions;
+    private _box;
+    private _sphere;
+    private _materialType;
+    private _needsUpdate;
+    private _cameraTransitionStart;
+    loedTilesSets: Set<() => void>;
+    constructor(ssp: SoonSpace, options: ITilesRendererOptions | ICesiumIonOptions);
+    /**
+     * 初始化 Cesium Ion 插件
+     */
+    private _initCesiumIon;
+    /**
+     * 初始化基础插件
+     */
+    private _initBasePlugins;
+    /**
+     * 设置 GLTF Loader
+     */
+    private _setupGLTFLoader;
+    /**
+     * 设置相机过渡事件监听
+     */
+    private _setupCameraTransitionEvents;
+    /**
+     * 按需渲染回调
+     */
+    private _onNeedsRender;
+    /**
+     * 获取当前材质类型
+     */
+    get materialType(): MaterialTypeValue;
+    /**
+     * 设置材质类型
+     */
+    set materialType(value: MaterialTypeValue);
+    /**
+     * 模型加载时保存原始材质
+     */
+    onLoadModel: ({ scene, }: {
+        scene: Object3D;
+    }) => void;
+    /**
+     * 更新场景中所有网格的材质（参考 customMaterial.js）
+     */
+    updateMaterial: (scene: Object3D) => void;
+    onDisposeModel: ({ scene, }: {
+        scene: Object3D;
+    }) => void;
+    /**
+     * 应用自动居中逻辑
+     */
+    applyAutoCenter(): void;
+    /**
+     * 每帧渲染前的处理
+     */
+    beforeRenderHandler: () => void;
+    render: () => void;
+    enable(): void;
+    disable(): void;
+    invalidate(lon: number, lat: number, alt: number): () => void;
+    dispose(): void;
+}

package/dist/tiles-renderer/TilesRendererManager.d.ts

@@ -0,0 +1,51 @@
+import { default as SoonSpace } from 'soonspacejs';
+import { TilesRenderer, ITilesRendererOptions, ICesiumIonOptions } from './TilesRenderer';
+/**
+ * TilesRendererManager - 管理多个 TilesRenderer 实例
+ * 参考 TilesPlugin 的设计
+ */
+export declare class TilesRendererManager {
+    readonly ssp: SoonSpace;
+    /** 存储多个 tiles 实例，key 为 url */
+    tilesMap: Map<string, TilesRenderer>;
+    /** 按需渲染标志 */
+    needsUpdate: boolean;
+    cameraTransitionStart: boolean;
+    private _tilesCamera;
+    private _lruCache;
+    private _parseQueue;
+    private _downloadQueue;
+    constructor(ssp: SoonSpace);
+    private _beforeRenderHandler;
+    private _onCameraObjectChange;
+    /**
+     * 加载 3D Tiles
+     * @param url - tileset.json 地址
+     * @param options - 配置项
+     * @returns Promise<ThreeDTilesRenderer>
+     */
+    loadTiles(options: ITilesRendererOptions | ICesiumIonOptions): Promise<TilesRenderer | undefined>;
+    /**
+     * 移除 3D Tiles
+     * @param url - tileset.json 地址
+     * @returns boolean
+     */
+    removeTiles(url: string): boolean;
+    /**
+     * 获取指定 url 的 renderer
+     */
+    getTiles(url: string): TilesRenderer | undefined;
+    /**
+     * 获取所有已加载的 renderer
+     */
+    getAllTiles(): TilesRenderer[];
+    /**
+     * 清除所有 tiles
+     */
+    clear(): void;
+    invalidate(lon: number, lat: number, alt: number): void;
+    /**
+     * 销毁插件
+     */
+    dispose(): void;
+}

package/docs/cesium-ion-terrain-white-spots.md

@@ -0,0 +1,90 @@
+# Cesium Ion 地形渲染白色斑点问题
+
+## 问题描述
+
+使用 Cesium Ion 地形（assetId: '1'）时，渲染结果出现白色高光斑点，类似 Phong 材质的镜面反射效果。而使用自定义 QuantizedMesh 地形时没有此问题。
+
+## 原因分析
+
+Cesium Ion World Terrain 返回的地形网格使用了 PBR 材质（`MeshStandardMaterial`），其中包含金属度（metalness）属性。当场景没有正确的环境贴图时，PBR 材质的光照计算会产生异常的高光反射。
+
+自定义地形服务通常使用更简单的材质设置（metalness = 0），因此不会出现此问题。
+
+## 解决方案
+
+### 方案一：设置场景环境贴图（推荐）
+
+为场景添加一个简单的白色环境贴图，使 PBR 材质能正确计算光照：
+
+```typescript
+import { DataTexture, EquirectangularReflectionMapping } from 'three'
+
+// 在初始化时设置
+const env = new DataTexture(new Uint8Array(64 * 64 * 4).fill(255), 64, 64)
+env.mapping = EquirectangularReflectionMapping
+env.needsUpdate = true
+scene.environment = env
+```
+
+在 soonspacejs 中：
+
+```typescript
+const env = new DataTexture(new Uint8Array(64 * 64 * 4).fill(255), 64, 64)
+env.mapping = EquirectangularReflectionMapping
+env.needsUpdate = true
+this.ssp.scene.environment = env
+```
+
+### 方案二：重置材质金属度
+
+在模型加载回调中强制重置材质的金属度和粗糙度：
+
+```typescript
+tiles.addEventListener('load-model', (event) => {
+  event.scene.traverse((c) => {
+    if (c.material) {
+      // 消除金属反射
+      if (c.material.metalness !== undefined) {
+        c.material.metalness = 0
+        c.material.roughness = 1
+        c.material.needsUpdate = true
+      }
+    }
+  })
+})
+```
+
+## 方案对比
+
+| 方案 | 优点 | 缺点 |
+|------|------|------|
+| 环境贴图 | 保留 PBR 材质效果，渲染更自然 | 需要额外设置 |
+| 重置金属度 | 简单直接 | 失去 PBR 材质的真实感 |
+
+## 调试方法
+
+打印材质属性以确认问题：
+
+```typescript
+tiles.addEventListener('load-model', (event) => {
+  event.scene.traverse((c) => {
+    if (c.material) {
+      console.log('Material:', {
+        type: c.material.type,
+        metalness: c.material.metalness,
+        roughness: c.material.roughness,
+      })
+    }
+  })
+})
+```
+
+## 相关文件
+
+- `TilesRenderer.ts` - 主渲染器类
+- `TileCustomMaterialPlugin.ts` - 自定义材质插件
+
+## 参考
+
+- [um-3d-tiles-renderer ionExample.js](https://github.com/NASA-AMMOS/3DTilesRendererJS/blob/main/example/ionExample.js)
+- [Three.js MeshStandardMaterial](https://threejs.org/docs/#api/en/materials/MeshStandardMaterial)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soonspacejs/plugin-tiles",
   "pluginName": "TilesPlugin",
-  "version": "2.14.29",
+  "version": "2.14.30",
   "description": "3D Tiles plugin for SoonSpace.js",
   "main": "dist/index.esm.js",
   "module": "dist/index.esm.js",
@@ -16,7 +16,7 @@
   "license": "UNLICENSED",
   "gitHead": "4a87dd85050651088e11c3da777c49fab3db7e5d",
   "peerDependencies": {
-    "3d-tiles-renderer": "0.4.19",
-    "soonspacejs": "2.14.29"
+    "um-3d-tiles-renderer": "^0.4.21",
+    "soonspacejs": "2.14.30"
   }
 }