tessl/npm-three

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

—

Pending

Overview

Eval results

Files

Lights

Name: tessl/npm-three
Author: tessl

Lighting system providing illumination for 3D scenes through various light types, shadow casting, and physically-based lighting calculations. Lights determine how materials appear under different illumination conditions.

Capabilities

Light Base Class

Abstract foundation for all light types providing common color, intensity, and transformation properties.

import { Light, Object3D, Color, LightShadow } from 'three';

/**
 * Abstract base class for all light types
 */
abstract class Light extends Object3D {
  /** Type flag for light detection */
  readonly isLight: true;
  
  /** Light color */
  color: Color;
  
  /** Light intensity */
  intensity: number;
  
  /** Shadow configuration (if supported) */
  shadow?: LightShadow;
  
  /**
   * Create base light
   * @param color - Light color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   */
  constructor(color?: Color | string | number, intensity?: number);
  
  /**
   * Dispose light resources
   */
  dispose(): void;
  
  /**
   * Copy properties from another light
   * @param source - Source light
   * @param recursive - Copy children recursively
   * @returns This light for chaining
   */
  copy(source: Light, recursive?: boolean): this;
  
  /**
   * Serialize to JSON
   * @param meta - Metadata object
   * @returns JSON representation
   */
  toJSON(meta?: any): any;
}

Usage Examples:

import { Light, Color } from 'three';

// Basic light properties (available on all lights)
light.color = new Color(0xff0000);
light.intensity = 2.0;
light.position.set(10, 10, 10);

// Enable shadows (if supported)
if (light.shadow) {
  light.castShadow = true;
  light.shadow.mapSize.width = 2048;
  light.shadow.mapSize.height = 2048;
}

// Dispose when no longer needed
light.dispose();

Directional Light

Parallel light rays simulating distant sources like the sun, with configurable target and shadow mapping.

import { DirectionalLight, Light, Object3D, DirectionalLightShadow } from 'three';

/**
 * Directional light with parallel rays (sun-like illumination)
 */
class DirectionalLight extends Light {
  /** Type flag for directional light detection */
  readonly isDirectionalLight: true;
  
  /** Light target object (determines direction) */
  target: Object3D;
  
  /** Shadow configuration */
  shadow: DirectionalLightShadow;
  
  /**
   * Create directional light
   * @param color - Light color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   */
  constructor(color?: Color | string | number, intensity?: number);
  
  /**
   * Dispose directional light resources
   */
  dispose(): void;
  
  /**
   * Copy from another directional light
   * @param source - Source light
   * @param recursive - Copy children recursively
   * @returns This light for chaining
   */
  copy(source: DirectionalLight, recursive?: boolean): this;
}

/**
 * Shadow configuration for directional lights
 */
class DirectionalLightShadow extends LightShadow {
  /** Type flag for directional shadow detection */
  readonly isDirectionalLightShadow: true;
  
  /** Shadow camera (orthographic) */
  camera: OrthographicCamera;
  
  /**
   * Create directional light shadow
   */
  constructor();
}

Usage Examples:

import { DirectionalLight, Object3D } from 'three';

// Create sun-like directional light
const sunlight = new DirectionalLight(0xffffff, 1);
sunlight.position.set(10, 10, 5);
sunlight.castShadow = true;

// Configure target (light direction)
const target = new Object3D();
target.position.set(0, 0, 0);
scene.add(target);
sunlight.target = target;

// Configure shadows
sunlight.shadow.mapSize.width = 2048;
sunlight.shadow.mapSize.height = 2048;
sunlight.shadow.camera.near = 0.5;
sunlight.shadow.camera.far = 50;

// Set shadow camera frustum
sunlight.shadow.camera.left = -10;
sunlight.shadow.camera.right = 10;
sunlight.shadow.camera.top = 10;
sunlight.shadow.camera.bottom = -10;

scene.add(sunlight);

// Helper for visualizing light direction
const helper = new DirectionalLightHelper(sunlight, 5);
scene.add(helper);

Point Light

Omnidirectional light emitting from a single point with distance-based attenuation and cube shadow mapping.

import { PointLight, Light, PointLightShadow } from 'three';

/**
 * Point light emitting in all directions (bulb-like illumination)
 */
