cve-connector/docs/controllers.md

UE Web 开发套件

CVE Controllers 插件提供各类 Controller，其中封装了最常使用的 UE 交互指令。

- 每个 Controller 都是一个指令集，包含若干操作指令
- 每个指令都返回一个 Promise，用于异步编程
- 对于不想使用 Promise 的开发者，每个指令最后一个参数均为回调函数

**只执行指令**

```ts
import { SystemController } from 'cve-connector'

SystemController.restartLevel()
```

**异步编程**

```ts
import { SystemController } from 'cve-connector'

await SystemController.restartLevel()
console.log('Level Restarted!')
```

**Promise**

```ts
import { SystemController } from 'cve-connector'

SystemController.restartLevel().then((res) => {
  console.log(res)
})
```

# Actor Controller

**Methods**

| 方法名   | 参数           | 说明                          |
| -------- | -------------- | ----------------------------- |
| addDecal | Tag, URL, BBox | 创建贴花                      |
| delete   | Tag, Deep      | 删除指定 Tag 的 Actor，可递归 |
| hide     | Tag, Deep      | 隐藏指定 Tag 的 Actor，可递归 |
| show     | Tag, Deep     | 显示指定 Tag 的 Actor，可递归 |

**Usage**

- 创建贴花时，URL 传入图片的 Base64 字符串
- BBox 为平行于坐标轴的最小包围盒坐标，[xMin, yMin, xMax, yMax]

```ts
import { ActorController } from 'cve-connector'

ActorController.addDecal('Heatmap2D', 'data:image/png;base64,ABCDEF', [0, 0, 1, 1])
ActorController.delete('hidden', true)
ActorController.hide('hidden', true)
ActorController.show('visible', false)
```

# Analysis Controller

**Methods**

| 方法名           | 参数  | 说明                     |
| ---------------- | ----- | ------------------------ |
| addMultiView     | tag   | 多视角分析：添加多视角   |
| deleteSightline  | index | 通视分析:  删除检视线   |
| deleteSkyline    | -     | 天际线分析: 删除天际线   |
| deleteViewshed   | index | 可视域分析:  删除可视域 |
| drawSightline    | -     | 通视分析: 绘制检视线     |
| drawSkyline      | -     | 天际线分析: 绘制天际线   |
| drawViewshed     | -     | 可视域分析: 绘制可视域   |
| refreshMultiView | -     | 多视角分析：刷新多视角   |
| removeMultiView  | tag   | 多视角分析：移除多视角   |
| startMultiView   | tags  | 多视角分析：开始多视角   |
| stopMultiView    | -     | 多视角分析：停止多视角   |

**Usage**

- 执行空间分析指令之前，必须将 _视角_ 设置为 _编辑器模式_
- 通视分析: 执行 drawSightline() 后单击鼠标左键选取视点，移动光标后单击鼠标右键，绘制检视线
- 天际线分析: 执行 drawSkyline() 后改变视角，自动绘制检天际线
- 可视域分析: 执行 drawViewshed() 后单击鼠标左键选取视点，移动光标后单击鼠标右键结束，绘制可视域

```ts
import { AnalysisController, ViewController, ViewMode } from 'cve-connector'

ViewController.changeMode(ViewMode.Editor)

const resIA = await AnalysisController.drawSightline()
AnalysisController.deleteSightline(resIA.Data)

const resVA = await AnalysisController.drawViewshed()
AnalysisController.deleteViewshed(resVA.Data)

AnalysisController.drawSkyline()
AnalysisController.deleteSkyline()
```

# Gis Controller

**Methods**

