Three.js 相机核心 API

Camera（基类 — abstract）

说明：相机的抽象基类，通常不直接实例化。包含投影矩阵、视图矩阵等基础字段与方法。

属性 / 方法（文档列出的）：

• isCamera（只读）
  说明：判断对象是否为 Camera 的标志（boolean）。
  示例：

• layers（继承自 Object3D）
  说明：控制哪些 layer 可见（摄像机必须和物体共享 layer 才能看到）。
  示例：

• matrixWorldInverse（Matrix4）
  说明：相机的视矩阵（camera.matrixWorld 的逆），渲染器会在需要时更新它。你可以读取或 clone。
  示例：

• projectionMatrix（Matrix4）
  说明：投影矩阵，描述如何把相机空间投影到裁剪空间。通常通过 updateProjectionMatrix() 生成/更新。
  示例（读取）：

• projectionMatrixInverse（Matrix4）
  说明：投影矩阵的逆。可用于把裁剪空间坐标反算回相机空间。
  示例：

• clone() / copy(source) / getWorldDirection(target)
  说明：常用方法，克隆/复制相机，或获取相机朝向（世界空间，camera 视为沿 -Z 轴看向前方）。
  示例：

PerspectiveCamera（透视相机）

构造：new THREE.PerspectiveCamera( fov, aspect, near, far )
说明：模拟人眼 / 照相机的透视投影，常用相机。修改某些参数后需调用 updateProjectionMatrix()。

属性 & 示例：

• aspect: number（默认 1）
  说明：宽高比（通常 canvas 宽/高）。改变后 updateProjectionMatrix() 生效。
  示例：

• far: number（默认 2000）
  说明：远裁剪面，必须 > near。
  示例：

• near: number（默认 0.1）
  说明：近裁剪面（>0），影响深度精度。
  示例：

• fov: number（默认 50）
  说明：垂直视场角（度数）。改动后 updateProjectionMatrix() 生效。
  示例：

• zoom: number（默认 1）
  说明：缩放因子，影响视图（与 setFocalLength/getEffectiveFOV 有关系）。
  示例：

• filmGauge: number 与 filmOffset: number
  说明：用于按“胶片/传感器”物理参数计算 FOV / 透镜偏移（filmOffset 用于水平偏移）。通常在做摄影机模拟或视差时用。
  示例：

• focus: number（默认 10）
  说明：用于立体/景深估算（不直接影响投影矩阵，除非配合 StereoCamera / DOF 效果）。
  示例：

• view: Object | null（由 setViewOffset 设置）
  说明：多视图/多窗口时的视域描述（fullWidth/fullHeight/x/y/width/height）。用 setViewOffset() / clearViewOffset() 管理。
  示例（分屏多视图）：

常用方法与示例：

• updateProjectionMatrix()
  说明：在修改 fov/aspect/near/far/zoom 等后必须调用以更新 projectionMatrix。

• getFocalLength() / setFocalLength(mm) / getFilmWidth() / getFilmHeight() / getEffectiveFOV()
  说明：与物理相机参数（焦距 / 35mm filmGauge）相关，常用于摄影学相关计算。
  示例：

• setViewOffset(fullW, fullH, x, y, w, h) / clearViewOffset()
  说明：用于多显示器或多视口渲染（例如 3x2 矩阵的显示墙）。示例见上面 view。
• toJSON()
  说明：将相机序列化为 three.js 的 JSON 格式。

OrthographicCamera（正交/正射相机）

构造：new THREE.OrthographicCamera( left, right, top, bottom, near, far )
说明：正交投影 — 物体远近不影响大小（常用于 UI、CAD、2D 或等距视图）。修改参数后需 updateProjectionMatrix()。

属性 & 示例：

• left, right, top, bottom（Numbers）
  说明：正交视体的六个平面（左右上下由世界单位指定），修改后 updateProjectionMatrix()。
  示例：

• near, far（Number）
  说明：近平面 / 远平面。注意 orthographic 的 near 可以为 0。
  示例：

• zoom（Number，默认 1）
  说明：缩放因子，改变视图缩放，改变后 updateProjectionMatrix() 生效。
  示例：

• view: Object | null（由 setViewOffset 设置）
  说明：与透视相机类似，用于分屏 / 多视口。
  示例：

常用方法：setViewOffset, clearViewOffset, updateProjectionMatrix, toJSON()（用法与 Perspective 相似）。(threejs.org)

ArrayCamera（相机数组 — 用于多视图 / XR 等）

构造：new THREE.ArrayCamera( arrayOfCameras )
说明：内部包含多个子相机（一般为 PerspectiveCamera）。每个子相机必须设置 viewport（一个 THREE.Vector4(x,y,width,height)），用于定义在最终画布上的子视口位置。常用于分屏、多视角或 XR（WebXRManager 返回的 camera 即为 ArrayCamera）。

重要属性与用法：

• cameras（Array）
  说明：子相机数组（通常是 PerspectiveCamera 实例）。
  示例：

• isArrayCamera（只读）
  说明：检测类型标志。
  示例：

渲染提示（常见做法）：

• 确保为每个子相机设置 .viewport（Vector4），否则不会按预期分屏渲染。
• 可直接 renderer.render(scene, arrayCam)（renderer/Three.js 会遍历子相机并在各自视口渲染）；在手动渲染多视口时，也可以使用 renderer.setViewport/setScissor 配合独立相机逐一渲染（但 ArrayCamera 方便于 XR / 内部多视图场景）。

CubeCamera（立方体相机 — 动态环境贴图 / 反射）

构造：new THREE.CubeCamera( near, far, WebGLCubeRenderTarget )
说明：创建 6 个方向（立方体六面）的相机并渲染到 WebGLCubeRenderTarget，常用于生成动态 environment map（反射、折射等）。调用 cubeCamera.update(renderer, scene) 更新 renderTarget。

核心字段 / 方法：

• renderTarget（WebGLCubeRenderTarget）
  说明：立方体渲染目标（包含 .texture 可直接作为 envMap）。
  示例：

• update(renderer, scene)
  说明：把场景渲染到 cube render target（通常在对象不可见时更新，这样自身不会出现在贴图中）。
  示例（动态反射）：

StereoCamera（立体相机 — 左眼/右眼双透视）

构造：new THREE.StereoCamera()
说明：管理左右两颗 PerspectiveCamera（cameraL、cameraR），用于产生立体（anaglyph、parallax）效果。关键字段：aspect、eyeSep、cameraL、cameraR，方法 update(camera) 将基于传入的普通 camera 更新左右摄像机位姿。渲染时通常分别使用 stereo.cameraL 与 stereo.cameraR。

属性 / 方法示例：

• aspect（默认 1） & eyeSep（默认 0.064，米，眼间距近似值）
  示例：

• cameraL, cameraR（PerspectiveCamera）
  说明：两个子相机，左相机通常用于 layer 1，右相机用于 layer 2（文档里有层的约定，某些示例中使用 layer 控制左右）。
  示例（更新并分别渲染）：

• update(camera)
  说明：基于传入 PerspectiveCamera 计算左右相机偏移与投影参数。必须在渲染前调用。示例见上。