gl-draw 0.17.12 → 0.18.1

package/dist/index.d.ts

@@ -1,13 +1,14 @@
-import { Box3 } from 'three';
+import { AmbientLight } from 'three';
 import { BufferGeometry } from 'three';
 import { BufferGeometryEventMap } from 'three';
-import { BufferGeometryLoader } from 'three';
 import { Camera } from 'three';
 import { Color } from 'three';
 import { ColorRepresentation } from 'three';
 import { CSS2DObject } from 'three/examples/jsm/renderers/CSS2DRenderer.js';
 import { CSS2DRenderer } from 'three/examples/jsm/renderers/CSS2DRenderer.js';
+import { CSS3DObject } from 'three/examples/jsm/renderers/CSS3DRenderer.js';
 import { CSS3DRenderer } from 'three/examples/jsm/renderers/CSS3DRenderer.js';
+import { CSS3DSprite } from 'three/examples/jsm/renderers/CSS3DRenderer.js';
 import { DataTexture } from 'three';
 import { default as default_2 } from 'stats-gl';
 import { DirectionalLight } from 'three';
@@ -19,11 +20,12 @@ import { ExtrudeGeometryOptions as ExtrudeGeometryOptions_2 } from 'three';
 import { geoEquirectangular } from 'd3-geo';
 import { geoMercator } from 'd3-geo';
 import { GeoProjection } from 'd3-geo';
+import { Group } from 'three';
 import { HemisphereLight } from 'three';
+import { InstancedMesh } from 'three';
 import { Intersection } from 'three';
 import { Layers } from 'three';
 import { LineMaterial as Line2Material } from 'three/examples/jsm/lines/LineMaterial.js';
-import { LineMaterialParameters } from 'three/examples/jsm/lines/LineMaterial.js';
 import { LineSegmentsGeometry } from 'three/examples/jsm/lines/LineSegmentsGeometry.js';
 import { LoadingManager } from 'three';
 import { Material } from 'three';
@@ -34,6 +36,7 @@ import { MeshStandardMaterial } from 'three';
 import { NormalBufferAttributes } from 'three';
 import { Object3D } from 'three';
 import { Object3DEventMap } from 'three';
+import { Object3DJSON } from 'three';
 import { OrthographicCamera } from 'three';
 import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js';
 import { PerspectiveCamera } from 'three';