| 方法名                | 参数                   | 说明                             |
| --------------------- | ---------------------- | -------------------------------- |
| addArcgisLayer        | ArcgisLayer            | 添加 ArcGIS WMTS 服务            |
| addCustomLayer        | CustomLayer            | 添加 自发布 WMTS 服务            |
| addMapboxLayer        | MapboxLayer            | 添加 Mapbox WMTS 服务            |
| addTiandituLayer      | TiandituLayer          | 添加 天地图  WMTS 服务          |
| create3dTiles         | Id, Url, Max           | 创建 3D Tiles 图层               |
| delete3dTiles         | Id                     | 匹配 ID 删除  3D Tiles 图层     |
| deleteAll             | -                      | 删除全部 WMTS 图层               |
| deleteLayer           | Id                     | 匹配 ID 删除  WMTS 图层         |
| deleteLayerGroup      | GroupId                | 匹配 Group ID 删除一组 WMTS 图层 |
| config                | GeoReference           | 配置  GeoReferencingSystem      |
| hide3dTiles           | Id                     | 匹配 ID 隐藏  3D Tiles  图层   |
| hideAll               | -                      | 隐藏全部 WMTS 图层               |
| hideLayer             | Id                     | 匹配 ID 隐藏  WMTS 图层         |
| hideLayerGroup        | GroupId                | 匹配 Group ID 隐藏一组 WMTS 图层 |
| hideOsgb              | Id                     | 匹配 ID 隐藏  OSGB 图层         |
| loadOsgb              | Id,Dir,LodScale,Offset | 加载指定目录下的 OSGB 数据       |
| setCesiumTerrainLayer | Ion                    | 设置地形服务源为 Cesium 在线地形 |
| setCustomLayer        | CustomLayer            | 更改图层参数                     |
| setHeaders            | Id, Headers            | 更改图层请求头                   |
| setLayerIndex         | Id, Index              | 更改图层的 z-index               |
| setTerrainLayer       | Url                    | 通过 url 设置地形服务源          |
| show3dTiles           | Id                     | 匹配 ID 显示  3D Tiles 图层     |
| showAll               | -                      | 显示全部 WMTS 图层               |
| showLayer             | Id                     | 匹配 ID 显示  WMTS 图层         |
| showLayerGroup        | GroupId                | 匹配 Group ID 显示一组 WMTS 图层 |
| showOsgb              | Id                     | 匹配 ID 显示  OSGB 图层         |
| toggleDebug           | Id, Visible            | 控制图层调试信息显隐             |
| unloadOsgb            | Id                     | 匹配 ID 销毁 OSGB 图层           |

**补充说明**

- _添加图层之前，必须先设置地形_
- 最多能加**15**个图层
- Layer 参数对照：

| Property                 | Description                 | Custom | ArcGIS | Mapbox | 天地图 |
| ------------------------ | :-------------------------- | :----: | :----: | :----: | :----: |
| EPSG                     | EPSG 编号                   |   ✔   |   -   |   -   |   -   |
| Format                   | 天地图风格的 URL  请求参数 |   ✔   |   -   |   -   |   -   |
| GroupId                  | 图层分组 ID                 |   ✔   |   ✔   |   ✔   |   ✔   |
| Id                       | 图层 ID                     |   ✔   |   ✔   |   ✔   |   ✔   |
| Index                    | 图层 z-index                |   ✔   |   ✔   |   ✔   |   ✔   |
| Layer                    | WMTS  请求参数             |   ✔   |   -   |   -   |   -   |
| RequestHeaders           | 天地图风格的 URL  请求参数 |   ✔   |   ✔   |   ✔   |   ✔   |
| Subdomains               | 子域名集合                  |   ✔   |   -   |   -   |   -   |
| Style                    | 天地图风格的 URL  请求参数 |   ✔   |   -   |   -   |   -   |
| TileMatrixSetID          | 天地图风格的 URL  请求参数 |   ✔   |   -   |   -   |   -   |
| TileMatrixSetLabelPrefix | 瓦片矩阵集标签的前缀        |   ✔   |   -   |   -   |   -   |
| Toekn                    | 地图服务  Token            |   -   |   ✔   |   ✔   |   -   |
| Type                     | 枚举值                      |   -   |   ✔   |   ✔   |   ✔   |
| Url                      | WMTS  服务 url             |   ✔   |   -   |   -   |   -   |

- GeoReference 参数说明：

| Property                       | Description          | Type        | Default Value |
| ------------------------------ | -------------------- | ----------- | ------------- |
| GeographicEPSG                 | 空间坐标系 ESPG 编号 | string      | '4326'        |
| IsBigScene                     | 是否为大场景         | boolean     | false         |
| IsOriginLocationInProjectedCRS | 是否使用投影坐标系   | boolean     | -             |
| OriginCenter                   | 中心点坐标           | Coordinates | -             |
| ProjectedEPSG                  | 投影坐标系 ESPG 编号 | string      | '4549'        |

