@terra.gl/core 0.0.1-alpha.66 → 0.0.1-alpha.68

package/dist/index.d.ts

@@ -677,6 +677,22 @@ export declare interface BasicPointStyle extends BaseStyle {
     sizeAttenuation?: boolean;
 }
 
+/**
+ * Camera follow configuration.
+ * 相机跟随配置
+ * @category Layer
+ */
+declare interface CameraFollowConfig {
+    /** Camera mode. 相机模式 */
+    mode: 'none' | 'first-person' | 'third-person';
+    /** Camera distance from target. 相机距离 */
+    distance?: number;
+    /** Camera polar angle (degrees, 0=top-down, 90=horizontal). 相机极角（度，0=俯视，90=水平） */
+    polarAngle?: number;
+    /** Camera smoothing factor (0-1). 相机平滑系数 */
+    smoothing?: number;
+}
+
 /** 类选项类型  * @category Core
  /** 类选项类型 */
 declare type ClassOptions_2 = Record<string, any>;
@@ -1091,6 +1107,24 @@ declare enum CollisionType {
  */
 export declare function concatenateTypedArrays<T extends TypedArray>(...typedArrays: T[]): T;
 
+/**
+ * Control point style configuration.
+ * 控制点样式配置
+ * @category Layer
+ */
+declare interface ControlPointStyle {
+    /** Control point type. 控制点类型 */
+    type?: 'point' | 'icon' | 'gif';
+    /** Color for point type. 点模式颜色 */
+    color?: string;
+    /** Size. 尺寸 */
+    size?: number;
+    /** Icon or GIF URL. 图标/GIF 地址 */
+    url?: string;
+    /** Sprite anchor [x, y], 0-1 range. Default [0.5, 0.5] = center. */
+    anchor?: [number, number];
+}
+
 /**
  * 转换整个geometry数据结构
  * @param geometryData - MVT解析出的 geometry 数据结构（包含 Vector2 对象）
@@ -5155,6 +5189,10 @@ declare abstract class OverlayLayer<T extends Feature = Feature> extends Layer {
      * 清空图层中的所有要素
      * @returns this
      */
+    /**
+     * 清空图层中的所有要素
+     * @returns this
+     */
     clear(): this;
     /**
      * Handler when removing a feature.
@@ -6971,6 +7009,349 @@ export declare type TPointsOptions = PointOptions & {
     geometries?: any;
 };
 
+/**
+ * Trail line style configuration.
+ * 轨迹线样式配置
+ * @category Layer
+ */
+declare interface TrailLineStyle {
+    color?: string;
+    width?: number;
+    opacity?: number;
+}
+
+/**
+ * Trajectory input data.
+ * 轨迹输入数据
+ * @category Layer
+ */
+export declare interface TrajectoryData {
+    /** Array of trajectory points. 轨迹点数组 */
+    points: TrajectoryPoint[];
+    /** Optional total duration override (ms). 可选总时长覆盖 */
+    duration?: number;
+}
+
+/**
+ * TrajectoryLayer - Trajectory playback layer.
+ * 轨迹图层 - 轨迹回放图层
+ *
+ * @description
+ * Provides trajectory visualization with playback control, speed adjustment,
+ * time display, control points, and first/third-person camera follow.
+ *
+ * 提供轨迹可视化，支持回放控制、速度调节、时间显示、控制点、
+ * 第一/第三人称相机跟随。
+ *
+ * @extends Layer
+ * @category Layer
+ */
+export declare class TrajectoryLayer extends Layer {
+    private _trailLine;
+    private _activeLine;
+    private _marker;
+    private _controlPointGroup;
+    private _timeLabels;
+    private _points;
+    private _worldPoints;
+    private _timestamps;
+    private _totalDuration;
+    private _state;
+    private _currentTime;
+    private _playbackSpeed;
+    private _loop;
+    private _cameraMode;
+    private _cameraConfig;
+    private _prevControlsEnabled;
+    private _options;
+    private _gifStates;
+    /**
+     * Create a TrajectoryLayer instance.
+     * 创建轨迹图层实例
+     *
+     * @param id Layer unique ID. 图层唯一标识
+     * @param data Trajectory data. 轨迹数据
+     * @param options Layer options. 图层配置
+     */
+    constructor(id: string, data?: TrajectoryData, options?: TrajectoryLayerOptions);
+    /**
+     * Override _bindMap to build geometry when map is available.
+     * 重写 _bindMap，在地图可用时构建几何体
+     */
+    _bindMap(map: Map_2): void;
+    /**
+     * Set or replace trajectory data.
+     * 设置或替换轨迹数据
+     *
+     * @param data Trajectory data. 轨迹数据
+     */
+    setData(data: TrajectoryData): void;
+    /**
+     * Internal data setup (no geometry build).
+     */
+    private _setDataInternal;
+    /**
+     * Start or resume playback.
+     * 开始或恢复播放
+     */
+    play(): void;
+    /**
+     * Pause playback.
+     * 暂停播放
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to start.
+     * 停止播放并重置到起点
+     */
+    stop(): void;
+    /**
+     * Seek to a specific time.
+     * 跳转到指定时间
+     *
+     * @param timeMs Time in milliseconds from start. 从起点开始的毫秒数
+     */
+    seekTo(timeMs: number): void;
+    /**
+     * Set playback speed multiplier.
+     * 设置播放速度倍率
+     *
+     * @param multiplier Speed multiplier (1 = normal). 速度倍率
+     */
+    setSpeed(multiplier: number): void;
+    /**
+     * Set loop mode.
+     * 设置循环模式
+     *
+     * @param enabled Whether to loop. 是否循环
+     */
+    setLoop(enabled: boolean): void;
+    /**
+     * Show or hide control points.
+     * 显示或隐藏控制点
+     *
+     * @param visible Whether to show control points. 是否显示控制点
+     */
+    setShowControlPoints(visible: boolean): void;
+    /**
+     * Show or hide time labels.
+     * 显示或隐藏时间标签
+     *
+     * @param visible Whether to show time labels. 是否显示时间标签
+     */
+    setShowTimeLabels(visible: boolean): void;
+    /**
+     * Set camera follow mode.
+     * 设置相机跟随模式
+     *
+     * @param mode Camera mode. 相机模式
+     * @param config Optional camera config override. 可选相机配置覆盖
+     */
+    setCameraMode(mode: 'none' | 'first-person' | 'third-person', config?: Partial<CameraFollowConfig>): void;
+    /**
+     * Get current playback time (ms from start).
+     * 获取当前播放时间
+     */
+    getCurrentTime(): number;
+    /**
+     * Get total duration (ms).
+     * 获取总时长
+     */
+    getDuration(): number;
+    /**
+     * Get current playback state.
+     * 获取当前播放状态
+     */
+    getPlaybackState(): 'idle' | 'playing' | 'paused';
+    /**
+     * Get current speed multiplier.
+     * 获取当前速度倍率
+     */
+    getSpeed(): number;
+    /**
+     * Per-frame animation update.
+     * 每帧动画更新
+     *
+     * @param delta Frame delta time (seconds). 帧间隔时间（秒）
+     * @param elapsedtime Total elapsed time (seconds). 累计时间（秒）
+     * @param context Viewer instance. Viewer 实例
+     */
+    protected animate(delta: number, _elapsedtime: number, context: Viewer): void;
+    /**
+     * Build all visual elements.
+     * 构建所有视觉元素
+     */
+    private _buildAll;
+    /**
+     * Transform geographic coordinates to world coordinates relative to prjcenter.
+     * 将地理坐标转换为相对于 prjcenter 的世界坐标
+     */
+    private _transformCoordinates;
+    /**
+     * Build the full trail line (static).
+     * 构建完整轨迹线（静态）
+     */
+    private _buildTrailLine;
+    /**
+     * Build the active (traveled) trail line (dynamic).
+     * 构建已走轨迹线（动态）
+     */
+    private _buildActiveLine;
+    /**
+     * Build the moving marker.
+     * 构建移动标记
+     */
+    private _buildMarker;
+    /**
+     * Build control points.
+     * 构建控制点
+     */
+    private _buildControlPoints;
+    /**
+     * Create a GIF animated control point.
+     * 创建 GIF 动图控制点
+     */
+    private _createGifControlPoint;
+    /**
+     * Update GIF textures each frame.
+     * 每帧更新 GIF 纹理
+     *
+     * Note: Browsers animate GIFs automatically in <img> elements.
+     * drawImage() draws the current frame of the animated GIF.
+     * We just need to periodically redraw and flag texture update.
+     */
+    private _updateGifTextures;
+    /**
+     * Build time labels using UIMarker.
+     * 使用 UIMarker 构建时间标签
+     */
+    private _buildTimeLabels;
+    /**
+     * Update all visuals to match current time.
+     * 更新所有视觉元素以匹配当前时间
+     */
+    private _updateVisuals;
+    /**
+     * Update marker position via interpolation.
+     * 通过插值更新标记位置
+     */
+    private _updateMarkerPosition;
+    /**
+     * Update the active trail line.
+     * 更新已走轨迹线
+     */
+    private _updateActiveLine;
+    /**
+     * Interpolate position at a given time offset.
+     * 在给定时间偏移处插值位置
+     *
+     * @param timeMs Time offset from start (ms). 从起点开始的时间偏移
+     * @returns Interpolated world position (relative to prjcenter). 插值世界坐标
+     */
+    private _interpolatePosition;
+    /**
+     * Compute heading angle from trajectory direction.
+     * 从轨迹方向计算航向角
+     */
+    private _computeCurrentHeading;
+    /**
+     * Update camera for follow mode.
+     * 更新相机跟随
+     *
+     * First-person: Camera behind the marker, nearly horizontal,
+     *               looking at the marker as it moves forward.
+     * 第一视角：相机在控制点后方，接近水平，看着控制点前进。
+     *
+     * Third-person: Camera high above and behind, looking down at marker.
+     * 第三视角：相机在控制点上方偏后，俯视控制点。
+     */
+    private _updateCamera;
+    /**
+     * Dispose all visual elements.
+     * 销毁所有视觉元素
+     */
+    private _disposeAll;
+    private _disposeTrailLine;
+    private _disposeActiveLine;
+    private _disposeMarker;
+    private _disposeControlPoints;
+    private _disposeTimeLabels;
+    private _disposeGifStates;
+    private _removeResizeHandler;
+    /**
+     * Emit a custom event.
+     * 触发自定义事件
+     */
+    private _emitEvent;
+    /**
+     * Destroy the layer and clean up all resources.
+     * 销毁图层并清理所有资源
+     */
+    destroy(): void;
+}
+
+/**
+ * TrajectoryLayer options.
+ * 轨迹图层配置项
+ * @category Layer
+ */
+export declare interface TrajectoryLayerOptions extends LayerOptions {
+    /** Full trail line style. 完整轨迹线样式 */
+    trailStyle?: TrailLineStyle;
+    /** Active (traveled) trail line style. 已走轨迹线样式 */
+    activeTrailStyle?: TrailLineStyle;
+    /** Moving marker style. 移动标记样式 */
+    markerStyle?: TrajectoryMarkerStyle;
+    /** Whether to show control points. 是否显示控制点 */
+    showControlPoints?: boolean;
+    /** Control point style. 控制点样式 */
+    controlPointStyle?: ControlPointStyle;
+    /** Whether to show time labels. 是否显示时间标签 */
+    showTimeLabels?: boolean;
+    /** Custom time format function. 自定义时间格式化函数 */
+    timeFormat?: (timestamp: number) => string;
+    /** Custom time label HTML renderer. Returns full HTML string. 自定义时间标签渲染函数，返回完整 HTML */
+    timeLabelContent?: (timestamp: number) => string;
+    /** Initial playback speed multiplier. 初始播放速度 */
+    speed?: number;
+    /** Whether to loop playback. 是否循环播放 */
+    loop?: boolean;
+    /** Camera follow configuration. 相机跟随配置 */
+    cameraFollow?: CameraFollowConfig;
+}
+
+/**
+ * Moving marker style configuration.
+ * 移动标记样式配置
+ * @category Layer
+ */
+declare interface TrajectoryMarkerStyle {
+    /** Marker type: 'point' for sphere, 'icon' for sprite. */
+    type?: 'point' | 'icon';
+    /** Icon URL (for icon type). 图标地址 */
+    url?: string;
+    /** Marker size. 标记尺寸 */
+    size?: number;
+    /** Marker color (for point type). 标记颜色 */
+    color?: string;
+    /** Sprite anchor [x, y], 0-1 range. Default [0.5, 0.5] = center. [0.5, 0] = bottom-center. */
+    anchor?: [number, number];
+}
+
+/**
+ * Trajectory point data.
+ * 轨迹点数据
+ * @category Layer
+ */
+export declare interface TrajectoryPoint {
+    /** Geographic coordinate [lng, lat, alt?]. 地理坐标 */
+    coordinate: [number, number, number?];
+    /** Timestamp in milliseconds. 时间戳（毫秒） */
+    timestamp: number;
+    /** Extra metadata. 附加属性 */
+    properties?: Record<string, any>;
+}
+
 /**
  * Tile event map
  * 瓦片事件映射
@@ -7494,6 +7875,19 @@ export declare class VectorTileLayer extends BaseTileLayer {
     private _bindRendererEvents;
     _setRenderer(renderer: VectorTileRenderLayer): void;
     _getRenderer(): VectorTileRenderLayer;
+    /**
+     * 获取 processTileData 处理统计信息
+     */
+    getProcessStats(): {
+        totalTime: number;
+        processCount: number;
+        totalFeatures: number;
+        avgTime: number;
+    } | null;
+    /**
+     * 重置 processTileData 统计信息
+     */
+    resetProcessStats(): void;
     getStyle(): any;
     /**
      * Update layer style configuration dynamically.
@@ -7581,7 +7975,7 @@ declare class VectorTileRenderLayer extends OverlayLayer<Feature> {
     interactive: boolean;
     /**
      * Store Features corresponding to each tile for lifecycle management and updates.
-     * 存储每个瓦片对应的 Features，用于管理生命周期和更新。
+     * 存储每个瓦片对应的 Features，用于管理生命周期和优化。
      * @private
      */
     private _tileFeatureMap;
@@ -7591,6 +7985,42 @@ declare class VectorTileRenderLayer extends OverlayLayer<Feature> {
      * @private
      */
     private _activeFeatureFilter?;
+    /**
+     * 样式规则按 layerName 分组缓存，避免每次都遍历所有规则
+     * @private
+     */
+    private _layerStyleMapCache;
+    private _lastBuiltStyleMap;
+    /**
+     * 已添加的 feature uuid 集合，用于 O(1) 查找
+     * @private
+     */
+    private _addedFeatureIds;
+    /**
+     * Style 实例缓存，相同配置的 Style 共享实例
+     * @private
+     */
+    private _styleInstanceCache;
+    /**
+     * processTileData 累计处理时间（仅统计新建，不含缓存命中）
+     * @private
+     */
+    private _totalProcessTime;
+    private _processCount;
+    private _totalFeatureCount;
+    /**
+     * 获取 processTileData 处理统计信息
+     */
+    getProcessStats(): {
+        totalTime: number;
+        processCount: number;
+        totalFeatures: number;
+        avgTime: number;
+    };
+    /**
+     * 重置统计信息
+     */
+    resetProcessStats(): void;
     constructor(id: string, options: VectorTileRenderLayerOptions);
     /**
      * **Core Method:** Process single tile data, create Features based on global style rules array.
@@ -7611,6 +8041,11 @@ declare class VectorTileRenderLayer extends OverlayLayer<Feature> {
      * @returns {boolean} Whether it matches. 是否匹配。
      */
     private _evaluateFilter;
+    /**
+     * 构建 layerName -> 样式规则数组 的映射
+     * @private
+     */
+    private _buildLayerStyleMap;
     /**
      * Hide Features of a tile (do not destroy).
      * Used for tile-hidden event.