0
# Cameras
1

2
Camera system providing perspective and orthographic projection modes for rendering 3D scenes. All cameras inherit from the base Camera class and extend Object3D for full transformation capabilities.
3

4
## Capabilities
5

6
### Camera Base Class
7

8
Abstract base class providing core camera functionality including projection matrices and coordinate systems.
9

10
```typescript { .api }
11
import { Camera, Object3D, Matrix4, Vector3, WebGLCoordinateSystem, WebGPUCoordinateSystem } from 'three';
12

13
/**
14
 * Abstract base class for all camera types
15
 */
16
abstract class Camera extends Object3D {
17
  /** Type flag for camera detection */
18
  readonly isCamera: true;
19
  
20
  /** Inverse world matrix (view matrix) */
21
  matrixWorldInverse: Matrix4;
22
  
23
  /** Projection matrix */
24
  projectionMatrix: Matrix4;
25
  
26
  /** Inverse projection matrix */
27
  projectionMatrixInverse: Matrix4;
28
  
29
  /** Coordinate system (WebGL or WebGPU) */
30
  coordinateSystem: typeof WebGLCoordinateSystem | typeof WebGPUCoordinateSystem;
31
  
32
  /** Reversed depth buffer flag */
33
  readonly reversedDepth: boolean;
34
  
35
  /**
36
   * Constructor for camera base class
37
   */
38
  constructor();
39
  
40
  /**
41
   * Get camera's look direction in world space
42
   * @param target - Target vector to store result
43
   * @returns Camera direction vector (negative Z)
44
   */
45
  getWorldDirection(target: Vector3): Vector3;
46
  
47
  /**
48
   * Update projection matrix (must be implemented by subclasses)
49
   */
50
  abstract updateProjectionMatrix(): void;
51
  
52
  /**
53
   * Copy properties from another camera
54
   * @param source - Source camera to copy from
55
   * @param recursive - Copy children recursively
56
   * @returns This camera for chaining
57
   */
58
  copy(source: Camera, recursive?: boolean): this;
59
  
60
  /**
61
   * Clone camera
62
   * @param recursive - Clone children recursively
63
   * @returns Cloned camera
64
   */
65
  clone(recursive?: boolean): this;
66
}
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { Camera, Vector3 } from 'three';
73

74
// Get camera direction
75
const direction = new Vector3();
76
camera.getWorldDirection(direction);
77
console.log('Camera looking towards:', direction);
78

79
// Position camera
80
camera.position.set(0, 5, 10);
81
camera.lookAt(0, 0, 0);
82
```
83

84
### Perspective Camera
85

86
Camera using perspective projection that mimics human vision with foreshortening effects.
87