- IsBigScene 为 true 时地球曲率会影响计算
- 使用投影坐标系时 OriginCenter 的值为投影坐标 [x, y, z]
- 使用空间坐标系时 OriginCenter 的值为投影坐标 [longitude, latitude, altitude]

**Usage**

```ts
import { GisController } from 'cve-connector'
import type {
  ArcgisLayer,
  CustomLayer,
  GeoReference,
  MapboxLayer,
  TiandituLayer,
} from 'cve-connector'

const reference: GeoReference = {
  IsOriginLocationInProjectedCRS: true,
  OriginCenter: [116, 39, 100],
}
GisController.config(reference)

const Id = 'uid-A1B2C3D4E5'
const GroupId = 'guid-A1B2C3D4E5'
const RequestHeaders = {}
const arcgisLayer: ArcgisLayer = {
  GroupId,
  Id,
  Index: 0,
  RequestHeaders,
  Type: 0,
}
const mapboxLayer: MapboxLayer = {
  GroupId,
  Id,
  Index: 0,
  RequestHeaders,
  Token: '',
  Type: 0,
}
const tiandituLayer: TiandituLayer = {
  GroupId,
  Id,
  Index: 0,
  RequestHeaders,
  Token: '',
  Type: 0,
}
const wmtsLayer: CustomLayer = {
  EPSG: '3857',
  Format: '',
  GroupId,
  Id,
  Index: 0,
  Layer: '',
  RequestHeaders,
  Subdomains: [],
  Style: 'image/jpeg',
  TileMatrixSetID: '',
  TileMatrixSetLabelPrefix: '',
  Url: 'default',
}
const Url = 'http://fake.ip.address:port/path/name'

GisController.addArcgisLayer(arcgisLayer)
GisController.addCustomLayer(wmtsLayer)
GisController.addMapboxLayer(mapboxLayer)
GisController.addTiandituLayer(tiandituLayer)

GisController.create3dTiles(Id, Url)

GisController.delete3dTiles(Id)
GisController.deleteAll()
GisController.deleteLayer(Id)
GisController.deleteLayerGroup(GroupId)

GisController.hide3dTiles(Id)
GisController.hideAll()
GisController.hideLayer(Id)
GisController.hideLayerGroup(GroupId)
GisController.hideOsgb(Id)

GisController.setCesiumTerrainLayer(1)
GisController.setCustomLayer(wmtsLayer)
GisController.setHeaders(ID, RequestHeaders)
GisController.setLayerIndex(ID, 1)
GisController.setTerrainLayer('')

GisController.show3dTiles(Id)
GisController.showAll()
GisController.showLayer(Id)
GisController.showLayerGroup(GroupId)
GisController.showOsgb(Id)

GisController.toggleDebug(ID, true)
```

# Level Controller

**Methods**

| 方法名             | 参数                                  | 说明       |
| ------------------ | ------------------------------------- | ---------- |
| openLevel          | main, streamings                      | 打开主关卡 |
| restartLevel       |                                       | 重启主关卡 |
| loadStreamLevels   | streamings, exclusive, visible, block | 加载流关卡 |
| unloadStreamLevels | streamings, block                     | 卸载流关卡 |

**补充说明**

- load 第一个可选参数为 **是否卸载其他的流关卡**，默认为 true
- load 第二个可选参数为 **流关卡加载后是否可见**，默认为 true
- load/unload 最后一个可选参数为 **是否阻塞主关卡**，默认为 false

**Usage**

```ts
import { LevelController } from 'cve-connector'

LevelController.openLevel('Level1_Main', ['Level1_Base'])
LevelController.restartLevel()
LevelController.loadStreamLevel(['Level1_Base'])
LevelController.unloadStreamLevel(['Level1_Base'])
```

# Model Controller

**Methods**

| 方法名        | 参数              | 说明                     |
| ------------- | ----------------- | ------------------------ |
| focus         | id                | 通过 ID 视角聚焦到 Model |
| load          | path, id, groupId | 加载 Model               |
| unload        | id                | 通过 ID 卸载 Model       |
| unloadAll     | -                 | 卸载所有 Model           |
| unloadByGroup | groupId           | 通过 Group ID 卸载 Model |

