Scene API Docs#

Overview#

window.scene.api is the JavaScript API interface exposed by GeoTwin APP, allowing external systems to control and manipulate the 3D scene map through this interface. External systems (including page scripts, integration platforms, etc.) should uniformly call related functions through window.scene.api.

Initialization#

When the scene map component is created, the API is automatically mounted to window.scene.api. You can listen for the sceneReady event to ensure the API is ready:

window.addEventListener('sceneReady', (event) => {
    const { compositeViewer, viewer } = event.detail;
    console.log('Scene is ready');
    // Now you can safely use window.scene.api
});

API Methods#

getCompositeViewer()#

Gets the composite viewer instance.

Returns:

• CompositeViewer - Composite viewer instance containing all component managers of the scene

Example:

const compositeViewer = window.scene.api.getCompositeViewer();
const layerComponent = compositeViewer.componentManager.getComponent(LayerComponent);

getBookmark()#

Gets the bookmark list for the current scene. This method requests the backend API to fetch bookmark data associated with the current scene's sceneId.

Note:

• Depends on sceneId in scene data and option.server in map component configuration (used as API baseURL)
• If sceneId or server cannot be obtained, returns a rejected Promise

Returns:

• Promise<any> - Raw response data from the bookmark list API

Example:

window.scene.api.getBookmark()
  .then((res) => {
    // Specific structure depends on backend implementation, here's a typical usage
    const rows = res.data?.data?.rows ?? [];
    console.log('Bookmark list:', rows);
  })
  .catch((err) => {
    console.error('Failed to get bookmarks:', err);
  });

triggerSceneGraphDelta(delta)#

Triggers a scene graph incremental update for adding, deleting, or modifying nodes in the scene.

Parameters:

• delta: ISceneGraphDelta - Scene graph delta data object

ISceneGraphDelta Types:

1. Insert Node

{
    type: "Insert",
    delta: INodeData  // Complete node data
}

2. Change Node

{
    type: "Change",
    delta: {
        guid: string,  // Required: unique identifier of the node
        // Other properties to modify (optional)
        name?: string,
        visible?: boolean,
        // ... other INodeData properties
    }
}

3. Delete Node

{
    type: "Delete",
    delta: {
        guid: string,  // Required: unique identifier of the node to delete
    }
}

Example:

// Modify node visibility
window.scene.api.triggerSceneGraphDelta({
    type: "Change",
    delta: {
        guid: "node-guid-123",
        visible: false
    }
});

// Delete node
window.scene.api.triggerSceneGraphDelta({
    type: "Delete",
    delta: {
        guid: "node-guid-123"
    }
});

genGUID()#

Generates a GUID, ensuring that entities created externally use the same ID generation rules as entities in the scene graph.

Returns:

• GUID - GUID

Example:

const guid = window.scene.api.genGUID()

flyTo(...args)#

Flies the camera to a specified position.

Parameters:

• x: number - X coordinate
• y: number - Y coordinate
• z: number - Z coordinate (height)
• heading?: number - Heading angle (degrees)
• pitch?: number - Pitch angle (degrees)
• roll?: number - Roll angle (degrees)
• duration?: number - Flight duration (milliseconds)

Example:

// Fly to specified position
window.scene.api.flyTo({
    x: 0,
    y: 0,
    z: 1000,
    heading: 0,
    pitch: -45,
    duration: 2000
});

flyToEntity(guid)#

Flies the camera to a specified entity (layer).

Parameters:

• guid: string - Unique identifier GUID of the entity

Example:

// Fly to specified layer
window.scene.api.flyToEntity("layer-guid-123");

flyToGeometry(geometry)#

Flies the camera to a specified GeoJSON geometry.

Parameters:

• geometry: Geometry - GeoJSON standard geometry object

GeoJSON Geometry Types include:

• Point - Point
• LineString - Line
• Polygon - Polygon
• MultiPoint - Multi-point
• MultiLineString - Multi-line
• MultiPolygon - Multi-polygon

Example:

// Fly to polygon area
window.scene.api.flyToGeometry({
    type: "Polygon",
    coordinates: [
        [
            [116.3, 39.9],
            [116.4, 39.9],
            [116.4, 40.0],
            [116.3, 40.0],
            [116.3, 39.9]
        ]
    ]
});

// Fly to point
window.scene.api.flyToGeometry({
    type: "Point",
    coordinates: [116.404, 39.915]
});

flyToBookmark(bookmark, duration)#

Flies to a specified view position based on bookmark data.

Parameters:

• bookmark: object - Bookmark data object, typically containing the following fields:
  • longitude: number - Bookmark longitude (WGS84, EPSG:4326)
  • latitude: number - Bookmark latitude (WGS84, EPSG:4326)
  • height: number - Camera height
  • heading: number - Heading angle (degrees)
  • tilt: number - Pitch angle (degrees)
• duration: number - Flight duration (seconds)

Example:

const bookmark = {
  longitude: 116.404,
  latitude: 39.915,
  height: 500,
  heading: 30,
  tilt: -45,
};

// Fly to bookmark position in 3 seconds
window.scene.api.flyToBookmark(bookmark, 3);

translateCoord(options)#

Coordinate transformation utility method, based on the engine's built-in CoordTransform.translate implementation, allowing conversion between different coordinate systems / projections.