class PointLight extends Light {
  /** Type flag for point light detection */
  readonly isPointLight: true;
  
  /** Maximum light distance (0 = infinite) */
  distance: number;
  
  /** Light decay rate */
  decay: number;
  
  /** Shadow configuration */
  shadow: PointLightShadow;
  
  /** Power in lumens (WebGPURenderer only) */
  power: number;
  
  /**
   * Create point light
   * @param color - Light color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   * @param distance - Maximum distance (default: 0)
   * @param decay - Decay rate (default: 2)
   */
  constructor(
    color?: Color | string | number,
    intensity?: number,
    distance?: number,
    decay?: number
  );
  
  /** Get power in lumens */
  readonly power: number;
  
  /** Set power in lumens */
  set power(power: number);
  
  /**
   * Dispose point light resources
   */
  dispose(): void;
  
  /**
   * Copy from another point light
   * @param source - Source light
   * @param recursive - Copy children recursively
   * @returns This light for chaining
   */
  copy(source: PointLight, recursive?: boolean): this;
}

/**
 * Shadow configuration for point lights (cube shadow mapping)
 */
class PointLightShadow extends LightShadow {
  /** Type flag for point shadow detection */
  readonly isPointLightShadow: true;
  
  /** Shadow camera (perspective) */
  camera: PerspectiveCamera;
  
  /**
   * Create point light shadow
   */
  constructor();
  
  /**
   * Update shadow matrices for cube faces
   * @param light - Point light casting shadow
   * @param viewportIndex - Cube face index
   */
  updateMatrices(light: Light, viewportIndex?: number): void;
}

Usage Examples:

import { PointLight } from 'three';

// Create light bulb
const bulb = new PointLight(0xffaa00, 1, 100);
bulb.position.set(0, 10, 0);
bulb.castShadow = true;

// Configure attenuation
bulb.distance = 50; // Light reaches 50 units
bulb.decay = 1;     // Linear decay

// Configure shadows (cube mapping)
bulb.shadow.mapSize.width = 512;
bulb.shadow.mapSize.height = 512;
bulb.shadow.camera.near = 0.5;
bulb.shadow.camera.far = 50;

scene.add(bulb);

// Power-based intensity (physically correct)
bulb.power = 4 * Math.PI * 100; // 100 cd * 4π sr

// Helper for visualization
const helper = new PointLightHelper(bulb, 1);
scene.add(helper);

Spot Light

Cone-shaped light with configurable angle, penumbra, and target-based direction control.

import { SpotLight, Light, Object3D, SpotLightShadow, Texture } from 'three';

/**
 * Spot light emitting in a cone (flashlight-like illumination)
 */
class SpotLight extends Light {
  /** Type flag for spot light detection */
  readonly isSpotLight: true;
  
  /** Light target object (determines direction) */
  target: Object3D;
  
  /** Maximum light distance (0 = infinite) */
  distance: number;
  
  /** Cone angle in radians */
  angle: number;
  
  /** Penumbra soft edge (0-1) */
  penumbra: number;
  
  /** Light decay rate */
  decay: number;
  
  /** Light texture/cookie */
  map: Texture | null;
  
  /** Shadow configuration */
  shadow: SpotLightShadow;
  
  /** Power in lumens (WebGPURenderer only) */
  power: number;
  
  /**
   * Create spot light
   * @param color - Light color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   * @param distance - Maximum distance (default: 0)
   * @param angle - Cone angle (default: Math.PI/3)
   * @param penumbra - Penumbra softness (default: 0)
   * @param decay - Decay rate (default: 2)
   */
  constructor(
    color?: Color | string | number,
    intensity?: number,
    distance?: number,
    angle?: number,
    penumbra?: number,
    decay?: number
  );
  
  /** Get power in lumens */
  readonly power: number;
  
  /** Set power in lumens */
  set power(power: number);
  
  /**
   * Dispose spot light resources
   */
  dispose(): void;
  
  /**
   * Copy from another spot light
   * @param source - Source light
   * @param recursive - Copy children recursively
   * @returns This light for chaining
   */
  copy(source: SpotLight, recursive?: boolean): this;
}

/**
 * Shadow configuration for spot lights
 */
