tessl/npm-deck-gl

A suite of 3D-enabled data visualization overlays, suitable for react-map-gl

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Effects and Lighting

Name: tessl/npm-deck-gl
Author: tessl

Visual enhancement system including lighting models, shadows, and post-processing effects for creating realistic and visually appealing 3D visualizations.

Capabilities

Effect Base Class

Abstract base class for all visual effects in deck.gl.

/**
 * Base class for all visual effects
 * Handles pre-render and post-render processing
 */
abstract class Effect {
  constructor(props?: any);
  /** Called before layer rendering */
  preRender(gl: WebGLRenderingContext, params: PreRenderOptions): void;
  /** Called after layer rendering */
  postRender(gl: WebGLRenderingContext, params: PostRenderOptions): void;
  /** Clean up effect resources */
  cleanup(): void;
}

interface PreRenderOptions {
  /** Render layers pass */
  layersPass: any;
  /** View manager */
  viewManager: any;
  /** Effect manager */
  effectManager: any;
}

interface PostRenderOptions {
  /** Render layers pass */
  layersPass: any;
  /** View manager */
  viewManager: any;
  /** Effect manager */
  effectManager: any;
}

LightingEffect

Comprehensive lighting system supporting multiple light types and realistic shading.

/**
 * Lighting effect providing realistic shading and illumination
 * Supports ambient, directional, and point lights
 */
class LightingEffect extends Effect {
  constructor(props?: LightingEffectProps);
  /** Add a light to the effect */
  addLight(light: AmbientLight | DirectionalLight | PointLight): void;
  /** Remove a light from the effect */
  removeLight(light: AmbientLight | DirectionalLight | PointLight): void;
  /** Get all lights */
  getLights(): (AmbientLight | DirectionalLight | PointLight)[];
}

interface LightingEffectProps {
  /** Array of light instances */
  lights?: (AmbientLight | DirectionalLight | PointLight)[];
  /** Enable shadows */
  shadowColor?: Color;
}

Usage Example:

import { Deck, LightingEffect, AmbientLight, DirectionalLight, PointLight } from "deck.gl";

const lightingEffect = new LightingEffect({
  lights: [
    new AmbientLight({
      color: [255, 255, 255],
      intensity: 0.3
    }),
    new DirectionalLight({
      color: [255, 255, 255],
      intensity: 0.8,
      direction: [-1, -1, -1]
    }),
    new PointLight({
      color: [255, 255, 255],
      intensity: 1.0,
      position: [0, 0, 100]
    })
  ]
});

const deck = new Deck({
  effects: [lightingEffect],
  // ... other props
});

Light Types

AmbientLight

Provides uniform illumination from all directions.

/**
 * Ambient light providing uniform illumination
 * Simulates light scattered by the atmosphere
 */
class AmbientLight {
  constructor(props?: AmbientLightOptions);
}

interface AmbientLightOptions {
  /** Light color */
  color?: Color;
  /** Light intensity (0-1) */
  intensity?: number;
}

DirectionalLight

Provides parallel light rays from a specific direction, like sunlight.

/**
 * Directional light providing parallel rays
 * Simulates distant light sources like the sun
 */
class DirectionalLight {
  constructor(props?: DirectionalLightOptions);
}

interface DirectionalLightOptions {
  /** Light color */
  color?: Color;
  /** Light intensity (0-1) */
  intensity?: number;
  /** Light direction vector */
  direction?: [number, number, number];
  /** Enable shadow casting */
  _shadow?: boolean;
}

PointLight

Provides omnidirectional light from a specific position.

/**
 * Point light radiating in all directions
 * Simulates light bulbs or other point sources
 */
class PointLight {
  constructor(props?: PointLightOptions);
}

interface PointLightOptions {
  /** Light color */
  color?: Color;
  /** Light intensity */
  intensity?: number;
  /** Light position in world coordinates */
  position?: [number, number, number];
  /** Light attenuation factor */
  attenuation?: number;
}

Specialized Lights

/**
 * Camera-attached light (experimental)
 * Moves with the camera for consistent illumination
 */
class _CameraLight {
  constructor(props?: CameraLightOptions);
}

/**
 * Sun light with time-based positioning (experimental)
 * Automatically calculates sun position based on time and location
 */
class _SunLight {
  constructor(props?: SunLightOptions);
}

interface CameraLightOptions {
  color?: Color;
  intensity?: number;
}

interface SunLightOptions {
  /** Timestamp for sun calculation */
  timestamp: number;
  /** Latitude for sun calculation */
  latitude: number;
  /** Longitude for sun calculation */
  longitude: number;
  color?: Color;
  intensity?: number;
}

PostProcessEffect

Base class for screen-space post-processing effects.

