===============
LIBRARY RULES
===============
From library maintainers:
- Use "https://www.tuguan.net/public/tgapp/TGApp.min.js" as the online address of this library.
- Note that pickOverlay API command must be issued to enable any mouse click interaction.

### Add Path, Start, and Stop Path Following (JavaScript)

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Enables the camera to follow a predefined path overlay. This involves first adding the path using 'addPath' and then initiating the following behavior with 'pathingCamera'. The process can be stopped using 'stopPathingCamera'. Configuration options include path ID, looping, direction, distance from the path, pitch, and speed.

```javascript
// First, add a path overlay
function addCameraPath() {
    let pathData = {
        id: 'cameraPath',
        name: 'Camera Route',
        coordType: 0,
        coordTypeZ: 0,
        type: 'Segment06',      // Path style type
        color: '#00ff00',
        colorPass: '#00ff00',
        width: 2,
        visible: true,
        points: [
            { coord: [116.3500030557184, 40.08284427622822], coordZ: 0.357 },
            { coord: [116.3500530557184, 40.083374423769506], coordZ: 0.276 },
            { coord: [116.35010305571839, 40.08390457131078], coordZ: 0.195 },
            { coord: [116.35015305571839, 40.08443471885207], coordZ: 0.114 },
            { coord: [116.35020305571839, 40.08496486639335], coordZ: 0.033 }
        ]
    };

    appInstance.uniCall('addPath', pathData, (result) => {
        if (result.result === 1) {
            console.log("Path added successfully");
            startPathFollowing();
        }
    });
}

function startPathFollowing() {
    let pathingConfig = {
        pathId: 'cameraPath',   // ID of the path overlay
        loopMode: 'round',      // 'round'=loop, 'once'=single pass
        reverse: false,         // Movement direction
        distance: 30,           // Distance from path (meters)
        pitch: 5,               // Camera pitch angle
        speed: 10               // Movement speed
    };

    appInstance.uniCall('pathingCamera', pathingConfig, (result) => {
        if (result.result === 1) {
            console.log("Camera following path");
        }
    });
}

// Stop path following
function stopPathFollowing() {
    appInstance.uniCall('stopPathingCamera', {}, (result) => {
        console.log("Stopped following path");
    });
}
```

--------------------------------

### Start and Stop Camera Roaming (JavaScript)

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Initiates and stops automated camera tours along a sequence of waypoints. The roaming functionality supports looping, direction control, speed adjustments, and configurable stay durations at each waypoint. This is achieved using the 'roamingCamera' and 'stopRoamingCamera' uniCall methods.

```javascript
function startCameraRoaming() {
    let roamingConfig = {
        coordType: 0,
        coordTypeZ: 0,
        loopMode: 'round',      // 'round'=continuous loop, 'once'=single pass
        reverse: false,         // false=forward, true=backward
        speed: 10,              // Movement speed
        waypoints: [
            {
                centerCoord: [116.34953788361443, 40.08387756599562],
                coordZ: 65,
                distance: 500,
                pitch: 30,
                heading: 45,
                stay: 2000      // Stay duration in milliseconds
            },
            {
                centerCoord: [116.35153788361443, 40.08487756599562],
                coordZ: 80,
                distance: 600,
                pitch: 25,
                heading: 90,
                stay: 1500
            },
            {
                centerCoord: [116.35353788361443, 40.08587756599562],
                coordZ: 70,
                distance: 550,
                pitch: 35,
                heading: 135,
                stay: 2000
            }
        ]
    };

    appInstance.uniCall('roamingCamera', roamingConfig, (result) => {
        if (result.result === 1) {
            console.log("Camera roaming started");
        }
    });
}

// Stop roaming
function stopCameraRoaming() {
    appInstance.uniCall('stopRoamingCamera', {}, (result) => {
        console.log("Camera roaming stopped");
    });
}
```

--------------------------------

### Application Initialization - Client-Side Rendering

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Initializes a TGAPI application instance in client-side rendering mode for locally hosted 3D scenes. This involves creating an app instance, requesting a scene token from the server, and then initializing the service with the scene URL and token.