88
```typescript { .api }
89
import { PerspectiveCamera, Camera, Vector2 } from 'three';
90

91
/**
92
 * Camera with perspective projection (realistic depth perception)
93
 */
94
class PerspectiveCamera extends Camera {
95
  /** Type flag for perspective camera detection */
96
  readonly isPerspectiveCamera: true;
97
  
98
  /** Vertical field of view in degrees */
99
  fov: number;
100
  
101
  /** Zoom factor for scaling projection */
102
  zoom: number;
103
  
104
  /** Near clipping plane distance */
105
  near: number;
106
  
107
  /** Far clipping plane distance */
108
  far: number;
109
  
110
  /** Focus distance for stereoscopy and DOF */
111
  focus: number;
112
  
113
  /** Aspect ratio (width/height) */
114
  aspect: number;
115
  
116
  /** View offset for multi-view rendering */
117
  view: {
118
    enabled: boolean;
119
    fullWidth: number;
120
    fullHeight: number;
121
    offsetX: number;
122
    offsetY: number;
123
    width: number;
124
    height: number;
125
  } | null;
126
  
127
  /** Film gauge in millimeters (larger axis) */
128
  filmGauge: number;
129
  
130
  /** Film offset for asymmetric frustum */
131
  filmOffset: number;
132
  
133
  /**
134
   * Create perspective camera
135
   * @param fov - Vertical field of view in degrees (default: 50)
136
   * @param aspect - Aspect ratio width/height (default: 1)
137
   * @param near - Near clipping plane (default: 0.1)
138
   * @param far - Far clipping plane (default: 2000)
139
   */
140
  constructor(fov?: number, aspect?: number, near?: number, far?: number);
141
  
142
  /**
143
   * Update projection matrix from camera parameters
144
   */
145
  updateProjectionMatrix(): void;
146
  
147
  /**
148
   * Set view offset for multi-view rendering
149
   * @param fullWidth - Full framebuffer width
150
   * @param fullHeight - Full framebuffer height
151
   * @param x - Horizontal offset of subcamera
152
   * @param y - Vertical offset of subcamera
153
   * @param width - Width of subcamera
154
   * @param height - Height of subcamera
155
   */
156
  setViewOffset(
157
    fullWidth: number, 
158
    fullHeight: number, 
159
    x: number, 
160
    y: number, 
161
    width: number, 
162
    height: number
163
  ): void;
164
  
165
  /**
166
   * Remove view offset
167
   */
168
  clearViewOffset(): void;
169
  
170
  /**
171
   * Get effective vertical field of view accounting for zoom
172
   * @returns Effective FOV in degrees
173
   */
174
  getEffectiveFOV(): number;
175
  
176
  /**
177
   * Get film width based on aspect ratio and film gauge
178
   * @returns Film width in millimeters
179
   */
180
  getFilmWidth(): number;
181
  
182
  /**
183
   * Get film height based on aspect ratio and film gauge
184
   * @returns Film height in millimeters
185
   */
186
  getFilmHeight(): number;
187
  
188
  /**
189
   * Set focal length from film gauge and current FOV
190
   * @param focalLength - Focal length in millimeters
191
   */
192
  setFocalLength(focalLength: number): void;
193
  
194
  /**
195
   * Get focal length from film gauge and current FOV
196
   * @returns Focal length in millimeters
197
   */
198
  getFocalLength(): number;
199
  
200
  /**
201
   * Get view bounds at given Z distance
202
   * @param distance - Z distance from camera
203
   * @param minTarget - Target vector for minimum bounds
204
   * @param maxTarget - Target vector for maximum bounds
205
   */
206
  getViewBounds(distance: number, minTarget: Vector2, maxTarget: Vector2): void;
207
  
208
  /**
209
   * Get view size at given Z distance
210
   * @param distance - Z distance from camera
211
   * @param target - Target vector to store size
212
   * @returns View size at distance
213
   */
214
  getViewSize(distance: number, target: Vector2): Vector2;
215
  
216
  /**
217
   * Copy properties from another perspective camera
218
   * @param source - Source camera
219
   * @param recursive - Copy children recursively
220
   * @returns This camera for chaining
221
   */
222
  copy(source: PerspectiveCamera, recursive?: boolean): this;
223
  
224
  /**
225
   * Serialize camera to JSON
226
   * @param meta - Metadata object
227
   * @returns JSON representation
228
   */
229
  toJSON(meta?: any): any;
230
}
231
```
232

233
**Usage Examples:**
234

235
```typescript
236
import { PerspectiveCamera, Vector2 } from 'three';
237

238
// Create standard perspective camera
239
const camera = new PerspectiveCamera(
240
  75,                    // FOV
241
  window.innerWidth / window.innerHeight, // Aspect
242
  0.1,                   // Near
243
  1000                   // Far
244
);
245

246
// Position camera
247
camera.position.z = 5;
248

249
// Adjust parameters
250
camera.fov = 60;
251
camera.zoom = 1.5;
252
camera.updateProjectionMatrix(); // Apply changes
253

254
// Multi-view rendering (split screen)
255
camera.setViewOffset(
256
  1920, 1080,  // Full resolution
257
  0, 0,        // Offset for left eye
258
  960, 1080    // Half width
259
);
260

261
// Camera calculations
262
const effectiveFOV = camera.getEffectiveFOV();
263
const focalLength = camera.getFocalLength();
264

265
// View bounds at distance
266
const min = new Vector2();
267
const max = new Vector2(); 
268
camera.getViewBounds(10, min, max);
269
console.log(`View at distance 10: ${max.x - min.x} x ${max.y - min.y}`);
270

271
// Handle resize
272
function onWindowResize() {
273
  camera.aspect = window.innerWidth / window.innerHeight;
274
  camera.updateProjectionMatrix();
275
}
276
```
277

