deeptwins-engine-3d 0.1.69 → 0.1.71

package/dist/esm/particle/common.d.ts

@@ -0,0 +1,18 @@
+/// <reference path="../typings.d.ts" />
+import type { Matrix4 } from 'deeptwins-cesium';
+import type { BaseParticleOptions } from './BaseParticle';
+export interface BaseParticleInternalOptions {
+    modelMatrix?: Matrix4;
+    emitterModelMatrix?: Matrix4;
+}
+export declare const PARTICLE_INTERNAL_OPTIONS: unique symbol;
+type MatrixExternalOptions = {
+    modelMatrix?: Matrix4;
+    emitterModelMatrix?: Matrix4;
+};
+export declare const createInternalParticleOptions: <T extends BaseParticleOptions>(options: T, internalOptions: BaseParticleInternalOptions) => T & BaseParticleOptions & {
+    [PARTICLE_INTERNAL_OPTIONS]?: BaseParticleInternalOptions | undefined;
+};
+export declare const getInternalParticleOptions: (options: BaseParticleOptions) => BaseParticleInternalOptions | undefined;
+export declare const omitExternalMatrixOptions: <T extends BaseParticleOptions>(options: T) => T & MatrixExternalOptions;
+export {};

package/dist/esm/particle/common.js

@@ -0,0 +1,23 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+export var PARTICLE_INTERNAL_OPTIONS = Symbol('PARTICLE_INTERNAL_OPTIONS');
+export var createInternalParticleOptions = function createInternalParticleOptions(options, internalOptions) {
+  var nextOptions = _objectSpread({}, options);
+  Object.defineProperty(nextOptions, PARTICLE_INTERNAL_OPTIONS, {
+    value: internalOptions
+  });
+  return nextOptions;
+};
+export var getInternalParticleOptions = function getInternalParticleOptions(options) {
+  return options[PARTICLE_INTERNAL_OPTIONS];
+};
+export var omitExternalMatrixOptions = function omitExternalMatrixOptions(options) {
+  var safeOptions = _objectSpread({}, options);
+  delete safeOptions.modelMatrix;
+  delete safeOptions.emitterModelMatrix;
+  return safeOptions;
+};

package/dist/esm/particle/index.d.ts

@@ -0,0 +1,5 @@
+import BaseParticle from './BaseParticle';
+import FireParticle from './FireParticle';
+import FountainParticle from './FountainParticle';
+import SmokeParticle from './SmokeParticle';
+export { BaseParticle, FireParticle, FountainParticle, SmokeParticle };

package/dist/esm/particle/index.js

@@ -0,0 +1,5 @@
+import BaseParticle from "./BaseParticle";
+import FireParticle from "./FireParticle";
+import FountainParticle from "./FountainParticle";
+import SmokeParticle from "./SmokeParticle";
+export { BaseParticle, FireParticle, FountainParticle, SmokeParticle };

package/dist/esm/tileLayer/CustomRasterLayer.d.ts