```APIDOC
## Application Initialization - Client-Side Rendering

### Description
Initializes a TGAPI application instance with client-side rendering mode for locally hosted 3D scenes. This process involves creating an app instance, obtaining a scene token from a server endpoint, and then initializing the service with the scene details.

### Method
POST (for token acquisition)

### Endpoint
- Token URL: `/api/user/v1/visitorScene/{id}`
- Scene URL: `/api/sceneEditor/v1/scenes/{id}/loadAVWS`

### Parameters
#### Request Body (for token acquisition POST request)
- **Content-Type**: `application/json charset=utf-8`

#### Request Body (for `appInstance.initService`)
- **container** (HTMLElement) - Required - The HTML element where the 3D scene will be rendered.
- **mode** (string) - Required - Set to `"scene"` for client-side rendering mode.
- **url** (string) - Required - The URL to load the 3D scene.
- **token** (string) - Required - The access token obtained from the server.
- **resourceBasePath** (string) - Optional - The path to local resources (e.g., lib/texture/resource).

### Request Example (Conceptual - Token Acquisition and Scene Initialization)
```javascript
// Create app instance
var appInstance = new TGApp.App();

// Request scene token from server
function onBodyLoaded() {
    let server = "www.tuguan.net";
    let id = "ed402a51-a00a-48f2-8b60-f51963440e82";
    let sceneUrl = `http://${server}/api/sceneEditor/v1/scenes/${id}/loadAVWS`;
    let tokenUrl = `http://${server}/api/user/v1/visitorScene/${id}`;

    let xhr = new XMLHttpRequest();
    xhr.open("post", tokenUrl, true);
    xhr.setRequestHeader("Content-Type", "application/json charset=utf-8");
    xhr.onreadystatechange = () => {
        if (xhr.readyState == 4 && xhr.status == 200) {
            let result = JSON.parse(xhr.responseText);
            loadScene(sceneUrl, result.accessToken);
        }
    };
    xhr.send();
}

// Initialize service with token
function loadScene(url, token) {
    appInstance.initService({
        container: document.getElementById("container"),
        mode: "scene",  // Client-side rendering mode
        url: url,
        token: token,
        resourceBasePath: './scene'  // Path to local resources (lib/texture/resource)
    }, (result) => {
        if (result.result === 1) {
            console.log("Service initialized successfully:", result.message);
            document.querySelector('.appLoading').className = 'appLoading hide';
        } else {
            console.error("Initialization failed:", result.message);
        }
    });
}

// Call onBodyLoaded when the body is ready
// onBodyLoaded(); 
```

### Response
#### Success Response (200 for token acquisition)
- **accessToken** (string) - The token required for scene initialization.

#### Success Response (Callback for `initService`)
- **result** (number) - 1 for success, other values for failure.
- **message** (string) - A message indicating the status of the initialization.

#### Response Example (Callback for `initService`)
```json
{
  "result": 1,
  "message": "Service initialized successfully: Scene loaded."
}
```
```

--------------------------------

### Initialize TGAPI App - Client-Side Rendering

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Initializes a TGAPI application instance for client-side rendering of locally hosted 3D scenes. This involves requesting a scene token from the server and then calling `initService` with the scene URL and token. It requires a DOM element for the container and specifies the rendering mode as 'scene'.

```javascript
var appInstance = new TGApp.App();

function onBodyLoaded() {
    let server = "www.tuguan.net";
    let id = "ed402a51-a00a-48f2-8b60-f51963440e82";
    let sceneUrl = `http://${server}/api/sceneEditor/v1/scenes/${id}/loadAVWS`;
    let tokenUrl = `http://${server}/api/user/v1/visitorScene/${id}`;

    let xhr = new XMLHttpRequest();
    xhr.open("post", tokenUrl, true);
    xhr.setRequestHeader("Content-Type", "application/json charset=utf-8");
    xhr.onreadystatechange = () => {
        if (xhr.readyState == 4 && xhr.status == 200) {
            let result = JSON.parse(xhr.responseText);
            loadScene(sceneUrl, result.accessToken);
        }
    };
    xhr.send();
}

function loadScene(url, token) {
    appInstance.initService({
        container: document.getElementById("container"),
        mode: "scene",  // Client-side rendering mode
        url: url,
        token: token,
        resourceBasePath: './scene'  // Path to local resources (lib/texture/resource)
    }, (result) => {
        if (result.result === 1) {
            console.log("Service initialized successfully:", result.message);
            document.querySelector('.appLoading').className = 'appLoading hide';
        } else {
            console.error("Initialization failed:", result.message);
        }
    });
}
```

--------------------------------

### Set Camera View and Get Camera Info (JavaScript)

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Controls the camera's position and orientation with optional smooth animation. It also provides a function to retrieve the current camera's positional and directional information. This utilizes the uniCall method for interacting with the camera system.

```javascript
function setCameraView() {
    let cameraConfig = {
        coordType: 0,           // 0=WGS84, 1=GCJ02, 2=BD09
        coordTypeZ: 0,          // 0=absolute altitude, 1=relative altitude
        centerCoord: [113.93989639458, 22.5110484727475],  // [longitude, latitude]
        coordZ: 500,            // Altitude in meters
        distance: 1500,         // Distance from target point
        pitch: 35,              // Pitch angle (0-90 degrees)
        heading: 0,             // Heading angle (0-360 degrees)
        fly: true,              // Enable smooth animation
        duration: 0.5           // Animation duration in seconds
    };

    appInstance.uniCall('setCamera', cameraConfig, (result) => {
        if (result.result === 1) {
            console.log("Camera positioned successfully");
        }
    });
}