**Usage**

```ts
import { ModelController } from 'cve-connector'

const groupId = 'gid-1'
const id = 'uid-a1b2c3d4e5f0'
const path = 'C:\\fakepath\\demo-model.udatasmith'
ModelController.load(path, id, groupId)
ModelController.focus(id)
ModelController.unload(id)
ModelController.unloadAll()
ModelController.unloadByGroup(groupId)
```

# Feature Controllers

**Interface**

```ts
interface Selector {
  Id?: string
  Name?: string
  Operator?: 'AND' | 'OR'
  Tags?: Condition[]
}
```

**补充说明**

Feature 的查找条件，支持 Id、Name、Tags 三种模式：

- 按 Id 进行筛选，例如: { Id: ['Id-01','Id-02','Id-03'] }
- 按 Name 进行筛选，例如: { Name: ['Name-01','Name-02','Name-03'] }
- 按条件筛选，例如: { Tags: [ ["Age",">=",[18]], ["Job","in",["Tutor","Police"]] ], Operator:"And" }
- 筛选条件 Condition 的数据结构: [key, operation, values]
- Operation 为关系运算符，支持: '>'、'>='、'<'、'<='、 '=='、'!='、'in'、'not in'
- 多个条件需要指定 Operator 逻辑运算符，支持: 'And'、'Or'

## Point Controller

**Methods**

| 方法名        | 参数                   | 说明                     |
| ------------- | ---------------------- | ------------------------ |
| addTag        | Selector,string,string | 为 Point 增加一条 Tag    |
| removeTag     | Selector,string        | 为 Point 删除一条 Tag    |
| removeAllTags | Selector               | 删除 Point 的全部 Tag    |
| create        | PointData[]            | 生成 Point               |
| delete        | Selector               | 删除指定的 Point         |
| show          | Selector               | 显示指定的 Point         |
| hide          | Selector               | 隐藏指定的 Point         |
| select        | Selector               | 选中指定的 Point（唯一） |
| unselect      | -                      | 取消选择的 Point         |
| update        | PointData[]            | 更新 Point 的补充参数    |

**补充说明**

- create 时 Parameters 参数必须设置，Parameters 决定点的样式；
- create 执行完，找不到点，可以使用 select 方法选中该点位，视角会聚焦到点位上。

**Usage**

```ts
import {PointController} from 'cve-connector'

// PointData 参见 Features
const points = [...]

PointController.create(points)
PointController.delete([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PointController.show({Id: ['Id-01', 'Id-02', 'Id-03']})
PointController.hide({Id: ['A1B2C3D4E5']})
PointConytoller.hide({"Tags":  [["Group", "==", ["Point"]]]})
PointController.select({Id: ['Id-01']})
PointController.unselect()


```

## Polyline Controller

**Methods**

| 方法名                     | 参数                        | 说明                                          |
| -------------------------- | --------------------------- | --------------------------------------------- |
| addTag                     | Selector,string,string      | 为 Polyline 增加一条 Tag                      |
| removeTag                  | Selector,string             | 为 Polyline 删除一条 Tag                      |
| removeAllTags              | Selector                    | 删除 Polyline 的全部 Tag                      |
| create                     | PolylineData[]              | 生成  Polyline                               |
| delete                     | Selector                    | 删除指定的  Polyline                         |
| show                       | Selector                    | 显示指定的  Polyline                         |
| showWithAnimateAndDuration | Selector, Animate, Duration | 同上，指定显示动画和动画持续时间              |
| showWithAnimateAndSpeed    | Selector, Animate, Speed    | 同上，指定显示动画和动画速度                  |
| hide                       | Selector                    | 隐藏指定的  Polyline                         |
| hideWithAnimateAndDuration | Selector, Animate, Duration | 同上，指定显示动画和动画持续时间              |
| hideWithAnimateAndSpeed    | Selector, Animate, Speed    | 同上，指定隐藏动画和动画速度                  |
| select                     | Selector                    | 选中指定的 Polyline（唯一）                   |
| unselect                   | -                           | 取消选择的  Polyline                         |
| update                     | PolylineData[]              | 更新 Polyline  的补充参数(不包括 Width 属性) |

