vis-core 0.33.3 → 0.33.4

package/dist/index.d.ts

@@ -53,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;
@@ -76,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;
@@ -117,6 +157,9 @@ declare class Base_2 extends Camera {
     visName: string;
     private detectRes?;
     private ownsPencil;
+    private renderingSuspensions;
+    /* Excluded from this release type: suspendRendering */
+    private acquireRenderingSuspensions;
     publicDir: Record<string, string>;
     private prefabAssets;
     private prefabMaterials;
@@ -445,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;
@@ -533,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;
@@ -759,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;
@@ -813,7 +868,7 @@ declare class Map_3 extends Base_2 {
     /** undefined 表示沿用设计师构图；对象（包括全 0）表示宿主覆盖。 */
     getSafeAreaInsets(): MapSafeAreaInsets | undefined;
     setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
-    refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<void>;
+    refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<boolean>;
     findAdcodeInfo(adcode: number): {
         adcode: number;
         lng: number;
@@ -850,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;
@@ -960,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>;
@@ -1271,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;
@@ -1284,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 {
@@ -1542,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;
@@ -1585,6 +1651,7 @@ export declare class SceneManager extends Event_2 {
     private pencil?;
     private safeAreaInsets?;
     private generation;
+    private displayPreparationAbort;
     private documentIdentityRevision;
     private preparedStructures;
     private pendingInstances;
@@ -1613,6 +1680,7 @@ export declare class SceneManager extends Event_2 {
     setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
     getSafeAreaInsets(): MapSafeAreaInsets | undefined;
     private captureCamera;
+    private prepareSceneDisplay;
     private playTransition;
     /** 更新可编辑文档，并释放已经不属于文档的非活动场景实例。 */
     setDocument(document: VisSceneDocument): void;
@@ -1740,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. */
@@ -1936,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>;
@@ -2009,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.3";
+export declare const VERSION = "0.33.4";
 
 export declare interface VisSceneDocument extends SceneDocumentMarker {
     entrySceneId: string;