// Get current camera information
function getCurrentCamera() {
    appInstance.uniCall('getCameraInfo', {}, (result) => {
        if (result.result === 1) {
            console.log("Camera position:", result.centerCoord);
            console.log("Altitude:", result.coordZ);
            console.log("Distance:", result.distance);
            console.log("Pitch:", result.pitch);
            console.log("Heading:", result.heading);
        }
    });
}
```

--------------------------------

### Initialize TGAPI App - Streaming Rendering

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Initializes a TGAPI application instance for server-side streaming rendering. This mode is suitable for scenes with lower client-side resource requirements. The initialization requires a token and the scene URL. It also includes an event listener for `onServiceInit` to confirm full initialization before proceeding.

```javascript
var appInstance = new TGApp.App();

function initStreamingMode(token) {
    appInstance.initService({
        container: document.getElementById("container"),
        mode: "streaming",  // Server-side streaming rendering
        url: "http://www.tuguan.net/api/sceneEditor/v1/scenes/scene-id/loadAVWS",
        token: token
    }, (result) => {
        if (result.result === 1) {
            console.log("Streaming service ready");
            appInstance.uniCall('addEventListener', {
                eventName: 'onServiceInit',
                callback: function(event) {
                    console.log("Service fully initialized:", event);
                    initializeScene();
                }
            });
        }
    });
}

function initializeScene() {
    console.log("Ready to add overlays and control scene");
}
```

--------------------------------

### Add Landmark with Interactive HTML Popup (JavaScript)

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Demonstrates how to add a landmark, enable click events on it, and then display a custom HTML tooltip associated with that landmark. It covers adding the landmark, setting up event listeners, creating and attaching the HTML tooltip, and removing it.

```javascript
function addLandmarkWithPopup() {
    // First add the landmark
    let landmarkData = {
        id: 'poi_residence',
        coordType: 0,
        coordTypeZ: 0,
        iconName: 'residence',
        label: '',
        tag: 'residential',
        coord: [116.34953788361443, 40.08387756599562],
        coordZ: 65,
        visible: true
    };

    appInstance.uniCall('addLandmark', landmarkData, (result) => {
        if (result.result === 1) {
            // Enable clicking
            appInstance.uniCall('pickOverlay', {
                overlayType: 'landmark',
                idLayer: 'poi_residence',
                type: 'click',
                isShowDecorator: false
            });
        }
    });

    // Listen for clicks
    appInstance.uniCall('addEventListener', {
        eventName: 'onLandmarkClick',
        callback: function(event) {
            if (event.id === 'poi_residence') {
                showCustomPopup();
            }
        }
    });
}

function showCustomPopup() {
    // Create custom HTML tooltip
    const tooltipDiv = document.createElement('div');
    tooltipDiv.id = 'customTooltip';
    tooltipDiv.innerHTML = `
        <div style="background: white; padding: 15px; border-radius: 5px; box-shadow: 0 2px 10px rgba(0,0,0,0.2);">
            <h3>Residential Building</h3>
            <p><strong>Address:</strong> 123 Main Street</p>
            <p><strong>Units:</strong> 48</p>
            <p><strong>Year Built:</strong> 2018</p>
            <button onclick="closePopup()">Close</button>
        </div>
    `;
    tooltipDiv.style.position = 'absolute';
    document.body.appendChild(tooltipDiv);

    // Attach tooltip to landmark
    let tipConfig = {
        id: 'poi_residence',
        url: '',                // Leave empty for custom HTML
        divId: 'customTooltip', // ID of the HTML element
        isShowClose: true,      // Show close button
        size: [300, 200],       // [width, height]
        offset: [50, -100],     // [x, y] offset from landmark
        overlayType: 'landmark'
    };

    appInstance.uniCall('addOverlayTip', tipConfig, (result) => {
        if (result.result === 1) {
            console.log("Tooltip displayed");
        }
    });
}

