0
# Cameras
1

2
Camera components providing different projection and rendering modes for 3D scenes. All camera components integrate with React Three Fiber's camera system and can be made the default scene camera.
3

4
## Capabilities
5

6
### PerspectiveCamera
7

8
A perspective camera that uses field-of-view based projection, mimicking human vision where distant objects appear smaller.
9

10
```typescript { .api }
11
/**
12
 * Perspective camera with FOV-based projection
13
 * @param props - Camera configuration props
14
 * @returns JSX element for the camera
15
 */
16
function PerspectiveCamera(props: PerspectiveCameraProps): JSX.Element;
17

18
interface PerspectiveCameraProps extends Omit<ThreeElements['perspectiveCamera'], 'ref'> {
19
  /** Makes this camera the default camera for the scene, false */
20
  makeDefault?: boolean;
21
  /** The camera's field of view in degrees, 75 */
22
  fov?: number;
23
  /** Camera position in 3D space */
24
  position?: [number, number, number];
25
  /** Camera near clipping plane, 0.1 */
26
  near?: number;
27
  /** Camera far clipping plane, 1000 */
28
  far?: number;
29
  /** Zoom factor, 1 */
30
  zoom?: number;
31
  /** Manual aspect ratio override */
32
  aspect?: number;
33
  /** Film gauge for sensor size calculations, 35 */
34
  filmGauge?: number;
35
  /** Film offset for lens shift effects, 0 */
36
  filmOffset?: number;
37
  /** Auto-update projection matrix, true */
38
  matrixAutoUpdate?: boolean;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { PerspectiveCamera } from '@react-three/drei';
46

47
// Basic perspective camera
48
<PerspectiveCamera 
49
  makeDefault 
50
  position={[0, 0, 5]} 
51
  fov={75} 
52
/>
53

54
// Camera with custom settings
55
<PerspectiveCamera
56
  position={[10, 10, 10]}
57
  fov={45}
58
  near={0.1}
59
  far={2000}
60
  zoom={1.5}
61
/>
62
```
63

64
### OrthographicCamera
65

66
An orthographic camera that uses parallel projection, where object size remains constant regardless of distance from the camera.
67

68
```typescript { .api }
69
/**
70
 * Orthographic camera with parallel projection
71
 * @param props - Camera configuration props
72
 * @returns JSX element for the camera
73
 */
74
function OrthographicCamera(props: OrthographicCameraProps): JSX.Element;
75

76
interface OrthographicCameraProps extends Omit<ThreeElements['orthographicCamera'], 'ref'> {
77
  /** Makes this camera the default camera for the scene, false */
78
  makeDefault?: boolean;
79
  /** Camera position in 3D space */
80
  position?: [number, number, number];
81
  /** Camera zoom factor, 1 */
82
  zoom?: number;
83
  /** Left boundary of camera frustum */
84
  left?: number;
85
  /** Right boundary of camera frustum */
86
  right?: number;
87
  /** Top boundary of camera frustum */
88
  top?: number;
89
  /** Bottom boundary of camera frustum */
90
  bottom?: number;
91
  /** Near clipping plane, 0.1 */
92
  near?: number;
93
  /** Far clipping plane, 1000 */
94
  far?: number;
95
}
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { OrthographicCamera } from '@react-three/drei';
102

103
// Basic orthographic camera
104
<OrthographicCamera 
105
  makeDefault 
106
  position={[0, 0, 5]} 
107
  zoom={1} 
108
/>
109

110
// Camera with custom frustum
111
<OrthographicCamera
112
  position={[5, 5, 5]}
113
  left={-10}
114
  right={10}
115
  top={10}
116
  bottom={-10}
117
  near={0.1}
118
  far={100}
119
/>
120
```
121

122
### CubeCamera
123

124
A specialized camera for rendering cube maps, commonly used for environment mapping, reflections, and dynamic skyboxes.
125

126
```typescript { .api }
127
/**
128
 * Cube camera for environment mapping and reflections
129
 * @param props - Cube camera configuration props
130
 * @returns JSX element for the cube camera
131
 */
132
function CubeCamera(props: CubeCameraProps): JSX.Element;
133

134
interface CubeCameraProps extends Omit<ThreeElements['group'], 'ref'> {
135
  /** Cube map resolution, 256 */
136
  resolution?: number;
137
  /** Camera near clipping plane, 0.1 */
138
  near?: number;
139
  /** Camera far clipping plane, 1000 */
140
  far?: number;
141
  /** Environment map preset */
142
  preset?: string;
143
  /** Custom environment files */
144
  files?: string[];
145
  /** Update frames interval, 1 */
146
  frames?: number;
147
  /** Auto-update the cube map, true */
148
  update?: boolean;
149
  /** Fog rendering in cube map, false */
150
  fog?: boolean;
151
}
152

153
interface CubeCameraOptions {
154
  resolution: number;
155
  near: number;
156
  far: number;
157
  frames: number;
158
}
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { CubeCamera } from '@react-three/drei';
165

166
// Basic cube camera for reflections
167
<CubeCamera resolution={256} position={[0, 0, 0]}>
168
  {(texture) => (
169
    <mesh>
170
      <sphereGeometry />
171
      <meshStandardMaterial envMap={texture} />
172
    </mesh>
173
  )}
174
</CubeCamera>
175

176
// High-resolution cube camera with custom settings
177
<CubeCamera
178
  resolution={1024}
179
  near={0.1}
180
  far={1000}
181
  frames={1}
182
  fog={false}
183
  position={[0, 2, 0]}
184
>
185
  {(texture) => (
186
    <mesh>
187
      <boxGeometry />
188
      <meshStandardMaterial 
189
        envMap={texture} 
190
        metalness={1} 
191
        roughness={0} 
192
      />
193
    </mesh>
194
  )}
195
</CubeCamera>
196
```
197

198
## Integration Patterns
199

200
### Making a Camera Default
201

202
Any camera can be made the default scene camera:
203

204
```typescript
205
// This camera will be used by controls and other components
206
<PerspectiveCamera makeDefault position={[0, 0, 5]} />
207
<OrbitControls /> // Will automatically use the default camera
208
```
209

210
### Multiple Cameras
211

212
You can have multiple cameras in a scene and switch between them:
213

214
```typescript
215
const [activeCamera, setActiveCamera] = useState('perspective');
216

217
return (
218
  <>
219
    <PerspectiveCamera 
220
      makeDefault={activeCamera === 'perspective'} 
221
      position={[0, 0, 5]} 
222
    />
223
    <OrthographicCamera 
224
      makeDefault={activeCamera === 'orthographic'} 
225
      position={[0, 0, 5]} 
226
      zoom={50}
227
    />
228
    <button onClick={() => setActiveCamera(
229
      activeCamera === 'perspective' ? 'orthographic' : 'perspective'
230
    )}>
231
      Switch Camera
232
    </button>
233
  </>
234
);
235
```
236

237
### Camera Animation
238

239
Cameras can be animated using React Three Fiber patterns:
240

241
```typescript
242
import { useFrame } from '@react-three/fiber';
243

244
function AnimatedCamera() {
245
  const cameraRef = useRef();
246
  
247
  useFrame((state) => {
248
    if (cameraRef.current) {
249
      cameraRef.current.position.x = Math.sin(state.clock.elapsedTime) * 5;
250
    }
251
  });
252
  
253
  return (
254
    <PerspectiveCamera 
255
      ref={cameraRef}
256
      makeDefault 
257
      position={[0, 0, 5]} 
258
    />
259
  );
260
}
261
```