相机

CameraControls 用于对相机进行控制操作。

通过 app.cameraControl 来访问.

示例

基本用法

let svc = new vjmap3d.Service(env.serviceUrl, env.accessToken);
let app = new vjmap3d.App(svc, {
container: "map", // 容器id
    scene: {  // 场景设置
        gridHelper: { visible: true } // 是否显示坐标网格
    }
})
const mesh = new THREE.Mesh(
	new THREE.BoxGeometry( 1, 1, 1 ),
	new THREE.MeshBasicMaterial( { color: 0xff0000, wireframe: true } )
);
app.scene.add( mesh );
let cameraControls = app.cameraControl;
const ui = await app.getConfigPane({ title: "相机操作", style: { width: "250px"}});
let gui = new vjmap3d.UiPanelJsonConfig();
gui.add(cameraControls, "enabled")
gui.add(cameraControls, "verticalDragToForward")
gui.add(cameraControls, "dollyToCursor")
gui.add(cameraControls, "dollyDragInverted")
gui.addButton('rotate theta 45deg' , () => cameraControls.rotate( 45 * THREE.MathUtils.DEG2RAD, 0, true ));
gui.addButton('rotate theta -90deg' , () => cameraControls.rotate( - 90 * THREE.MathUtils.DEG2RAD, 0, true ));
gui.addButton('rotate theta 360deg' , () => cameraControls.rotate( 360 * THREE.MathUtils.DEG2RAD, 0, true ));
gui.addButton('rotate phi 20deg' , () => cameraControls.rotate( 0, 20 * THREE.MathUtils.DEG2RAD, true ));
gui.addButton('pan( 0, 1 )' , () => cameraControls.pan(   1,   0, true));
gui.addButton('pan( -1, -1 )' , () => cameraControls.pan( - 1, - 1, true ));
gui.addButton('dolly  1' , () => cameraControls.dolly(   1, true ));
gui.addButton('dolly -1' , () => cameraControls.dolly( - 1, true ));
gui.addButton('zoom `camera.zoom / 2`' , () => cameraControls.zoom( app.camera.zoom / 2, true ));
gui.addButton('move to( 3, 5, 2 )' , () => cameraControls.moveTo( 3, 5, 2, true ));
gui.addButton('fit to the bounding box of the mesh' , () => cameraControls.fitToBox( mesh, true ))
gui.addButton('move to ( -5, 2, 1 )' , () => cameraControls.setPosition( - 5, 2, 1, true ));
gui.addButton('look at ( 3, 0, -3 )' , () => cameraControls.setTarget( 3, 0, -3, true ));
gui.addButton('move to ( 1, 2, 3 ), look at ( 1, 1, 0 )' , () => cameraControls.setLookAt( 1, 2, 3, 1, 1, 0, true ));
gui.addButton('move to somewhere between ( -2, 0, 0 ) -> ( 1, 1, 0 ) and ( 0, 2, 5 ) -> ( -1, 0, 0 )' , () => cameraControls.lerpLookAt( - 2, 0, 0, 1, 1, 0, 0, 2, 5, - 1, 0, 0, Math.random(), true ));
gui.addButton('shake' , () => cameraControls.shake( 1000, 10, 1, false ));
gui.addButton('reset' , () => cameraControls.reset( true ));
let state;
gui.addButton('saveState' , () => state = cameraControls.saveState());
gui.addButton('loadState' , () => {if(state) cameraControls.loadState( state )});
gui.toJson().forEach(c => ui.appendChild(c));

轨道旋转

CameraControls 使用球面坐标进行轨道旋转。

如果您的相机是 Y 轴向上，则方位角将是 y 轴旋转的角度，而极角将是垂直位置的角度。

Dolly指将镜头移近或远离主体, pan 则是平行主体移动镜头

Dolly 和 Zoom

• 缩放涉及改变镜头焦距。在 three.js 中，缩放实际上是改变相机 FOV，而相机是静止的（不会移动）。
• 移动摄影机通过物理移动相机来改变画面。

#特性

1. 每旋转360度，值都会增加.azimuthAngle，是累积的​​。
   360º = 360 * THREE.MathUtils.DEG2RAD = Math.PI * 2，720º = Math.PI * 4。