function closePopup() {
    appInstance.uniCall('removeOverlayTip', {
        id: 'poi_residence',
        overlayType: 'landmark'
    }, (result) => {
        // Remove HTML element
        const tooltip = document.getElementById('customTooltip');
        if (tooltip) {
            tooltip.remove();
        }
    });
}
```

--------------------------------

### Application Initialization - Streaming Rendering

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Initializes the TGAPI application in streaming rendering mode, which is suitable for server-rendered 3D scenes and requires lower client-side resources. It involves initializing the service and then listening for the 'onServiceInit' event to confirm readiness.

```APIDOC
## Application Initialization - Streaming Rendering

### Description
Initializes the TGAPI application with streaming rendering mode. This mode is designed for server-rendered 3D scenes, offering lower client-side resource requirements. The process includes initializing the service and subsequently listening for a confirmation event.

### Method
POST (implicitly used by `initService` for initialization)

### Endpoint
- Scene URL: `http://www.tuguan.net/api/sceneEditor/v1/scenes/scene-id/loadAVWS` (example provided)

### Parameters
#### Request Body (for `appInstance.initService`)
- **container** (HTMLElement) - Required - The HTML element where the 3D scene will be rendered.
- **mode** (string) - Required - Set to `"streaming"` for server-side streaming rendering mode.
- **url** (string) - Required - The URL to load the 3D scene.
- **token** (string) - Required - The access token obtained from the server.

### Request Example
```javascript
var appInstance = new TGApp.App();

// Initialize with streaming mode
function initStreamingMode(token) {
    appInstance.initService({
        container: document.getElementById("container"),
        mode: "streaming",  // Server-side streaming rendering
        url: "http://www.tuguan.net/api/sceneEditor/v1/scenes/scene-id/loadAVWS",
        token: token
    }, (result) => {
        if (result.result === 1) {
            console.log("Streaming service ready");
            // Listen for initialization complete event
            appInstance.uniCall('addEventListener', {
                eventName: 'onServiceInit',
                callback: function(event) {
                    console.log("Service fully initialized:", event);
                    initializeScene();
                }
            });
        }
    });
}

function initializeScene() {
    // Scene is ready for API calls
    console.log("Ready to add overlays and control scene");
}

// Example of calling initStreamingMode (assuming token is obtained elsewhere)
// initStreamingMode("your_access_token");
```

### Response
#### Success Response (Callback for `initService`)
- **result** (number) - 1 for success, other values for failure.
- **message** (string) - A message indicating the status of the initialization.

#### Success Response (Event data for `onServiceInit`)
- **event** (object) - Contains information about the service initialization completion.

#### Response Example (Callback for `initService`)
```json
{
  "result": 1,
  "message": "Streaming service initialized."
}
```

#### Response Example (Event data for `onServiceInit`)
```json
{
  "event": {
    "status": "initialized"
  }
}
```
```

--------------------------------

### Camera Control - Path Following

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Moves the camera along a predefined path overlay with automatic orientation adjustments and smooth transitions between points on the path.

```APIDOC
## Camera Control - Path Following

### Description
Moves camera along a predefined path overlay with automatic orientation and smooth transitions.

### Methods

*   **`addPath(pathData)`**: Adds a path overlay to the scene.
*   **`pathingCamera(config)`**: Starts the camera following the specified path overlay.
*   **`stopPathingCamera()`**: Stops the camera from following the current path.

### Parameters for `addPath`

*   **`pathData`** (object) - Required - Data defining the path overlay.
    *   **`id`** (string) - Required - Unique identifier for the path.
    *   **`name`** (string) - Optional - Name of the path.
    *   **`coordType`** (number) - Optional - Coordinate system type (0=WGS84, 1=GCJ02, 2=BD09). Defaults to 0.
    *   **`coordTypeZ`** (number) - Optional - Altitude reference (0=absolute, 1=relative). Defaults to 0.
    *   **`type`** (string) - Optional - Path style type (e.g., 'Segment06').
    *   **`color`** (string) - Optional - Path color (hex format).
    *   **`colorPass`** (string) - Optional - Color for the passed segment of the path.
    *   **`width`** (number) - Optional - Path width.
    *   **`visible`** (boolean) - Optional - Whether the path is visible. Defaults to true.
    *   **`points`** (array) - Required - An array of points defining the path.
        *   **`coord`** (array) - Required - [longitude, latitude] of the point.
        *   **`coordZ`** (number) - Required - Altitude of the point.

### Parameters for `pathingCamera`

*   **`config`** (object) - Required - Configuration object for path following.
    *   **`pathId`** (string) - Required - The ID of the path overlay to follow.
    *   **`loopMode`** (string) - Optional - Defines the looping behavior ('round' for loop, 'once' for single pass). Defaults to 'round'.
    *   **`reverse`** (boolean) - Optional - Movement direction (false=forward, true=backward). Defaults to false.
    *   **`distance`** (number) - Optional - Distance from the path in meters. Defaults to 30.
    *   **`pitch`** (number) - Optional - Camera pitch angle in degrees. Defaults to 5.
    *   **`speed`** (number) - Optional - Movement speed. Defaults to 10.