@@ -0,0 +1,188 @@
+/// <reference path="../typings.d.ts" />
+import * as Cesium from 'deeptwins-cesium';
+import ImageryLayer from './ImageryLayer';
+/**
+ * CustomRasterLayer 是一个通用栅格瓦片图层：
+ * - 使用 Cesium.UrlTemplateImageryProvider 加载任意 URL 模板瓦片。
+ * - 使用 proj4 将瓦片范围和裁剪 GeoJSON 从 dataCrs 转到 renderCrs。
+ * - GCJ02 渲染时按 tileLayer/test 的瓦片坐标方案计算瓦片范围。
+ * - 可选按 GeoJSON 面要素裁剪瓦片。
+ * - 裁剪前先求瓦片 bbox 与裁剪面的交集，避免多面重叠时误裁。
+ * - 可选输出调试事件，便于排查范围、瓦片加载、裁剪和丢弃行为。
+ *
+ * @example 基础瓦片图层
+ * ```ts
+ * const layer = new DeepTwinsEngine3D.CustomRasterLayer({
+ *   id: 'base-raster',
+ *   source: {
+ *     url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+ *     minimumLevel: 0,
+ *     maximumLevel: 18,
+ *   },
+ *   debug: true,
+ * });
+ * map.imageryLayers.add(layer);
+ * ```
+ *
+ * @example 带范围、坐标转换和裁剪的图层
+ * ```ts
+ * const layer = new DeepTwinsEngine3D.CustomRasterLayer({
+ *   id: 'project-raster',
+ *   source: {
+ *     url: 'https://example.com/project/{z}/{x}/{y}.png',
+ *     maximumLevel: 20,
+ *   },
+ *   // bounds 格式：[minX, minY, maxX, maxY]，这里表示 EPSG:3857 米制范围。
+ *   bounds: [13210000, 3520000, 13230000, 3540000],
+ *   dataCrs: 'EPSG:3857',
+ *   renderCrs: 'EPSG:4326',
+ *   clipFeature: geoJsonPolygon,
+ *   debug: (event) => console.debug(event),
+ * });
+ * map.imageryLayers.add(layer);
+ * ```
+ *
+ * @remarks API 文档
+ * - `source`：必填，Cesium.UrlTemplateImageryProvider 原生配置。
+ * - `layerOptions`：可选，Cesium.ImageryLayer 原生配置。
+ * - `bounds`：可选，瓦片范围 `[minX, minY, maxX, maxY]`。
+ * - `dataCrs`：可选，bounds 与 clipFeature 的原始坐标系，默认 `EPSG:4326`。
+ * - `renderCrs`：可选，bounds、clipFeature 和瓦片范围转换后的目标坐标系，默认 `EPSG:4326`。
+ * - `projectionDefs`：可选，自定义 proj4 坐标系定义。
+ * - `clipFeature`：可选，GeoJSON Polygon/MultiPolygon/Feature/FeatureCollection。
+ * - `autoFitBounds`：可选，创建后自动将相机定位到最终范围，需同时传入 `map`。
+ * - `debug`：可选，`true` 使用 console.debug，函数则接收结构化调试事件。
+ */
+/** 通用范围格式：[minX, minY, maxX, maxY]。 */
+export type CustomRasterBounds = [number, number, number, number];
+/** 调试事件类型，覆盖范围初始化、瓦片加载和裁剪决策。 */
+export type CustomRasterLayerDebugEventType = 'range' | 'tile-loaded' | 'tile-kept' | 'tile-clipped' | 'tile-discarded' | 'tile-error';
+/** debug 回调收到的结构化事件。 */
+export type CustomRasterLayerDebugEvent = {
+    /** 事件类型。 */
+    type: CustomRasterLayerDebugEventType;
+    /** 图层 id。 */
+    layerId?: string;
+    /** 瓦片 x 坐标。 */
+    x?: number;
+    /** 瓦片 y 坐标。 */
+    y?: number;
+    /** 瓦片层级。 */
+    level?: number;
+    /** 当前瓦片范围，格式为 [west, south, east, north]。 */
+    bbox?: CustomRasterBounds;
+    /** 用户传入的原始瓦片范围。 */
+    bounds?: CustomRasterBounds;
+    /** bounds 转换到 renderCrs 后的瓦片范围。 */
+    tileBounds?: CustomRasterBounds;
+    /** clipFeature 转换到 renderCrs 后通过 turf.bbox 生成的裁剪范围。 */
+    clipBounds?: CustomRasterBounds;
+    /** 最终用于瓦片调度的渲染范围。 */
+    renderBounds?: CustomRasterBounds;
+    /** 原始数据坐标系。 */
+    dataCrs?: string;
+    /** bounds、clipFeature 和瓦片范围转换后的目标坐标系。 */
+    renderCrs?: string;
+    /** 裁剪或丢弃原因。 */
+    reason?: string;
+    /** 异常信息。 */
+    error?: unknown;
+    /** 瓦片图片尺寸。 */
+    imageSize?: {
+        width: number;
+        height: number;
+    };
+};
+/** debug 配置：关闭、console.debug 输出，或自定义事件处理函数。 */
+export type CustomRasterLayerDebug = boolean | ((event: CustomRasterLayerDebugEvent) => void);
+/** 内置切片方案名称，或 Cesium 原生 TilingScheme 实例。 */
+export type CustomRasterTilingSchemeOption = 'webMercator' | 'geographic' | Cesium.TilingScheme;
+/** CustomRasterLayer 数据源配置，扩展 tilingScheme 字符串默认选项。 */
+export type CustomRasterSourceOptions = Omit<Cesium.UrlTemplateImageryProvider.ConstructorOptions, 'tilingScheme'> & {
+    /** 切片方案，默认 webMercator，可传 geographic 或 Cesium.TilingScheme 实例。 */
+    tilingScheme?: CustomRasterTilingSchemeOption;
+};
+/** CustomRasterLayer 构造配置。 */
+export type CustomRasterLayerOptions = {
+    /** 图层 id，透传到实例，便于外部管理和 debug 标识。 */
+    id?: string;
+    /** 图层排序值，透传到实例，便于外部图层集合管理。 */
+    zIndex?: number;
+    /** Cesium.UrlTemplateImageryProvider 配置，tilingScheme 额外支持内置字符串名称。 */
+    source: CustomRasterSourceOptions;
+    /** Cesium.ImageryLayer 原生配置。 */
+    layerOptions?: Cesium.ImageryLayer.ConstructorOptions;
+    /** 瓦片范围，格式为 [minX, minY, maxX, maxY]，坐标系跟随 dataCrs。 */
+    bounds?: CustomRasterBounds;
+    /** bounds 和 clipFeature 的原始坐标系，默认 EPSG:4326。 */
+    dataCrs?: string;
+    /** bounds、clipFeature 和瓦片范围转换后的目标坐标系，默认 EPSG:4326。 */
+    renderCrs?: string;
+    /** 自定义 proj4 坐标系定义，key 可为 EPSG:xxxx 或其他 proj4 名称。 */
+    projectionDefs?: Record<string, string>;
+    /** 用于裁剪瓦片的 GeoJSON 面要素。 */
+    clipFeature?: any;
+    /** 地图实例，autoFitBounds 或手动 fitToBounds 时用于控制相机。 */
+    map?: any;
+    /** 是否创建后自动将相机定位到最终渲染范围，默认 false。 */
+    autoFitBounds?: boolean;
+    /** 自动定位到范围时透传给相机 flyTo 的配置，默认 { duration: 0 }。 */
+    fitBoundsOptions?: any;
+    /** 调试开关或自定义调试事件处理函数。 */
+    debug?: CustomRasterLayerDebug;
+};
+type TileImage = HTMLImageElement | HTMLCanvasElement | ImageBitmap;
+type RasterImagery = {
+    x: number;
+    y: number;
+    level: number;
+    rectangle: Cesium.Rectangle;
+    image: TileImage;
+};
+/**
+ * 通用自定义栅格图层。
+ *
+ * 继承项目现有 ImageryLayer 封装，内部使用 UrlTemplateImageryProvider。
+ * 若传入 clipFeature，会在 Cesium 创建纹理前用 canvas 对瓦片进行透明裁剪。
+ */
+export default class CustomRasterLayer extends ImageryLayer {
+    /** 图层 id，方便业务图层集合按 id 管理。 */
+    id?: string;
+    /** 图层层级，方便业务图层集合排序。 */
+    zIndex?: number;
+    /** Cesium 瓦片数据源实例。 */
+    readonly source: Cesium.UrlTemplateImageryProvider;
+    private readonly _debug?;
+    private readonly _clipFeatures;
+    private readonly _fitBounds?;
+    private _mapContext;
+    /** 创建通用栅格图层。 */
+    constructor(options: CustomRasterLayerOptions);
+    getMap(): any;
+    /** 将相机定位到当前图层最终渲染范围。 */
+    fitToBounds(map?: any, options?: any): this;
+    /**
+     * Cesium 内部纹理创建钩子。
+     *
+     * 这里按 tileLayer/test 的 ClipLayer 逻辑处理裁剪：
+     * - 完全在裁剪面内：原图保留。
+     * - 完全不相交：替换为空透明 canvas。
+     * - 部分相交：按瓦片与裁剪面的交集裁剪 canvas。
+     */
+    _createTexture(context: any, imagery: RasterImagery): any;
+    /** 调用 Cesium 原始纹理创建逻辑。 */
+    private createTexture;
+    /** 获取当前瓦片与所有裁剪面的交集，用交集路径裁剪当前瓦片。 */
+    private getClipIntersections;
+    /** 创建与当前瓦片同尺寸的透明 canvas。 */
+    private createTileCanvas;
+    /** 将地理坐标转换为当前瓦片画布像素坐标。 */
+    private pointToPixel;
+    /** 将裁剪后的 geometry 转换为画布 path 坐标数组。 */
+    private geometryToPathArray;
+    /** 按 path 坐标裁剪当前瓦片画布。 */
+    private clip;
+    /** 输出结构化 debug 事件。 */
+    private logDebug;
+}
+export {};