class SpotLightShadow extends LightShadow {
  /** Type flag for spot shadow detection */
  readonly isSpotLightShadow: true;
  
  /** Shadow camera (perspective) */
  camera: PerspectiveCamera;
  
  /** Focus for shadow camera */
  focus: number;
  
  /**
   * Create spot light shadow
   */
  constructor();
  
  /**
   * Update shadow matrices
   * @param light - Spot light casting shadow
   */
  updateMatrices(light: Light): void;
}

Usage Examples:

import { SpotLight, Object3D, TextureLoader } from 'three';

// Create flashlight/headlight
const spotlight = new SpotLight(0xffffff, 1);
spotlight.position.set(10, 10, 5);
spotlight.angle = Math.PI / 6;     // 30 degree cone
spotlight.penumbra = 0.2;          // Soft edges
spotlight.decay = 2;               // Physical decay
spotlight.distance = 100;

// Set target
const target = new Object3D();
target.position.set(0, 0, 0);
scene.add(target);
spotlight.target = target;

// Add texture projection (cookie/gobo)
const loader = new TextureLoader();
const lightTexture = loader.load('textures/spotlight-pattern.jpg');
spotlight.map = lightTexture;

// Configure shadows
spotlight.castShadow = true;
spotlight.shadow.mapSize.width = 1024;
spotlight.shadow.mapSize.height = 1024;
spotlight.shadow.camera.near = 0.5;
spotlight.shadow.camera.far = 50;
spotlight.shadow.camera.fov = 30;

scene.add(spotlight);

// Helper for visualization
const helper = new SpotLightHelper(spotlight);
scene.add(helper);

Ambient and Hemisphere Light

Global illumination providing base lighting without directional characteristics.

import { AmbientLight, HemisphereLight, Light, Color } from 'three';

/**
 * Ambient light providing uniform illumination from all directions
 */
class AmbientLight extends Light {
  /** Type flag for ambient light detection */
  readonly isAmbientLight: true;
  
  /**
   * Create ambient light
   * @param color - Light color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   */
  constructor(color?: Color | string | number, intensity?: number);
  
  /**
   * Copy from another ambient light
   * @param source - Source light
   * @returns This light for chaining
   */
  copy(source: AmbientLight): this;
}

/**
 * Hemisphere light with sky and ground colors
 */
class HemisphereLight extends Light {
  /** Type flag for hemisphere light detection */
  readonly isHemisphereLight: true;
  
  /** Ground color (bottom hemisphere) */
  groundColor: Color;
  
  /**
   * Create hemisphere light
   * @param skyColor - Sky color (default: 0xffffff)
   * @param groundColor - Ground color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   */
  constructor(
    skyColor?: Color | string | number,
    groundColor?: Color | string | number,
    intensity?: number
  );
  
  /**
   * Copy from another hemisphere light
   * @param source - Source light
   * @param recursive - Copy children recursively
   * @returns This light for chaining
   */
  copy(source: HemisphereLight, recursive?: boolean): this;
}

Usage Examples:

import { AmbientLight, HemisphereLight, Color } from 'three';

// Basic ambient lighting
const ambient = new AmbientLight(0x404040, 0.4); // Dim white
scene.add(ambient);

// Natural hemisphere lighting
const hemisphere = new HemisphereLight(
  0x87CEEB, // Sky blue
  0x8B4513, // Ground brown
  0.6
);
hemisphere.position.set(0, 50, 0);
scene.add(hemisphere);

// Colored ambient for mood
const coloredAmbient = new AmbientLight(0x330066, 0.2); // Purple tint
scene.add(coloredAmbient);

Area and Probe Lights

Advanced lighting for realistic illumination and image-based lighting.

import { 
  RectAreaLight, 
  LightProbe, 
  Light, 
  SphericalHarmonics3 
} from 'three';

/**
 * Rectangular area light for realistic lighting
 */
class RectAreaLight extends Light {
  /** Type flag for area light detection */
  readonly isRectAreaLight: true;
  
  /** Light width */
  width: number;
  
  /** Light height */
  height: number;
  
  /**
   * Create rectangular area light
   * @param color - Light color (default: 0xffffff)
   * @param intensity - Light intensity (default: 1)
   * @param width - Light width (default: 10)
   * @param height - Light height (default: 10)
   */
  constructor(
    color?: Color | string | number,
    intensity?: number,
    width?: number,
    height?: number
  );
  