### Parameters for `stopPathingCamera`

*   No parameters required.

### Request Example for `addPath`

```javascript
let pathData = {
    id: 'cameraPath',
    coordType: 0,
    coordTypeZ: 0,
    type: 'Segment06',
    color: '#00ff00',
    width: 2,
    visible: true,
    points: [
        { coord: [116.3500030557184, 40.08284427622822], coordZ: 0.357 },
        { coord: [116.3500530557184, 40.083374423769506], coordZ: 0.276 },
        { coord: [116.35010305571839, 40.08390457131078], coordZ: 0.195 },
        { coord: [116.35015305571839, 40.08443471885207], coordZ: 0.114 },
        { coord: [116.35020305571839, 40.08496486639335], coordZ: 0.033 }
    ]
};
appInstance.uniCall('addPath', pathData, (result) => { ... });
```

### Request Example for `pathingCamera`

```javascript
let pathingConfig = {
    pathId: 'cameraPath',
    loopMode: 'round',
    reverse: false,
    distance: 30,
    pitch: 5,
    speed: 10
};
appInstance.uniCall('pathingCamera', pathingConfig, (result) => { ... });
```

### Request Example for `stopPathingCamera`

```javascript
appInstance.uniCall('stopPathingCamera', {}, (result) => { ... });
```

### Response Example for `addPath` (Success)

```json
{
  "result": 1,
  "message": "Path added successfully"
}
```

### Response Example for `pathingCamera` (Success)

```json
{
  "result": 1,
  "message": "Camera following path"
}
```

### Response Example for `stopPathingCamera` (Success)

```json
{
  "result": 1,
  "message": "Stopped following path"
}
```
```

--------------------------------

### JavaScript: Add, Update, and Remove Path Overlays (Routes/Trajectories)

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Demonstrates how to add a new path overlay, update an existing one with new points and styles, and remove a path overlay using the TGIS API. Requires an initialized `appInstance` and provides options for styling and animation.

```javascript
function addRoutePath() {
    let pathData = {
        id: 'route_001',
        name: 'Delivery Route',
        coordType: 0,
        coordTypeZ: 0,
        type: 'Segment06',      // Path style (various types available)
        color: '#0088ff',       // Path color
        colorPass: '#00ff00',   // Color for passed sections (animations)
        width: 3,               // Line width
        visible: true,
        speed: 50,              // Animation speed (if animated)
        points: [
            { coord: [116.350003, 40.082844], coordZ: 0.5 },
            { coord: [116.350253, 40.083144], coordZ: 0.5 },
            { coord: [116.350503, 40.083374], coordZ: 0.6 },
            { coord: [116.350753, 40.083604], coordZ: 0.7 },
            { coord: [116.351003, 40.083904], coordZ: 0.8 }
        ]
    };

    appInstance.uniCall('addPath', pathData, (result) => {
        if (result.result === 1) {
            console.log("Path added successfully");
        }
    });
}

// Update path dynamically
function updatePath() {
    let updateData = {
        id: 'route_001',
        color: '#ff0000',       // Change color
        width: 5,               // Change width
        visible: true,
        points: [
            { coord: [116.350003, 40.082844], coordZ: 0.5 },
            { coord: [116.350453, 40.083244], coordZ: 0.6 },
            { coord: [116.350903, 40.083644], coordZ: 0.7 }
        ]
    };

    appInstance.uniCall('updatePath', updateData, (result) => {
        console.log("Path updated");
    });
}

// Remove path
function removePath() {
    appInstance.uniCall('removeOverlay', {
        id: 'route_001',
        overlayType: 'path'
    }, (result) => {
        console.log("Path removed");
    });
}
```

--------------------------------

### Manage Scene Switching and Effects - JavaScript

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Facilitates switching between different scenes within an application, supporting both instant transitions and animated fly-to effects with configurable durations. It also allows for the application of environmental effects such as lighting, shadows, weather, and atmosphere settings. The 'appInstance' object with its 'uniCall' method is required for these operations. Inputs include scene IDs and configuration objects for effects.

```javascript
function listScenes() {
    appInstance.uniCall('getScenesInfo', {}, (result) => {
        if (result.result === 1) {
            console.log("Available scenes:", result.scenes);
            result.scenes.forEach(scene => {
                console.log(`Scene ID: ${scene.id}, Name: ${scene.name}`);
            });
        }
    });
}