/**
 * Base class for post-processing effects
 * Applies screen-space effects after layer rendering
 */
class PostProcessEffect extends Effect {
  constructor(props?: PostProcessEffectProps);
}

interface PostProcessEffectProps {
  /** Custom shader modules */
  modules?: any[];
  /** Effect parameters */
  parameters?: {[key: string]: any};
}

Material System

Material properties for controlling how surfaces interact with light.

interface Material {
  /** Ambient reflection coefficient */
  ambient?: number;
  /** Diffuse reflection coefficient */
  diffuse?: number;
  /** Specular shininess exponent */
  shininess?: number;
  /** Specular reflection color */
  specularColor?: Color;
}

Usage Example:

import { PolygonLayer } from "deck.gl";

const layer = new PolygonLayer({
  id: 'buildings',
  data: buildingData,
  extruded: true,
  getElevation: d => d.height,
  getFillColor: [255, 255, 255],
  material: {
    ambient: 0.2,
    diffuse: 0.6,
    shininess: 32,
    specularColor: [255, 255, 255]
  }
});

Advanced Lighting Examples

Realistic Building Visualization

import { 
  Deck, 
  PolygonLayer, 
  LightingEffect, 
  AmbientLight, 
  DirectionalLight,
  _SunLight 
} from "deck.gl";

// Create realistic lighting for architectural visualization
const lightingEffect = new LightingEffect({
  lights: [
    // Ambient light for general illumination
    new AmbientLight({
      color: [64, 128, 255], // Slightly blue for sky color
      intensity: 0.2
    }),
    // Main sun light
    new DirectionalLight({
      color: [255, 255, 255],
      intensity: 1.0,
      direction: [-1, -1, -0.5], // From top-left
      _shadow: true
    }),
    // Fill light from opposite direction
    new DirectionalLight({
      color: [255, 255, 255],
      intensity: 0.3,
      direction: [1, 1, -0.5]
    })
  ]
});

const buildingLayer = new PolygonLayer({
  id: 'buildings',
  data: buildingData,
  extruded: true,
  getPolygon: d => d.polygon,
  getElevation: d => d.height,
  getFillColor: d => d.color,
  material: {
    ambient: 0.15,
    diffuse: 0.7,
    shininess: 16,
    specularColor: [255, 255, 255]
  }
});

Dynamic Time-Based Lighting

import { _SunLight } from "deck.gl";

function createTimeBasedLighting(timestamp: number, latitude: number, longitude: number) {
  return new LightingEffect({
    lights: [
      new AmbientLight({
        color: [64, 128, 255],
        intensity: 0.15
      }),
      new _SunLight({
        timestamp,
        latitude,
        longitude,
        color: [255, 255, 255],
        intensity: 1.0
      })
    ]
  });
}

// Update lighting based on time
const currentTime = Date.now();
const cityLat = 37.7749;
const cityLng = -122.4194;
const lightingEffect = createTimeBasedLighting(currentTime, cityLat, cityLng);

Multi-Point Lighting Scene

// Create a scene with multiple point lights
const multiPointLighting = new LightingEffect({
  lights: [
    new AmbientLight({
      color: [32, 32, 32],
      intensity: 0.1
    }),
    // Street lamp 1
    new PointLight({
      color: [255, 200, 100], // Warm white
      intensity: 2.0,
      position: [-122.45, 37.75, 20],
      attenuation: 0.01
    }),
    // Street lamp 2
    new PointLight({
      color: [255, 200, 100],
      intensity: 2.0,
      position: [-122.46, 37.76, 20],
      attenuation: 0.01
    }),
    // Building spotlight
    new PointLight({
      color: [100, 200, 255], // Cool white
      intensity: 3.0,
      position: [-122.455, 37.755, 50],
      attenuation: 0.005
    })
  ]
});

Performance Considerations

Light Count Limits

Maximum of 5 directional lights
Maximum of 5 point lights
Unlimited ambient lights (but only the last one is used)

Shadow Performance

Shadow rendering is expensive and should be used sparingly:

// Enable shadows only for key directional lights
new DirectionalLight({
  color: [255, 255, 255],
  intensity: 1.0,
  direction: [-1, -1, -1],
  _shadow: true // Experimental shadow feature
});

Material Optimization

Use appropriate material values for performance:

// Efficient material for large datasets
const efficientMaterial = {
  ambient: 0.2,
  diffuse: 0.8,
  shininess: 4, // Lower values are faster
  specularColor: [255, 255, 255]
};

// High-quality material for hero objects
const qualityMaterial = {
  ambient: 0.1,
  diffuse: 0.6,
  shininess: 64, // Higher values for realistic reflections
  specularColor: [255, 255, 255]
};

Install with Tessl CLI