Parameters:

• options: object - Coordinate transformation configuration object, common fields include:
  • fromEPSG?: string - Source coordinate system EPSG code (e.g., "4326")
  • toProj4?: string - Target projection proj4 string (usually obtained from viewer.proj4)
  • x: number - Source coordinate X (longitude or planar X)
  • y: number - Source coordinate Y (latitude or planar Y)

Returns:

• number[] - Transformed coordinate array, typically [x, y]

Example:

const cv = window.scene.api.getCompositeViewer();
const viewer = cv.viewer;

// Convert WGS84 coordinates to current scene projection coordinates
const [x, y] = window.scene.api.translateCoord({
  fromEPSG: "4326",
  toProj4: viewer.proj4,
  x: 116.404,
  y: 39.915,
});

console.log('Projected coordinates:', x, y);

setViewMode(mode)#

Sets the view mode.

Parameters:

• mode: "2D" | "3D" - View mode
  • "2D" - 2D flat view
  • "3D" - 3D stereoscopic view

Example:

// Switch to 2D mode
window.scene.api.setViewMode("2D");

// Switch to 3D mode
window.scene.api.setViewMode("3D");

backToTheNorth()#

Resets the camera heading to north (heading = 0), maintaining current position and pitch angle.

Example:

// Return to north direction
window.scene.api.backToTheNorth();

getFlyControl()#

Gets the fly control component instance (FlyThroughComponent) for implementing more complex flight path control and other advanced features.

Returns:

• FlyThroughComponent - Fly control component instance, see @gt-viewer/sdk documentation for specific capabilities

Example:

const flyControl = window.scene.api.getFlyControl();
// Use flyControl instance for custom flight control according to SDK documentation

vectorHighlight Highlight Control#

vectorHighlight is a sub-object mounted under window.scene.api for controlling highlight effects on vector layers.

vectorHighlight.add(guid, ids)#

Adds highlighted features to a specified vector layer.

Parameters:

• guid: string - Layer GUID
• ids: number[] - Array of feature IDs to highlight

Example:

// Highlight features with IDs 1, 2, 3 in the layer
window.scene.api.vectorHighlight.add("layer-guid-123", [1, 2, 3]);

vectorHighlight.remove(guid, ids)#

Removes highlight effects from specified features.

Parameters:

• guid: string - Layer GUID
• ids: number[] - Array of feature IDs to remove highlight from

Example:

// Remove highlight from features 2, 3
window.scene.api.vectorHighlight.remove("layer-guid-123", [2, 3]);

vectorHighlight.clear(guid)#

Clears all highlight effects from a specified layer.

Parameters:

• guid: string - Layer GUID

Example:

// Clear all highlights from the layer
window.scene.api.vectorHighlight.clear("layer-guid-123");

Other Events#

sceneGraphChange Event#

Triggered when the scene graph changes.

Listen Example:

window.addEventListener('sceneGraphChange', (event) => {
    const sceneData = event.detail.data;
    console.log('Scene graph updated', sceneData);
});

Complete Usage Example#

// Wait for scene to be ready
window.addEventListener('sceneReady', (event) => {
    console.log('Scene is ready');

    // Get composite viewer
    const compositeViewer = window.scene.api.getCompositeViewer();

    // Fly to specified position
    window.scene.api.flyTo({
        x: 0,
        y: 0,
        z: 5000,
        heading: 0,
        pitch: -60,
        duration: 3000
    });

    // Switch to 2D view after 3 seconds
    setTimeout(() => {
        window.scene.api.setViewMode("2D");
    }, 3000);

    // Return to north direction after 6 seconds
    setTimeout(() => {
        window.scene.api.backToTheNorth();
    }, 6000);
});

// Listen for scene graph changes
window.addEventListener('sceneGraphChange', (event) => {
    console.log('Scene data updated:', event.detail.data);
});

// Modify node visibility
function toggleNodeVisibility(guid, visible) {
    window.scene.api.triggerSceneGraphDelta({
        type: "Change",
        delta: {
            guid: guid,
            visible: visible
        }
    });
}

// Fly to an entity
function focusOnEntity(guid) {
    window.scene.api.flyToEntity(guid);
}

// Fly to Tiananmen, Beijing
function flyToTiananmen() {
    window.scene.api.flyToGeometry({
        type: "Point",
        coordinates: [116.404, 39.915]
    });
}

Data Structures#

INodeData#

Node data structure (simplified version):

interface INodeData {
    guid: string;           // Node unique identifier
    type: string;           // Node type: VIEWER | LAYER | FEATURE
    name?: string;          // Node name
    visible?: boolean;      // Whether visible
    parentIndex?: number;   // Parent node index
    render?: object;        // Render data
    animation?: any[];      // Animation data
    meta?: object;          // Metadata
}

Notes#

1. API Availability: Ensure the API is used after the sceneReady event is triggered
2. GUID Format: All GUID parameters should be valid string identifiers
3. Coordinate System: Coordinate parameters depend on the projection coordinate system used by the scene
4. Angle Units: heading, pitch, roll parameters in flyTo method are in degrees
5. Asynchronous Operations: Flight operations are asynchronous; use appropriate delays or callbacks if you need to execute operations after flight completion

Version Information#

• Documentation version: 1.1.0
• Updated: 2026-02-28