2. 请注意，colliderMeshes 可能会降低性能。碰撞测试使用来自相机的 4 个射线发射器，因为近平面有 4 个角。
3. 如果 Dolly 距离小于（或大于）minDistance（或maxDistance），infinityDolly则将保持距离并推动目标位置。

事件

CameraControls 实例发出以下事件。
要订阅，请使用cameraControl.addEventListener( 'eventname', function )。
要取消订阅，请使用cameraControl.removeEventListener( 'eventname', function )。

1. mouseButtons.wheel（鼠标滚轮控制）不发出'controlstart'。内部使用滚动事件，并且滚动事件间歇发生。这意味着无法检测到“开始”和“结束” 'controlend'。mouseButtons.wheel
2. 由于阻尼，通常_会_在相机停止移动sleep后几秒触发。如果您想在相机停止时执行某些操作（例如启用 UI、执行另一个转换），您可能需要该事件。可以使用参数进行微调。

用户输入设置

1. 鼠标滚轮事件用于在 Mac 上“上/下/左/右”滚动“上/下”
2. 鼠标点击滚轮事件“按钮”

• * 是默认值。
• 的默认值为mouseButtons.wheel：
  • DOLLY对于透视相机。
  • ZOOM对于正交相机，无法设置DOLLY。

• * 是默认值。
• touches.two和的默认值为touches.three：
  • TOUCH_DOLLY_TRUCK对于透视相机。
  • TOUCH_ZOOM_TRUCK对于正交相机，无法设置TOUCH_DOLLY_TRUCK和TOUCH_DOLLY。

方法

rotate

旋转方位角（水平）和极角（垂直）。
每个值都添加到当前值。

如果只想旋转一个轴，请为要旋转的轴设置一个角度，并0为另一个轴设置一个角度。

rotate( 20 * THREE.MathUtils.DEG2RAD, 0, true );

rotateAzimuthTo

将方位角（水平）旋转到给定角度并保持相同的极角（垂直）目标。

rotatePolarTo

将极角（垂直）旋转到给定角度并保持相同的方位角（水平）目标。

rotateTo

将方位角（水平）和极角（垂直）旋转到给定的角度。
相机视图将绝对旋转到轨道轴上：

方位角

       0º
         \
 90º -----+----- -90º
           \
           180º

0º 前、90º ( Math.PI / 2) 左、-90º ( - Math.PI / 2) 右、180º ( Math.PI) 后

极角

     180º
      |
      90º
      |
      0º

极角 0 = 相机在目标正上方向下俯视；Math.PI / 2 = 水平视角；Math.PI = 相机在目标正下方仰视（看向天空）。上图的"180º 顶部 / 0º 底部"指的是视线方向（看天 / 看地），不是相机所在位置。

dolly

移动相机位置。（指将镜头移近或远离主体进行缩放）

dollyTo

将摄影机位置移动至指定距离。（指将镜头移近或远离主体进行缩放）

dollyInFixed

拉近镜头，但不改变目标与相机之间的距离，而是移动目标位置。
为拉远镜头指定负值。

zoom

放大/缩小相机。该值添加到相机缩放。使用和
设置的限制.minZoom .maxZoom

您还可以使用camera.zoom属性来实现放大功能。
例如

const zoomIn  = () => cameraControls.zoom(   camera.zoom / 2, true );
const zoomOut = () => cameraControls.zoom( - camera.zoom / 2, true );

zoomTo

将相机放大/缩小至指定比例。该值会覆盖相机缩放。使用和
设置的限制.minZoom .maxZoom

pan

使用当前方位角平移相机。

lookInDirectionOf

朝给定点方向看。

setFocalOffset

使用屏幕平行坐标设置焦点偏移。
z与 Dolly 不同，它不会对正交摄影产生影响。

setOrbitPoint

不移动相机即可设置轨道点。

forward

前进/后退。

moveTo

移动target位置到给定点。

elevate

向上/向下移动。

fitToBox

使用最近的轴将视口适配到对象的框或边界框。填充以单位表示。
设置cover: true为填充输入屏幕。