function switchToScene(sceneId) {
    appInstance.uniCall('switchScene', {
        sceneId: sceneId
    }, (result) => {
        if (result.result === 1) {
            console.log("Scene switched successfully");
        }
    });
}

function flyToScene(sceneId) {
    appInstance.uniCall('flyToScene', {
        sceneId: sceneId,
        duration: 2.0           // Transition duration in seconds
    }, (result) => {
        console.log("Flying to new scene");
    });
}

function setSceneEnvironment() {
    let effectsConfig = {
        lighting: {
            ambient: 0.6,       // Ambient light intensity (0-1)
            sunlight: 0.8,      // Sunlight intensity (0-1)
            sunAngle: 45        // Sun elevation angle
        },
        shadow: {
            enabled: true,      // Enable shadows
            quality: 'high'     // 'low', 'medium', 'high'
        },
        weather: {
            type: 'clear',      // 'clear', 'rain', 'snow', 'fog'
            intensity: 0.5      // Weather effect intensity
        },
        atmosphere: {
            fog: true,
            fogDensity: 0.001,  // Fog density
            skybox: true        // Show skybox
        }
    };

    appInstance.uniCall('setSceneEffect', effectsConfig, (result) => {
        if (result.result === 1) {
            console.log("Scene effects applied");
        }
    });
}
```

--------------------------------

### Camera Control - Roaming Along Waypoints

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Creates automated camera tours that smoothly transition between predefined waypoints with configurable timing and loop modes.

```APIDOC
## Camera Control - Roaming Along Waypoints

### Description
Creates automated camera tours that smoothly transition between predefined waypoints with configurable timing and loop modes.

### Methods

*   **`roamingCamera(config)`**: Starts an automated camera tour along a defined set of waypoints.
*   **`stopRoamingCamera()`**: Stops the current automated camera tour.

### Parameters for `roamingCamera`

*   **`config`** (object) - Required - Configuration object for the camera roaming.
    *   **`coordType`** (number) - Optional - Coordinate system type (0=WGS84, 1=GCJ02, 2=BD09). Defaults to 0.
    *   **`coordTypeZ`** (number) - Optional - Altitude reference (0=absolute, 1=relative). Defaults to 0.
    *   **`loopMode`** (string) - Optional - Defines the looping behavior ('round' for continuous, 'once' for single pass). Defaults to 'round'.
    *   **`reverse`** (boolean) - Optional - Determines the movement direction (false=forward, true=backward). Defaults to false.
    *   **`speed`** (number) - Optional - Movement speed. Defaults to 10.
    *   **`waypoints`** (array) - Required - An array of waypoint objects defining the camera's path.
        *   **`centerCoord`** (array) - Required - [longitude, latitude] of the waypoint.
        *   **`coordZ`** (number) - Required - Altitude in meters.
        *   **`distance`** (number) - Required - Distance from the waypoint in meters.
        *   **`pitch`** (number) - Optional - Pitch angle in degrees (0-90).
        *   **`heading`** (number) - Optional - Heading angle in degrees (0-360).
        *   **`stay`** (number) - Optional - Duration in milliseconds to stay at the waypoint. Defaults to 0.

### Parameters for `stopRoamingCamera`

*   No parameters required.

### Request Example for `roamingCamera`

```javascript
let roamingConfig = {
    coordType: 0,
    coordTypeZ: 0,
    loopMode: 'round',
    reverse: false,
    speed: 10,
    waypoints: [
        { centerCoord: [116.34953788361443, 40.08387756599562], coordZ: 65, distance: 500, pitch: 30, heading: 45, stay: 2000 },
        { centerCoord: [116.35153788361443, 40.08487756599562], coordZ: 80, distance: 600, pitch: 25, heading: 90, stay: 1500 },
        { centerCoord: [116.35353788361443, 40.08587756599562], coordZ: 70, distance: 550, pitch: 35, heading: 135, stay: 2000 }
    ]
};
appInstance.uniCall('roamingCamera', roamingConfig, (result) => { ... });
```

### Request Example for `stopRoamingCamera`

```javascript
appInstance.uniCall('stopRoamingCamera', {}, (result) => { ... });
```

### Response Example for `roamingCamera` (Success)

```json
{
  "result": 1,
  "message": "Camera roaming started"
}
```

### Response Example for `stopRoamingCamera` (Success)

