tessl/npm-three

JavaScript 3D library providing WebGL and WebGPU renderers for creating interactive 3D graphics in web browsers

—

Pending

Overview

Eval results

Files

Cameras

Name: tessl/npm-three
Author: tessl

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.

Capabilities

Camera Base Class

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

import { Camera, Object3D, Matrix4, Vector3, WebGLCoordinateSystem, WebGPUCoordinateSystem } from 'three';

/**
 * Abstract base class for all camera types
 */
abstract class Camera extends Object3D {
  /** Type flag for camera detection */
  readonly isCamera: true;
  
  /** Inverse world matrix (view matrix) */
  matrixWorldInverse: Matrix4;
  
  /** Projection matrix */
  projectionMatrix: Matrix4;
  
  /** Inverse projection matrix */
  projectionMatrixInverse: Matrix4;
  
  /** Coordinate system (WebGL or WebGPU) */
  coordinateSystem: typeof WebGLCoordinateSystem | typeof WebGPUCoordinateSystem;
  
  /** Reversed depth buffer flag */
  readonly reversedDepth: boolean;
  
  /**
   * Constructor for camera base class
   */
  constructor();
  
  /**
   * Get camera's look direction in world space
   * @param target - Target vector to store result
   * @returns Camera direction vector (negative Z)
   */
  getWorldDirection(target: Vector3): Vector3;
  
  /**
   * Update projection matrix (must be implemented by subclasses)
   */
  abstract updateProjectionMatrix(): void;
  
  /**
   * Copy properties from another camera
   * @param source - Source camera to copy from
   * @param recursive - Copy children recursively
   * @returns This camera for chaining
   */
  copy(source: Camera, recursive?: boolean): this;
  
  /**
   * Clone camera
   * @param recursive - Clone children recursively
   * @returns Cloned camera
   */
  clone(recursive?: boolean): this;
}

Usage Examples:

import { Camera, Vector3 } from 'three';

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

// Position camera
camera.position.set(0, 5, 10);
camera.lookAt(0, 0, 0);

Perspective Camera

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

import { PerspectiveCamera, Camera, Vector2 } from 'three';

/**
 * Camera with perspective projection (realistic depth perception)
 */
class PerspectiveCamera extends Camera {
  /** Type flag for perspective camera detection */
  readonly isPerspectiveCamera: true;
  
  /** Vertical field of view in degrees */
  fov: number;
  
  /** Zoom factor for scaling projection */
  zoom: number;
  
  /** Near clipping plane distance */
  near: number;
  
  /** Far clipping plane distance */
  far: number;
  
  /** Focus distance for stereoscopy and DOF */
  focus: number;
  
  /** Aspect ratio (width/height) */
  aspect: number;
  
  /** View offset for multi-view rendering */
  view: {
    enabled: boolean;
    fullWidth: number;
    fullHeight: number;
    offsetX: number;
    offsetY: number;
    width: number;
    height: number;
  } | null;
  
  /** Film gauge in millimeters (larger axis) */
  filmGauge: number;
  
  /** Film offset for asymmetric frustum */
  filmOffset: number;
  
  /**
   * Create perspective camera
   * @param fov - Vertical field of view in degrees (default: 50)
   * @param aspect - Aspect ratio width/height (default: 1)
   * @param near - Near clipping plane (default: 0.1)
   * @param far - Far clipping plane (default: 2000)
   */
  constructor(fov?: number, aspect?: number, near?: number, far?: number);
  
  /**
   * Update projection matrix from camera parameters
   */
  updateProjectionMatrix(): void;
  
  /**
   * Set view offset for multi-view rendering
   * @param fullWidth - Full framebuffer width
   * @param fullHeight - Full framebuffer height
   * @param x - Horizontal offset of subcamera
   * @param y - Vertical offset of subcamera
   * @param width - Width of subcamera
   * @param height - Height of subcamera
   */
  setViewOffset(
    fullWidth: number, 
    fullHeight: number, 
    x: number, 
    y: number, 
    width: number, 
    height: number
  ): void;
  
  /**
   * Remove view offset
   */
  clearViewOffset(): void;
  
  /**
   * Get effective vertical field of view accounting for zoom
   * @returns Effective FOV in degrees
   */
  getEffectiveFOV(): number;
  
  /**
   * Get film width based on aspect ratio and film gauge
   * @returns Film width in millimeters
   */
  getFilmWidth(): number;
  
  /**
   * Get film height based on aspect ratio and film gauge
   * @returns Film height in millimeters
   */
  getFilmHeight(): number;
  
  /**
   * Set focal length from film gauge and current FOV
   * @param focalLength - Focal length in millimeters
   */
  setFocalLength(focalLength: number): void;
  
  /**
   * Get focal length from film gauge and current FOV
   * @returns Focal length in millimeters
   */
  getFocalLength(): number;
  
  /**
   * Get view bounds at given Z distance
   * @param distance - Z distance from camera
   * @param minTarget - Target vector for minimum bounds
   * @param maxTarget - Target vector for maximum bounds
   */
  getViewBounds(distance: number, minTarget: Vector2, maxTarget: Vector2): void;
  
