# Cameras

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

```ts
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 |

## Related

- [Camera guide](https://matthiasbrandolin.dev/apricot/guides/camera).
- [Coordinates and units](https://matthiasbrandolin.dev/apricot/concepts/coordinates#camera-views).