```json
{
  "result": 1,
  "message": "Camera roaming stopped"
}
```
```

--------------------------------

### Add and Manage Starlight Layers in JavaScript

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

This snippet shows how to create a starlight layer for highlighting point distributions with glowing effects. It covers adding the layer with custom colors and radii, updating its data dynamically by appending new points, and modifying its visual style.

```javascript
function addStarLightLayer() {
    let starlightData = {
        id: 'starlight_001',
        name: 'Activity Hotspots',
        coordType: 0,
        coordTypeZ: 0,
        coordZ: 10,             // Base altitude in meters
        alpha: 0.3,             // Transparency (0-1)
        color: '#ff0000',       // Star color
        radius: 1,              // Star radius in meters
        visible: true,
        tags: ['hotspot', 'activity'],
        data: [
            [113.326675, 23.124065],
            [113.327721, 23.127426],
            [113.328450, 23.125890],
            [113.329100, 23.126500]
        ]
    };

    appInstance.uniCall('addStarLightLayer', starlightData, (result) => {
        if (result.result === 1) {
            console.log("Starlight layer added");
        }
    });
}

// Update starlight data dynamically
function updateStarLightData() {
    let updateData = {
        id: 'starlight_001',
        coordType: 0,
        coordTypeZ: 0,
        coordZ: 15,
        isAppend: true,         // Append to existing data
        data: [
            [113.330000, 23.128000],
            [113.331000, 23.129000]
        ]
    };

    appInstance.uniCall('updateStarLightLayerCoord', updateData, (result) => {
        console.log("Starlight data updated");
    });
}

// Update starlight style
function updateStarLightStyle() {
    appInstance.uniCall('updateStarLightLayerStyle', {
        id: 'starlight_001',
        alpha: 0.5,
        color: '#00ff00',
        radius: 2
    }, (result) => {
        console.log("Starlight style updated");
    });
}
```

--------------------------------

### JavaScript: Add and Manage Interactive Landmark Overlays

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Add points of interest (landmarks) to the 3D scene with custom icons, labels, and positioning. Enables click and hover interactions on landmarks, with listeners for these events. Requires `appInstance` for API calls.

```javascript
function addLandmarkMarkers() {
    let landmarkData = {
        id: 'poi_001',
        coordType: 0,
        coordTypeZ: 0,
        iconName: 'residence',
        label: 'Residential Building A',
        tag: 'residential',
        coord: [116.34953788361443, 40.08387756599562],
        coordZ: 65,
        visible: true,
        scale: 1.0,
        rotation: 0
    };

    appInstance.uniCall('addLandmark', landmarkData, (result) => {
        if (result.result === 1) {
            console.log("Landmark added:", result.message);
            enableLandmarkInteraction();
        }
    });
}

function enableLandmarkInteraction() {
    appInstance.uniCall('pickOverlay', {
        overlayType: 'landmark',
        idLayer: 'poi_001',
        type: 'click',
        isShowDecorator: false
    }, (result) => {
        console.log("Landmark interaction enabled");
    });

    appInstance.uniCall('addEventListener', {
        eventName: 'onLandmarkClick',
        callback: function(event) {
            console.log("Landmark clicked:", event.id);
            console.log("Coordinates:", event.coord);
            console.log("Custom tag:", event.tag);
            showLandmarkPopup(event.id);
        }
    });

    appInstance.uniCall('addEventListener', {
        eventName: 'onLandmarkHover',
        callback: function(event) {
            console.log("Mouse entered landmark:", event.id);
        }
    });

    appInstance.uniCall('addEventListener', {
        eventName: 'onLandmarkUnhover',
        callback: function(event) {
            console.log("Mouse left landmark:", event.id);
        }
    });
}
```

--------------------------------

### Control Overlay Layer Visibility and Ordering - JavaScript

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Manage the visibility and z-order of individual overlay layers, groups of overlays by type, or by custom tags. It also includes functions to retrieve the current layer order and manipulate the forward/backward positioning of specific overlays. This is useful for complex scene compositions where precise layer control is needed. Dependencies include the 'appInstance' object with its 'uniCall' method.

```javascript
function toggleOverlayVisibility(overlayId, isVisible) {
    appInstance.uniCall('setOverlayVisibility', {
        id: overlayId,
        visible: isVisible
    }, (result) => {
        console.log(`Overlay ${overlayId} visibility: ${isVisible}`);
    });
}

function toggleOverlayTypeVisibility(type, isVisible) {
    appInstance.uniCall('setOverlayTypeVisibility', {
        overlayType: type,      // 'landmark', 'path', 'area', etc.
        visible: isVisible
    }, (result) => {
        console.log(`All ${type} overlays visibility: ${isVisible}`);
    });
}

function toggleOverlaysByTag(tag, isVisible) {
    appInstance.uniCall('setOverlayTagsVisibility', {
        tags: [tag],            // Array of tag strings
        visible: isVisible
    }, (result) => {
        console.log(`Overlays with tag '${tag}' visibility: ${isVisible}`);
    });
}

