ESMap3.0 SDK

https://www.esmap.cn/docs/sdk3.0-document/
Admin
ESMap3.0 SDK是一个三维可视化引擎，它集成了室内和城市三维场景，使开发者能够在Web浏览器中展示交互式的三维环境。
Tokens:95,658
Snippets:490
Trust Score:5.5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Switch Indoor Scene ID in City Mode with openBuildingById

Source: https://www.esmap.cn/docs/sdk3.0-document/map-switchMap

This code snippet illustrates how to switch indoor maps within a city context using the `openBuildingById` method. Similar to the `openMapById` example, it manages state variables for scene IDs and a flag to control switching frequency, ensuring a smooth user experience. This is ideal for applications that feature city-scale environments with selectable indoor locations.

```javascript
// 第一步：准备必要的变量定义
const innerMapIDList = ['10005', 'test666']       // 存储需要切换的id数组
const curSelectedID = { value: '10005',index: 0 } // 当前场景id
const isAllowSwitchSign = { value: true }         // 判定是否允许切换场景，可用于按钮状态

// 第二步：设定由按钮触发，点击切换下一个场景
function switchMapBtn () {
    if (isAllowSwitchSign.value) {
        innerMapIDList.some((bid,index) => {
            if (bid !== curSelectedID.value) {

                // 该业务场景仅供参考，与当前场景ID不同时切换该场景
                curSelectedID.value = bid
                curSelectedID.index = index

                // *********** 关键API：城市模式下，执行切换室内场景 ***********
                map.openBuildingById(bid)
                return true
            }
        })

        // 第三步：监听一次场景加载进度是否完成，避免频繁切换操作
        isAllowSwitchSign.value = false         // 切换按钮不可点击
        map.once('progressComplete', () => {    // 监听完成一次便会销毁该事件
            // 监听到场景完全加载完毕，恢复按钮可点击
            isAllowSwitchSign.value = true
        })
    }
}
```

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

### Configure Scene Properties and Screen Effects

Source: https://www.esmap.cn/docs/sdk3.0-document/effect-edit

This configuration object allows for setting scene properties such as transparent highlight maps and sRGB texture encoding. It also enables the setup of full-screen effects like Unreal Bloom and outline glow, including customizable parameters for each effect.

```json
{
    "transprentHightLight": ["jinzheng_ef_transparentHL_lineframe"],
    "sRGB": true,
    "renderOrder": [
        {
            "name": "Object001",
            "order": 68
        }
    ],
    "screenEffects": {
        "unrealBloom": {
            "bloomStrength": 1,
            "bloomThreshold": 0,
            "bloomRadius": 0
        },
        "outline": {
            "color": "#ff9800",
            "edgeWidth": 3.0,
            "edgeSpread": 0.0,
            "edgeThickness": 2.0,
            "blink": true
        }
    }
}
```

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

### Initialize Navigation Object and Set Route

Source: https://www.esmap.cn/docs/sdk3.0-document/map-navi

Initializes the ESNavigation object with various configuration options and then sets the start and end points for navigation. Finally, it draws the navigation route. This process should be triggered after the map scene is fully loaded.

```javascript
// 第一步：初始化导航对象(navi只能全局唯一，不能多次new)
const navi = new esmap.ESNavigation({
    locationMarkerUrl: './image/pointer.png', // 定位标注图片地址
    locationMarkerSize: 150,                  // 定位标注图片大小
    locationMarkerSeeThough: true,            // 定位标注图片穿透显示
    speed: 5,             // 模拟导航速度
    maxEnd: 5,            // 距离终点多少米时结束导航(单位: 米/m)
    followAngle: true,    // 三维场景视角是否跟随旋转方向
    followPosition: true, // 三维场景视角是否跟随位置移动
    followGap: 3,         // 导航视角跟随间隔(单位: 秒/s)
    scaleAnimate: true,   // 模拟导航时是否自动缩放及移动到合适视角
    tiltAngle: 30,        // 模拟导航时的倾斜角
    audioPlay: true,      // 是否开启语音播报
    offsetHeight: 1,      // 模拟导航时定位标注距离地面的高度
    ladderType: 1,        // 跨层方案选择(其他选项参考下表)  
    tipDistance: 3,       // 拐弯处提前多少米播报转弯语音(单位: 米/m)
    reRouteDis: 10,       // 偏差多少米就进行重新路径规划(单位: 米/m)
    linkStartEnd: false,  // 设置导航时起点终点是否连接导航线
    showMultiFloor: true  // 第三人称导航时是否展示多楼层 （2024-04-18新增加参数）
});

// 第二步：确定起点和终点

// 确定起点
avi.setStartPoint({
    name: '起点1',
    x: map.center.x + 10,
    y: map.center.y + 10,
    fnum: 1,         // 楼层
    height: 10,      // 起点距离地面的高度
    url: './image/start.png', // 图片路径,
    size: 64,        // 图片尺寸
    showLevel: 23,   // 到达三维场景缩放等级隐藏导航对象
    // text: '起点位置', // 场景中展示的文字内容
    // textStyle:{
        // fontSize: 20,           // 字体大小
        // fillStyle: '#ff0000',   // 填充色
    // }
    // imageStyle:{
        // align:'bottom'   // 图片位置
        // scale: 1,        // 单独设置图片缩放比例
    // },
    // renderOrder: 79,     // 渲染等级
    // pickable: false,     // 是否可被点击
    // callback: (marker)=> {
        // console.log(marker)    // 输出起点实例
    // }
});

// 确定终点
avi.setEndPoint({
    name: '终点1',
    x: map.center.x - 10,
    y: map.center.y - 10,
    fnum: 1,
    height: 10,
    url: './image/end.png',
    size: 64,
    showLevel: 23,
    // text: '终点位置', 
    // textStyle:{
        // fontSize: 20,           
        // fillStyle: '#ff0000',   
    // }
    // imageStyle:{
        // align:'bottom' 
        // scale: 1, 
    // },
    // renderOrder: 79,
    // pickable: false, 
    // callback: (marker)=> {
        // console.log(marker)
    // }
});

// 第三步：绘制导航线
avi.getRouteResult({
    drawRoute: true,
})

// 第四步完成：根据导航的模式选择语音播报，导航开始
if( navi.mode == 1 ){
    map.ESAudioTool.playSoundByName('startNaving')    // 开始步行导航
}else{
    map.ESAudioTool.playSoundByName('startCarNaving') // 开始车行导航
}
// 导航开始
avi.simulate();

```

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