  /** Get power in lumens */
  readonly power: number;
  
  /** Set power in lumens */
  set power(power: number);
  
  /**
   * Copy from another area light
   * @param source - Source light
   * @param recursive - Copy children recursively
   * @returns This light for chaining
   */
  copy(source: RectAreaLight, recursive?: boolean): this;
}

/**
 * Light probe for image-based lighting
 */
class LightProbe extends Light {
  /** Type flag for light probe detection */
  readonly isLightProbe: true;
  
  /** Spherical harmonics coefficients */
  sh: SphericalHarmonics3;
  
  /**
   * Create light probe
   * @param sh - Spherical harmonics (optional)
   * @param intensity - Light intensity (default: 1)
   */
  constructor(sh?: SphericalHarmonics3, intensity?: number);
  
  /**
   * Copy from another light probe
   * @param source - Source light probe
   * @returns This light for chaining
   */
  copy(source: LightProbe): this;
  
  /**
   * Initialize from cube texture
   * @param cubeTexture - Environment cube texture
   * @param size - Sample size
   * @returns This light probe for chaining
   */
  fromJSON(json: any): this;
}

Usage Examples:

import { RectAreaLight, LightProbe, CubeTextureLoader } from 'three';

// Rectangular area light (like LED panel)
const areaLight = new RectAreaLight(0xffffff, 5, 4, 4);
areaLight.position.set(0, 10, 0);
areaLight.lookAt(0, 0, 0);
scene.add(areaLight);

// Requires RectAreaLightUniformsLib
import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
RectAreaLightUniformsLib.init();

// Image-based lighting with probe
const loader = new CubeTextureLoader();
const cubeTexture = loader.load([
  'px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg'
]);

const lightProbe = new LightProbe();
// Use LightProbeGenerator to create from cube texture
// lightProbe.copy(LightProbeGenerator.fromCubeTexture(cubeTexture));
scene.add(lightProbe);

Shadow System

Shadow casting and receiving configuration for realistic depth and occlusion effects.

import { 
  LightShadow,
  DirectionalLightShadow,
  PointLightShadow,
  SpotLightShadow,
  Camera,
  WebGLRenderTarget,
  Vector2,
  Vector4,
  Matrix4
} from 'three';

/**
 * Base shadow configuration class
 */
abstract class LightShadow {
  /** Shadow camera for rendering */
  camera: Camera;
  
  /** Shadow map render target */
  map: WebGLRenderTarget | null;
  
  /** Shadow map size */
  mapSize: Vector2;
  
  /** Shadow camera matrices */
  matrix: Matrix4;
  
  /** Auto-update shadow */
  autoUpdate: boolean;
  
  /** Needs shadow update */
  needsUpdate: boolean;
  
  /** Shadow bias to prevent acne */
  bias: number;
  
  /** Normal bias */
  normalBias: number;
  
  /** Shadow map radius for soft shadows */
  radius: number;
  
  /** Blur samples for soft shadows */
  blurSamples: number;
  
  /**
   * Get shadow viewport
   * @returns Shadow viewport
   */
  getViewport(viewportIndex: number): Vector4;
  
  /**
   * Get viewport count
   * @returns Number of viewports
   */
  getViewportCount(): number;
  
  /**
   * Update shadow matrices
   * @param light - Light casting shadow
   */
  updateMatrices(light: Light): void;
  
  /**
   * Get shadow frame extents
   * @returns Frame extents
   */
  getFrameExtents(): Vector2;
  
  /**
   * Dispose shadow resources
   */
  dispose(): void;
  
  /**
   * Copy from another shadow
   * @param source - Source shadow
   * @returns This shadow for chaining
   */
  copy(source: LightShadow): this;
  
  /**
   * Clone shadow
   * @returns Cloned shadow
   */
  clone(): this;
  
  /**
   * Serialize to JSON
   * @returns JSON representation
   */
  toJSON(): any;
}

Usage Examples:

import { DirectionalLight, PCFSoftShadowMap } from 'three';

// Configure renderer for shadows
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = PCFSoftShadowMap;