fitToSphere

将视口与对象的球体或边界球体相适应。

fitToRect

将视口与矩形大小相适应。

setLookAt

target从来看position。

lerpLookAt

与 类似setLookAt，但它在两种状态之间进行插值。

setPosition

根据给定位置设置角度和距离。
的别名setLookAt()，不改变目标。因此继续注视当前目标

setTarget

设置注视的目标位置。
的别名setLookAt()，不改变位置。从而保持相同的位置。

setBoundary

设置包围相机目标的边界框box3。THREE.Box3

setViewport

设置（或取消设置）当前视口。
当您想要dollyToCursor同时使用渲染器视口和功能时，请设置此项。

参见：THREE.WebGLRenderer.setViewport()

getTarget

返回相机所观察的轨道中心位置。

getPosition

返回相机位置。

getSpherical

返回轨道的球面坐标。

getFocalOffset

返回焦点偏移，即相机在屏幕平行坐标中平移的距离。

saveState

将当前相机位置设置为默认位置。返回完整 CameraState 对象（字段：cameraPosition/cameraTarget/cameraZoom/cameraUp/cameraFocalOffset——vjmap3d@2.0.0）。

loadState

加载位置做为当前相机位置。

loadState(state, enableTransition?) 只要求 cameraPosition/cameraTarget（cameraUp 缺省 (0,1,0)、cameraZoom 缺省 1、cameraFocalOffset 缺省 0，自动补齐），值须为 THREE.Vector3（或含 x/y/z 的对象）。⚠️ 传数组 [x, y, z] 时内部读 .x 得 undefined → camera.position 变 NaN，相机坏掉且所有 Marker2D/Popup2D 的 CSS2D 元素随之消失（投影出 NaN → 渲染器判定不可见）。

normalizeRotations

将相机方位角旋转标准化为 0 至 360 度之间。

reset

将所有旋转和位置重置为默认值。

update

更新相机位置和方向。这应该在您的 tick 循环中调用，并true在需要重新渲染时返回。

updateCameraUp

当您改变相机向上矢量时，运行.updateCameraUp()以同步。

applyCameraUp

将当前相机向上方向应用于相机。
轨道系统将使用当前位置重新初始化。

shake

相机抖动

toJSON

获取 JSON 字符串中的所有状态

fromJSON

用 JSON 重现控制状态。enableTransition其中 anim 是否为布尔值。

高级

归一化累积方位角

如果您需要标准化的累积方位角（介于 0 到 360 度之间），请使用THREE.MathUtils.euclideanModulo
计算，例如：

const TAU = Math.PI * 2;

function normalizeAngle( angle ) {

	return THREE.MathUtils.euclideanModulo( angle, TAU );

}

const normalizedAzimuthAngle = normalizeAngle( cameraControls.azimuthAngle );

找最短方位角旋转的绝对角度

您可能旋转了 380 度，但实际上您希望旋转 -20 度。
要获取绝对角度，请使用以下命令：

const TAU = Math.PI * 2;

function absoluteAngle( targetAngle, sourceAngle ){

  const angle = targetAngle - sourceAngle
  return THREE.MathUtils.euclideanModulo( angle + Math.PI, TAU ) - Math.PI;

}

console.log( absoluteAngle( 380 * THREE.MathUtils.DEG2RAD, 0 ) * THREE.MathUtils.RAD2DEG ); // -20deg
console.log( absoluteAngle( -1000 * THREE.MathUtils.DEG2RAD, 0 ) * THREE.MathUtils.RAD2DEG ); // 80deg

创建复杂的过渡

enableTransition所有接受参数返回Promise的方法均可用于创建复杂的动画，例如：

async function complexTransition() {
	await cameraControls.rotateTo( Math.PI / 2, Math.PI / 4, true );
	await cameraControls.dollyTo( 3, true );
	await cameraControls.fitToSphere( mesh, true );
}

这将旋转相机，然后dolly，最后适应的边界球mesh。

.restThreshold可以使用和调整转换的速度和时间.smoothTime。

如果enableTransition是false，则立即返回：

// will resolve immediately
await cameraControls.dollyTo( 3, false );