### Initialize ESMap 3.0 for Indoor Mode

Source: https://www.esmap.cn/docs/sdk3.0-document/map-upgrade

Demonstrates initializing the ESMap 3.0 instance for indoor mode. Key changes include using `esmap.MapMode.Building`, specifying `mapDataSrc` and `token`, and using an object for the `center` parameter. Opening the scene is done via `openMapById()`.

```javascript
var map = new esmap.ESMap({
    mode: esmap.MapMode.Building,       // *添加配置室内三维场景模式*
    container: document.getElementById('map-container'),  // 三维场景显示容器
    mapDataSrc: './data/',               // 离线室内三维场景数据位置
    token: 'escope',                    // 打开室内三维场景对应的token
    center:{
        x:123456.111,
        y:123456.111
    }
    ...
});
map.openMapById('test666');             // *根据室内三维场景ID打开三维场景*
```

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

### Vue.js iframe Template for Multiple Indoor Maps

Source: https://www.esmap.cn/docs/sdk3.0-document/map-switchMap

This Vue.js template code defines the HTML structure for displaying multiple indoor maps within iframes. It includes a container element and uses `v-show` for conditional rendering. This setup is designed to manage the visibility and lifecycle of embedded 3D scenes.

```html
// 用于装载多个室内图(可能多个，尽量单个iframe) 
<div id="map-frames-container" v-show="isShowInnerMap"></div>
```

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

### Include ESMap 3.0 SDK for Indoor Mode

Source: https://www.esmap.cn/docs/sdk3.0-document/map-upgrade

This snippet shows how to include the unified ESMap 3.0 SDK file for indoor 3D scenes. This is a prerequisite for using indoor mode functionalities.

```html
<script src='./esmap-3.0.min.js'></script>
```

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

### Switch Indoor Scene ID with openMapById

Source: https://www.esmap.cn/docs/sdk3.0-document/map-switchMap

This code snippet demonstrates how to switch between different indoor scene IDs using the `openMapById` method. It includes logic for managing scene switching states and listening for scene load completion to prevent frequent operations. This is suitable for scenarios where you need to toggle between distinct indoor environments.

```javascript
// 第一步：准备必要的变量定义
const innerMapIDList = ['10005', 'test666']       // 存储需要切换的id数组
const curSelectedID = { value: '10005',index: 0 } // 当前场景id
const isAllowSwitchSign = { value: true }         // 判定是否允许切换场景，可用于按钮状态

// 第二步：设定由按钮触发，点击切换下一个场景
function switchMapBtn () {
    if (isAllowSwitchSign.value) {
        innerMapIDList.some((bid,index) => {
            if (bid !== map.id) {

                // 该业务场景仅供参考，与当前场景ID不同时切换该场景
                curSelectedID.value = bid
                curSelectedID.index = index

                // *********** 关键API：执行切换场景 ***********
                map.openMapById(bid)
                return true
            }
        })

        // 第三步：监听一次场景加载进度是否完成，避免频繁切换操作
        isAllowSwitchSign.value = false         // 切换按钮不可点击
        map.once('progressComplete', () => {    // 监听完成一次便会销毁该事件
            // 监听到场景完全加载完毕，恢复按钮可点击
            isAllowSwitchSign.value = true
        })
    }
}
```

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

### Draw 3D Path Planning Route with ESMap

Source: https://www.esmap.cn/docs/sdk3.0-document/map-routeAnalysis

This snippet demonstrates how to initialize the ESNavigation object, set start and end points with custom markers, and then request the route. It requires the 'loadComplete' event to be triggered before execution. The lineStyle object allows extensive customization of the route's appearance.