  /**
   * Get view size at given Z distance
   * @param distance - Z distance from camera
   * @param target - Target vector to store size
   * @returns View size at distance
   */
  getViewSize(distance: number, target: Vector2): Vector2;
  
  /**
   * Copy properties from another perspective camera
   * @param source - Source camera
   * @param recursive - Copy children recursively
   * @returns This camera for chaining
   */
  copy(source: PerspectiveCamera, recursive?: boolean): this;
  
  /**
   * Serialize camera to JSON
   * @param meta - Metadata object
   * @returns JSON representation
   */
  toJSON(meta?: any): any;
}

Usage Examples:

import { PerspectiveCamera, Vector2 } from 'three';

// Create standard perspective camera
const camera = new PerspectiveCamera(
  75,                    // FOV
  window.innerWidth / window.innerHeight, // Aspect
  0.1,                   // Near
  1000                   // Far
);

// Position camera
camera.position.z = 5;

// Adjust parameters
camera.fov = 60;
camera.zoom = 1.5;
camera.updateProjectionMatrix(); // Apply changes

// Multi-view rendering (split screen)
camera.setViewOffset(
  1920, 1080,  // Full resolution
  0, 0,        // Offset for left eye
  960, 1080    // Half width
);

// Camera calculations
const effectiveFOV = camera.getEffectiveFOV();
const focalLength = camera.getFocalLength();

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

// Handle resize
function onWindowResize() {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
}

Orthographic Camera

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

import { OrthographicCamera, Camera } from 'three';

/**
 * Camera with orthographic projection (no perspective distortion)
 */
class OrthographicCamera extends Camera {
  /** Type flag for orthographic camera detection */
  readonly isOrthographicCamera: true;
  
  /** Zoom factor for scaling projection */
  zoom: number;
  
  /** View offset for multi-view rendering */
  view: {
    enabled: boolean;
    fullWidth: number;
    fullHeight: number;
    offsetX: number;
    offsetY: number;
    width: number;
    height: number;
  } | null;
  
  /** Left frustum plane */
  left: number;
  
  /** Right frustum plane */
  right: number;
  
  /** Top frustum plane */
  top: number;
  
  /** Bottom frustum plane */
  bottom: number;
  
  /** Near clipping plane distance */
  near: number;
  
  /** Far clipping plane distance */
  far: number;
  
  /**
   * Create orthographic camera
   * @param left - Left frustum plane (default: -1)
   * @param right - Right frustum plane (default: 1)
   * @param top - Top frustum plane (default: 1)
   * @param bottom - Bottom frustum plane (default: -1)
   * @param near - Near clipping plane (default: 0.1)
   * @param far - Far clipping plane (default: 2000)
   */
  constructor(
    left?: number, 
    right?: number, 
    top?: number, 
    bottom?: number, 
    near?: number, 
    far?: number
  );
  
  /**
   * Update projection matrix from camera parameters
   */
  updateProjectionMatrix(): void;
  
  /**
   * Set view offset for multi-view rendering
   * @param fullWidth - Full framebuffer width
   * @param fullHeight - Full framebuffer height
   * @param x - Horizontal offset of subcamera
   * @param y - Vertical offset of subcamera
   * @param width - Width of subcamera
   * @param height - Height of subcamera
   */
  setViewOffset(
    fullWidth: number, 
    fullHeight: number, 
    x: number, 
    y: number, 
    width: number, 
    height: number
  ): void;
  
  /**
   * Remove view offset
   */
  clearViewOffset(): void;
  
  /**
   * Copy properties from another orthographic camera
   * @param source - Source camera
   * @param recursive - Copy children recursively
   * @returns This camera for chaining
   */
  copy(source: OrthographicCamera, recursive?: boolean): this;
  
  /**
   * Serialize camera to JSON
   * @param meta - Metadata object
   * @returns JSON representation
   */
  toJSON(meta?: any): any;
}

Usage Examples:

import { OrthographicCamera } from 'three';

// Create orthographic camera for 2D scene
const camera = new OrthographicCamera(
  -window.innerWidth / 2,   // left
  window.innerWidth / 2,    // right  
  window.innerHeight / 2,   // top
  -window.innerHeight / 2,  // bottom
  1,                        // near
  1000                      // far
);

// Position camera
camera.position.z = 10;

// Zoom functionality
camera.zoom = 2; // 2x zoom
camera.updateProjectionMatrix();

// UI camera setup (pixel-perfect)
const uiCamera = new OrthographicCamera(
  0,                    // left (screen left)
  window.innerWidth,    // right (screen right)
  0,                    // top (screen top) 
  window.innerHeight,   // bottom (screen bottom)
  -1,                   // near
  1                     // far
);

// Handle resize for orthographic camera
function onWindowResize() {
  const aspect = window.innerWidth / window.innerHeight;
  const frustumHeight = 10;
  const frustumWidth = frustumHeight * aspect;
  
  camera.left = -frustumWidth / 2;
  camera.right = frustumWidth / 2;
  camera.top = frustumHeight / 2;
  camera.bottom = -frustumHeight / 2;
  camera.updateProjectionMatrix();
}