**补充说明**

- Animation 几种类型的使用：

| Key          | Create | Hide | Show |
| ------------ | :----: | :--: | :--: |
| Immediately  |   ✔   |  ✔  |  ✔  |
| StartToEnd   |   ✔   |  ✔  |  ✔  |
| EndToStart   |   ✔   |  ✔  |  ✔  |
| MiddleToSide |   ✔   |  -  |  ✔  |
| SideToMiddle |   -   |  ✔  |  -  |

**Usage**

```ts
import {PolylineController} from 'cve-connector'

// PolylineData 参见 Features
const polylines = [...]

PolylineController.create(polylines)
PolylineController.delete({Tags: [["XX属性", ">=", [100]], ["XX类型", "in", ["类型1", "类型2"]]], Operator: "And"})
PolylineController.show([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PolylineController.showWithAnimateAndDuration([{Id: ['Id-01', 'Id-02', 'Id-03']}], 'StartToEnd', 1)
PolylineController.showWithAnimateAndSpeed([{Id: ['Id-01', 'Id-02', 'Id-03']}], 'StartToEnd', 5)
PolylineController.hide([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PolylineController.hideWithAnimateAndDuration([{Id: ['Id-01', 'Id-02', 'Id-03']}], 'StartToEnd', 1)
PolylineController.hideWithAnimateAndSpeed([{Id: ['Id-01', 'Id-02', 'Id-03']}], 'StartToEnd', 5)
PolylineController.select({Id: ['Id-01']})
PolylineController.unselect()


```

## Polygon Controller

**Methods**

| 方法名        | 参数                   | 说明                       |
| ------------- | ---------------------- | -------------------------- |
| addTag        | Selector,string,string | 为 Polygon  增加一条 Tag  |
| removeTag     | Selector,string        | 为 Polygon  删除一条 Tag  |
| removeAllTags | Selector               | 删除 Polygon  的全部 Tag  |
| create        | PolygonData[]          | 生成  Polygon             |
| delete        | Selector               | 删除指定的  Polygon       |
| show          | Selector               | 显示指定的  Polygon       |
| hide          | Selector               | 隐藏指定的  Polygon       |
| select        | Selector               | 选中指定的 Polygon（唯一） |
| unselect      | -                      | 取消选择的  Polygon       |
| update        | PolygonData[]          | 更新 Polygon 的补充参数    |

**Usage**

```ts
import {PolygonController} from 'cve-connector'

// PolygonData 参见 Features
const polygons = [...]

PolygonController.create(polygons)
PolygonController.delete({Tags: [["XX属性", ">=", [100]], ["XX类型", "in", ["类型1", "类型2"]]], Operator: "And"})
PolygonController.show([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PolygonController.hide([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PolygonController.select({Id: ['Id-01']})
PolygonController.unselect()

```

## Polymesh Controller

**Methods**

| 方法名        | 参数                   | 说明                        |
| ------------- | ---------------------- | --------------------------- |
| addTag        | Selector,string,string | 为 Polymesh  增加一条 Tag  |
| removeTag     | Selector,string        | 为 Polymesh  删除一条 Tag  |
| removeAllTags | Selector               | 删除 Polymesh  的全部 Tag  |
| create        | PolymeshData[]         | 生成  Polymesh             |
| delete        | Selector               | 删除指定的  Polymesh       |
| show          | Selector               | 显示指定的  Polymesh       |
| hide          | Selector               | 隐藏指定的  Polymesh       |
| select        | Selector               | 选中指定的 Polymesh（唯一） |
| unselect      | -                      | 取消选择的  Polymesh       |
| update        | PolymeshData[]         | 更新 Polymesh 的补充参数    |

**Usage**

```ts
import { PolymeshController } from 'cve-connector'

// PolymeshData 参见 Features
const polygmeshes = [...]
PolymeshController.create(polygmeshes)
PolymeshController.delete({Tags: [["XX属性", ">=", [100]], ["XX类型", "in", ["类型1", "类型2"]]], Operator: "And"})
PolymeshController.show([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PolymeshController.hide([{Id: ['Id-01', 'Id-02', 'Id-03']}])
PolymeshController.select({Id: ['Id-01']})
PolymeshController.unselect()


```