```javascript
var navi = new esmap.ESNavigation({
    lineStyle: {
        color: '#33cc61',
        lineType: esmap.ESLineType.ESARROW,
        lineWidth: 6,
        offsetHeight: 0.5,
        smooth: true,
        seeThrough: false,
        noAnimate: false,
        godEdgeColor: '#920000',
        godArrowColor: '#ff0000'
    },
});

avi.setStartPoint({
    name: '起点1',
    x: map.center.x + 10,
    y: map.center.y + 10,
    fnum: 1,
    height: 10,
    url: './image/start.png',
    size: 64,
    showLevel: 23
});

avi.setEndPoint({
    name: '终点1',
    x: map.center.x - 10,
    y: map.center.y - 10,
    fnum: 1,
    height: 10,
    url: './image/end.png',
    size: 64,
    showLevel: 23
});

avi.getRouteResult({
    drawRoute: true,
})
```

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

### Include ESMap 3.0 SDK and Tile Plugin for City Scenes (HTML)

Source: https://www.esmap.cn/docs/sdk3.0-document/index

This HTML snippet includes the ESMap 3.0 SDK and an additional plugin for tile-based base maps, necessary for city-scale 3D scene visualization. Ensure these scripts are loaded before initializing the map.

```html
<script src='./lib/esmap-3.0.min.js'></script>
// 需使用城市三维场景的瓦片底图功能，添加引入以下文件
<script src='./lib/esplugin-tile-3.0.min.js'></script>
```

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

### Indoor Building Floor Focusing

Source: https://www.esmap.cn/docs/sdk3.0-document/map-ordinary

This section explains how to focus on specific floors within an indoor building. It covers getting the floor number by name, changing the focused floor (which can hide other floors), and setting the focused floor while keeping others visible, along with specifying visible floors.

```javascript
var fnum = building.getFloorNumByName('F1'); // Get the internal floor fnum of the 3D scene by floor name
// Switch focused floor Method 1,
building.changeFocusFloor(fnum);             // If multiple floors are displayed simultaneously, other floors are hidden. fnum must be a number, not a string.

// Switch focused floor Method 2
building.focusFloorNum = fnum;               // If multiple floors are displayed simultaneously, other floors are not hidden.
building.visibleFloorNums = [fnum1,fnum2];   // Switch visible floors
```

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

### Include ESMap 3.0 SDK and Tile Plugin for City Mode

Source: https://www.esmap.cn/docs/sdk3.0-document/map-upgrade

Shows how to include the unified ESMap 3.0 SDK and the `esplugin-tile-3.0.min.js` plugin for city 3D scenes. The tile plugin is necessary for city mode's tile-based map functionality.

```html
// 引入统一SDk文件
<script src='./esmap-3.0.min.js'></script>   

// 需使用城市三维场景的瓦片底图功能，添加引入以下文件
<script src='./esplugin-tile-3.0.min.js'></script>
```

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

### Switch Map Scene Using API (Indoor/City Mode)

Source: https://www.esmap.cn/docs/sdk3.0-document/map-switchMap

This method allows for switching map scenes using direct API calls. `openMapById` is used for indoor mode to switch scenes by ID, while `openBuildingById` is for city mode to switch indoor map scenes. This approach is relatively simple and reduces memory overhead during scene transitions.

```javascript
// *********** 关键API：执行切换场景 ***********
map.openMapById(bid)       // 室内模式：根据id切换场景

map.openBuildingById(bid)  // 城市模式：只切换室内地图场景
```

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

### Create a Line Marker with Texture

Source: https://www.esmap.cn/docs/sdk3.0-document/map-lineMarker

This example shows how to create a line marker with a texture applied. The `lineType` must be set to `esmap.ESLineType.TEXTURE`, and a `url` property must be provided to specify the texture image. This is useful for creating realistic pipeline or road visualizations.

```javascript
var points = [
    { bid: building.id, x: map.center.x + 20, y: map.center.y + 20, fnum: 1, offset: 10 },
    { bid: building.id, x: map.center.x - 10, y: map.center.y - 10, fnum: 1, offset: 10 }
]

var lineMarker = new esmap.ESLineMarker({
    id: 'myLineMarker',
    points: points,
    style: {
        lineWidth: 6,
        alpha: 0.8,
        offsetHeight: 0,
        pickable: true,
        color: '#FF0000',
        smooth: true,
        lineType: esmap.ESLineType.TEXTURE,
        url: './image/tube0.png',
    }
})

map.drawLineMark(lineMarker);
```

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

### Include ESMap 3.0 SDK for Indoor 3D Scenes (HTML)

Source: https://www.esmap.cn/docs/sdk3.0-document/index

This snippet shows how to include the ESMap 3.0 SDK JavaScript file in an HTML document for indoor 3D scene visualization. It's a prerequisite for using the SDK's functionalities.

```html
<script src='./lib/esmap-3.0.min.js'></script>
```

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

### uni-app: Embed Web-view Component for 3D Scene