// Top-down view setup
const topDownCamera = new OrthographicCamera(-50, 50, 50, -50, 0.1, 100);
topDownCamera.position.set(0, 50, 0);
topDownCamera.lookAt(0, 0, 0);

Specialized Cameras

Additional camera types for specific use cases.

import { 
  ArrayCamera, 
  CubeCamera, 
  StereoCamera,
  Camera,
  PerspectiveCamera,
  Scene,
  WebGLCubeRenderTarget
} from 'three';

/**
 * Array of cameras for VR and multi-view rendering
 */
class ArrayCamera extends PerspectiveCamera {
  /** Type flag for array camera detection */
  readonly isArrayCamera: true;
  
  /** Array of cameras */
  cameras: PerspectiveCamera[];
  
  /**
   * Create array camera
   * @param cameras - Array of perspective cameras
   */
  constructor(cameras?: PerspectiveCamera[]);
}

/**
 * Camera for cube map generation
 */
class CubeCamera extends Object3D {
  /** Type flag for cube camera detection */
  readonly isCubeCamera: true;
  
  /** Render target for cube map */
  renderTarget: WebGLCubeRenderTarget;
  
  /** Coordinate system */
  coordinateSystem: number;
  
  /**
   * Create cube camera
   * @param near - Near clipping plane
   * @param far - Far clipping plane
   * @param renderTarget - Cube render target
   */
  constructor(near: number, far: number, renderTarget: WebGLCubeRenderTarget);
  
  /**
   * Update cube map from position
   * @param renderer - WebGL renderer
   * @param scene - Scene to render
   */
  update(renderer: any, scene: Scene): void;
}

/**
 * Stereo camera pair for VR rendering
 */
class StereoCamera extends Camera {
  /** Type flag for stereo camera detection */
  readonly isStereoCamera: true;
  
  /** Camera aspect ratio */
  aspect: number;
  
  /** Eye separation distance */
  eyeSep: number;
  
  /** Left eye camera */
  cameraL: PerspectiveCamera;
  
  /** Right eye camera */
  cameraR: PerspectiveCamera;
  
  /**
   * Create stereo camera
   */
  constructor();
  
  /**
   * Update stereo cameras
   * @param camera - Base camera to derive from
   */
  update(camera: PerspectiveCamera): void;
}

Usage Examples:

import { ArrayCamera, PerspectiveCamera, StereoCamera, CubeCamera, WebGLCubeRenderTarget } from 'three';

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

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

// Render each eye
renderer.setViewport(0, 0, width/2, height);
renderer.render(scene, stereoCamera.cameraL);
renderer.setViewport(width/2, 0, width/2, height);
renderer.render(scene, stereoCamera.cameraR);

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

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

// Use generated cube map
reflectiveObject.material.envMap = cubeRenderTarget.texture;

Camera Utilities and Helpers

import { CameraHelper, Camera, LineSegments } from 'three';

/**
 * Helper for visualizing camera frustum
 */
class CameraHelper extends LineSegments {
  /** Camera being visualized */
  camera: Camera;
  
  /** Helper geometry points */
  pointMap: Record<string, number[]>;
  
  /**
   * Create camera helper
   * @param camera - Camera to visualize
   */
  constructor(camera: Camera);
  
  /**
   * Update helper geometry
   */
  update(): void;
  
  /**
   * Dispose of helper resources
   */
  dispose(): void;
}

Usage Examples:

import { CameraHelper } from 'three';

// Visualize camera frustum
const helper = new CameraHelper(camera);
scene.add(helper);

// Update when camera changes
camera.updateProjectionMatrix();
helper.update();

Camera Control Patterns

Basic Camera Setup

// Standard perspective camera setup
function createPerspectiveCamera(aspect: number): PerspectiveCamera {
  const camera = new PerspectiveCamera(75, aspect, 0.1, 1000);
  camera.position.set(0, 0, 5);
  return camera;
}

// Orthographic camera for UI
function createUICamera(width: number, height: number): OrthographicCamera {
  const camera = new OrthographicCamera(0, width, 0, height, -1, 1);
  camera.position.z = 1;
  return camera;
}

Responsive Camera Management

function handleResize(
  camera: PerspectiveCamera | OrthographicCamera,
  width: number,
  height: number
): void {
  if (camera.isPerspectiveCamera) {
    camera.aspect = width / height;
    camera.updateProjectionMatrix();
  } else if (camera.isOrthographicCamera) {
    const aspect = width / height;
    const frustumHeight = 10;
    const frustumWidth = frustumHeight * aspect;
    
    camera.left = -frustumWidth / 2;
    camera.right = frustumWidth / 2;
    camera.top = frustumHeight / 2;
    camera.bottom = -frustumHeight / 2;
    camera.updateProjectionMatrix();
  }
}

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.

Install with Tessl CLI