# Sequence Controller

**Methods**

| 方法名 | 必要参数     | 数据类型 | 说明     |
| ------ | ------------ | -------- | -------- |
| pause  | IsLockCamera | -        | 暂停     |
| play   | SequenceName | string   | 播放     |
| stop   | -            | -        | 停止播放 |

**Usage**

```ts
import { SequenceController } from 'cve-connector'

SequenceController.pause()
SequenceController.play('Intro')
SequenceController.stop()
```

# System Controller

**Methods**

| 方法名    | 必要参数 | 说明                     |
| --------- | -------- | ------------------------ |
| mute      | -        | 关闭声音                 |
| setVolume | Volume   | 设置音量大小, [0.0,1.0] |
| unmute    | -        | 打开声音                 |

**Usage**

```ts
import { SystemController } from 'cve-connector'

SystemController.mute()
SystemController.setVolume(0.3)
SystemController.unmute()
```

# Time Controller

**Methods**

| 方法名          | 参数     | 说明         |
| --------------- | -------- | ------------ |
| disableRealtime | -        | 禁用实时     |
| enableRealtime  | -        | 启用实时     |
| setDateTime     | DateTime | 设置场景时间 |

**补充说明**

- 禁用实时后，渲染场景中的时间不随服务器时间变化；
- 启用实时，渲染场景中的时间随服务器时间变化；
- 在调用 setDateTime 函数前，请先调用 disableRealtime 函数。

**Usage**

```ts
import { TimeController } from 'cve-connector'

const now = new Date('2020-10-24 12:34:56')
TimeController.disableRealtime()
TimeController.enableRealtime()
TimeController.setDateTime(now)
```

# View Controller

**View Mode**

```ts
enum ViewMode {
  SpringArm = 0, // 摇臂镜头视角
  GIS = 1,       // GIS 系统视角
  Free = 2,      // 自由视角
  Editor = 3,    // 编辑模式
}
```

|     操作模式     |     SpringArm     |        GIS        |          Free          |         Editor         |
| :---------------: | :----------------: | :----------------: | :---------------------: | :---------------------: |
|      实际值      |         0         |         1         |            2            |            3            |
|       描述       |    摇臂镜头视角    | 传统 GIS 操作模式 |        自由视角        |       编辑器模式       |
|     操作基准     |     基于中心点     | 基于鼠标所点击的点 |        基于镜头        |        基于镜头        |
|   WASDEQE 操作   |     移动中心点     |    移动镜头位置    |      移动镜头位置      |      移动镜头位置      |
|     鼠标左键     |      旋转镜头      |    拖动镜头平移    |        旋转镜头        |        旋转镜头        |
|     鼠标中键     |         -         |    旋转当前镜头    |            -            |            -            |
|     鼠标右键     | 拖动中心点进行平移 |  基于当前镜头旋转  |        旋转镜头        |        旋转镜头        |
|       滚轮       |   拉近\拉远距离   |   拉近\拉远距离   |    前方/后方稍微位移    |    前方/后方稍微位移    |
| 鼠标长摁右键+滚轮 |         -         |         -         | 增加/减少镜头移动的速率 | 增加/减少镜头移动的速率 |

- 执行空间分析指令之前，必须将 _视角模式_ 设置为 _编辑器模式_

**Methods**

| 方法名        | 参数                   | 说明                                 |
| ------------- | ---------------------- | ------------------------------------ |
| addPath       | RoamingPath            | 新增漫游路径                         |
| changeMode    | ViewMode               | 改变视角模式                         |
| deletePath    | time                   | 通过 ID 删除漫游路径                 |
| flyTo         | ViewSettings, duration | 飞到指定的位置                       |
| flyToBookmark | bookmark, duration     | 飞到书签位置                         |
| getView       | -                      | 获取当前视角                         |
| playPath      | id                     | 通过 ID 播放路径漫游                 |
| replayPath    | id                     | 通过 ID 重播路径漫游                 |
| resetView     | duration               | 视角初始化                           |
| seekPath      | id, time              | 通过 ID 和时间切换当前路径漫游的位置 |
| stopPath      | id                     | 通过 ID 停止路径漫游                 |