Source: https://www.esmap.cn/docs/sdk3.0-document/map-multi-platform

This example demonstrates embedding a web-view component in a uni-app project to display an ESMap 3D scene. The `web-view` component is added to a `.vue` file, and its `src` attribute is set to the URL of the H5 page containing the 3D scene. This approach is necessary because uni-app's native platforms may not directly support Vue for rendering complex 3D content.

```html
<web-view src='https://您的域名/esmap.html'></web-view>
```

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

### Create Custom DOM Bubble Marker (Vue Example)

Source: https://www.esmap.cn/docs/sdk3.0-document/map-popMarker

Demonstrates creating a bubble marker bound to a custom DOM element, using Vue.js for the popup component. It involves defining a Vue component for the popup and then binding it to the marker, updating its position and visibility in real-time.

```html
<template>
    <div 
        class='popup-component'
        :style='{
            position: absolute;
            transform: popConfig.transformStyle
        }'
        v-show='popConfig.visible'
    >
        <div>Custom popup content</div>
    </div>
</template>

```

```javascript
<script>
export default {
    popConfig: {
        transformStyle: '',
        visible: false
    },
}
</script>

<style scoped>
</style>

```

```javascript
// Create bubble marker
const popMarker = new esmap.ESPopMarker({
    mapCoord: {
        bid: building.id, // *Bind to the building ID to be displayed* (bid attribute can be ignored in indoor mode)
        x: map.center.x,  // Coordinates
        y: map.center.y,
        height: 4,        // Height from the ground
        fnum: 1           // Floor number
    },
    showLevel: 20,        // Display level
});

// Dynamically configure styles to achieve dynamic updates of bubble marker positions; real-time relative positions are returned through the onUpdatePosition callback function
popMarker.onUpdatePosition((transformStyle, displayStyle) => {
    popConfig.transformStyle = transformStyle  // transformStyle value is ultimately passed into the DOM's CSS style;
    popConfig.visible = (displayStyle.display === 'none') ? false : true
})

```

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

### Set Container Width and Height for Map

Source: https://www.esmap.cn/docs/sdk3.0-document/map-switchMap

This CSS snippet provides a solution for blank screen issues that may arise with the map. By setting the container's position, left, top, width, and height properties, you ensure the map has a defined viewport, resolving the blank screen problem.

```css
#map-container {
    position: absolute;
    left: 0;
    top: 0;
    width: 100vw;
    height: 100vh;
}
```

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

### WeChat Mini Program: Embed Web-view Component

Source: https://www.esmap.cn/docs/sdk3.0-document/map-multi-platform

This is an example of how to embed a web-view component within a WeChat Mini Program's WXML file. The `web-view` tag is used, with the `src` attribute pointing to the URL of the H5 page containing the ESMap 3D scene. This allows you to display external web content directly within your mini-program.

```html
<web-view src='https://您的域名/esmap.html'/>
```

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

### 配置Springboot项目静态文件打包

Source: https://www.esmap.cn/docs/sdk3.0-document/map-demorun

在Springboot项目中，需要确保.esmap和.bin等三维场景相关文件被正确打包到jar或war文件中。通过修改pom.xml中的resources配置，可以控制文件过滤和打包行为。

```xml
<build>
<plugins>
    <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
</plugins>

<resources>
<resource>
    <directory>src/main/resources</directory>
    <excludes>
        <exclude>**/*.esmap</exclude>
        
        <exclude>**/*.bin</exclude>
    </excludes>
    <filtering>true</filtering>
</resource>
    
<resource>
    <directory>src/main/resources</directory>
    <includes>
        <include>**/*.esmap</include>
        
        <include>**/*.bin</include>
    </includes>
    <filtering>false</filtering>
</resource>
</resources>
</build>
```

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

### Get Indoor Building Floor Height

Source: https://www.esmap.cn/docs/sdk3.0-document/map-ordinary_section=3

Retrieve the height of a specific floor in an indoor building. The `building.getFloorHeight()` method takes the floor number (`fnum`) as an argument and returns its height.

```javascript
building.getFloorHeight(fnum)   // Pass the floor number fnum
```

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

### Configure Building Scan Lights (Horizon and Center Spread)

Source: https://www.esmap.cn/docs/sdk3.0-document/effect-edit

This JSON defines building scan light effects for vector buildings and rooms. It includes configurations for 'horizon_scan' with parameters like center point, color, speed, extent, and width, and 'center_spread' with similar parameters but focused on radial expansion up to a maximum radius.

```json
{
    "buildingScanLight": [
        {
            "type": "horizon_scan",
            "lineScanCenter": { "x": 0, "y": 0 },
            "scanColor": "#aad5ff",
            "scanSpeed": 150,
            "scanExtent": [500, -500],
            "scanLightWidth": 25
        },
        {
            "type": "center_spread",
            "lineScanCenter": { "x": 0, "y": 0 },
            "scanColor": "#FFFFFF",
            "scanSpeed": 800,
            "maxRadius": 2500
        }
    ]
}
```

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

### Configure Ground Textures and Shadow Settings