278
### Orthographic Camera
279

280
Camera using orthographic projection with no perspective distortion, useful for UI, 2D scenes, and technical drawings.
281

282
```typescript { .api }
283
import { OrthographicCamera, Camera } from 'three';
284

285
/**
286
 * Camera with orthographic projection (no perspective distortion)
287
 */
288
class OrthographicCamera extends Camera {
289
  /** Type flag for orthographic camera detection */
290
  readonly isOrthographicCamera: true;
291
  
292
  /** Zoom factor for scaling projection */
293
  zoom: number;
294
  
295
  /** View offset for multi-view rendering */
296
  view: {
297
    enabled: boolean;
298
    fullWidth: number;
299
    fullHeight: number;
300
    offsetX: number;
301
    offsetY: number;
302
    width: number;
303
    height: number;
304
  } | null;
305
  
306
  /** Left frustum plane */
307
  left: number;
308
  
309
  /** Right frustum plane */
310
  right: number;
311
  
312
  /** Top frustum plane */
313
  top: number;
314
  
315
  /** Bottom frustum plane */
316
  bottom: number;
317
  
318
  /** Near clipping plane distance */
319
  near: number;
320
  
321
  /** Far clipping plane distance */
322
  far: number;
323
  
324
  /**
325
   * Create orthographic camera
326
   * @param left - Left frustum plane (default: -1)
327
   * @param right - Right frustum plane (default: 1)
328
   * @param top - Top frustum plane (default: 1)
329
   * @param bottom - Bottom frustum plane (default: -1)
330
   * @param near - Near clipping plane (default: 0.1)
331
   * @param far - Far clipping plane (default: 2000)
332
   */
333
  constructor(
334
    left?: number, 
335
    right?: number, 
336
    top?: number, 
337
    bottom?: number, 
338
    near?: number, 
339
    far?: number
340
  );
341
  
342
  /**
343
   * Update projection matrix from camera parameters
344
   */
345
  updateProjectionMatrix(): void;
346
  
347
  /**
348
   * Set view offset for multi-view rendering
349
   * @param fullWidth - Full framebuffer width
350
   * @param fullHeight - Full framebuffer height
351
   * @param x - Horizontal offset of subcamera
352
   * @param y - Vertical offset of subcamera
353
   * @param width - Width of subcamera
354
   * @param height - Height of subcamera
355
   */
356
  setViewOffset(
357
    fullWidth: number, 
358
    fullHeight: number, 
359
    x: number, 
360
    y: number, 
361
    width: number, 
362
    height: number
363
  ): void;
364
  
365
  /**
366
   * Remove view offset
367
   */
368
  clearViewOffset(): void;
369
  
370
  /**
371
   * Copy properties from another orthographic camera
372
   * @param source - Source camera
373
   * @param recursive - Copy children recursively
374
   * @returns This camera for chaining
375
   */
376
  copy(source: OrthographicCamera, recursive?: boolean): this;
377
  
378
  /**
379
   * Serialize camera to JSON
380
   * @param meta - Metadata object
381
   * @returns JSON representation
382
   */
383
  toJSON(meta?: any): any;
384
}
385
```
386

387
**Usage Examples:**
388

