课程4：镜头操作
小伙伴们大家好，欢迎大家来到图观统一开发API及API调试器入门课程的第4课。
上节内容，我们为大家详细介绍了如何获取已发布的场景、如何获取和引用图观统一开发API的SDK、服务/场景/状态的关系以及端渲染场景操作等内容。
本节课程，我们主要讲解“镜头操作“，主要包含“获取镜头的视界 、设置镜头的视界、限制镜头视界的操作、接口操作镜头”4部分内容，并会在统一API调试器中进行相关的演示操作。
本节课程安排
第一部分：获取镜头视界
第二部分：设置镜头视界
第三部分：限制镜头视界的操作
第四部分：接口操作镜头
图观™引擎 统一API调试器零基础入门课程4《镜头操作》
（点击视频，观看本节完整版教程）
本节课程详解
一、获取镜头视界
首先，先要给大家讲解的是“获取镜头视界”，调用的是getCameraInfo这个方法。
点击执行，会在返回参数里看到：坐标系的类型、视角的中心点，可以看到场景围绕这中间这棵树的位置来进行旋转，这就是视角中心点，如果拖动场景，那中心点对应场景的位置也会发生变化。
coordZ是中心点的高度
distance是镜头距离
pitch是镜头的俯仰角（如果设置成负数，视野将在水平线以下）
Heading 是镜头的旋转参数
以上，我们就获取了当前场景的镜头基本参数。
二、设置镜头视界的操作
接下来我们来介绍一下如何设置镜头的视界。
，时长00:40
设置镜头视界我们使用setCamera这个方法，然后传入参数，点击执行，就可以完成视角的设置。
给大家介绍一下设置镜头视界的参数：
| 属性 | 类型 | 说明 |
| 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 | 飞行时间，秒 |
以上就是设置镜头视界的主要操作和内容。
三、限制镜头视界
接下来我们来给大家介绍一下限制镜头视界的操作。
，时长02:26
限制镜头视界简单理解是，希望用户在操作镜头的时候，不要超出某一些范围。就可以通过限制镜头视界来避免这些镜头的出现。
限制镜头视界需要调用2个方法，第一个是restrictCamera方法，这个方法是限制镜头视野的参数；另外我们还要开启setCameraRestrictionState视野限制状态。
我们先讲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 | 摄像机 镜头垂直俯仰角 限制 (5~89) |
| limitYaw | Array | 摄像机 镜头水平摇摆角 限制 (0 正北, 0~359) |
| limitDistance | Array | 摄像机 镜头距离限制 (单位:米) |
| limitCoordZ | Array | 摄像机 坐标高度限制 (单位:米)，(注意：端渲染暂未实现此属性。)。 |
| center | Array | 视点 限制区中心坐标，(注意：端渲染暂未实现此属性。)。 |
| radius | Number | 视点 限制区半径，会形成一个球体，并在所有条件中取交集，(注意：端渲染暂未实现此属性。)。 |
开启镜头视野限制
开启镜头的视野限制，可以在state方法中选择restrict受限或是free不受限。
取消镜头视野限制
取消镜头视野的限制，要使用state方法。先复制state方法代码，然后将其他的代码删掉，再将刚刚复制的内容粘贴进来，只需要将restrict 改为 free，点击执行，再来拖动场景，可以看到前面我们所作的哪些镜头限制就取消了。
四、接口操作镜头
在本小节中，我们为大家重点讲解漫游镜头、路径移动镜头、镜头环绕旋转、模型跟随镜头四部分内容。
1.漫游镜头
漫游镜头可以让镜头在场景多个点之间实现位移、漫游的效果。通过使用roamingCamera方法来开启镜头漫游。
通过下方的setCameraRoamingState方法来进行镜头漫游的暂停、继续和停止移动。
开启镜头漫游的参数，这里包含了镜头的坐标系、漫游循环方式、漫游点位的信息列表包含了坐标位置、高度、镜头与坐标点距离、镜头俯仰角、镜头偏航角、镜头速度等信息。参数设置好了以后就可以调用roamingCamera方法来开启镜头漫游。
参数描述：
| 属性 | 类型 | 说明 |
| 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’指令并执行，场景漫游会立即停止，并无法继续移动。
2.路径移动镜头
路径移动镜头就是在场景中先添加一个路径，当我们开启路径移动镜头之后，这个镜头会按照路径规划的顺序来实现镜头的移动。
第一步先来添加一个路径，在右侧代码面板中，已经预设好了一条路径数据，包含各个点位的信息，并且先清除不需要的路径，再添加路径，点击执行，可以看到在园区的公园里面，已经显示出一条路径，之后就可以开启路径移动镜头。
首先来看下路径移动镜头中的参数，包含路径的ID、循环模式、reverse是否反向移动、镜头距离路径的距离、镜头俯仰角和镜头移动速度。
参数描述：
| 属性 | 类型 | 说明 |
| pathId | String | 路径 ID (唯一标识) |
| loopMode | String | 循环模式：none，不循环；round，往返；repeat，从头循环 |
| reverse | Boolean | 是否反向移动 |
| distance | Number | 镜头距离覆盖物距离(单位:米) |
| pitch | Number | 镜头俯仰角(0~89) |
| speed | Number | 镜头速度 (单位:米/秒) |
通过调用pathingCamera就可以实现开启路径移动镜头，点击执行，可以看到场景中，镜头开始按照路径进行移动。
此外，我们还可以为路径移动镜头设置暂停或开启动作。在代码面板下方，通过setCameraPathingState方法来进行路径移动镜头的暂停、继续和停止移动。
调用 pause ，镜头移动暂停；
调用continue，镜头移动继续；
调用stop，镜头移动停止、无法再次继续。
经过以上操作，就实现了路径移动镜头的添加、暂停、继续和停止操作。
3.镜头环绕旋转
镜头环绕旋转就是让镜头围绕中心点，按照设定的俯仰角和旋转角实现旋转，我们可以通过简单的参数修改，实现镜头环绕旋转的速度和方向。
镜头环绕旋转的代码参数，通过调用rotateCamera这个方法。
开启镜头环绕旋转，其中的参数包含了相机开启的状态、镜头飞行一周所用时间、是否可以被打断、以及镜头的飞行方向。想要暂停，只需将前面enabled参数改为false就可以了。
同时也可以进行简单的参数修改，比如我们想将镜头的旋转速度调快，可将duration数字调小，数值越小，速度越快，点击执行，可实时看到调整后的效果。如果想要暂停旋转，将enabled参数改为false，点击执行即可暂停镜头旋转。调用continue，镜头旋转继续。
参数描述：
| 属性 | 类型 | 说明 |
| enabled | Boolean | 是否启用相机围绕目标飞行 |
| duration | Number | 飞行一周所需要的秒数，数值越大飞行越慢 |
| direction | String | 飞行方向，clockwise 为顺时针，counterclockwise 为逆时针 |
| interruptable | Boolean | 是否可以被打断，默认为 true |
4.模型跟随镜头
模型跟随镜头是指当场景中有模型在移动的时候，镜头可以跟随移动的模型进行移动。
首先是通过focusModel方法聚焦镜头到模型，接下来通过setModelTransform2方法，设定模型从一个点位移到另一个点位的路径、持续时长，之后再去开启followingCamera镜头跟随模型方法，来实现镜头的移动。
最后，我们通过setCameraFollowingState的方法来实现镜头移动的暂停、继续和停止移动。
本节总结
好了，本节课和大家介绍了操作镜头的方法和内容，相信大家已经熟练掌握了各种镜头操控方法的配置方式，小伙伴可以自己在API调试器中进行练习使用哦~
下节预告
下节课，我们将为大家介绍图层操作，会在API调试器中为大家详细演示，助您更加便捷高效地调试复杂代码、构建数字孪生应用。记得一定要持续关注我们哦~
图观在线试用地址
图观™引擎现可申请免费试用！现在试用还可获得1对1技术支持和专属大礼包~还等什么，快快联系我们体验图观™引擎的强大功能吧~
1.访问图观™官方网站，在浏览器中输入网址：https://www.tuguan.net