Source: https://www.esmap.cn/docs/sdk3.0-document/effect-edit

This section defines configurations for ground textures, allowing for repeating patterns with specified images and scales. It also includes settings for shadow configuration in 3D scenes, specifically designating which light source casts shadows.

```json
{
    "ground": [
        {
            "roomStyle": "25",
            "repeatType": "repeat",
            "repeatImg": "images/ground/HZ-lvhua.png",
            "repeatScaleFactor": 0.05
        }
    ],
    "shadow": {
        "setShadowLight": "mainLight"
    }
}
```

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

### Get Building and Floor Objects

Source: https://www.esmap.cn/docs/sdk3.0-document/map-ordinary_section=3

Retrieves building and floor objects from the 3D scene. Building objects can be obtained by scene ID, and floor objects can be accessed by their internal number or name.

```APIDOC
## Get Building and Floor Objects

### Description
Retrieves building and floor objects from the 3D scene. Building objects can be obtained by scene ID, and floor objects can be accessed by their internal number or name. Floor objects are used to create and manage annotation layers.

### Method
JavaScript

### Endpoint
N/A (Client-side JavaScript API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Get the building object for the 3D scene
let building = map.getBuilding(); // Method 1: Suitable for indoor mode to get the Building object
let building = map.getBuildingById('test666'); // Method 2: Get Building object by scene ID

// Get the floor object for the 3D scene
let floorNames = building.floorNames; // Get floor names, usually returns an array like ['F1', 'F2', 'F3']
let fnum = building.getFloorNumByName('F1'); // Get the internal floor number by floor name, returns fnum = 1
let floor = building.getFloor(fnum); // Get the floor object for floor number fnum, used to mount annotation layers

// Create an annotation layer using the floor object
let textLayer = floor.getOrCreateLayerByName('textLayer', esmap.ESLayerType.TEXT_MARKER); // Example: Create a text-graphic annotation layer
floor.removeLayersByTypes(esmap.ESLayerType.TEXT_MARKER); // Remove annotation layers by 'annotation type'
floor.removeLayersByNames('textLayer'); // Remove annotation layers by 'annotation name'
```

### Response
#### Success Response (200)
- **building** (object) - Represents the building object in the scene.
- **floor** (object) - Represents a specific floor object in the scene.
- **floorNames** (array) - An array of strings representing the names of the floors.
- **fnum** (number) - The internal number of a floor.

#### Response Example
```json
{
  "building": { /* Building object details */ },
  "floor": { /* Floor object details */ },
  "floorNames": ["F1", "F2", "F3"],
  "fnum": 1
}
```
```

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

### Configure Directional and Added Lights

Source: https://www.esmap.cn/docs/sdk3.0-document/effect-edit

This JSON snippet configures lighting in the 3D scene. It includes replacing the main light with specified intensity and direction, and adding a new light source with its own color, intensity, and direction. This allows for fine-tuning scene illumination.

```json
{
    "directLight": [
        {
            "replaceLight": "mainLight",
            "intensity": 0.3,
            "direction": { "x": -0.2, "y": 0.71, "z": 0.6 }
        },
        {
            "color": "#888888",
            "intensity": 0.7,
            "direction": { "x": 0, "y": 0.25, "z": 0.5 }
        }
    ]
}
```

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

### Listen for Scene Initialization Complete Event

Source: https://www.esmap.cn/docs/sdk3.0-document/map-event

This event is triggered once the 3D scene has finished initializing. It's a common starting point for many scene-related operations.

```javascript
map.on('loadComplete', function () {
                                  
});
```

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

### Get Indoor Building Object

Source: https://www.esmap.cn/docs/sdk3.0-document/map-ordinary_section=3

Retrieve the building object for indoor scenes. This can be done using the `map.getBuilding()` method for the current indoor mode or `map.getBuildingById('buildingId')` to fetch a specific building by its scene ID.

```javascript
let building = map.getBuilding();               // Method 1: Applicable for getting Building object in indoor mode
let building = map.getBuildingById('test666');  // Method 2: Get Building object based on scene ID
```

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

### map.on('controlstart')

Source: https://www.esmap.cn/docs/sdk3.0-document/map-event

Fires when the user begins interacting with the 3D scene (e.g., panning, rotating).

```APIDOC
## map.on('controlstart')

### Description
This event is triggered at the beginning of any user interaction with the 3D scene, such as clicking, rotating, or panning.

### Method
map.on

### Endpoint
N/A

### Parameters
#### Event Parameters
- **controlstart** (string) - The event name for the start of user control.

### Request Example
```javascript
map.on('controlstart', function () {
  // User has started interacting with the scene
});
```

### Response
#### Success Response
N/A (This is an event listener)

#### Response Example
N/A
```

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

### Get Path Planning Prompt Information

Source: https://www.esmap.cn/docs/sdk3.0-document/map-routeAnalysis

This method retrieves descriptive information or prompts related to the path planning process. This can include turn-by-turn directions or other navigational guidance messages.

```javascript
const prompt = navi.naviDescriptions;
```

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

### 3D Visualization Scene Effect Theme Initialization and Development

Source: https://www.esmap.cn/docs/sdk3.0-document/map-init_section=2

Initialize and develop 3D visualization scene effect themes. Note: Full-screen effects are not supported in IE.

```APIDOC
## 3D Visualization Scene Effect Theme Initialization and Development