function getLayerOrdering() {
    appInstance.uniCall('getOverlaysOrder', {}, (result) => {
        if (result.result === 1) {
            console.log("Layer order (bottom to top):", result.overlays);
            // result.overlays is array of overlay IDs in z-order
        }
    });
}

function bringOverlayForward(overlayId) {
    appInstance.uniCall('moveOverlayForward', {
        id: overlayId,
        overlayType: 'landmark'  // Specify overlay type
    }, (result) => {
        console.log("Overlay moved forward");
    });
}

function sendOverlayBackward(overlayId) {
    appInstance.uniCall('moveOverlayBackward', {
        id: overlayId,
        overlayType: 'landmark'
    }, (result) => {
        console.log("Overlay moved backward");
    });
}

function setupLayerHierarchy() {
    toggleOverlayTypeVisibility('gisMap', true);
    toggleOverlayVisibility('zone_001', true);
    toggleOverlayVisibility('route_001', true);
    toggleOverlayTypeVisibility('landmark', true);
    bringOverlayForward('poi_001');
}
```

--------------------------------

### Add Trail Layer with JavaScript

Source: https://context7.com/lucas-dh/tgapidocs-testflight/llms.txt

Demonstrates how to add a trail layer to visualize moving objects. It configures trail properties such as duration, width, and associated legends with specific icon and color configurations. This function expects an `appInstance` object with a `uniCall` method and triggers `startTrackingVehicles` upon successful addition.

```javascript
function addTrailLayer() {
    let trailData = {
        id: 'trail_001',
        name: 'Vehicle Tracking',
        coordType: 0,
        coordTypeZ: 0,
        trackStyle: 'style001',     // Trail particle style
        trackDuration: 10,          // Trail lifetime in seconds
        iconRotate: 'auto',         // 'disable', 'auto', or 'manual'
        objLife: 30,                // Object batch lifetime
        trackWidth: 10,             // Trail width
        trackVisible: 'ShowAll',    // 'ShowAll', 'HideAll', or object ID
        duration: 1,                // Movement duration in seconds
        visible: true,
        tags: ['vehicles', 'tracking'],
        legends: [
            {
                name: 'car',
                iconName: 'car',        // Built-in icon name
                iconScale: 1,
                labelScale: 1,
                trackColor: '#ff0000'
            },
            {
                name: 'taxi',
                iconName: 'taxi',
                iconScale: 1,
                labelScale: 1,
                trackColor: '#99ECFB'
            },
            {
                name: 'ambulance',
                iconName: 'ambulance',
                iconScale: 1,
                labelScale: 1,
                trackColor: '#fff000'
            }
        ],
        data: [
            {
                id: '1',
                label: 'Vehicle 1',
                coord: [113.942536, 22.517767],
                coordZ: 64,
                yaw: 0,                 // Rotation angle
                type: 'car'
            },
            {
                id: '2',
                label: 'Taxi 1',
                coord: [113.942508, 22.517455],
                coordZ: 64,
                yaw: 0,
                type: 'taxi'
            }
        ]
    };

    appInstance.uniCall('addTrailLayer', trailData, (result) => {
        if (result.result === 1) {
            console.log("Trail layer added");
            startTrackingVehicles();
        }
    });
}

// Update vehicle positions to create animated trails
function startTrackingVehicles() {
    const updates = [
        {
            id: 'trail_001',
            coordType: 0,
            coordTypeZ: 0,
            isAppend: true,
            duration: 1,
            data: [
                {
                    id: '1',
                    label: 'Vehicle 1',
                    coord: [113.941495, 22.518460],
                    coordZ: 64,
                    yaw: 0,
                    type: 'car'
                },
                {
                    id: '2',
                    label: 'Taxi 1',
                    coord: [113.941538, 22.518856],
                    coordZ: 64,
                    yaw: 0,
                    type: 'taxi'
                }
            ]
        }
    ];

    // Update positions periodically
    updates.forEach((update, index) => {
        setTimeout(() => {
            appInstance.uniCall('updateTrailLayerCoord', update, (result) => {
                console.log("Vehicle positions updated");
            });
        }, index * 1000);
    });
}

// Update trail style
function updateTrailStyle() {
    appInstance.uniCall('updateTrailLayerStyle', {
        id: 'trail_001',
        trackStyle: 'style001',
        trackDuration: 5,
        trackWidth: 10,
        trackVisible: 'ShowAll',
        legends: [
            {
                name: 'car',
                iconName: 'policecar',
                iconScale: 1.2,
                labelScale: 1,
                trackColor: '#00BFFF'
            }
        ]
    }, (result) => {
        console.log("Trail style updated");
    });
}

```