Cameras

Reference for FitCamera, CameraRig (views, orbit, inset, follow, drift, flyTo and jumpTo), FollowCamera, CAMERA_VIEWS and the CameraView, OrbitOptions, Inset and FollowOptions types.

import { CAMERA_VIEWS, CameraRig, FitCamera, FollowCamera } from "@apricot/react";
import type { CameraRigHandle, CameraView, FollowOptions, Inset, OrbitOptions } from "@apricot/react";

One camera controller per scene. Without one, the camera stays where <Scene camera> put it. All angles on this page are in degrees except where noted.

`FitCamera`#

Keeps a flat area fully in view at any screen size: moves the camera along its line of sight so size fits, now and after every resize. For cards, single objects and hero screens.

Prop	Type	Default	Description
`size`	`[width, height]`	required	The area to keep on screen, facing the camera, in units
`margin`	number	`0.1`	Space around it, as a fraction
`target`	`Vec3`	`[0, 0, 0]`	The point looked at

The camera keeps the direction and fov it was given in <Scene camera>.

`CameraRig`#

Places the camera on an orbit around a subject and flies between views along arcs. Put it inside the object to frame (a <Model>, <Group> or shape); without a distance, it backs off until the subject fits the free part of the screen.

Prop	Type	Default	Description
`view`	`string \| CameraView`	`"three-quarter"`	A built-in name, a name from `views`, or a view object. Changing it flies there
`views`	`Record<string, CameraView>`		Your own named views
`transition`	seconds	`0.9`	How long a change of view takes
`inset`	`Inset`	none	Points covered by UI on each side; the subject is framed in the rest
`margin`	number	`0.1`	Extra room around the subject, as a fraction
`subject`	`Object3D \| null`	the parent	What to frame. `null` frames nothing: views then need a `distance` (and usually a `target`)
`follow`	ref or `Object3D \| null`		A moving object the orbit's centre eases after (a train, a runner)
`followStiffness`	number	`3`	How tightly it follows, per second
`drift`	degrees per second	`0`	Slowly circles the subject. Pauses while a finger is on the scene
`orbit`	`boolean \| OrbitOptions`	`false`	Drag to turn, pinch to zoom (wheel on the web). Taps still work
`onOrbitStart`, `onOrbitEnd`	`() => void`		A finger went down to turn the camera; all fingers lifted. Use them to pause a `ScrollView` on iOS
`ref`	`Ref<CameraRigHandle>`

`CameraView`#

Field	Type	Description
`azimuth`	degrees	Around the vertical axis. 0 is in front (+z), 90 on the left (+x)
`elevation`	degrees	Above the horizon. 90 looks straight down
`distance`	units	From the target. Default: fit the subject
`target`	`Vec3`	The point looked at. Default: the subject's centre, or the origin
`position`	`Vec3`	Places the camera exactly instead of using angles
`fov`	degrees	Field of view for this view

`CAMERA_VIEWS`#

Name	Azimuth	Elevation
`front`	0	8
`back`	180	8
`left`	90	8
`right`	−90	8
`top`	0	90
`three-quarter`	35	16

`OrbitOptions`#

Field	Type	Default	Description
`turn`	degrees	all the way round	How far the camera may turn either way from the view's azimuth
`elevation`	`[lowest, highest]`	`[0, 85]`	Never below the floor by default
`zoom`	`[nearest, farthest] \| false`	`[0.5, 2]`	Fractions of the view's distance. `false` turns pinch off
`speed`	number	`1`	1 turns 180° for a drag across the whole canvas
`inertia`	boolean	`true`	Keeps turning after a flick, slowing down
`returnAfter`	seconds	stay	Flies back to the view this long after the last touch

`Inset`#

{ top?, bottom?, left?, right? } in points.

`CameraRigHandle`#

Method	Description
`flyTo(view, seconds?)`	Flies to a view (name or object) over `seconds` (default: `transition`)
`jumpTo(view)`	Puts the camera at a view at once

Setting view to the value it already has does nothing, so use flyTo to return after the user orbited.

The rig widens the camera's far plane for distant views (to five times the distance); it never narrows it.

`FollowCamera`#

A chase camera behind and above a target, easing after it and looking a little ahead. Made for <Vehicle>; it ignores the target's pitch. Options are read once, at mount. Place it after the target in the tree.

Prop	Type	Default	Description
`target`	`RefObject<SceneObject \| null>`	required	The object to chase, such as a `<Vehicle ref>`
`distance`	units	`6`	Behind the target
`height`	units	`2.6`	Above the target
`lookAhead`	`[ahead, up]`	`[3, 0.6]`	The point looked at, relative to the target
`stiffness`	per second	`4`	How quickly it catches up; higher is stiffer