### Description
Initialize and develop 3D visualization scene effect themes. Full-screen effects are currently not supported in IE browsers, but are supported in Edge, Chrome, Firefox, WeChat, and mobile devices.

### Method
`esmap.ESEffectTool.init(options)`

### Parameters
#### Request Body
- **effectThemeSrc** (String) - Optional - The path to the effect theme files. If omitted, the SDK will read from the path specified in the map data.
- **effectThemeId** (String) - Optional - The ID of the effect theme. If omitted, the SDK will read from the path specified in the map data.
- **isSetRoomEffect** (Boolean) - Optional - Whether to apply the building effect styles defined in the effect configuration. Defaults to `true`.
- **loadRoads** (Boolean) - Optional - Whether to load the road network effects defined in the configuration. Defaults to `true`.
- **isShowSkybox** (Boolean) - Optional - Whether to use a skybox. Defaults to `true`.
- **isShowWater** (Boolean) - Optional - Whether to apply the water surface effects defined in the configuration. Defaults to `true`.
- **isSetModelEffect** (Boolean) - Optional - Whether to apply the model effects defined in the configuration. Defaults to `true`.
- **isShowGround** (Boolean) - Optional - Whether to apply the ground style defined in the configuration. Defaults to `true`.
- **isOpenScreenEffect** (Boolean) - Optional - Whether to apply the full-screen effect styles defined in the configuration. Defaults to `true`.
- **isShowBuildingTip** (Boolean) - Optional - Whether to display a diamond-shaped animation above buildings that can open indoor maps. Defaults to `true`.
- **effectQuality** (String) - Optional - Sets the effect quality when full-screen effects are enabled (`'high'`, `'medium'`, `'low'`). Defaults to automatic adjustment based on device performance.

### Request Example
```javascript
esmap.ESEffectTool.init({
    effectThemeSrc: './data/effects',       // File path
    effectThemeId: 'E001',                  // Effect theme ID
    isSetRoomEffect: true,                  // Apply building effects
    loadRoads: true,                        // Load road effects
    isShowSkybox: true,                     // Use skybox
    isShowWater: true,                      // Apply water effects
    isSetModelEffect: true,                 // Apply model effects
    isShowGround: true,                     // Apply ground style
    isOpenScreenEffect: true,               // Apply full-screen effects
    isShowBuildingTip: true,                // Show building tip animation
    // effectQuality: 'high'                 // Effect quality setting (high, medium, low)
});
```
```

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

### Handle Mouse Control Start Event

Source: https://www.esmap.cn/docs/sdk3.0-document/map-event

This event fires when the user begins interacting with the 3D scene using mouse controls, such as clicking or rotating. It can be used to prepare for user input.

```javascript
map.on('controlstart', function () {
   // 鼠标开始操作三维场景后触发，例如点击、旋转等。
});
```

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

### Listen for Scene Loading Progress Complete Event

Source: https://www.esmap.cn/docs/sdk3.0-document/map-event

This event signifies the completion of the scene loading progress. It fires slightly later than 'loadComplete' and can be used for final scene setup tasks.

```javascript
map.on('progressComplete', function () => { 
   // 加载进度完成，触发时机比'loadComplete'相对稍晚些
})
```

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

### Configure Environment Texture for Reflections

Source: https://www.esmap.cn/docs/sdk3.0-document/effect-edit

This JSON configures the environment texture used for HDR reflections. It requires an array of six HDR image paths (px, nx, py, ny, pz, nz) and allows adjustment of the reflection intensity.

```json
{
    "envTexture": {
        "imgPaths": [
            "images/env/hdr3/px.png",
            "images/env/hdr3/nx.png",
            "images/env/hdr3/py.png",
            "images/env/hdr3/ny.png",
            "images/env/hdr3/pz.png",
            "images/env/hdr3/nz.png"
        ],
        "intensity": 4
    }
}
```

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

### Configure and Show Compass Control in 3D Scene

Source: https://www.esmap.cn/docs/sdk3.0-document/map-init

Configures and displays the compass control in a 3D scene. The compass can be shown by setting 'showCompass' to true during initialization. Advanced configuration includes setting its position, offset, size, and custom image URLs for the background and pointer. The position and image URLs can also be updated dynamically after initialization.

```javascript
// 添加指南针非常简单，只需要在三维场景初始化时声明以下属性即可
map.showCompass = true;     // 显示指南针

// 三维场景初始化时配置指南针样式配置:
var map = new esmap.ESMap({
    // ...
    // compassPosition 参数选择： LEFT_TOP: 左上方, LEFT_BOTTOM: 左下方, RIGHT_TOP: 右上方, RIGHT_BOTTOM: 右下方
    compassPosition: esmap.ESControlPositon.LEFT_TOP,  // 默认根据左上方偏移xy坐标
    compassOffset: [50, 50],       // 根据指定方向偏移的x,y屏幕坐标
    compassSize:30,                // 指南针大小
    compassBackgroundUrl: bgUrl,   // 自定义指南针背景图片地址
    compassPointerUrl: pointerUrl  // 自定义指南针指针图片地址
})