@@ -89,6 +92,13 @@ declare const ACTION: Readonly<{
 
 declare type ACTION = number;
 
+export declare class AmbientLightObject extends BaseObject<AmbientLight> {
+    objectType: string;
+    constructor(lightOrColor?: AmbientLight | string | number, intensity?: number);
+}
+
+declare function analyzeSceneJsonSize(sceneJson: any): void;
+
 declare function applyTextureColorSpace({ node, material, texture, }: ColorCorrectionOptions): void;
 
 declare interface Asset extends AssetOptions {
@@ -104,29 +114,95 @@ declare interface AssetOptions {
     responseType?: string;
 }
 
-export declare class BaseObject extends UseMaterial {
+declare class AttributesWorker {
+    options: Options_15 & {
+        cacheVersion: string;
+        dbName: string;
+        maxCacheSize: number;
+    };
+    pool: WorkerPool;
+    cacheManager: CacheManager;
+    constructor(options?: Options_15);
+    geoGeometry(type: 'extrudePolygon', options: GeoGeometryOptions & {
+        mesaage: ExtrudePolygonMessage;
+    }): Promise<BufferGeometry>;
+    geoGeometry(type: 'conicPolygon', options: GeoGeometryOptions & {
+        mesaage: ConicPolygonMessage;
+    }): Promise<BufferGeometry>;
+    geoGeometry(type: 'conicLine', options: GeoGeometryOptions & {
+        mesaage: ConicLineMessage;
+    }): Promise<BufferGeometry>;
+    geoGeometry(type: 'line', options: GeoGeometryOptions & {
+        mesaage: LineMessage;
+    }): Promise<BufferGeometry>;
+    getCachedGeometry(options: Pick<GeoGeometryOptions, 'cacheKey'>): Promise<ReturnType<typeof _default_2> | null>;
+    saveCache(): Promise<void>;
+    /**
+     * 批量保存待更新的元数据
+     */
+    flushMetadata(): Promise<void>;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): Promise<{
+        total: number;
+        maxSize: number;
+        usage: number;
+        items: {
+            key: IDBValidKey;
+            metadata: CacheMetadata;
+        }[];
+    }>;
+    /**
+     * 手动清空所有缓存
+     */
+    clearCache(): Promise<void>;
+    /**
+     * 检查存储配额使用情况
+     */
+    checkStorageQuota(): Promise<{
+        usage: number;
+        quota: number;
+        percentUsed: number;
+    } | null>;
+    flattenCoordinates(coordinatesArr: number[][][], metaArray?: number[][], _globalMeta?: number[], useFloat64Array?: boolean): {
+        flat: Float64Array | Float32Array;
+        lengths: number[];
+        metaLength: number;
+    };
+    dispose(): void;
+}
+
+export declare class BaseObject<T extends Object3D = Object3D> extends UseMaterial {
     key: string;
-    keyType?: string;
-    keyUId?: string;
-    keyName?: string;
+    get name(): string;
+    set name(v: string);
     objectType: string;
-    objectOptions?: Record<string, any>;
+    options: any;
+    private _keyType;
+    get keyType(): string;
+    set keyType(v: string);
+    uuid: string;
     pencil: Pencil;
     lead: Lead;
     mList: MList;
-    object3d: Object3D;
+    object3d: T;
     userData: Record<string, any>;
     isPrefab: boolean;
     isInstantiate: boolean;
     isBloom: boolean;
     isBaseObject: boolean;
+    constructor(object3d: T);
     get parent(): BaseObject | null;
-    get children(): BaseObject[];
+    get children(): BaseObject<Object3D<Object3DEventMap>>[];
     get position(): Vector3;
     get rotation(): Euler;
     get scale(): Vector3;
-    lookAt(vector: Vector3 | [number, number, number]): void;
-    add(...object: Object3D[]): void;
+    lookAt(vector: Vector3): void;
+    lookAt(x: number, y: number, z: number): void;
+    draw<C extends new (...args: any[]) => BaseObject>(ClassRef: C, ...args: ConstructorParameters<C>): Promise<InstanceType<C>>;
+    drawPrefab<C extends new (...args: any[]) => BaseObject>(ClassRef: C, ...args: ConstructorParameters<C>): Promise<InstanceType<C>>;
+    add(...objects: (Object3D | BaseObject)[]): void;
     remove(...object: Object3D[]): void;
     get visible(): boolean;
     /**
@@ -147,13 +223,6 @@ export declare class BaseObject extends UseMaterial {
      * 递归启用 layers（只有自己 visible=true 时才 enable 并继续递归）
      */
     protected _enableLayersRecursive(): void;
-    createGroup(): this;
-    createMesh(...args: ConstructorParameters<typeof Mesh>): this;
-    createPoints(...args: ConstructorParameters<typeof Points>): this;
-    createCSS2DObject(dom: HTMLElement): this;
-    createCSS3DObject(dom: HTMLElement): this;
-    createCSS3DSprite(dom: HTMLElement): this;
-    createSprite(material: SpriteMaterial): this;
     attach(...args: BaseObject[]): this;
     getSize(): {
         min: Vector3;
@@ -164,10 +233,7 @@ export declare class BaseObject extends UseMaterial {
     setTop(onTop: number): void;
     traverse(fn: (o: BaseObject) => void): void;
     instantiate(ops?: {
-        key?: string;
-        uId?: string;
         target?: BaseObject;
-        create?: ((...args: any[]) => any) | boolean;
         recursive?: boolean;
         instancedAttr?: {
             position: Vector3 | number[] | [number, number, number];
@@ -176,10 +242,14 @@ export declare class BaseObject extends UseMaterial {
         cloneMaterial?: boolean;
     }): Promise<this>;
     erase(): void;
+    setKey(ops: {
+        keyType?: string;
+        uuid?: string;
+        syncParentUuid?: boolean;
+    }): void;
     handleMaterialChange(mat: Material | null): void;
     enableBloom(traverse?: boolean): void;
     disableBloom(traverse?: boolean): void;
-    disposeTrack: boolean;
     private isDispose;
     dispose(): void;
 }
@@ -201,11 +271,11 @@ declare class CacheManager {
     /**
      * 添加缓存到内存队列
      */
-    addToCache(cacheKey: string, cacheVersion: string, data: any): void;
+    addToCache(cacheKey: string, data: any): void;
     /**
      * 记录待更新的缓存元数据（非阻塞）
      */
-    recordMetadataUpdate(cacheKey: string, size: number): void;
+    recordMetadataUpdate(cacheKey: string, size?: number): void;
     /**
      * 批量保存待更新的元数据
      */
@@ -217,7 +287,7 @@ declare class CacheManager {
     /**
      * 从缓存中获取数据
      */
-    get<T = any>(cacheKey: string, cacheVersion?: string): Promise<T | undefined>;
+    get<T = any>(cacheKey: string): Promise<T | undefined>;
     /**
      * 保存内存缓存到 IndexedDB
      */
@@ -261,7 +331,6 @@ declare interface CacheManagerOptions {
 declare interface CacheMetadata {
     lastAccessed: number;
     accessCount: number;
-    size: number;
 }
 
 declare class CameraControls extends EventDispatcher {
@@ -1314,21 +1383,21 @@ declare class CollisionManager {
      * 添加标签到碰撞检测系统
      * @param node Node 实例
      */
-    add(node: Node_2, options?: {
+    add(node: NodeObject, options?: {
         priority?: number;
     }): void;
     /**
      * 移除标签
      */
-    remove(node: Node_2): void;
+    remove(node: NodeObject): void;
     /**
      * 更新标签优先级
      */
-    setPriority(node: Node_2, priority: number): void;
+    setPriority(node: NodeObject, priority: number): void;
     /**
      * 批量添加标签
      */
-    addBatch(nodes: Node_2[], priorityFn?: (node: Node_2, index: number) => number): void;
+    addBatch(nodes: NodeObject[], priorityFn?: (node: NodeObject, index: number) => number): void;
     /**
      * 启用/禁用碰撞检测
      */
@@ -1424,7 +1493,7 @@ declare class Composer {
     setPremultiplieAlpha(premultiplieAlpha: boolean): void;
     addSSAOPass(params: SSAOParams): void;
     addBloomPass(params: BloomParams): void;
-    bloomSelection: Set<BaseObject>;
+    bloomSelection: Set<BaseObject<Object3D<Object3DEventMap>>>;
     bloomLayer: Layers;
     bloomMaterials: Record<string, Material | Material[]>;
     bloomVisible: Record<string, boolean>;
@@ -1453,30 +1522,20 @@ declare interface ComposerParams {
     premultiplieAlpha: boolean;
 }
 
-declare interface ConicLineOptions extends GetCoordinatesArrOptions {
-    meta?: number[][];
+declare interface ConicLineMessage {
+    projection?: 'cesium' | 'sphere';
     useGroups?: 0 | 1 | 2;
-    projection?: any;
-    splitPolygons?: number;
-    line2?: boolean;
     useRTC?: boolean;
 }
 
-export declare class ConicPolygon extends BaseObject {
-    options: Parameters_2;
-    constructor(options: Parameters_2);
-    create(): void;
-}
-
-declare interface ConicPolygonOptions extends GetCoordinatesArrOptions {
-    meta?: number[][];
+declare interface ConicPolygonMessage {
     useGroups?: 0 | 1 | 2;
     hasTop?: boolean;
     topFirst?: boolean;
     hasBottom?: boolean;
     hasSide?: boolean;
     curvatureResolution?: number;
-    projection?: ProjectionOptions | 'cesium' | 'sphere';
+    projection?: 'cesium' | 'sphere';
     bbox?: number[];
     splitPolygons?: number;
 }
@@ -1498,6 +1557,23 @@ declare interface ControlsParams {
     domElement: HTMLElement;
 }
 
+export declare class CSS2DObjectObject extends BaseObject<CSS2DObject> {
+    objectType: string;
+    constructor(domOrObject?: HTMLElement | CSS2DObject);
+}
+
+export declare class CSS3DObjectObject extends BaseObject<CSS3DObject> {
+    objectType: string;
+    constructor(domOrObject?: HTMLElement | CSS3DObject);
+}
+
+export declare class CSS3DSpriteObject extends BaseObject<CSS3DSprite> {
+    objectType: string;
+    constructor(domOrSprite?: HTMLElement | CSS3DSprite);
+}
+
+declare type CSSObject = CSS2DObject | CSS3DObject | CSS3DSprite;
+
 declare class CSSRendererController {
     css2Drenderer?: CSS2DRenderer;
     css3Drenderer?: CSS3DRenderer;
@@ -1537,6 +1613,13 @@ declare const _default: (composer: EffectComposer) => ShaderPass;
 
 declare const _default_2: (attributes: any) => BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>;
 
+export declare class DirectionalLightObject extends BaseObject<DirectionalLight> {
+    objectType: string;
+    constructor(lightOrColor?: DirectionalLight | string | number, intensity?: number);
+    render(): void;
+    dispose(): void;
+}
+
 declare interface DispatcherEvent {
     type: string;
     [key: string]: any;
@@ -1551,6 +1634,11 @@ declare const DOLLY_DIRECTION: {
 declare type DOLLY_DIRECTION =
 (typeof DOLLY_DIRECTION)[keyof typeof DOLLY_DIRECTION];
 
+declare interface DrawOptions {
+    target?: BaseObject | string | null;
+    prefab?: boolean;
+}
+
 export declare const effect: {
     Scan: typeof ScanEffect;
     Scan2: typeof ScanEffect_2;
@@ -1560,10 +1648,11 @@ export declare const effect: {
  * Cesium 风格的 WGS84 椭球体地球
  * 使用与 Cesium 相同的坐标系和 WGS84 椭球体参数
  */
-export declare class Ellipsoid extends BaseObject {
+export declare class EllipsoidObject extends MeshObject {
+    objectType: string;
     options: EllipsoidOptions;
     constructor(options?: EllipsoidOptions);
-    create(): Mesh<BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>, Material, Object3DEventMap>;
+    create(): void;
 }
 
 declare interface EllipsoidOptions {
@@ -1660,26 +1749,47 @@ declare interface ExtrudeGeometryOptions extends ExtrudeGeometryOptions_2 {
     hasSide?: boolean;
 }
 
-export declare class ExtrudePolygon extends BaseObject {
-    options: Omit<Options_18, 'depth'> & {
-        depth: number | number[];
-    };
-    constructor(options: Options_18);
+declare interface ExtrudePolygonMessage {
+    bbox?: number[];
+    projection?: ProjectionOptions;
+    useGroups?: 0 | 1 | 2;
+    hasTop?: boolean;
+    hasBottom?: boolean;
+    hasSide?: boolean;
+    splitPolygons?: number;
+    topSegments?: number;
+}
+
+export declare class ExtrudePolygonObject extends MeshObject {
+    objectType: string;
+    options: ExtrudePolygonObjectOptions;
+    constructor(options: ExtrudePolygonObjectOptions);
     create(): Promise<void>;
-    addGeometries(geometries: BufferGeometry[]): void;
-    setTextureAnisotropic(texture: Texture, maxAnisotropy?: number): void;
+    private createWithWorker;
+    private createLocal;
 }
 
-declare interface ExtrudePolygonOptions extends GetCoordinatesArrOptions {
-    meta?: number[][];
-    bbox?: number[];
-    projection?: ProjectionOptions;
+export declare interface ExtrudePolygonObjectOptions {
+    material?: Material | Material[];
+    geometry?: BufferGeometry;
+    coordinatesArr?: number[][][];
+    metaArray?: number[][];
+    globalMeta?: number[];
+    useWorker?: boolean;
     useGroups?: 0 | 1 | 2;
     hasTop?: boolean;
     hasBottom?: boolean;
     hasSide?: boolean;
+    bbox?: number[];
+    projection?: ProjectionOptions | 'cesium' | 'sphere';
     splitPolygons?: number;
     topSegments?: number;
+    cacheKey?: string;
+    userData?: Record<string, any>;
+    curvatureResolution?: number;
+    topFirst?: boolean;
+    useFloat64Array?: boolean;
+    onCacheMiss?: (options: Partial<ExtrudePolygonObjectOptions>) => Partial<ExtrudePolygonObjectOptions> | Promise<Partial<ExtrudePolygonObjectOptions>>;
 }
 
 declare interface FitToOptions {
@@ -1693,6 +1803,7 @@ declare interface FitToOptions {
 declare interface GeoGeometryOptions extends Options_15 {
     coordinatesArr: number[][][];
     metaArray?: number[][];
+    globalMeta?: number[];
     cacheKey?: string;
     userData?: Record<string, any>;
     useFloat64Array?: boolean;
@@ -1701,15 +1812,9 @@ declare interface GeoGeometryOptions extends Options_15 {
 
 declare function geoWinkel3(): GeoProjection;
 
-declare interface GetCoordinatesArrOptions {
-    coordinates?: Float64Array | Float32Array;
-    lengths?: number[];
-    dimension?: number;
-    metaLength?: number;
-}
-
-export declare class Group extends BaseObject {
-    create(): void;
+export declare class GroupObject extends BaseObject<Group> {
+    objectType: string;
+    constructor(group?: Group<Object3DEventMap>);
     render(): void;
 }
 
@@ -1728,9 +1833,17 @@ declare class HelperController {
     dispose(): void;
 }
 
-declare function isPlainObject(o: any): boolean;
+export declare class HemisphereLightObject extends BaseObject<HemisphereLight> {
+    objectType: string;
+    constructor(skyColorOrLight?: HemisphereLight | string | number, groundColor?: string | number, intensity?: number);
+}
+
+export declare class InstancedMeshObject<G extends BufferGeometry = BufferGeometry, M extends Material | Material[] = Material | Material[]> extends BaseObject<InstancedMesh<G, M>> {
+    objectType: string;
+    constructor(geometryOrInstancedMesh?: G | InstancedMesh<G, M>, material?: M, count?: number);
+}
 
-declare type KeyOf<T extends object> = Extract<keyof T, string>;
+declare function isPlainObject(o: any): boolean;
 
 declare const KNOWN_ASSET_TYPES: {
     readonly images: readonly ["png", "jpg", "jpeg", "ico", "webp", "avif"];
@@ -1742,72 +1855,70 @@ declare const KNOWN_ASSET_TYPES: {
     readonly lottie: readonly ["lottie.json"];
 };
 
-export declare class Lead<T extends ObjectFactoryMap = any> extends Pick_2 {
-    objMap: Map<Object3D<Object3DEventMap>, BaseObject>;
-    objects: Map<string, BaseObject>;
-    objectsPm: Map<BaseObject, Promise<void>>;
-    objectWrapChindIdMap: Map<BaseObject, number>;
+export declare class Lead extends Pick_2 {
+    objMap: Map<Object3D<Object3DEventMap>, BaseObject<Object3D<Object3DEventMap>>>;
+    objects: Map<string, BaseObject<Object3D<Object3DEventMap>>>;
+    objectsPm: Map<BaseObject<Object3D<Object3DEventMap>>, Promise<void>>;
+    objectWrapChindIdMap: Map<BaseObject<Object3D<Object3DEventMap>>, number>;
     scene: BaseObject;
     mList: MList;
     group: BaseObject;
     prefabGroup: BaseObject;
-    private objectNamesToFactories;
     get objectsPromise(): MapIterator<Promise<void>>;
     constructor(pencil: Pencil, ops: {
         scene: Scene;
         mList: MList;
     });
-    createBaseObject(object3d: Object3D, opsO?: {
-        key?: string;
-        name?: string;
-        target?: BaseObject | null;
-        mList?: boolean;
-    }): BaseObject;
-    init<K extends ObjectFactoryMap>(objectFactories: K): Lead<K>;
-    getObject<Y extends KeyOf<T>>(nameOrigin: Y, options?: {
+    /* Excluded from this release type: register */
+    /**
+     * 内部初始化核心对象 (Scene, Camera 等)
+     * 模拟 add 的部分逻辑，但不走完整的 spawn 流程
+     */
+    private _initCoreObject;
+    draw<C extends new (...args: any[]) => BaseObject>(ClassRef: C, ...args: ConstructorParameters<C>): Promise<InstanceType<C>>;
+    draw<C extends new (...args: any[]) => BaseObject>(options: DrawOptions, ClassRef: C, ...args: ConstructorParameters<C>): Promise<InstanceType<C>>;
+    /**
+     * 将原生 Object3D 包装为 BaseObject (Wrapper Pattern)
+     * 如果已存在包装器，则返回现有实例
+     */
+    wrap(object3d: Object3D): BaseObject;
+    /**
+     * 统一的添加入口
+     * 替代原有的 addBaseObject 私有方法，公开给 spawn 使用
+     */
+    add<T extends BaseObject = BaseObject>(baseObject: T, target?: BaseObject | string | null): Promise<T>;
+    private _addLogic;
+    getObject<T extends BaseObject = BaseObject>(nameOrigin: string, options?: {
         key: string;
-    }): InstanceType<T[Y]> | undefined;
-    getAllObject<Y extends KeyOf<T>>(nameOrigin: Y, options?: {
+    }): T | undefined;
+    getAllObject<T extends BaseObject = BaseObject>(nameOrigin: string, options?: {
         key: string;
-    }): InstanceType<T[Y]>[];
-    draw<Y extends KeyOf<T>, U extends KeyOf<T> | `${KeyOf<T>}#${string}` | BaseObject | null>(nameOrigin: Y, options?: ConstructorParameters<T[Y]>[0] extends undefined ? {
-        keyType?: string;
-        key?: string;
-        uId?: string;
-        target?: U;
-        onTop?: number;
-        create?: ((...args: any[]) => any) | boolean;
-        prefab?: boolean;
-    } : ConstructorParameters<T[Y]>[0] & {
+    }): T[];
+    /**
+     * 更新对象的 Key
+     * 通常用于重命名
+     */
+    updateBaseObjectKey(baseObject: BaseObject, ops?: {
         keyType?: string;
-        key?: string;
-        uId?: string;
-        target?: U;
-        onTop?: number;
-        create?: ((...args: any[]) => any) | boolean;
-        prefab?: boolean;
-    }, target?: U): Promise<InstanceType<T[Y]>>;
-    private setBaseObjectKey;
-    updateBaseObjectKey(baseObject: BaseObject, ops: {
-        type?: string;
-        key?: string;
-        uId?: string;
-    }): string;
-    private addBaseObject;
-    erase(...args: (KeyOf<T> | `${KeyOf<T>}#${string}` | InstanceType<T[keyof T]>)[]): void;
-    eraseWithoutMaterial(...args: (KeyOf<T> | `${KeyOf<T>}#${string}` | InstanceType<T[keyof T]>)[]): void;
+        uuid?: string;
+    }): string | undefined;
+    erase(...args: (string | BaseObject)[]): void;
+    eraseWithoutMaterial(...args: (string | BaseObject)[]): void;
     private handleErase;
     update(delta: number, elapsed: number): void;
     setSize(width: number, height: number): void;
     eraseAll(): void;
+    private _serializer;
+    exportScene(...args: Parameters<SceneSerializer['exportScene']>): string;
+    restoreScene(...args: Parameters<SceneSerializer['restoreScene']>): Promise<void>;
     dispose(): void;
 }
 
 declare class LeadPages extends OrigonPages<Lead> {
     options: Options_13;
-    get lead(): Lead<any>;
+    get lead(): Lead;
     constructor(options: Options_13);
-    addLead(scene: Scene, mList: MList, index?: number): Lead<any>;
+    addLead(scene: Scene, mList: MList, index?: number): Lead;
     removePage(index: number): void;
     setPageActive(index: number): void;
     setSize(width: number, height: number): void;
@@ -1817,33 +1928,24 @@ declare type LeadParams = {};
 
 declare type LeadParams_2 = {};
 
-export declare class Light extends BaseObject {
-    options: LightOptions;
-    directionalLight?: DirectionalLight;
-    spotLight?: SpotLight;
-    pointLight?: PointLight;
-    hemisphereLight?: HemisphereLight;
-    rectAreaLight?: RectAreaLight;
-    rectAreaLightUniformsLibInit: boolean;
-    constructor(options: LightOptions);
-    create(): void;
-    render(): void;
-    dispose(): void;
-}
+export { Line2Material }
 
-declare interface LightOptions {
-    type: 'AmbientLight' | 'DirectionalLight' | 'PointLight' | 'SpotLight' | 'RectAreaLight' | 'HemisphereLight';
-    [key: string]: any;
+declare interface LineMessage {
+    projection?: ProjectionOptions;
+    useGroups?: 0 | 1 | 2;
+    splitPolygons?: number;
 }
 
-export declare class Line extends BaseObject {
-    options: Options_19;
-    constructor(options?: Partial<Options_19>);
+export declare class LineObject extends MeshObject<MeshLineGeometry | BufferGeometry, MeshLineMaterial> {
+    objectType: string;
+    options: LineObjectOptions;
+    constructor(options?: Partial<LineObjectOptions>);
     get material(): MeshLineMaterial;
     create(): Promise<void>;
+    private createWithWorker;
+    private createLocal;
     setGeometry(nodes: PointsInput_2, setPointWidth?: (p: number) => any, useRTC?: boolean, rtcCenter?: Vector3): void;
     createMaterial(materialOptions: Omit<MeshLineMaterialParameters, 'resolution'>): MeshLineMaterial;
-    addGeometries(geometries: BufferGeometry[]): void;
     resize(w: number, h: number): void;
     handleMaterialChange(mat: MeshLineMaterial | null): void;
     animate({ duration, delay, repeat, lineLoop, onRepeat, onUpdate, onComplete, startShow, }?: {
@@ -1861,22 +1963,23 @@ export declare class Line extends BaseObject {
     update(): void;
 }
 
-export declare class Line2 extends BaseObject {
-    options: Options_20;
-    constructor(options?: Partial<Options_20>);
-    get material(): Line2Material;
-    create(): Promise<void>;
-    createMaterial(materialOptions: LineMaterialParameters): Line2Material;
-}
-
-export { Line2Material }
-
-declare interface LineOptions extends GetCoordinatesArrOptions {
-    meta?: number[][];
-    projection?: ProjectionOptions;
-    useGroups?: 0 | 1 | 2;
+declare interface LineObjectOptions {
+    geometry?: BufferGeometry;
+    material?: MeshLineMaterial;
+    coordinatesArr?: number[][][];
+    metaArray?: number[][];
+    globalMeta?: number[];
+    useWorker?: boolean;
+    projection?: ProjectionOptions | 'cesium' | 'sphere';
     splitPolygons?: number;
-    line2?: boolean;
+    useGroups?: 0 | 1 | 2;
+    setPointWidth?: (p: number) => any;
+    lineWidthArr?: number[];
+    cacheKey?: string;
+    userData?: Record<string, any>;
+    useFloat64Array?: boolean;
+    useRTC?: boolean;
+    onCacheMiss?: (options: Partial<LineObjectOptions>) => Partial<LineObjectOptions> | Promise<Partial<LineObjectOptions>>;
 }
 
 export { LineSegmentsGeometry }
@@ -1907,7 +2010,7 @@ declare class Loader {
     getAsset(src: `${string}.${TypeGzipJSON}`): any;
     getAsset(src: `${string}.${TypeEXR}`): DataTexture;
     getAsset(src: string): Texture;
-    getAssetType(src: string): "json" | "gltf" | "exr" | "images" | "media" | "gzipJson" | "lottie" | undefined;
+    getAssetType(src: string): "images" | "json" | "gltf" | "exr" | "media" | "gzipJson" | "lottie" | undefined;
     getLoader(type: string, options?: AssetOptions): any;
     add(src: string | string[], options?: AssetOptions): void;
     getSrcByAsset(asset: Texture | Object3D | any, assets?: Map<string, any>): string | undefined;
@@ -2009,6 +2112,11 @@ export declare class MeshLineMaterial extends ShaderMaterial {
      * @param objectMatrixWorld 物体的世界矩阵（可选，用于支持缩放和旋转）
      */
     updateRTC(center: Vector3, cameraMatrixWorld: Matrix4, objectMatrixWorld?: Matrix4): void;
+    /**
+     * 从 Three.js 原生解析好的 ShaderMaterial 中还原出 MeshLineMaterial
+     * 用于反序列化场景
+     */
+    static fromParsedShaderMaterial(shaderMat: ShaderMaterial): MeshLineMaterial;
 }
 
 declare interface MeshLineMaterialParameters extends ShaderMaterialParameters {
@@ -2072,11 +2180,17 @@ declare interface MeshLineMaterialParameters extends ShaderMaterialParameters {
 
 export declare function MeshLineRaycast(this: Mesh<BufferGeometry, MeshLineMaterial>, raycaster: Raycaster, intersects: Intersection[]): void;
 
+export declare class MeshObject<G extends BufferGeometry = BufferGeometry, M extends Material | Material[] = Material | Material[]> extends BaseObject<Mesh<G, M>> {
+    objectType: string;
+    constructor(geometryOrMesh?: G | Mesh<G, M>, material?: M);
+}
+
 declare class MList {
     pencil: Pencil;
     private materials;
     fixBaseObjects: Map<string, BaseObject>;
     private materialBaseObjectMap;
+    private static _emptyGeometry;
     constructor(pencil: Pencil);
     add(key: string, material: Material): void;
     get(key: string): Material | undefined;
@@ -2097,7 +2211,7 @@ declare class MList {
     private material2array;
     addBaseObjectMap(object: BaseObject): void;
     rmBaseObjectMap(object: BaseObject, targetMaterial?: Material | Material[], disposeMaterial?: boolean): void;
-    getBaseObjectMap(material: Material): Set<BaseObject>;
+    getBaseObjectMap(material: Material): Set<BaseObject<Object3D<Object3DEventMap>>>;
     syncChangeMaterial(oldMaterial: Material, material: Material): void;
     dispose(): void;
 }
@@ -2158,7 +2272,7 @@ declare type multiTouchAction =
 | typeof ACTION.TOUCH_OFFSET
 | typeof ACTION.NONE;
 
-declare class Node_2 extends BaseObject {
+export declare class NodeObject extends BaseObject<CSSObject> {
     objectType: string;
     options: Options_7;
     pickObject?: Sprite;
@@ -2167,7 +2281,6 @@ declare class Node_2 extends BaseObject {
     private static sharedObserver?;
     private static observerMap;
     constructor(options: Options_7);
-    create(): void;
     /**
      * 启用碰撞检测跟踪
      * @param priority 优先级，数值越大越优先显示，默认 0
@@ -2185,13 +2298,6 @@ declare class Node_2 extends BaseObject {
     onPointerEvent(type: PickFunctionsItem['type'], cb: PickFunctionsItem['cb']): void;
     dispose(): void;
 }
-export { Node_2 as Node }
-
-declare type ObjectFactory<T extends BaseObject = BaseObject> = new (...args: any[]) => T;
-
-declare type ObjectFactoryMap = {
-    [key: string]: ObjectFactory;
-};
 
 declare interface Options {
     color: string | number;
@@ -2261,39 +2367,15 @@ declare interface Options_16 {
     exclude?: Mesh[];
 }
 
-declare interface Options_17 extends Omit<Parameters_3, 'polygonGeoJson' | 'endHeight'> {
-    coordinate: number[][];
-    height?: number;
-}
-
-declare interface Options_18 {
-    points?: Vector2[];
-    pointsArr?: Vector2[][];
-    material: Material | Material[];
-    geometry?: BufferGeometry;
-    geometryArr?: BufferGeometry[];
-    depth?: number | number[];
-    useGroups?: 0 | 1 | 2;
-    split?: number;
-    box3?: Box3 | Box3[];
-    hasTop?: boolean;
-    hasBottom?: boolean;
-    hasSide?: boolean;
-}
-
-declare interface Options_19 {
-    nodes?: PointsInput_2;
-    nodesArr?: PointsInput_2[];
-    geometry?: BufferGeometry;
-    geometryArr?: BufferGeometry[];
-    material?: MeshLineMaterial;
-    key?: string;
-    useGroups?: 0 | 1 | 2;
-    setPointWidth?: (p: number) => any;
-    lineWidthArr?: number[];
-    materialParameters?: Omit<MeshLineMaterialParameters, 'resolution'>;
-    useRTC?: boolean;
-    rtcCenter?: Vector3;
+declare interface Options_17 {
+    maxDepth?: number;
+    percentDepth?: boolean;
+    innerRadius?: number;
+    outRadius?: number;
+    data: number[];
+    colors: string[];
+    activeIndex?: number;
+    material?: MeshBasicMaterial | MeshStandardMaterial;
 }
 
 declare interface Options_2 {
@@ -2318,30 +2400,7 @@ declare interface Options_2 {
     css3DRenderer?: boolean;
     css3DRendererParams?: Partial<CSSRendererParams>;
     WebGPUTHREE?: any;
-}
-
-declare interface Options_20 {
-    nodes?: PointsInput_2;
-    nodesArr?: PointsInput_2[];
-    geometry?: BufferGeometry;
-    geometryArr?: BufferGeometry[];
-    material?: Line2Material;
-    key?: string;
-    useGroups?: 0 | 1 | 2;
-    setPointWidth?: (p: number) => any;
-    lineWidthArr?: number[];
-    materialParameters?: LineMaterialParameters;
-}
-
-declare interface Options_21 {
-    maxDepth?: number;
-    percentDepth?: boolean;
-    innerRadius?: number;
-    outRadius?: number;
-    data: number[];
-    colors: string[];
-    activeIndex?: number;
-    material?: MeshBasicMaterial | MeshStandardMaterial;
+    attributesWorkerVersion?: string;
 }
 
 declare interface Options_3 {
@@ -2410,29 +2469,6 @@ declare class Pages {
     getMinDisabledLayer(): number | null;
 }
 
-declare interface Parameters_2 extends Omit<Options_17, 'coordinate'> {
-    geometry?: BufferGeometry;
-    material?: Material | Material[];
-    coordinate?: number[][];
-    coordinateArr?: number[][][];
-    useGroups?: 0 | 1 | 2;
-}
-
-declare type Parameters_3 = {
-    polygonGeoJson: PolygonCoords;
-    startHeight?: number;
-    endHeight?: number;
-    hasSide?: boolean;
-    hasTop?: boolean;
-    topFirst?: boolean;
-    hasBottom?: boolean;
-    includeSides?: boolean;
-    curvatureResolution?: number;
-    projection?: any; // 'cesium' | 'sphere' | D3 projection function | null
-    bbox?: number[];
-    resetCenter?: boolean;
-};
-
 declare class Pencil {
     options: Omit<DeepRequiredOptions, 'controls' | 'loader' | 'css2DRendererParams' | 'css3DRendererParams'> & Pick<Options_2, 'controls' | 'loader'> & {
         css2DRendererParams: CSSRendererParams;
@@ -2454,7 +2490,8 @@ declare class Pencil {
     raycaster: Raycaster;
     private maxBackufferArea;
     installPlugins: Map<string, any>;
-    getPlugin(name: 'worker'): Wk;
+    attributesWorker: AttributesWorker;
+    getPlugin(name: string): any;
     get renderer(): WebGLRenderer;
     get maxAnisotropy(): number;
     get controls(): CameraControls;
@@ -2463,9 +2500,9 @@ declare class Pencil {
     get cameraPositon(): Vector3;
     get cameraTarget(): Vector3;
     get camera(): PerspectiveCamera;
-    get scene(): Scene<Object3DEventMap>;
+    get scene(): Scene;
     get loader(): Loader;
-    get lead(): Lead<any>;
+    get lead(): Lead;
     get mList(): MList;
     event: EventEmitter;
     timer: Timer;
@@ -2539,6 +2576,7 @@ declare class Pencil {
                 viewportMargin?: number;
             };
         };
+        attributesWorkerVersion: string;
     };
     private TweenRaf;
     private tweenUpdateRaf;
@@ -2653,11 +2691,12 @@ export declare type PickFunctionsItem = {
     }) => void;
 };
 
-export declare class Pie extends BaseObject {
-    options: Required<Omit<Options_21, 'material'>> & {
+export declare class PieObject extends GroupObject {
+    objectType: string;
+    options: Required<Omit<Options_17, 'material'>> & {
         material?: MeshBasicMaterial | MeshStandardMaterial;
     };
-    constructor(options: Options_21);
+    constructor(options: Options_17);
     create(): Promise<void>;
     createGeometry(depth: number, angle: number): ExtrudeGeometry;
     handlePick(e: MouseEvent, scale?: number): any;
@@ -2687,11 +2726,19 @@ declare interface PointerInput {
     mouseButton: MOUSE_BUTTON | null;
 }
 
+export declare class PointLightObject extends BaseObject<PointLight> {
+    objectType: string;
+    constructor(lightOrColor?: PointLight | string | number, intensity?: number, distance?: number, decay?: number);
+}
+
 declare type PointsInput = Vector3[] | Vector2[] | number[][] | number[];
 
 declare type PointsInput_2 = Vector3[] | Vector2[] | number[][] | number[];
 
-declare type PolygonCoords = number[][][];
+export declare class PointsObject<G extends BufferGeometry = BufferGeometry, M extends Material | Material[] = Material | Material[]> extends BaseObject<Points<G, M>> {
+    objectType: string;
+    constructor(geometryOrPoints?: G | Points<G, M>, material?: M);
+}
 
 declare const projectionObj: {
     mercator: typeof geoMercator;
@@ -2708,6 +2755,12 @@ declare type ProjectionOptions = {
     rotate?: [number, number];
 };
 
+export declare class RectAreaLightObject extends BaseObject<RectAreaLight> {
+    objectType: string;
+    static rectAreaLightUniformsLibInit: boolean;
+    constructor(colorOrLight?: RectAreaLight | string | number, intensity?: number, width?: number, height?: number);
+}
+
 declare type Ref = {
     value: number;
 };
@@ -2749,7 +2802,7 @@ export declare class ResourceTracker {
     resources: Set<Resource>;
     disposeMaterial: boolean;
     disposeVideo: boolean;
-    track(resource: Resource | Resource[]): Material | Object3D<Object3DEventMap> | Texture<unknown> | BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap> | BaseObject | HTMLVideoElement | Resource[];
+    track(resource: Resource | Resource[]): Object3D<Object3DEventMap> | Material | Texture<unknown> | BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap> | BaseObject<Object3D<Object3DEventMap>> | HTMLVideoElement | Resource[];
     dispose(): void;
 }
 
@@ -2784,11 +2837,36 @@ declare class ScanEffect_2 {
     stop(): void;
 }
 
+/**
+ * 场景 JSON 引用回溯工具
+ * 从 sceneJson 中构建 uuid -> 可读路径 的映射表
+ * 供分析、去重日志等场景共用
+ */
+declare class SceneJsonRefTracer {
+    /** object uuid / geometry uuid -> 对象路径 */
+    readonly uuidToObject: Map<string, string>;
+    /** material uuid -> 使用它的对象路径 */
+    readonly uuidToMaterial: Map<string, string>;
+    /** texture uuid -> 使用它的材质描述 */
+    readonly uuidToTexture: Map<string, string>;
+    /** image uuid -> 使用它的纹理描述 */
+    readonly uuidToImage: Map<string, string>;
+    constructor(sceneJson: any);
+    /** 根据 uuid 获取可读描述，依次查找各映射 */
+    resolve(uuid: string): string;
+    /** 将 uuid -> uuid 的 remap 映射转为可读的日志行数组 */
+    formatRemap(remap: Map<string, string>): string[];
+    private _traceObjects;
+    private static _mapTypes;
+    private _traceMaterials;
+    private _traceTextures;
+}
+
 declare class ScenePages extends OrigonPages<Scene> {
     options: Options_4;
-    get scene(): Scene<Object3DEventMap>;
+    get scene(): Scene;
     constructor(options: Options_4);
-    addScene(sceneParams?: SceneParams, index?: number): Scene<Object3DEventMap>;
+    addScene(sceneParams?: SceneParams, index?: number): Scene;
     removePage(index: number): void;
     setPageActive(index: number): void;
 }
@@ -2797,6 +2875,85 @@ declare interface SceneParams {
     background: Scene['background'];
 }
 
+declare class SceneSerializer {
+    private lead;
+    constructor(lead: Lead);
+    private get scene();
+    private get group();
+    private get prefabGroup();
+    private get mList();
+    private get objects();
+    exportCompressScene(): Promise<ArrayBuffer>;
+    exportScene({ checkTextures }?: {
+        checkTextures?: boolean | undefined;
+    }): string;
+    restoreScene(data: string | ArrayBuffer | Object3DJSON, registry?: Record<string, new (...args: any[]) => any>, roomEnvMap?: any): Promise<void>;
+    /**
+     * 根据 objectType 和 registry 创建 BaseObject 实例
+     */
+    private _createInstance;
+    /**
+     * 安全地克隆 options，过滤掉不可序列化的 Three.js 对象
+     */
+    private _cloneObjectOptions;
+    /**
+     * 将解析后的场景树移植到现有核心 Object3D，保持外部引用不变
+     */
+    private _graftParsedScene;
+    private _graftObject3d;
+    /**
+     * 同步 Object3D 属性，保留 target 上非 _baseObject 的 userData
+     */
+    private _syncObject3dProps;
+    /**
+     * 清理临时写入的 _baseObject* userData 键
+     */
+    private _cleanUserData;
+    /**
+     * 需要提取到共享池进行去重的 _baseObjectOptions 字段名
+     * 新增字段只需在此数组中添加即可
+     */
+    private static _sharedOptionsKeys;
+    /**
+     * 去重场景 JSON 中重复的 image、VideoTexture、DataTexture
+     */
+    private _deduplicateSceneJson;
+    /**
+     * 遍历 sceneJson 的对象树，提取 _baseObjectOptions 中可共享的大字段
+     * 相同内容只存储一份，对象中替换为引用索引
+     */
+    private _extractSharedOptionsPool;
+    /**
+     * 还原共享 options 池：将 { _sharedRef: index } 替换回真实值
+     */
+    private _restoreSharedOptionsPool;
+    /**
+     * 深度优先遍历 sceneJson 对象树，对每个节点执行回调
+     */
+    private _traverseObjectJson;
+    private _compressGzip;
+    private _decompressGzip;
+    /**
+     * 从纹理实例提取通用属性为 plain object（导出用）
+     */
+    private _serializeTexProps;
+    /**
+     * 将 JSON 中的通用属性应用到纹理实例（还原用）
+     */
+    private _applyTexProps;
+    /**
+     * 创建序列化占位纹理（通用工厂）
+     */
+    private _createPlaceholder;
+    private _videoTexToPlaceholder;
+    private _createVideoTextureFromJson;
+    private static _typedArrayCtors;
+    private _dataTexToPlaceholder;
+    private _createDataTextureFromJson;
+    private _typedArrayToBase64;
+    private _base64ToTypedArray;
+}
+
 declare type singleTouchAction =
 | typeof ACTION.TOUCH_ROTATE
 | typeof ACTION.TOUCH_TRUCK
@@ -2806,6 +2963,18 @@ declare type singleTouchAction =
 | typeof ACTION.ZOOM
 | typeof ACTION.NONE;
 
+export declare class SpotLightObject extends BaseObject<SpotLight> {
+    objectType: string;
+    constructor(lightOrColor?: SpotLight | string | number, intensity?: number, distance?: number, angle?: number, penumbra?: number, decay?: number);
+    render(): void;
+    dispose(): void;
+}
+
+export declare class SpriteObject<M extends SpriteMaterial = SpriteMaterial> extends BaseObject<Sprite> {
+    objectType: string;
+    constructor(materialOrSprite?: M | Sprite);
+}
+
 declare interface SSAOParams {
     kernelRadius: number;
     minDistance: number;
@@ -2874,6 +3043,7 @@ declare class UseMaterial extends PointerEvent_2 {
 
 export declare const utils: {
     applyTextureColorSpace: typeof applyTextureColorSpace;
+    analyzeSceneJsonSize: typeof analyzeSceneJsonSize;
     CacheManager: typeof CacheManager;
     cartographicToCartesian: typeof cartographicToCartesian;
     WGS84: {
@@ -2885,80 +3055,11 @@ export declare const utils: {
     isPlainObject: typeof isPlainObject;
     parseVector2: (v: Vector2 | number[]) => Vector2;
     parseVector3: (v: PointsInput[0]) => Vector3;
-    claerUVGenerator: () => void;
-    getUVGenerator: (options?: {
-        box3?: Box3;
-        sideRepeat?: number;
-    }) => {
-        generateTopUV(geometry: any, vertices: number[], indexA: number, indexB: number, indexC: number): Vector2[];
-        generateSideWallUV(geometry: any, vertices: number[], indexA: number, indexB: number, indexC: number, indexD: number): Vector2[];
-    };
+    SceneJsonRefTracer: typeof SceneJsonRefTracer;
 };
 
 declare type ValuesOf<T extends readonly any[]> = T[number];
 
 declare type WidthCallback = (p: number) => number;
 
-export declare class Wk {
-    pluginName: string;
-    options: Options_15 & {
-        cacheVersion: string;
-        dbName: string;
-        maxCacheSize: number;
-    };
-    pencil: Pencil;
-    pool: WorkerPool;
-    bufferGeometryLoader: BufferGeometryLoader;
-    cacheManager: CacheManager;
-    constructor(options: Options_15);
-    install(pencil: Pencil): void;
-    geoGeometry(type: 'extrudePolygon', options: GeoGeometryOptions & {
-        mesaage: ExtrudePolygonOptions;
-    }): Promise<BufferGeometry>;
-    geoGeometry(type: 'conicPolygon', options: GeoGeometryOptions & {
-        mesaage: ConicPolygonOptions;
-    }): Promise<BufferGeometry>;
-    geoGeometry(type: 'conicLine', options: GeoGeometryOptions & {
-        mesaage: ConicLineOptions;
-    }): Promise<BufferGeometry>;
-    geoGeometry(type: 'line', options: GeoGeometryOptions & {
-        mesaage: LineOptions;
-    }): Promise<BufferGeometry>;
-    getCachedGeometry(options: Pick<GeoGeometryOptions, 'cacheKey' | 'cacheVersion'>): Promise<ReturnType<typeof _default_2>[]>;
-    saveCache(): Promise<void>;
-    /**
-     * 批量保存待更新的元数据
-     */
-    flushMetadata(): Promise<void>;
-    /**
-     * 获取缓存统计信息
-     */
-    getCacheStats(): Promise<{
-        total: number;
-        maxSize: number;
-        usage: number;
-        items: {
-            key: IDBValidKey;
-            metadata: CacheMetadata;
-        }[];
-    }>;
-    /**
-     * 手动清空所有缓存
-     */
-    clearCache(): Promise<void>;
-    /**
-     * 检查存储配额使用情况
-     */
-    checkStorageQuota(): Promise<{
-        usage: number;
-        quota: number;
-        percentUsed: number;
-    } | null>;
-    flattenCoordinates(coordinatesArr: number[][][], metaArray?: number[][], useFloat64Array?: boolean): {
-        flat: Float64Array | Float32Array;
-        lengths: number[];
-    };
-    dispose(): void;
-}
-
 export { }