389
```typescript
390
import { OrthographicCamera } from 'three';
391

392
// Create orthographic camera for 2D scene
393
const camera = new OrthographicCamera(
394
  -window.innerWidth / 2,   // left
395
  window.innerWidth / 2,    // right  
396
  window.innerHeight / 2,   // top
397
  -window.innerHeight / 2,  // bottom
398
  1,                        // near
399
  1000                      // far
400
);
401

402
// Position camera
403
camera.position.z = 10;
404

405
// Zoom functionality
406
camera.zoom = 2; // 2x zoom
407
camera.updateProjectionMatrix();
408

409
// UI camera setup (pixel-perfect)
410
const uiCamera = new OrthographicCamera(
411
  0,                    // left (screen left)
412
  window.innerWidth,    // right (screen right)
413
  0,                    // top (screen top) 
414
  window.innerHeight,   // bottom (screen bottom)
415
  -1,                   // near
416
  1                     // far
417
);
418

419
// Handle resize for orthographic camera
420
function onWindowResize() {
421
  const aspect = window.innerWidth / window.innerHeight;
422
  const frustumHeight = 10;
423
  const frustumWidth = frustumHeight * aspect;
424
  
425
  camera.left = -frustumWidth / 2;
426
  camera.right = frustumWidth / 2;
427
  camera.top = frustumHeight / 2;
428
  camera.bottom = -frustumHeight / 2;
429
  camera.updateProjectionMatrix();
430
}
431

432
// Top-down view setup
433
const topDownCamera = new OrthographicCamera(-50, 50, 50, -50, 0.1, 100);
434
topDownCamera.position.set(0, 50, 0);
435
topDownCamera.lookAt(0, 0, 0);
436
```
437

438
### Specialized Cameras
439

440
Additional camera types for specific use cases.
441

442
```typescript { .api }
443
import { 
444
  ArrayCamera, 
445
  CubeCamera, 
446
  StereoCamera,
447
  Camera,
448
  PerspectiveCamera,
449
  Scene,
450
  WebGLCubeRenderTarget
451
} from 'three';
452

453
/**
454
 * Array of cameras for VR and multi-view rendering
455
 */
456
class ArrayCamera extends PerspectiveCamera {
457
  /** Type flag for array camera detection */
458
  readonly isArrayCamera: true;
459
  
460
  /** Array of cameras */
461
  cameras: PerspectiveCamera[];
462
  
463
  /**
464
   * Create array camera
465
   * @param cameras - Array of perspective cameras
466
   */
467
  constructor(cameras?: PerspectiveCamera[]);
468
}
469

470
/**
471
 * Camera for cube map generation
472
 */
473
class CubeCamera extends Object3D {
474
  /** Type flag for cube camera detection */
475
  readonly isCubeCamera: true;
476
  
477
  /** Render target for cube map */
478
  renderTarget: WebGLCubeRenderTarget;
479
  
480
  /** Coordinate system */
481
  coordinateSystem: number;
482
  
483
  /**
484
   * Create cube camera
485
   * @param near - Near clipping plane
486
   * @param far - Far clipping plane
487
   * @param renderTarget - Cube render target
488
   */
489
  constructor(near: number, far: number, renderTarget: WebGLCubeRenderTarget);
490
  
491
  /**
492
   * Update cube map from position
493
   * @param renderer - WebGL renderer
494
   * @param scene - Scene to render
495
   */
496
  update(renderer: any, scene: Scene): void;
497
}
498

499
/**
500
 * Stereo camera pair for VR rendering
501
 */
502
class StereoCamera extends Camera {
503
  /** Type flag for stereo camera detection */
504
  readonly isStereoCamera: true;
505
  
506
  /** Camera aspect ratio */
507
  aspect: number;
508
  
509
  /** Eye separation distance */
510
  eyeSep: number;
511
  
512
  /** Left eye camera */
513
  cameraL: PerspectiveCamera;
514
  
515
  /** Right eye camera */
516
  cameraR: PerspectiveCamera;
517
  
518
  /**
519
   * Create stereo camera
520
   */
521
  constructor();
522
  
523
  /**
524
   * Update stereo cameras
525
   * @param camera - Base camera to derive from
526
   */
527
  update(camera: PerspectiveCamera): void;
528
}
529
```
530

531
**Usage Examples:**
532