// 在初始化后更新指南针位置
map.on('loadComplete', () => {
  map.compassOffset = [100, 100]   // 实时更新x,y的屏幕坐标
})

// 也可以动态修改指南针图片样式:
// 动态修改指南针背景图片:
map.setCompassBgUrl(bgUrl);        // bgUrl:自定义指南针背景图片地址

// 动态修改指南针指针图片:
map.setCompassPointerUrl(pointerUrl);  // pointerUrl:自定义指南针指针图片地址
```

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

### Modify Bubble Marker Method in ESMap 3.0

Source: https://www.esmap.cn/docs/sdk3.0-document/map-upgrade

Describes the update for bubble markers. If targeting an indoor scene, the `bid` must now be specified within the `mapCoord` property when creating an `ESPopMarker` instance.

```javascript
//添加气泡标注
var popMarker = new esmap.ESPopMarker({
    mapCoord:{
        bid: building.id,   // *绑定到需要显示的场景id*
        x: map.center.x,
        y: map.center.y,
        height: 1,
        fnum: 3,
    }
    ...
})
```

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

### Vue.js: 使用keep-alive缓存路由组件

Source: https://www.esmap.cn/docs/sdk3.0-document/map-componentCache

通过在router.js中设置meta.keepAlive属性，并结合App.vue中的<keep-alive>组件，可以实现对特定路由及其子组件的缓存。这对于需要保持地图状态和业务组件不被刷新的场景非常有用。

```javascript
const routes = [
  {
    path: '/',
    redirect: '/showManyPop',
    component: () => import('@/views/Home.vue'),  // Home.vue挂载map实例，子路由里展示业务组件模块
    meta: {
        keepAlive: true,    // 缓存该路由下的所有内容，使得该路由下的ESMap地图资源缓存和业务组件不被刷新
    },
    children: [
      {
        path: 'showManyPop',
        component: () => import('@/views/module/showManyPop.vue'),
      },
      {
        path: 'showOnlyPop',
        component: () => import('@/views/module/showOnlyPop.vue'),
      }
    ]
  },
  {
    path: '/about',
    name: 'about',
    meta: {
        keepAlive: false,   // 不缓存该路径，跳转路由会销毁该路由下内容
    },
    component: () => import('@/views/About.vue')
  },
]
```

```vue
<template>
    <div class="app">

        // vue3版本的keep-live缓存组件写法,通过router.js设置keepAlive值判断是否需要缓存
        <router-view v-slot="{ Component }">
            <keep-alive>
                <component
                :is="Component"
                v-if="$route.meta.keepAlive"
                />
            </keep-alive>
        </router-view>

        // 不需要缓存的路由跳转将会走这里，例如'/about'路由会走这里
        <router-view v-if="!$route.meta.keepAlive"></router-view>
    </div>
</template>
```

```vue
<template>
    <div class="home">
        // esmap地图资源挂载组件,与子路由的业务组件同级
        <mapView ref="mapViewRef"></mapView>
    
        // '/showManyPop'和'/showOnlyPop'子路由的业务组件内容会走这里
        <router-view></router-view>
    </div>
</template>
```

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

### Get Boundary Data for a Specific Floor

Source: https://www.esmap.cn/docs/sdk3.0-document/map-ordinary_section=3

Obtain the boundary points for a specified floor within an indoor building. Use `building.getFloorBounds(fnum)` where `fnum` is the floor number. The result is an array, and the `points` property of the first element contains the boundary coordinates.

```javascript
const fnum = 1  // Set the floor number to 1st floor
building.getFloorBounds(fnum)[0].points   // Pass fnum to get the boundary point set for that floor number
```

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

### Configure Floor Effects with Transparency Transition

Source: https://www.esmap.cn/docs/sdk3.0-document/effect-edit

This JSON configuration defines a floor effect with a transparency transition. It specifies the floor number, effect type ('alpha_trans'), vertical offset, and detailed effect configurations including color, repeating texture, tiling, transparency interpolation factors, and transition radius.

```json
{
    "version": "1.1",
    "floor": [
        {
            "floorNum": 1,
            "effectType": "alpha_trans",
            "offsetHeight": -10,
            "effectConfigs": {
                "color": "#d7d7d7",
                "repeatImg": "images/building/baidiban.png",
                "repeat": { "x": 2000, "y": 2000 },
                "transFactor": [0.3, 0.9],
                "radius": 3000
            }
        }
    ]
}
```

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

### Get Path Planning Results Collection

Source: https://www.esmap.cn/docs/sdk3.0-document/map-routeAnalysis

This snippet shows how to access the collection of all calculated path planning results. The 'outcome' property of the navigation object holds an array of route results, which can be iterated upon for further processing or display.

```javascript
const roads = navi.outcome;
```

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

### Initialize ESMap 3.0 for City Mode

Source: https://www.esmap.cn/docs/sdk3.0-document/map-upgrade

Demonstrates initializing the ESMap 3.0 instance for city mode. Similar to indoor mode, it uses `esmap.MapMode.City`, an object for `center`, and `openMapById()`. The `mapDataSrc` and `token` parameters are also relevant.

```javascript
var map = new esmap.ESMap({
    mode: esmap.MapMode.City,           // *添加配置三维场景模式*
    container: document.getElementById('map-container'),  // 三维场景显示容器
    mapDataSrc: './data/',               // 离线三维场景数据位置
    token: 'escope',                    // 打开三维场景对应的token
    center:{
        x:123456.111,
        y:123456.111
    }
    ...
});
map.openMapById('esmapcitydemo');       // *根据城市三维场景ID打开三维场景*
```

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

### Create Line Marker

Source: https://www.esmap.cn/docs/sdk3.0-document/map-lineMarker

This section explains how to create a basic line marker instance. It requires at least two points and can be customized with various style properties. The creation should be triggered after the 'loadComplete' event.

```APIDOC
## POST /drawLineMark