import { CAMERA_VIEWS, CameraRig, FitCamera, FollowCamera } from "@apricot/react";
import type { CameraRigHandle, CameraView, FollowOptions, Inset, OrbitOptions } from "@apricot/react";

One camera controller per scene. Without one, the camera stays where <Scene camera> put it. All angles on this page are in degrees except where noted.

`FitCamera`#

Keeps a flat area fully in view at any screen size: moves the camera along its line of sight so size fits, now and after every resize. For cards, single objects and hero screens.

Prop	Type	Default	Description
`size`	`[width, height]`	required	The area to keep on screen, facing the camera, in units
`margin`	number	`0.1`	Space around it, as a fraction
`target`	`Vec3`	`[0, 0, 0]`	The point looked at

The camera keeps the direction and fov it was given in <Scene camera>.

`CameraRig`#

Prop	Type	Default	Description
`view`	`string \| CameraView`	`"three-quarter"`	A built-in name, a name from `views`, or a view object. Changing it flies there
`views`	`Record<string, CameraView>`		Your own named views
`transition`	seconds	`0.9`	How long a change of view takes
`inset`	`Inset`	none	Points covered by UI on each side; the subject is framed in the rest
`margin`	number	`0.1`	Extra room around the subject, as a fraction
`subject`	`Object3D \| null`	the parent	What to frame. `null` frames nothing: views then need a `distance` (and usually a `target`)
`follow`	ref or `Object3D \| null`		A moving object the orbit's centre eases after (a train, a runner)
`followStiffness`	number	`3`	How tightly it follows, per second
`drift`	degrees per second	`0`	Slowly circles the subject. Pauses while a finger is on the scene
`orbit`	`boolean \| OrbitOptions`	`false`	Drag to turn, pinch to zoom (wheel on the web). Taps still work
`onOrbitStart`, `onOrbitEnd`	`() => void`		A finger went down to turn the camera; all fingers lifted. Use them to pause a `ScrollView` on iOS
`ref`	`Ref<CameraRigHandle>`

`CameraView`#

Field	Type	Description
`azimuth`	degrees	Around the vertical axis. 0 is in front (+z), 90 on the left (+x)
`elevation`	degrees	Above the horizon. 90 looks straight down
`distance`	units	From the target. Default: fit the subject
`target`	`Vec3`	The point looked at. Default: the subject's centre, or the origin
`position`	`Vec3`	Places the camera exactly instead of using angles
`fov`	degrees	Field of view for this view

`CAMERA_VIEWS`#

Name	Azimuth	Elevation
`front`	0	8
`back`	180	8
`left`	90	8
`right`	−90	8
`top`	0	90
`three-quarter`	35	16

`OrbitOptions`#

Field	Type	Default	Description
`turn`	degrees	all the way round	How far the camera may turn either way from the view's azimuth
`elevation`	`[lowest, highest]`	`[0, 85]`	Never below the floor by default
`zoom`	`[nearest, farthest] \| false`	`[0.5, 2]`	Fractions of the view's distance. `false` turns pinch off
`speed`	number	`1`	1 turns 180° for a drag across the whole canvas
`inertia`	boolean	`true`	Keeps turning after a flick, slowing down
`returnAfter`	seconds	stay	Flies back to the view this long after the last touch

`Inset`#

{ top?, bottom?, left?, right? } in points.

`CameraRigHandle`#

Method	Description
`flyTo(view, seconds?)`	Flies to a view (name or object) over `seconds` (default: `transition`)
`jumpTo(view)`	Puts the camera at a view at once

Setting view to the value it already has does nothing, so use flyTo to return after the user orbited.

The rig widens the camera's far plane for distant views (to five times the distance); it never narrows it.

`FollowCamera`#

Prop	Type	Default	Description
`target`	`RefObject<SceneObject \| null>`	required	The object to chase, such as a `<Vehicle ref>`
`distance`	units	`6`	Behind the target
`height`	units	`2.6`	Above the target
`lookAhead`	`[ahead, up]`	`[3, 0.6]`	The point looked at, relative to the target
`stiffness`	per second	`4`	How quickly it catches up; higher is stiffer

FitCamera#

CameraRig#

CameraView#

CAMERA_VIEWS#

OrbitOptions#

Inset#

CameraRigHandle#

FollowCamera#

Related#

Cameras

FitCamera#

CameraRig#

CameraView#

CAMERA_VIEWS#

OrbitOptions#

Inset#

CameraRigHandle#

FollowCamera#

Related#

`FitCamera`#

`CameraRig`#

`CameraView`#

`CAMERA_VIEWS`#

`OrbitOptions`#

`Inset`#

`CameraRigHandle`#

`FollowCamera`#

`FitCamera`#

`CameraRig`#

`CameraView`#

`CAMERA_VIEWS`#

`OrbitOptions`#

`Inset`#

`CameraRigHandle`#

`FollowCamera`#