Flexible view and viewport system supporting multiple projection types including geospatial, orthographic, and 3D perspectives for comprehensive spatial data visualization.
Base class for coordinate system transformations and projection/unprojection between world and screen space.
/**
* Base viewport class managing coordinate transformations
* Handles projection between world coordinates and screen pixels
*/
abstract class Viewport {
/** Initialize viewport with configuration options */
constructor(opts: ViewportOptions);
/** Compare two viewports for equality */
equals(viewport: Viewport): boolean;
/** Project world coordinates to screen space */
project(xyz: [number, number, number], opts?: ProjectOptions): [number, number, number];
/** Unproject screen coordinates to world space */
unproject(xyz: [number, number], opts?: UnprojectOptions): [number, number, number];
/** Get viewport bounds in world coordinates */
getBounds(opts?: BoundsOptions): [[number, number], [number, number]];
/** Check if pixel coordinate is within viewport */
containsPixel(opts: {x: number; y: number; width?: number; height?: number}): boolean;
/** Get distance between two world coordinates */
getDistanceScales(coordinateOrigin?: [number, number, number]): any;
/** Fit viewport to contain given bounds */
fitBounds(bounds: [[number, number], [number, number]], opts?: FitBoundsOptions): ViewportOptions;
/** Viewport dimensions */
readonly width: number;
readonly height: number;
/** Zoom level */
readonly zoom: number;
/** Projection matrix (4x4) */
readonly projectionMatrix: number[];
/** View matrix (4x4) */
readonly viewMatrix: number[];
/** Combined view-projection matrix */
readonly viewProjectionMatrix: number[];
/** Coordinate center in common space */
readonly center: [number, number, number];
/** Scale factor at center */
readonly scale: number;
/** Distance scale factors */
readonly distanceScales: any;
}
interface ViewportOptions {
/** Viewport width in pixels */
width: number;
/** Viewport height in pixels */
height: number;
/** Zoom level */
zoom?: number;
/** Additional viewport-specific options */
[key: string]: any;
}
interface ProjectOptions {
/** Top-left viewport offset */
topLeft?: boolean;
}
interface UnprojectOptions {
/** Top-left viewport offset */
topLeft?: boolean;
/** Target Z coordinate */
targetZ?: number;
}
interface BoundsOptions {
/** Z value for bounds calculation */
z?: number;
}
interface FitBoundsOptions {
/** Padding around bounds */
padding?: number;
/** Viewport offset */
offset?: [number, number];
}Viewport for Web Mercator projection, the standard for web-based geospatial applications.
/**
* Web Mercator projection viewport for geospatial applications
* Standard projection used by most web mapping applications
*/
class WebMercatorViewport extends Viewport {
/** Initialize Web Mercator viewport */
constructor(opts: WebMercatorViewportOptions);
/** Add meter offsets to longitude/latitude coordinates */
addMetersToLngLat(
lngLat: [number, number],
meters: [number, number]
): [number, number];
/** Fit viewport to geographic bounds */
fitBounds(
bounds: [[number, number], [number, number]],
opts?: FitBoundsOptions
): WebMercatorViewportOptions;
/** Pan to place coordinate at specific pixel */
panByPosition(coords: [number, number], pixel: [number, number]): WebMercatorViewportOptions;
/** Get meters per pixel at current zoom */
getMetersPerPixel(latitude?: number): number;
/** Center longitude */
readonly longitude: number;
/** Center latitude */
readonly latitude: number;
/** Camera pitch angle in degrees */
readonly pitch: number;
/** Camera bearing angle in degrees */
readonly bearing: number;
/** Camera altitude for FOV calculation */
readonly altitude: number;
}
interface WebMercatorViewportOptions extends ViewportOptions {
/** Center longitude in degrees */
longitude: number;
/** Center latitude in degrees */
latitude: number;
/** Camera pitch (0-90 degrees) */
pitch?: number;
/** Camera bearing (0-360 degrees) */
bearing?: number;
/** Camera altitude for FOV calculation */
altitude?: number;
/** Field of view in degrees */
fovy?: number;
/** Near clipping plane */
near?: number;
/** Far clipping plane */
far?: number;
/** Orthographic projection */
orthographic?: boolean;
}Usage Examples:
import { WebMercatorViewport } from "@deck.gl/core";
// Create Web Mercator viewport
const viewport = new WebMercatorViewport({
width: 800,
height: 600,
longitude: -122.4194,
latitude: 37.7749,
zoom: 12,
pitch: 45,
bearing: 30
});
// Project San Francisco coordinates to screen
const screenCoords = viewport.project([-122.4194, 37.7749, 0]);
console.log('Screen coordinates:', screenCoords);
// Unproject screen center to world coordinates
const worldCoords = viewport.unproject([400, 300]);
console.log('World coordinates:', worldCoords);
// Fit to Golden Gate Park bounds
const parkBounds: [[number, number], [number, number]] = [
[-122.5107, 37.7694], // Southwest corner
[-122.4542, 37.7762] // Northeast corner
];
const fittedViewport = viewport.fitBounds(parkBounds, {
padding: 50
});
console.log('Fitted viewport:', fittedViewport);Viewport for orbital/trackball-style 3D navigation around a target point.
/**
* Orbit viewport for 3D trackball-style navigation
* Rotates around a fixed target point
*/
class OrbitViewport extends Viewport {
/** Initialize orbit viewport */
constructor(opts: OrbitViewportOptions);
/** Point being orbited */
readonly target: [number, number, number];
/** Rotation around X axis in degrees */
readonly rotationX: number;
/** Rotation around orbit axis in degrees */
readonly rotationOrbit: number;
/** Primary rotation axis */
readonly orbitAxis: 'Y' | 'Z';
/** Zoom level */
readonly zoom: number;
/** Minimum zoom level */
readonly minZoom: number;
/** Maximum zoom level */
readonly maxZoom: number;
}
interface OrbitViewportOptions extends ViewportOptions {
/** Target point to orbit around */
target: [number, number, number];
/** Rotation around X axis (pitch) */
rotationX?: number;
/** Rotation around orbit axis (yaw) */
rotationOrbit?: number;
/** Primary rotation axis */
orbitAxis?: 'Y' | 'Z';
/** Zoom level */
zoom?: number;
/** Minimum zoom */
minZoom?: number;
/** Maximum zoom */
maxZoom?: number;
/** Field of view */
fovy?: number;
/** Near clipping plane */
near?: number;
/** Far clipping plane */
far?: number;
}Viewport using orthographic projection, useful for 2D visualizations and technical drawings.
/**
* Orthographic projection viewport
* No perspective distortion - parallel lines remain parallel
*/
class OrthographicViewport extends Viewport {
/** Initialize orthographic viewport */
constructor(opts: OrthographicViewportOptions);
/** Target center point */
readonly target: [number, number, number];
/** Zoom level (can be per-axis) */
readonly zoom: number | [number, number];
/** Left boundary */
readonly left: number;
/** Right boundary */
readonly right: number;
/** Bottom boundary */
readonly bottom: number;
/** Top boundary */
readonly top: number;
}
interface OrthographicViewportOptions extends ViewportOptions {
/** Target center point */
target: [number, number, number];
/** Zoom level or per-axis zoom */
zoom?: number | [number, number];
/** Left boundary (overrides zoom) */
left?: number;
/** Right boundary (overrides zoom) */
right?: number;
/** Bottom boundary (overrides zoom) */
bottom?: number;
/** Top boundary (overrides zoom) */
top?: number;
/** Near clipping plane */
near?: number;
/** Far clipping plane */
far?: number;
}First-person camera viewport for immersive 3D navigation.
/**
* First-person camera viewport
* Camera positioned at a specific point looking in a direction
*/
class FirstPersonViewport extends Viewport {
/** Initialize first-person viewport */
constructor(opts: FirstPersonViewportOptions);
/** Camera longitude (if geospatial) */
readonly longitude?: number;
/** Camera latitude (if geospatial) */
readonly latitude?: number;
/** Camera position in world coordinates */
readonly position: [number, number, number];
/** Camera bearing in degrees */
readonly bearing: number;
/** Camera pitch in degrees */
readonly pitch: number;
}
interface FirstPersonViewportOptions extends ViewportOptions {
/** Camera longitude for geospatial positioning */
longitude?: number;
/** Camera latitude for geospatial positioning */
latitude?: number;
/** Direct position (alternative to lng/lat) */
position?: [number, number, number];
/** Camera bearing angle */
bearing?: number;
/** Camera pitch angle */
pitch?: number;
/** Field of view in degrees */
fovy?: number;
/** Near clipping plane */
near?: number;
/** Far clipping plane */
far?: number;
}Experimental viewport for 3D globe projection rendering geospatial data on a sphere.
/**
* Experimental globe viewport for 3D earth visualization
* Renders geospatial data on a 3D sphere
*/
class _GlobeViewport extends Viewport {
/** Initialize globe viewport */
constructor(opts: GlobeViewportOptions);
/** Globe center longitude */
readonly longitude: number;
/** Globe center latitude */
readonly latitude: number;
/** Tessellation resolution in degrees */
readonly resolution: number;
}
interface GlobeViewportOptions extends ViewportOptions {
/** Globe center longitude */
longitude: number;
/** Globe center latitude */
latitude: number;
/** Tessellation resolution */
resolution?: number;
/** Globe radius */
radius?: number;
}Abstract base class defining viewport layout within canvas and managing view state.
/**
* Abstract base class for views
* Defines viewport layout and manages view state integration
*/
abstract class View {
/** Initialize view with properties */
constructor(props: ViewProps);
/** Create viewport instance from view state */
makeViewport(opts: MakeViewportOptions): Viewport;
/** Get unique view state identifier */
getViewStateId(): string;
/** Process and filter view state */
filterViewState(viewState: any): any;
/** Calculate view dimensions within canvas */
getDimensions(canvasSize: {width: number; height: number}): {
x: number; y: number; width: number; height: number;
};
/** Check if coordinate is within view bounds */
containsCoordinate(coordinate: [number, number]): boolean;
/** View unique identifier */
readonly id: string;
/** View configuration properties */
readonly props: ViewProps;
}
interface ViewProps {
/** Unique view identifier */
id: string;
/** View position/size relative to canvas */
x?: number | string;
y?: number | string;
width?: number | string;
height?: number | string;
/** Controller configuration */
controller?: boolean | ControllerProps;
/** View-specific parameters */
[key: string]: any;
}
interface MakeViewportOptions {
/** Canvas dimensions */
width: number;
height: number;
/** Current view state */
viewState: any;
/** View matrix override */
viewMatrix?: number[];
/** Projection matrix override */
projectionMatrix?: number[];
}View for Web Mercator geospatial applications with standard map interaction patterns.
/**
* Map view for geospatial applications
* Uses Web Mercator projection with standard map controls
*/
class MapView extends View {
/** Initialize map view */
constructor(props: MapViewProps);
/** Creates WebMercatorViewport */
makeViewport(opts: MakeViewportOptions): WebMercatorViewport;
/** Default controller type */
static controllerType: typeof MapController;
}
interface MapViewProps extends ViewProps {
/** Repeat map horizontally */
repeat?: boolean;
/** Far clipping plane multiplier */
farZMultiplier?: number;
/** Near clipping plane multiplier */
nearZMultiplier?: number;
/** Orthographic projection */
orthographic?: boolean;
}
interface MapViewState {
/** Center longitude in degrees */
longitude: number;
/** Center latitude in degrees */
latitude: number;
/** Zoom level */
zoom: number;
/** Camera pitch angle */
pitch?: number;
/** Camera bearing angle */
bearing?: number;
/** Camera altitude */
altitude?: number;
}View for first-person 3D navigation with FPS-style controls.
/**
* First-person view for immersive 3D navigation
* Camera positioned at specific point with directional controls
*/
class FirstPersonView extends View {
/** Initialize first-person view */
constructor(props: FirstPersonViewProps);
/** Creates FirstPersonViewport */
makeViewport(opts: MakeViewportOptions): FirstPersonViewport;
/** Default controller type */
static controllerType: typeof FirstPersonController;
}
interface FirstPersonViewProps extends ViewProps {
/** Field of view in degrees */
fovy?: number;
/** Near clipping plane */
near?: number;
/** Far clipping plane */
far?: number;
}
interface FirstPersonViewState {
/** Camera longitude (geospatial) */
longitude?: number;
/** Camera latitude (geospatial) */
latitude?: number;
/** Direct position coordinates */
position?: [number, number, number];
/** Camera bearing */
bearing?: number;
/** Camera pitch */
pitch?: number;
}Additional view classes following similar patterns for their respective viewport types.
class OrbitView extends View {
constructor(props: OrbitViewProps);
makeViewport(opts: MakeViewportOptions): OrbitViewport;
static controllerType: typeof OrbitController;
}
class OrthographicView extends View {
constructor(props: OrthographicViewProps);
makeViewport(opts: MakeViewportOptions): OrthographicViewport;
static controllerType: typeof OrthographicController;
}
class _GlobeView extends View {
constructor(props: GlobeViewProps);
makeViewport(opts: MakeViewportOptions): _GlobeViewport;
static controllerType: typeof _GlobeController;
}Usage Examples:
import { Deck, MapView, OrbitView, FirstPersonView } from "@deck.gl/core";
// Single map view
const deck = new Deck({
views: [new MapView({id: 'map'})],
initialViewState: {
longitude: -122.4,
latitude: 37.8,
zoom: 12,
pitch: 45,
bearing: 30
}
});
// Multiple views layout
const multiViewDeck = new Deck({
views: [
new MapView({
id: 'map',
x: 0,
y: 0,
width: '50%',
height: '100%'
}),
new OrbitView({
id: 'orbit',
x: '50%',
y: 0,
width: '50%',
height: '50%'
}),
new FirstPersonView({
id: 'first-person',
x: '50%',
y: '50%',
width: '50%',
height: '50%'
})
],
viewState: {
map: {
longitude: -122.4,
latitude: 37.8,
zoom: 12
},
orbit: {
target: [0, 0, 0],
rotationX: 30,
rotationOrbit: 45,
zoom: 0
},
'first-person': {
position: [0, 0, 100],
bearing: 0,
pitch: 0
}
}
});
// View state transitions
const transitionToLocation = {
longitude: -74.006,
latitude: 40.7128,
zoom: 14,
pitch: 60,
bearing: 45,
transitionDuration: 2000,
transitionInterpolator: new FlyToInterpolator()
};
deck.setProps({
viewState: transitionToLocation
});