vis-core 0.33.2 → 0.33.4

package/dist/index.d.ts

@@ -24,7 +24,6 @@ import { Position } from 'geojson';
 import { ProjectionOptions } from 'gl-draw';
 import { RectAreaLightObject } from 'gl-draw';
 import { RestoreBaseObjectOptions } from 'gl-draw';
-import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
 import { SceneSnapshot } from 'gl-draw';
 import { SpotLightObject } from 'gl-draw';
 import { SpriteObject } from 'gl-draw';
@@ -54,9 +53,19 @@ declare class Arc extends LineObject {
     options: Options_5;
     constructor(options: Options_5);
     create(): Promise<void>;
-    getCurve(): THREE.CubicBezierCurve3;
-    setControlPoints(points: [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]): void;
-    setPath(from: THREE.Vector3 | number[], to: THREE.Vector3 | number[], radius: number, setPointWidth?: (p: number) => number): void;
+    /** Internal/local-space curve used for rendering, editor handles and snapshots. */
+    getCurve(): ArcCurve;
+    /** Set four world-space Bézier controls; persisted coordinates remain local. */
+    setControlPoints(points: readonly [ArcPoint, ArcPoint, ArcPoint, ArcPoint]): void;
+    /** Set a world-space path without changing this object or its parent transforms. */
+    setPath(from: ArcPoint, to: ArcPoint, options: ArcPathOptions): void;
+    /** Exact radial lift above the short great circle; preserves every object transform. */
+    setSpherePath(from: ArcPoint, to: ArcPoint, options: ArcSpherePathOptions): void;
+    private worldToLocalMatrix;
+    private validatedNodes;
+    private setWorldControls;
+    private getPickPathOptions;
+    private syncPickPathOptions;
     private updatePickTargetGeometry;
     pickTube: Tube | null;
     private pickTargetVersion;
@@ -77,6 +86,36 @@ declare class Arc extends LineObject {
     render(): void;
 }
 
+declare type ArcCurve = THREE.CubicBezierCurve3 | SphereArcCurve;
+
+export declare interface ArcPathOptions {
+    /** Maximum displacement from the endpoint segment along `up`, in world units. */
+    height: number;
+    /** World-space lift direction; normalized internally. Defaults to positive Z. */
+    up?: ArcPoint;
+    setPointWidth?: (progress: number) => number;
+}
+
+export declare type ArcPoint = THREE.Vector3 | readonly number[];
+
+/** A sphere frame in Arc-local coordinates. Its basis retains world-unit lengths. */
+declare interface ArcSpherePath {
+    matrix: number[];
+    angle: number;
+    radius: number;
+    height: number;
+}
+
+export declare interface ArcSpherePathOptions {
+    /** World-space sphere center. Both endpoints must lie on the same sphere. */
+    center: ArcPoint;
+    /** Maximum distance above the sphere surface, in world units. Zero follows its surface. */
+    height: number;
+    /** World-space circle-plane normal for coincident or antipodal endpoints. */
+    normal?: ArcPoint;
+    setPointWidth?: (progress: number) => number;
+}
+
 declare class Area extends GroupObject {
     objectType: string;
     options: Options_11;
@@ -112,14 +151,15 @@ declare class Base_2 extends Camera {
     lead: Lead;
     sceneResources: default_2['sceneResources'];
     tier0: boolean;
-    pmremGenerator: THREE.PMREMGenerator | null;
-    re: RoomEnvironment | null;
     roomEnvMap?: THREE.Texture;
     private roomEnvTarget?;
     private roomEnvLease?;
     visName: string;
     private detectRes?;
     private ownsPencil;
+    private renderingSuspensions;
+    /* Excluded from this release type: suspendRendering */
+    private acquireRenderingSuspensions;
     publicDir: Record<string, string>;
     private prefabAssets;
     private prefabMaterials;
@@ -448,7 +488,7 @@ declare class ContinentsBg extends GroupObject {
     mapArr: PlaneMap[];
     constructor(options: Options_8);
     create(): Promise<void>;
-    getLocationPosition(location: [number, number], name?: string): [number, number, number] | undefined;
+    getLocationPosition(location: [number, number], name?: string, height?: number): [number, number, number] | undefined;
     private calculatePosition;
     render(): void;
     rebuildFromScene(): void;
@@ -536,19 +576,28 @@ declare class Earth_2 extends Base_2 {
     };
     private rotationControls?;
     private releaseRotationLock?;
+    private visibilityChecks?;
     private readonly stopAutoRotate;
     private readonly resumeAutoRotate;
     protected onRuntimeReady(): Promise<void>;
     protected onDispose(): void;
-    getLocationPosition(location: [number, number], dr?: number): [number, number, number];
+    private getLocationFrame;
+    /** 球体表面的世界坐标；height 沿真实表面法线偏移，单位为世界单位。 */
+    getLocationPosition(location: [number, number], height?: number): [number, number, number];
+    /** 球对象原点对应的世界球心。 */
+    getCenter(): [number, number, number];
+    /** 几何的本地半径，用于创建同坐标空间的地图图层。 */
     getRadius(): number;
-    checkBehindEarth(objArr: () => BaseObject[], cb: (obj: BaseObject[], res: boolean[]) => any): void;
+    /** 真球的世界半径；非均匀缩放或剪切形成椭球时不能用于球面路径。 */
+    getWorldRadius(): number;
+    private requireSurfaceTransform;
+    checkBehindEarth(objArr: () => BaseObject[], cb: (obj: BaseObject[], res: boolean[]) => any): () => void;
     /**
      * 设置物体在球面上的位置和旋转，使其垂直于球面
      * @param object - 要设置的物体
      * @param location - 经纬度 [经度, 纬度]
-     * @param height - 距离球面的高度，默认为0
-     * @param upAxis - 物体的up轴方向，默认为Y轴 [0, 1, 0]
+     * @param height - 沿球面世界法线的距离，默认为0
+     * @param upAxis - Plane 的本地面法线（默认 -Z，正面朝球心）；其他对象的本地朝向轴（默认 Y）
      */
     setObjectOnSphere(baseObject: BaseObject, location: [number, number], height?: number, upAxis?: [number, number, number]): void;
     getSceneBindings(): EarthSceneBindings;
@@ -682,7 +731,7 @@ declare class Map_3 extends Base_2 {
     get adcode(): number | undefined;
     activePlaneMap: PlaneMap | null;
     /** 宿主大屏图表等遮挡形成的运行时安全区；不写入场景 options。 */
-    private safeAreaInsets;
+    private safeAreaInsets?;
     private safeAreaRefitPending;
     parentBg: PlaneMap[];
     continentsBg?: ContinentsBg;
@@ -698,6 +747,8 @@ declare class Map_3 extends Base_2 {
      * 和 sceneBindings，因此在场景刚恢复时记录，供后续 fitTo 复用设计师视角。
      */
     private regionCameraFitReference?;
+    private authoredCameraPose?;
+    private cameraAngleOverrides?;
     setOptions(options: MapOptions): void;
     private _getProjectionCenter;
     private _getProjectionRotate;
@@ -760,12 +811,15 @@ declare class Map_3 extends Base_2 {
     private labelGroupObject3dUserData;
     eraseLabels(): void;
     geAdcodePosition(adcode: number): [number, number, number] | undefined;
-    getLocationPosition(location: [number, number]): [number, number, number];
+    /** 地图顶面的世界坐标；height 沿顶面世界法线偏移，单位为世界单位。 */
+    getLocationPosition(location: [number, number], height?: number): [number, number, number];
+    private getMainMapLocationPosition;
+    private worldToObjectParent;
     /**
      * 设置物体在平面地图上的位置
      * @param object - 要设置的物体
      * @param location - 经纬度 [经度, 纬度]
-     * @param height - 距离地图平面的高度，默认为0
+     * @param height - 沿地图顶面法线的世界距离，默认为0
      */
     setObjectOnMap(object: BaseObject, location: [number, number], height?: number): void;
     setObjectOnMapAreaByProperty(object: BaseObject, key: string, value: any, height?: number): void;
@@ -783,16 +837,19 @@ declare class Map_3 extends Base_2 {
     private _loadBaseGeojson;
     private getGeojson;
     /* Excluded from this release type: buildRegion */
+    /** 流式读取实际世界坐标，不复制或持有地图几何。 */
+    private cameraFitPoints;
+    private cameraForPose;
+    private captureCameraFitReference;
+    /** 没有选中命名视角时，使用导出场景中的实际相机朝向和位置。 */
+    private readAuthoredCameraPose;
+    private getCameraFitReference;
     private calcPaddingFromReference;
     fitTo(obj: BaseObject, { polarAngle, azimuthAngle, reference, z, handleStart, adcode, enableTransition, smoothTime, }?: {
         adcode?: number;
         polarAngle?: number;
         azimuthAngle?: number;
-        reference?: {
-            lookat: [number, number, number, number, number, number];
-            adcode?: number;
-            center?: [number, number];
-        };
+        reference?: MapCameraFitReference;
         enableTransition?: boolean;
         smoothTime?: number;
         z?: number;
@@ -807,11 +864,11 @@ declare class Map_3 extends Base_2 {
         adcode: number;
         extrudelineBloom?: boolean;
     }): Promise<PlaneMap>;
-    private hasSafeAreaInsets;
     private getEffectiveSafeAreaPadding;
-    getSafeAreaInsets(): MapSafeAreaInsets;
-    setSafeAreaInsets(insets: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
-    refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<void>;
+    /** undefined 表示沿用设计师构图；对象（包括全 0）表示宿主覆盖。 */
+    getSafeAreaInsets(): MapSafeAreaInsets | undefined;
+    setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
+    refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<boolean>;
     findAdcodeInfo(adcode: number): {
         adcode: number;
         lng: number;
@@ -848,7 +905,7 @@ declare class Map_3 extends Base_2 {
     /* Excluded from this release type: rebuildRegion */
     private rebuildRegionGeometry;
     /** 候选区域提交后的相机过渡，不参与场景序列化。 */
-    playRegionEnterTransition({ duration, sourceCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
+    playRegionEnterTransition({ duration, sourceCamera, preparedCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
     /** Region rules are page-local runtime overrides of a saved material asset. */
     private regionRuleMaterial;
     private setRegionTexture;
@@ -871,6 +928,20 @@ declare interface MapAssetSources {
     };
 }
 
+declare interface MapCameraFitReference {
+    lookat: MapCameraPose;
+    adcode?: number;
+    /** 兼容原有 reference 输入；留白计算使用真实地图几何。 */
+    center?: [number, number];
+    padding?: MapSafeAreaInsets;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+
+declare type MapCameraPose = [number, number, number, number, number, number];
+
 declare interface MapCityOptions extends MapOptions {
     cacheCity?: boolean;
     nearbyCities?: boolean | 'full';
@@ -944,6 +1015,7 @@ export declare interface MapRegionBackInteraction {
 
 declare interface MapRegionEnterTransitionOptions extends SceneEnterTransitionOptions {
     sourceCamera?: [number, number, number, number, number, number];
+    /* Excluded from this release type: preparedCamera */
 }
 
 export declare type MapRegionSceneResolver = (document: VisSceneDocument, adcode: number) => string | SceneViewportDocument | null | undefined | Promise<string | SceneViewportDocument | null | undefined>;
@@ -1255,6 +1327,7 @@ declare interface Options_5 extends NonNullable<ConstructorParameters<typeof Lin
     to: number[];
     control1?: number[];
     control2?: number[];
+    spherePath?: ArcSpherePath;
     radius?: number;
     globe?: boolean;
     color?: string;
@@ -1268,6 +1341,7 @@ declare interface Options_6 {
     multiplyScalar?: number;
     /** Compact saved inputs for an Arc's derived picking geometry. */
     arcControlPoints?: number[][];
+    arcSpherePath?: ArcSpherePath;
 }
 
 declare interface Options_7 {
@@ -1526,6 +1600,14 @@ declare interface SceneControlsOptions {
     autoRotateSpeed?: number;
 }
 
+export declare interface SceneDisplayContext {
+    sceneId: string;
+    /** 本次准备前已重新适配地图相机；false 的缓存页保留此前视角。 */
+    cameraRefitted: boolean;
+    /** 文档替换或 manager 销毁时取消准备。 */
+    signal: AbortSignal;
+}
+
 export declare interface SceneDocumentMarker {
     format: typeof SCENE_DOCUMENT_FORMAT;
     schemaVersion: number;
@@ -1567,8 +1649,9 @@ export declare class SceneManager extends Event_2 {
     private isSwitching;
     private isRegionSwitching;
     private pencil?;
-    private safeAreaInsets;
+    private safeAreaInsets?;
     private generation;
+    private displayPreparationAbort;
     private documentIdentityRevision;
     private preparedStructures;
     private pendingInstances;
@@ -1592,11 +1675,12 @@ export declare class SceneManager extends Event_2 {
     remapCommittedIdentity(sceneId: string, previous: string, next: string, objectIdentity: boolean): boolean;
     /**
      * 设置宿主界面的运行时地图安全区。该状态不进入场景文档，并会自动传给
-     * 当前地图、缓存地图和后续创建的地图区域。
+     * 当前、缓存和加载中的地图。对象（包括全 0）替代设计留白；undefined 清除覆盖。
      */
-    setSafeAreaInsets(insets: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
-    getSafeAreaInsets(): MapSafeAreaInsets;
+    setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
+    getSafeAreaInsets(): MapSafeAreaInsets | undefined;
     private captureCamera;
+    private prepareSceneDisplay;
     private playTransition;
     /** 更新可编辑文档，并释放已经不属于文档的非活动场景实例。 */
     setDocument(document: VisSceneDocument): void;
@@ -1724,6 +1808,8 @@ export declare interface SceneManagerBehaviorOptions {
     debugInteractions?: boolean;
     /** 创建场景后、恢复 JSON 前调用。 */
     prepareScene?: (scene: Base_2) => void;
+    /** 场景与最终相机就绪后、提交和首帧绘制前等待宿主准备。失败时保留原场景。 */
+    beforeSceneDisplay?: (scene: Base_2, context: SceneDisplayContext) => void | Promise<void>;
     /** 是否保留非活动场景实例；编辑器可关闭以限制 GPU/内存占用。 */
     cacheScenes?: boolean;
     /** Pages retained after navigation, including the active page; oldest inactive pages retire first. */
@@ -1920,6 +2006,26 @@ declare class Sphere extends MeshObject {
     create(): void;
 }
 
+/** Exact radial lift above the short great circle, expressed in object-local space. */
+declare class SphereArcCurve extends THREE.Curve<THREE.Vector3> {
+    readonly type = "SphereArcCurve";
+    readonly data: ArcSpherePath;
+    readonly matrix: THREE.Matrix4;
+    constructor(path: ArcSpherePath);
+    get v0(): THREE.Vector3;
+    get v3(): THREE.Vector3;
+    getPoint(t: number, target?: THREE.Vector3): THREE.Vector3;
+    getTangent(t: number, target?: THREE.Vector3): THREE.Vector3;
+    clone(): this;
+    copy(source: THREE.Curve<THREE.Vector3>): this;
+    toJSON(): SphereArcCurveJSON;
+    fromJSON(json: THREE.CurveJSON): this;
+}
+
+declare interface SphereArcCurveJSON extends THREE.CurveJSON {
+    spherePath: ArcSpherePath;
+}
+
 declare class SphereShadow extends MeshObject {
     objectType: string;
     options: Required<Options_3>;
@@ -1993,7 +2099,7 @@ declare interface TweenOptions {
 
 export declare function updateProjectMaterial<T extends VisSceneDocument>(document: T, assetId: string, patch: Partial<Pick<MaterialAsset, 'name' | 'material' | 'locked'>>): T;
 
-export declare const VERSION = "0.33.2";
+export declare const VERSION = "0.33.4";
 
 export declare interface VisSceneDocument extends SceneDocumentMarker {
     entrySceneId: string;