threejs-camera-controls-and-rigs

摄像机控制与 Rig

一个 Rig 会为每个视图和每一帧发布一个语义位姿、一个未抖动的投影，以及一个原点纪元。控制、适配求解器、预设镜头、时间抖动和坐标重定位各自维护独立状态，并通过显式交接协同工作。

1. 声明所有者与空间

为每个通道指定唯一写入者：

通道	写入者
语义位姿	当前活动的控制、适配求解器、预设镜头或外部/XR 所有者
未抖动的投影	当前活动的取景或镜头所有者
瞬时抖动	渲染期间的一个时间节点
渲染原点	原点纪元中的大坐标所有者
后置摄像机数据	一个场景通道及其声明的使用者
监听器/资源/恢复	场景或视图生命周期所有者

声明单位、左右手约定、世界上方向、摄像机父级约定，以及对象空间、世界/全局空间、局部切平面空间、相机相对空间、视图空间、裁剪空间和屏幕空间之间的转换。摄像机局部前向为 -Z，右向为 +X，上向为 +Y。未激活的输入系统只发送意图；只有当前活动的语义所有者能写入摄像机。

完成标准： 每个可变摄像机字段、矩阵、时间资源和监听器都只有一个写入者，并且每次空间转换都明确说明其转换方式。

2. 选择取景方案

根据成像或测量需求选择：

需求	架构
资产检查	基于边界的透视或正交视图，加轨道控制
建筑	视点/剖面锚点、镜头偏移，以及受约束的轨道/平移/步行控制
科学视图	可复现的位姿、坐标轴/单位，以及根据测量语义选择的投影
地理空间尺度	局部切平面坐标系，加重定位坐标或高/低精度相机相对坐标
电影摄影	预设的位姿/投影轨迹，并明确标注剪切与混合纪元

定义主体支撑点、安全画框、所需深度范围，以及预设的镜头/投影意图。当屏幕比例必须与深度无关时使用正交投影；当透视缩短具有表达意义时使用透视投影。

阅读取景与投影，了解非对称视锥体、体积适配、正交规则和深度精度。

完成标准： 所选投影能满足视觉或测量需求，并且支撑点集合、安全画框和深度范围均已明确。

3. 求解有效位姿与投影

根据位置、目标点、上方向提示和最不对齐轴回退方案，构建确定性的正交基。对于深度较大的主体，应对保守的支撑点集合进行投影，而非仅适配平面宽高。拒绝非有限裁剪坐标和透视投影中的 w <= 0；要求视空间 z 为负、NDC 位于安全画框内，并且每个支撑点都处于近裁剪面/远裁剪面范围内。

在读取层级或视锥体数据前，先更新世界矩阵和投影矩阵。使用单位变换/单位缩放的祖先链，或通过已更新的刚性、保持朝向的父级进行转换。对于仅使用位置/四元数的摄像机路径，若祖先链存在剪切、反射、奇异变换或非均匀缩放，则应拒绝使用。

遮挡导致摄像机变化时，应求解路径对应的近裁剪面覆盖范围，并重新检查安全画框和深度可行性。构图和间隙必须同时满足要求。

完成标准： 输出的摄像机具有有限的右手基、带有效 w 的有限裁剪坐标，完整支撑点集合位于安全画框和深度范围内；若存在遮挡，还必须进行遮挡后的复检。

4. 执行一次明确的交接

更新前先确定当前所有者。有限时长的自定义交接只记录一次起始状态，按秒计算时间，执行一次位置 lerp 和最短路径四元数 slerp，并在完成时复制精确的目标值。零时长交接是显式切换，并重置其历史状态；插值前拒绝负时长或非有限时长。自定义移动镜头则单独负责路径连续性、瞄准/上方向字段、计时、安全画面和遮挡检查。

将控制权交还控制器时，先确认交付的姿态符合其支持的上方向/滚转、父空间和限制范围。对于 OrbitControls，在不渲染的事务中重建目标和配置，重新创建控制器以清除潜在状态，然后在其构造函数更新后重新应用交付的姿态。更改 camera.up 后应重新创建控制器；保留预期的重置基线。在首次 update(0) 能保持位置、目标、朝向和投影不变之前，暂停输入和自动旋转。不支持的滚转或受限幅值需要显式过渡或改用其他控制器，不能声称切换时不会跳变。指针视角控制器应在其声明的上方向坐标系中重建偏航角/俯仰角，并在取消锁定、失焦、所有权变更和释放时清除按键状态。

