Appearance
第四章 镜头操作
目录
第一节 获取镜头视界
引入版本：3.0 起支持
使用getCameraInfo方法，可以获取当前镜头视界参数。
JavaScript
// 获取镜头视界
appInstance.uniCall('getCameraInfo', {}, result => {
console.log(result);
});点击执行，会在返回参数里看到：坐标系的类型、视角的中心点，可以看到场景围绕这中间这棵树的位置来进行旋转，这就是视角中心点，如果拖动场景，那中心点对应场景的位置也会发生变化。
JavaScript
{
"result":1,
"message":"成功。",
"coordType":0,
"coordTypeZ":0,
"centerCoord":[1113.92489539458,22.5120589227475],
"coordZ":6000,
"distance":20000,
"pitch":73,
"heading":127,
"fov":30,
"status":"free",
}- centerCoord： 镜头中心点坐标
- coordZ： 镜头中心点高度
- distance： 镜头到中心点的距离
- pitch：镜头俯仰角度
- heading： 镜头旋转角度
相机可以围绕中心点进行旋转，拖拽场景，场景中心点为会发生变化
第二节 设置镜头视界
引入版本：3.0 起支持
接下来我们来介绍一下如何设置镜头的视界。
使用 setCamera方法，可以设置镜头视界，然后传入参数，点击执行，就可以完成视角的设置
JavaScript
let jsonData = {
coordType: 0, // XY 轴坐标类别，0：X 经度，Y 纬度；1：X 米，Y米，相对世界00点
coordTypeZ: 0, // Z 轴坐标类别，0：相对 3D 世界 0 海拔；1：相对 3D 世界地表；2：相对 3D 模型表面（单位：米）
centerCoord: [120.3471653,30.1045486], // 中心点的坐标 lng,lat
coordZ: 0, // Z 轴高度（单位：米）
distance: 5000.32, // 镜头距中心点距离(单位:米)
pitch: 47.7, // 镜头俯仰角(1~89)
heading: 351.22, // 镜头偏航角(0正北, 0~359)
fly: true, // true: 飞行动画(飞行时间根据当前点与目标点计算,则pitch及heading不生效, 会自行计算);
// false: 立刻跳转过去(有一个短暂飞行动画,并按照distance, pitch, heading设置镜头)
duration: 0.5 // 飞行时间，秒
};
appInstance.uniCall('setCamera', jsonData, result => {
console.log(result);
});给大家介绍一下设置镜头视界的参数：
| 属性 | 类型 | 说明 |
|---|---|---|
| coordType | Number | XY 轴坐标模式 坐标类型(0:X 经度 Y 纬度；1:X 米 Y 米，相对世界 00 点) 目前该属性仅支持属性值为 0 |
| coordTypeZ | Number | Z 轴坐标模式 坐标高度类型，单位：米(0:相对 3D 世界 0 海拔；1:相对 3D 世界地表；2:相对 3D 模型表面) 目前该属性仅支持属性值为 0 |
| centerCoord | Array | 中心点的坐标 lng,lat |
| coordZ | Number | Z 轴高度（单位：米） |
| distance | Number | 镜头距中心点距离(单位:米) |
| pitch | Number | 镜头俯仰角(5~89) |
| heading | Number | 镜头偏航角(0 正北, 0~359) |
| fly | Boolean | true: 飞行动画(飞行时间根据当前点与目标点计算,则 pitch 及 heading 不生效, 会自行计算); false: 立刻跳转过去(有一个短暂飞行动画,并按照 distance, pitch, heading 设置镜头) |
| duration | Number | 飞行时间，秒 |
以上就是设置镜头视界的主要操作和内容。
第三节 限制镜头视界
引入版本：3.1 起支持
接下来我们来给大家介绍一下限制镜头视界的操作。
限制镜头视界简单理解是，希望用户在操作镜头的时候，不要超出某一些范围。就可以通过限制镜头视界来避免这些镜头的出现。
限制镜头视界需要调用 2 个方法，第一个是restrictCamera 方法，这个方法是限制镜头视野的参数；另外我们还要开启 setCameraRestrictionState 视野限制状态。
JavaScript
let jsonData ={
coordType: 0, // XY 轴坐标类别，0：X 经度，Y 纬度；1：X 米，Y米，相对世界00点
coordTypeZ: 0, // Z 轴坐标类别，0：相对 3D 世界 0 海拔；1：相对 3D 世界地表；2：相对 3D 模型表面（单位：米）
limitPitch: [5,30], //摄像机 镜头垂直俯仰角 限制 (-89~89)
limitYaw: [30,300], //摄像机 镜头水平摇摆角 限制 (0正北, 0~359)
limitCoordZ: [10,300], //摄像机 坐标高度限制 (单位:米)
limitDistance: [160,1000], //摄像机 镜头距离限制 (单位:米)
center: [116.35030843454156,40.07618021155814], //视点 限制区中心坐标
radius: 1000 //视点 限制区半径，会形成一个球体，并在所有条件中取交集
}
;
appInstance.uniCall('restrictCamera', jsonData, (result) => {
console.log(result);
// 开启视野限制
});我们先讲restrictCamera 设置镜头视野参数，包含了摄像机的坐标系、摄像机镜头垂直俯仰角，这里我们设置为 30-60 度、摄像机镜头水平摇摆角，我们设置为 0-180 度、镜头高度 用户在拖拽的时候不允许超过 0-100 米的限制 、还有摄像机镜头距离 100-500 米 、视角的中心点位置以及 radius, radius 是代表我们能拖动场景的范围，是在距中心点 300 米为半径的圆形区域内，可以避免场景拖动的过远。
参数描述：
| 属性 | 类型 | 说明 |
|---|---|---|
| coordType | Number | XY 轴坐标模式 坐标类型(0:X 经度 Y 纬度；1:X 米 Y 米，相对世界 00 点) 目前该属性仅支持属性值为 0 |
| coordTypeZ | Number | Z 轴坐标模式 坐标高度类型，单位：米(0:相对 3D 世界 0 海拔；1:相对 3D 世界地表；2:相对 3D 模型表面) 目前该属性仅支持属性值为 0 |
| limitPitch | Array | 摄像机 镜头垂直俯仰角 限制 (-89~89) |
| limitYaw | Array | 摄像机 镜头水平摇摆角 限制 (0 正北, 0~359) |
| limitDistance | Array | 摄像机 镜头距离限制 (单位:米) |
| limitCoordZ | Array | 摄像机 坐标高度限制 (单位:米)，(注意：端渲染暂未实现此属性。)。 |
| center | Array | 视点 限制区中心坐标，(注意：端渲染暂未实现此属性。)。 |
| radius | Number | 视点 限制区中心坐标，( 视点 限制区半径，会形成一个球体，并在所有条件中取交集，(注意：端渲染暂未实现此属性。)。 |
- 开启镜头视野限制
开启镜头的视野限制，可以在 state 方法中选择 restrict 受限或是 free 不受限。
- 取消镜头视野限制
取消镜头视野的限制，要使用 state 方法。先复制 state 方法代码，然后将其他的代码删掉，再将刚刚复制的内容粘贴进来，只需要将 restrict 改为 free，点击执行，再来拖动场景，可以看到前面我们所作的哪些镜头限制就取消了。
第四节 接口操作镜头
引入版本：3.1 起支持
在本小节中，我们为大家重点讲解漫游镜头、路径移动镜头、镜头环绕旋转、模型跟随镜头四部分内容。
1. 漫游镜头
漫游镜头可以让镜头在场景多个点之间实现位移、漫游的效果。通过使用 roamingCamera 方法来开启镜头漫游。
JavaScript
// 相机漫游
let jsonData = {
coordType: 0, // XY 轴坐标类别，0：X 经度，Y 纬度；1：X 米，Y米，相对世界00点
coordTypeZ: 0, // Z 轴坐标类别，0：相对 3D 世界 0 海拔；1：相对 3D 世界地表；2：相对 3D 模型表面（单位：米）
loopMode: 'round', //循环模式：none，不循环；round，往返；repeat，从头循环
points: [{
coord: [116.34903521499965, 40.10420718793945], // XY 轴坐标，X：经度；Y：纬度
coordZ: 3, // Z 轴高度（单位：米）
distance: 200, //镜头与坐标点距离(单位:米)
pitch: 60, //镜头俯仰角 (-89~+89)
yaw: 60, //镜头偏航角 (0正北, 0~359)
speed: 300 //镜头速度 (单位:米/秒)
},
{
coord: [116.34893703018163, 40.1055656603118],
coordZ: 3,
distance: 200,
pitch: 60,
yaw: 60,
speed: 300
},
{
coord: [116.34581287014572, 40.10539743430285],
coordZ: 3,
distance: 200,
pitch: 60,
yaw: 60,
speed: 300
},
{
coord: [116.34580396133765, 40.10412003107448],
coordZ: 3,
distance: 200,
pitch: 60,
yaw: 60,
speed: 300
},
{
coord: [116.35023526459428, 40.10423899119746],
coordZ: 3,
distance: 200,
pitch: 60,
yaw: 60,
speed: 300
},
{
coord: [116.35021975339576, 40.103182859319986],
coordZ: 3,
distance: 200,
pitch: 60,
yaw: 60,
speed: 300
},
],
};
appInstance.uniCall('roamingCamera', jsonData, result => {
console.log(result);
});通过下方的 setCameraRoamingState 方法来进行镜头漫游的暂停、继续和停止移动。
JavaScript
appInstance.uniCall('setCameraRoamingState', { state: 'stop', }, (result) => {
console.log(result);
});开启镜头漫游的参数，这里包含了镜头的坐标系、漫游循环方式、漫游点位的信息列表包含了坐标位置、高度、镜头与坐标点距离、镜头俯仰角、镜头偏航角、镜头速度等信息。参数设置好了以后就可以调用 roamingCamera 方法来开启镜头漫游。
JavaScript
let jsonData = {
coordType: 0, // XY 轴坐标类别，0：X 经度，Y 纬度；1：X 米，Y米，相对世界00点
coordTypeZ: 0, // Z 轴坐标类别，0：相对 3D 世界 0 海拔；1：相对 3D 世界地表；2：相对 3D 模型表面（单位：米）
loopMode: 'round', //循环模式：none，不循环；round，往返；repeat，从头循环
points: [{
coord: [116.34903521499965, 40.10420718793945], // XY 轴坐标，X：经度；Y：纬度
coordZ: 3, // Z 轴高度（单位：米）
distance: 200, //镜头与坐标点距离(单位:米)
pitch: 60, //镜头俯仰角 (-89~+89)
yaw: 60, //镜头偏航角 (0正北, 0~359)
speed: 300 //镜头速度 (单位:米/秒)
},参数描述：
| 属性 | 类型 | 说明 |
|---|---|---|
| coordType | Number | XY 轴坐标模式 坐标类型(0:X 经度 Y 纬度；1:X 米 Y 米，相对世界 00 点) 目前该属性仅支持属性值为 0 |
| coordTypeZ | Number | Z 轴坐标模式 坐标高度类型，单位：米(0:相对 3D 世界 0 海拔；1:相对 3D 世界地表；2:相对 3D 模型表面) 目前该属性仅支持属性值为 0 |
| loopMode | String | 循环模式，none：不循环；round：往返循环；repeat：从头循环 |
| points | Array | 相机漫游数据集合 |
| points[0].coord | Array | XY 轴坐标，X：经度；Y：纬度 |
| points[0].coordZ | Number | Z 轴高度（单位：米） |
| points[0].distance | Number | 镜头与坐标点距离(单位:米) |
| points[0].pitch | Number | 镜头俯仰角(-89+89)(589) |
| points[0].yaw | Number | 镜头偏航角(0 正北, 0~359) |
| points[0].speed | Number | 镜头速度 (单位:米/秒) |
在现在的代码界面中，已经设置好镜头漫游 10 秒后暂停，如果暂停漫游，还是可以设置继续漫游，如果选择了停止移动，就不能再继续漫游了。
点击执行，可以看到现在场景视角就沿着预设的点位开始漫游。由于每一个点位的镜头偏航角都写的是 0，所以看到漫游路径都是沿着一个方向进行移动，当然这里面每一个点的参数都是可以自由去配置的。
接下来我们调用“继续移动”指令，只需要将‘continue’复制到 state 后，点击执行，场景会继续开始漫游。如果漫游到最后一个点，场景会沿着原有的路径返回。如果调用‘stop’指令并执行，场景漫游会立即停止，并无法继续移动。
JavaScript
appInstance.uniCall('setCameraRoamingState', { state: 'stop', }, (result) => {
console.log(result);
});2. 路径移动镜头
路径移动镜头就是在场景中先添加一个路径，当我们开启路径移动镜头之后，这个镜头会按照路径规划的顺序来实现镜头的移动。
第一步先来添加一个路径，在右侧代码面板中，已经预设好了一条路径数据，包含各个点位的信息，并且先清除不需要的路径，再添加路径，点击执行，可以看到在园区的公园里面，已经显示出一条路径，之后就可以开启路径移动镜头。
首先来看下路径移动镜头中的参数，包含路径的 ID、循环模式、reverse 是否反向移动、镜头距离路径的距离、镜头俯仰角和镜头移动速度。
参数描述：
| 属性 | 类型 | 说明 |
|---|---|---|
| pathId | String | 路径 ID (唯一标识) |
| loopMode | String | 循环模式：none，不循环；round，往返；repeat，从头循环 |
| reverse | Boolean | 是否反向移动 |
| distance | Number | 镜头距离覆盖物距离(单位:米) |
| pitch | Number | 镜头俯仰角(0~89) |
| speed | Number | 镜头速度 (单位:米/秒) |
通过调用 pathingCamera 就可以实现开启路径移动镜头，点击执行，可以看到场景中，镜头开始按照路径进行移动。
JavaScript
//路径移动镜头参数
function pathingCamera() {
let jsonData = {
pathId: 'pathId', // 路径的id
loopMode: 'round', //循环模式：none，不循环；round，往返；repeat，从头循环
reverse: false, //是否反向移动
distance: 300, //镜头距覆盖物距离(单位:米)
pitch: 35, //镜头俯仰角(0~89)
speed: 2, //移动速度 (单位:米/秒)
};
// 开启路径移动镜头
appInstance.uniCall('pathingCamera', jsonData, result => {
console.log(result);
});
}此外，我们还可以为路径移动镜头设置暂停或开启动作。在代码面板下方，通过setCameraPathingState方法来进行路径移动镜头的暂停、继续和停止移动。
JavaScript
appInstance.uniCall('setCameraPathingState', {state:'stop'}, (result) => {
console.log(result);
});- 调用 pause ，镜头移动暂停；
- 调用 continue，镜头移动继续；
- 调用 stop，镜头移动停止、无法再次继续。 经过以上操作，就实现了路径移动镜头的添加、暂停、继续和停止操作。
3. 环绕旋转镜头
镜头环绕旋转就是让镜头围绕中心点，按照设定的俯仰角和旋转角实现旋转，我们可以通过简单的参数修改，实现镜头环绕旋转的速度和方向
镜头环绕旋转的代码参数，通过调用rotateCamera这个方法。
JavaScript
let jsonData = {
enabled: true, // 是否启用相机围绕目标飞行
duration: 60, // 飞行一周所需要的秒数，数值越大飞行越慢
interruptable: true, // 是否可以被打断，默认为true
direction: 'clockwise' // 飞行方向，clockwise 为顺时针，counterclockwise 为逆时针
};
// 设置镜头旋转
appInstance.uniCall('rotateCamera', jsonData, result => {
console.log(result);
});开启镜头环绕旋转，其中的参数包含了相机开启的状态、镜头飞行一周所用时间、是否可以被打断、以及镜头的飞行方向。想要暂停，只需将前面 enabled 参数改为 false 就可以了。
同时也可以进行简单的参数修改，比如我们想将镜头的旋转速度调快，可将 duration 数字调小，数值越小，速度越快，点击执行，可实时看到调整后的效果。如果想要暂停旋转，将 enabled 参数改为 false，点击执行即可暂停镜头旋转。调用 continue，镜头旋转继续。
参数描述：
| 属性 | 类型 | 说明 |
|---|---|---|
| enabled | Boolean | 是否启用相机围绕目标飞行 |
| duration | Number | 飞行一周所需要的秒数，数值越大飞行越慢 |
| direction | String | 飞行方向，clockwise 为顺时针，counterclockwise 为逆时针 |
| interruptable | Boolean | 是否可以被打断，默认为 true |
4. 模型跟随镜头
模型跟随镜头是指，当我们的场景中有模型在移动的时候，镜头可以跟随移动的模型进行移动。
首先是通过focusModel方法聚焦镜头到模型，接下来通过setModelTransform2方法，设定模型从一个点位移到另一个点位的路径、持续时长，之后再去开启followingCamera镜头跟随模型方法，来实现镜头的移动。
JavaScript
let jsonData = {
modelId: "modelId", // 镜头跟踪的模型Id，镜头和模型之前保持相对静止关系，支持运动的模型
distance: 1000, // 镜头与被跟踪物体的距离(单位:米)
distanceMin: 10, //镜头与被跟踪物体的最近距离(单位:米)
pitch: 30, // 镜头俯仰角(5~89)
heading: 0 // 镜头偏航角(0正北, 0~359)
}
// 相机跟随模型移动
appInstance.uniCall('followingCamera', jsonData3, result => {
console.log(result);
});最后，我们通过setCameraFollowingState的方法来实现镜头移动的暂停、继续和停止移动。
JavaScript
let jsonData = {
state: "stop" //pause:暂停移动; continue:继续移动; stop:停止移动, 释放焦点
}
// 修改相机跟随模型移动状态
setTimeout(() => {
appInstance.uniCall('setCameraFollowingState', jsonData4, result => {
console.log(result);
});
}, 3000)