**视角补充说明**

- Distance 是相机到 Location 的距离，UseCurrentDistance 为 false 才生效；
- Location 的 x/y 不是经纬度，而是 UE 的世界坐标；
- Rotation 的三个值 roll/pitch/yaw 分别表示相机沿 _前后_、_左右_、_竖直_ 轴旋转；
- Rotation 三个参数，以人的视角为例，分别对应 _向左/右歪头_、_抬头/低头_、_向左/右转头_ 三种情况；
- 对于 Cesium 开发，yaw 对应 heading；

```ts
interface ViewSettings {
  Distance: number
  Location: [x: number, y: number, z: number]
  Rotation: [roll: number, pitch: number, yaw: number]
  UseCurrentDistance?: boolean
  UseCurrentRotation?: boolean
}
```

**路径漫游补充说明**

- Delays、Duration 单位是 _秒_，数组长度均为 _n-1_；
- Positions 长度为 _n_。

```ts
interface RoamingPosition {
  Location: [x: number, y: number, z: number]
  Rotation: [roll: number, pitch: number, yaw: number]
}

interface RoamingPath {
  Delays: number[]
  Durations: number[]
  Positions: RoamingPosition[]
}
```

**Usage**

```ts
import { ViewController, ViewMode } from 'cve-connector'
import type { ViewSettings } from 'cve-connector'

const position: ViewSettings = {
  Distance: 182103.671875,
  Location: [-150933.81522, -23069.396282, 25299.628117],
  Rotation: [0, -25.206932, -68.69767],
  UseCurrentDistance: false,
  UseCurrentRotation: false,
}
ViewController.changeMode(ViewMode.GIS)
ViewController.flyTo(position, 3).then((res) => {
  console.log(res)
})
ViewController.flyToBookmark('bookmark', 3)
ViewController.getView().then((desc) => {
  console.log(desc)
})
ViewController.resetView(1)
```

**补充说明**

- getView 方法返回一个 Promise，可用于异步编程 async/await
- getView 结果是一个对象，Data 字段内包含 Location/Rotation/Distance

# Weather Controller

**Methods**

| 方法名           | 参数               | 说明                 |
| ---------------- | ------------------ | -------------------- |
| changeByPreset   | Preset, Duration   | 根据预设变换天气效果 |
| changeBySettings | Settings, Duration | 根据参数变换天气效果 |

**补充说明**

- WeatherPreset 共有十种天气预设类型:

| Key           | Name |
| ------------- | ---- |
| Sunny         | 晴天 |
| Cloudy_Light  | 少云 |
| Cloudy_Medium | 多云 |
| Cloudy_Heavy  | 乌云 |
| Rainy_Light   | 小雨 |
| Rainy_Medium  | 中雨 |
| Rainy_Heavy   | 大雨 |
| Snowy_Light   | 小雪 |
| Snowy_Medium  | 中雪 |
| Snowy_Heavy   | 大雪 |

- WeatherSettings 参数均为可选，可自由组合。参数如下：

| Key              | Name             | Value   |
| ---------------- | ---------------- | ------- |
| CloudCoverage    | 天空中的云覆盖度 | (1, 10) |
| Dust             | 沙尘量           | (0, 10) |
| DustCoverage     | 场景沙尘覆盖度   | (0, 1)  |
| Fog              | 雾量             | (1, 10) |
| Rain             | 雨量             | (0, 10) |
| Snow             | 雪量             | (0, 10) |
| SnowCoverage     | 场景雪覆盖度     | (0, 1)  |
| ThunderLightning | 雷电强度         | (0, 10) |
| Wetness          | 场景湿润度       | (0, 1)  |
| WindIntensity    | 风强度           | (1, 10) |

**Usage**

```ts
import { WeatherController } from 'cve-connector'
import type { WeatherPreset, WeatherSettings } from 'cve-connector'

const preset: WeatherPreset = 'Sunny'
const settings: WeatherSettings = {
  CloudCoverage: 5, // 天空中的云覆盖度（1-10）
  Fog: 6, // 雾量（1-10）
  WindIntensity: 3, // 风强度（1-10）
}
WeatherController.changeByPreset(preset, 3)
WeatherController.changeBySettings(settings, 3)
```