Types - Camera#

API reference for ./evaluate/camera on @huukhanhnguyen/types.

See the Guide for the package's role.

API reference#

Signatures are generated from the live package .d.ts - not hand-written.

Camera#

type

A camera. Which projection it is follows from WHICH FIELD IS PRESENT — there is no type tag, the same way an Entity's kind is sniffed from its geometry rather than tagged and the way a block's behaviors are enabled by being present. Both fields at once, or neither, is not a camera; the union says so in TypeScript, and the model package's validation says so for JSON, which can still express it.

Absent by the same rule: zoom (a three.js viewport knob, absent from glTF, USD, BCF and USD's own GfCamera) and any sensor / film back / focal length (fov is an angle and needs no length unit; a film back is an EXPORTER convention — see crates/io/src/usd.rs).

type Camera
// = PerspectiveCamera | OrthographicCamera

CameraBase#

type

Where a camera stands and what it looks at — everything a camera carries that says nothing yet about HOW it projects. ONE declaration for the concept: a camera named on the cameras[] lane and a camera embedded in a view are the same object seen from two places (they were two types until 2026-08-14; identity is the only real difference).

Every length here is in the model's own unit (settings.units) — position, target, near, far. fov below is the one field that must name its unit, because settings.units says nothing about angles.

type CameraBase
// = {
    position: Point;
    /** What the camera looks at. MUST differ from `position`: equal points
     *  name no direction at all, and the basis built from them is NaN in
     *  every component. Producers throw rather than emit that (the model
     *  package's `evaluateLightOrCameraNode` / `foldHead`); this is the price
     *  of storing a target instead of a direction, which BCF, Revit and Rhino
     *  all store precisely to avoid. */
    target: Point;
    /** Camera roll reference — a DIRECTION, so a Vector: it has no location,
     *  and translating the camera must not translate it. REQUIRED (it was
     *  optional until 2026-08-15): a camera without an up vector has no roll
     *  defined, and every consumer was inventing world-up on its own. */
    up: Vector;
    /** Near/far clip, each a DISTANCE from `position` along the view
     *  direction (three.js convention). */
    near?: number;
    far?: number;
}

EvaluatedCamera#

type

A camera that the cameras[] lane names — a view3d head's camera arg resolves one of these by key (see the model package's viewChain foldHead).

type EvaluatedCamera
// = Camera & { key: string; }

OrthographicCamera#

type

A camera that projects through a BOX.

height is the world height visible, in the model's unit. ONE number, not four edges: left/right/top/bottom is the RENDERER's form (three.js feeds it straight to the projection matrix), while one number is the document form every other system stores — Blender ortho_scale, BCF ViewToWorldScale, glTF xmag/ymag, SketchUp height. The four edges are DERIVED, from this height plus the consumer's aspect.

A view's crop rectangle is a different subject and lives on the view (SavedView.window), not here.

type OrthographicCamera
// = CameraBase & { height: number; }

PerspectiveCamera#

type

A camera that projects through an ANGLE.

fov is the VERTICAL field of view in DEGREES. Stated here because three live conventions disagree and none of them errors at a boundary: glTF's spec is radians, three.js is degrees, and BCF's FieldOfView is HORIZONTAL degrees. This repo's own exporter already picked vertical degrees — crates/io/src/gltf_scene.rs names its field yfov_degrees and converts to radians on write — so the type now says what the exporter does instead of leaving it to be rediscovered.

There is deliberately NO aspectRatio: the consumer always supplies it (a viewport has the window's shape, a view3d placed on a sheet has the cell's), which is why glTF makes it optional too. With a VERTICAL fov that is well defined — widen the window and you see more horizontally.

type PerspectiveCamera
// = CameraBase & { fov: number; }