使用内置控制器、混合或自定义镜头时，请阅读控制器与交接。

**完成标准：**不同重放速率都能到达相同终点，控制器首次更新不会跳变，并且每帧恰好只有一个语义所有者写入状态。

5. 管理精度与时间历史

对于模拟或实时对象，在渲染采样时刻使用不可变的前一帧/当前帧呈现样本，而不是原始的固定步长端点。镜头跟随、剔除、阴影、拾取和速度计算必须使用相同的样本标识；当流或对象身份发生不连续变化时，重置这些状态。

全局位置应使用 CPU 双精度或显式的高/低精度表示。根据对象类型和工作负载，选择普通网格高精度、区块局部重定位或实例高/低精度数据。仅在达到声明的精度阈值时才进行重定位，并同时发布不可变的前一帧/当前帧全局到渲染变换。

按稳定的镜头/场景身份、投影周期、原点周期、渲染尺寸/DPR、MRT 布局和速度约定标记时间状态。切镜、传送、稳定身份变更、不兼容的投影、未补偿的重定位、尺寸或 DPR 变更，或速度布局变更，都会在渲染前递增受影响的历史周期。将重置应用于速度、时间抗锯齿、景深、阴影拟合，以及所有使用已更改映射的重投影缓存。

内置 r185 TRAANode 负责管理瞬态 setViewOffset() 抖动，要求输入尺寸与绘制缓冲区一致，不会保留自定义视图偏移，也没有公开的历史重置接口。遇到不兼容的周期时，应重新创建该节点；如果需要自定义/平铺偏移、XR、分辨率缩放或跨重定位保留历史，则应使用单独管理或修补过的节点。

有关 r185 抖动行为，请阅读时间历史；有关 ULP 门限、表示方式和重定位顺序，请阅读镜头相对精度。

**完成标准：**当前和前一帧变换具有相同的稳定身份和声明的周期；所有实时对象使用者共享相同的渲染时刻样本标识；每次不连续变化都有重置或经过验证的补偿；静止对象在重定位后不会产生错误运动。

6. 提交、调整大小并恢复所拥有的状态

只写入一次语义姿态和未抖动的投影，然后更新世界矩阵和投影矩阵。让时间域所有者仅在其渲染作用域内应用抖动。调整大小或 DPR 变化时，应在一个事务中更新相机投影、按绘图缓冲区大小设置的后处理资源、抖动缩放和历史纪元。

对 Rig 所拥有的每个字段进行快照：变换、up、父级、图层、矩阵标志、完整的投影／视图偏移状态、控件状态、输出图、时间域节点、原点缓冲区、监听器、借用的 DOM 样式，以及所拥有的输入捕获。测试按住 Control、拖动过程中以及所拥有的指针锁状态下的拆除；参考资料中说明了内置控件释放过程存在的特定版本缺陷。释放时恢复该快照，释放所拥有的控件／后处理／存储／调试资源，并在输出节点或输出转换发生变化后将渲染管线标记为脏。

修改借用的相机、控件实例或渲染管线之前，请先阅读生命周期与恢复。

完成标准： 调整大小后，投影和时间域资源保持一致；重复挂载／释放后，所有借用字段均恢复，且没有遗留的监听器、GPU 资源或调试对象。

7. 验证 Rig

在极端宽高比、完整控件范围、镜头切换与中断的混合过渡、投影变化、重复重定位、调整大小／DPR 变化，以及释放／重新创建循环中，测试适用的工作负载。检查最终帧和诊断帧。

记录姿态／投影／原点／历史的所有者及纪元；目标视图／裁剪空间／NDC；支撑集包络与安全帧；近／远平面；当前／前一原点；相对坐标最大幅度；控件交接状态；以及活跃的 MRT 和时间域资源。

完成标准： 所选的每个分支均通过其几何、交接、精度、重置、调整大小和生命周期标准；每个故障都能定位到单一所有者、空间转换、可行性测试或历史纪元。

路由

场景对象运动请使用 $threejs-procedural-motion-systems，阴影拟合请使用 $threejs-scalable-real-time-shadows，后处理／输出所有权请使用 $threejs-image-pipeline，固定视图和回放证据请使用 $threejs-visual-validation。