// Setup directional light with shadows
const dirLight = new DirectionalLight(0xffffff, 1);
dirLight.position.set(10, 10, 5);
dirLight.castShadow = true;

// Configure shadow quality
dirLight.shadow.mapSize.width = 2048;
dirLight.shadow.mapSize.height = 2048;

// Reduce shadow acne
dirLight.shadow.bias = -0.001;
dirLight.shadow.normalBias = 0.02;

// Configure shadow camera
dirLight.shadow.camera.near = 0.1;
dirLight.shadow.camera.far = 50;
dirLight.shadow.camera.left = -10;
dirLight.shadow.camera.right = 10;
dirLight.shadow.camera.top = 10;
dirLight.shadow.camera.bottom = -10;

// Soft shadows
dirLight.shadow.radius = 4;
dirLight.shadow.blurSamples = 25;

scene.add(dirLight);

// Enable shadows on objects
mesh.castShadow = true;
plane.receiveShadow = true;

Advanced Lighting (WebGPU)

Extended lighting features available in WebGPU renderer for enhanced realism.

import { 
  IESSpotLight, 
  ProjectorLight,
  SpotLight,
  DirectionalLight,
  Texture
} from 'three/webgpu';

/**
 * IES profile spotlight for realistic architectural lighting
 */
class IESSpotLight extends SpotLight {
  /** Type flag for IES light detection */
  readonly isIESSpotLight: true;
  
  /** IES profile texture */
  iesMap: Texture | null;
  
  /**
   * Create IES spotlight
   * @param color - Light color
   * @param intensity - Light intensity
   * @param distance - Maximum distance
   * @param angle - Cone angle
   * @param penumbra - Penumbra softness
   * @param decay - Decay rate
   */
  constructor(
    color?: Color | string | number,
    intensity?: number,
    distance?: number,
    angle?: number,
    penumbra?: number,
    decay?: number
  );
}

/**
 * Projector light for texture projection
 */
class ProjectorLight extends DirectionalLight {
  /** Type flag for projector light detection */
  readonly isProjectorLight: true;
  
  /** Projection texture */
  map: Texture | null;
  
  /** Projection matrix */
  projectionMatrix: Matrix4;
  
  /** Projection near plane */
  near: number;
  
  /** Projection far plane */
  far: number;
  
  /** Projection field of view */
  fov: number;
  
  /**
   * Create projector light
   * @param color - Light color
   * @param intensity - Light intensity
   */
  constructor(color?: Color | string | number, intensity?: number);
  
  /**
   * Update projection matrix
   */
  updateProjectionMatrix(): void;
}

Usage Examples:

import { IESSpotLight, ProjectorLight, TextureLoader } from 'three/webgpu';

// IES profile lighting for architecture
const iesLight = new IESSpotLight(0xffffff, 100);
iesLight.position.set(0, 5, 0);

const iesTexture = new TextureLoader().load('lighting/profile.ies');
iesLight.iesMap = iesTexture;

scene.add(iesLight);

// Projector light for texture projection
const projector = new ProjectorLight(0xffffff, 2);
projector.position.set(10, 10, 10);
projector.lookAt(0, 0, 0);

const slideTexture = new TextureLoader().load('textures/slide.jpg');
projector.map = slideTexture;
projector.fov = 45;
projector.near = 1;
projector.far = 20;

scene.add(projector);

Light Helper Visualization

import { 
  DirectionalLightHelper,
  PointLightHelper,
  SpotLightHelper,
  HemisphereLightHelper,
  RectAreaLightHelper
} from 'three';

// Visualize lights in scene
const dirHelper = new DirectionalLightHelper(directionalLight, 5);
const pointHelper = new PointLightHelper(pointLight, 1);
const spotHelper = new SpotLightHelper(spotLight);
const hemiHelper = new HemisphereLightHelper(hemisphereLight, 5);

scene.add(dirHelper);
scene.add(pointHelper);
scene.add(spotHelper);
scene.add(hemiHelper);

// Update helpers when lights change
spotHelper.update();

The lighting system provides comprehensive illumination control through physically-based light types, advanced shadow mapping, and specialized effects for realistic 3D rendering. Proper lighting setup is crucial for material appearance and scene atmosphere.

Install with Tessl CLI