533
```typescript
534
import { ArrayCamera, PerspectiveCamera, StereoCamera, CubeCamera, WebGLCubeRenderTarget } from 'three';
535

536
// VR stereo rendering
537
const stereoCamera = new StereoCamera();
538
stereoCamera.aspect = 0.5; // Half width per eye
539
stereoCamera.eyeSep = 0.064; // Average eye separation
540

541
// Update stereo cameras from base camera
542
stereoCamera.update(baseCamera);
543

544
// Render each eye
545
renderer.setViewport(0, 0, width/2, height);
546
renderer.render(scene, stereoCamera.cameraL);
547
renderer.setViewport(width/2, 0, width/2, height);
548
renderer.render(scene, stereoCamera.cameraR);
549

550
// Cube camera for environment mapping
551
const cubeRenderTarget = new WebGLCubeRenderTarget(256);
552
const cubeCamera = new CubeCamera(1, 1000, cubeRenderTarget);
553

554
// Position cube camera and update
555
cubeCamera.position.copy(reflectiveObject.position);
556
cubeCamera.update(renderer, scene);
557

558
// Use generated cube map
559
reflectiveObject.material.envMap = cubeRenderTarget.texture;
560
```
561

562
### Camera Utilities and Helpers
563

564
```typescript { .api }
565
import { CameraHelper, Camera, LineSegments } from 'three';
566

567
/**
568
 * Helper for visualizing camera frustum
569
 */
570
class CameraHelper extends LineSegments {
571
  /** Camera being visualized */
572
  camera: Camera;
573
  
574
  /** Helper geometry points */
575
  pointMap: Record<string, number[]>;
576
  
577
  /**
578
   * Create camera helper
579
   * @param camera - Camera to visualize
580
   */
581
  constructor(camera: Camera);
582
  
583
  /**
584
   * Update helper geometry
585
   */
586
  update(): void;
587
  
588
  /**
589
   * Dispose of helper resources
590
   */
591
  dispose(): void;
592
}
593
```
594

595
**Usage Examples:**
596

597
```typescript
598
import { CameraHelper } from 'three';
599

600
// Visualize camera frustum
601
const helper = new CameraHelper(camera);
602
scene.add(helper);
603

604
// Update when camera changes
605
camera.updateProjectionMatrix();
606
helper.update();
607
```
608

609
## Camera Control Patterns
610

611
### Basic Camera Setup
612

613
```typescript
614
// Standard perspective camera setup
615
function createPerspectiveCamera(aspect: number): PerspectiveCamera {
616
  const camera = new PerspectiveCamera(75, aspect, 0.1, 1000);
617
  camera.position.set(0, 0, 5);
618
  return camera;
619
}
620

621
// Orthographic camera for UI
622
function createUICamera(width: number, height: number): OrthographicCamera {
623
  const camera = new OrthographicCamera(0, width, 0, height, -1, 1);
624
  camera.position.z = 1;
625
  return camera;
626
}
627
```
628

629
### Responsive Camera Management
630

631
```typescript
632
function handleResize(
633
  camera: PerspectiveCamera | OrthographicCamera,
634
  width: number,
635
  height: number
636
): void {
637
  if (camera.isPerspectiveCamera) {
638
    camera.aspect = width / height;
639
    camera.updateProjectionMatrix();
640
  } else if (camera.isOrthographicCamera) {
641
    const aspect = width / height;
642
    const frustumHeight = 10;
643
    const frustumWidth = frustumHeight * aspect;
644
    
645
    camera.left = -frustumWidth / 2;
646
    camera.right = frustumWidth / 2;
647
    camera.top = frustumHeight / 2;
648
    camera.bottom = -frustumHeight / 2;
649
    camera.updateProjectionMatrix();
650
  }
651
}
652
```
653

654
The camera system provides flexible projection modes for different rendering scenarios, from realistic 3D scenes with perspective cameras to pixel-perfect UI rendering with orthographic cameras. All cameras inherit full 3D transformation capabilities from Object3D for complete positioning and orientation control.