### Description
Creates a line marker instance on the map. This function should be called after the 'loadComplete' event.

### Method
POST

### Endpoint
`/drawLineMark`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **lineMarker** (object) - Required - An `ESLineMarker` object with properties like `id`, `points`, and `style`.
  - **id** (string) - Required - Unique identifier for the line marker.
  - **points** (array) - Required - An array of point objects, each with `bid`, `x`, `y`, `fnum`, and `offset`.
  - **style** (object) - Optional - Styling options for the line marker.
    - **lineWidth** (number) - Optional - Width of the line.
    - **alpha** (number) - Optional - Transparency of the line (0.0 to 1.0).
    - **offsetHeight** (number) - Optional - Vertical offset from the ground.
    - **pickable** (boolean) - Optional - Whether the marker is selectable.
    - **color** (string) - Optional - Color of the line (e.g., '#FF0000').
    - **smooth** (boolean) - Optional - Whether the line should be smooth.
    - **lineType** (enum) - Optional - Type of line (e.g., `esmap.ESLineType.FULL`, `esmap.ESLineType.TEXTURE`).
    - **url** (string) - Optional - URL for the texture if `lineType` is `esmap.ESLineType.TEXTURE`.

### Request Example
```javascript
var points = [
    { bid: building.id, x: map.center.x + 20, y: map.center.y + 20, fnum: 1, offset: 10 },
    { bid: building.id, x: map.center.x - 10, y: map.center.y - 10, fnum: 1, offset: 10 }
]

var lineMarker = new esmap.ESLineMarker({
    id: 'myLineMarker',
    points: points,
    style: {
        lineWidth: 6,
        alpha: 0.8,
        offsetHeight: 0,
        pickable: true,
        color: '#FF0000',
        smooth: true,
        lineType: esmap.ESLineType.FULL
    }
})

map.drawLineMark(lineMarker);
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Line marker created successfully."
}
```
```

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

### Get All Navigation Data from Building Object

Source: https://www.esmap.cn/docs/sdk3.0-document/map-routeAnalysis

This method retrieves all navigation point and line data associated with a specific building object within the 3D scene. This data is crucial for understanding the navigable areas and paths within a building.

```javascript
const allroad_data = building.naviData;
```

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

### Alipay Mini Program: Create WebView Context and Post Message

Source: https://www.esmap.cn/docs/sdk3.0-document/map-multi-platform

This code snippet shows how to create a context for a web-view component in an Alipay Mini Program and send messages to it. The `my.createWebViewContext` function initializes the context, and `postMessage` is used to transmit data. This enables two-way communication between the Alipay mini-program and the embedded web page.

```javascript
this.webViewContext = my.createWebViewContext('web-view-1');
this.webViewContext.postMessage({'sendToWebView': '1'});
```

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

### Create Container for Indoor 3D Scene (HTML)

Source: https://www.esmap.cn/docs/sdk3.0-document/index

This HTML snippet defines a `div` element that will serve as the container for rendering the indoor 3D scene. The ID 'map-container' is used for referencing this element in JavaScript.

```html
<div id='map-container'> </div>
```

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

### Update Card Marker Coordinate Parameter in ESMap 3.0

Source: https://www.esmap.cn/docs/sdk3.0-document/map-upgrade

Explains the change in how coordinate parameters are passed for card markers. Previously, coordinates were nested within a `coord` object; now, `x` and `y` can be passed directly as properties of the marker configuration object.

```javascript
// 修改之前：
var config = {
    id: 1,
    name: "myCardMarker",
    coord: {
        x:122465.123,
        y:12345.123,
    },
    ···
}

// 修改之后:
var config = {
    id: 1,
    name: "myCardMarker",
    x:122465.123,           // *坐标参数更换，可直接赋值X坐标和Y坐标*
    y:12345.123,
    ···
}
```
Tokens:
Raw