@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.1

package/src/procedures/terrain-globe.ts

@@ -0,0 +1,32 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getProjectionSurface, PROJECTION_CONSTANTS} from '../scene/projection_math';
+
+/** Zero-relief globe point followed by the common-space displacement per unit exaggeration. */
+export function createTerrainGlobePoint(coordinate: readonly [number, number], height: number, normalized?: readonly [number, number]): Float64Array {
+    const circumference = 2 * Math.PI * PROJECTION_CONSTANTS.mercatorRadius;
+    const x = normalized ? (normalized[0] - Math.floor(normalized[0]) - 0.5) * circumference : coordinate[0];
+    const y = normalized ? (0.5 - normalized[1]) * circumference : coordinate[1];
+    const base = getProjectionSurface(x, y, 'globe').position;
+    return Float64Array.from([...base, ...base.map(component => component * height / PROJECTION_CONSTANTS.earthRadius)]);
+}
+
+/** Preserve a canonical face's affine globe plane rather than projecting a new cut back onto the sphere. */
+export function interpolateTerrainGlobePoints(points: readonly Float64Array[], weights: ArrayLike<number>): Float64Array {
+    return Float64Array.from({length: points[0].length}, (_value, channel) =>
+        points.reduce((sum, point, corner) => sum + point[channel] * weights[corner], 0));
+}
+
+/** Evaluate the same current/previous affine surface as the shader, with independent authored physical altitude. */
+export function projectTerrainGlobeVertex(channels: ArrayLike<number>, vertex: number, blend: number, exaggeration: number,
+    coordinate: readonly [number, number, number]): [number, number, number] {
+    const offset = vertex * 12;
+    const direction = coordinate[2] ? getProjectionSurface(coordinate[0], coordinate[1], 'globe').position : [0, 0, 0];
+    const component = (axis: number) =>
+        channels[offset + 6 + axis] * (1 - blend) + channels[offset + axis] * blend +
+        (channels[offset + 9 + axis] * (1 - blend) + channels[offset + 3 + axis] * blend) * exaggeration +
+        direction[axis] * coordinate[2] / PROJECTION_CONSTANTS.earthRadius;
+    return [component(0), component(1), component(2)];
+}

package/src/procedures/terrain-styled-topology.ts

@@ -0,0 +1,184 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type VertexLayout from '../gl/vertex_layout';
+import {interpolatePackedVertex, selectTrianglePlane} from '../gl/globe_mesh';
+
+/** A clipped authored vertex, retaining its unrounded geometric clipping position. */
+interface ClipVertex {
+    /** Authored packed channels, never shared across feature triangles. */
+    record: Uint8Array;
+    /** Expanded nominal tile-space XY used for clipping. */
+    position: [number, number];
+}
+
+/** Closed tile-space triangle envelope and original canonical face offset. */
+interface FaceBounds {
+    /** Canonical index-buffer offset, not a reordered face identity. */
+    offset: number;
+    /** Closed XY envelope. */
+    bounds: [number, number, number, number];
+}
+
+/** Temporary balanced bounds tree; released after one worker mesh is prepared. */
+interface FaceNode {
+    /** Union of descendant envelopes. */
+    bounds: [number, number, number, number];
+    /** Original canonical triangles at a small leaf. */
+    faces?: FaceBounds[];
+    /** Median-partitioned children. */
+    children?: [FaceNode, FaceNode];
+}
+
+/** Styled geometry and its barycentric references to the shared physical surface. */
+export interface TerrainStyledTopology {
+    /** Packed source channels interpolated only within each original feature face. */
+    vertices: Uint8Array;
+    /** Source winding/order retained; disconnected features never weld their attributes. */
+    indices: Uint32Array;
+    /** Three canonical vertex identities per output vertex. */
+    surfaceIndices: Uint32Array;
+    /** Three surface weights at the actual packed nominal XY per output vertex. */
+    surfaceWeights: Float64Array;
+}
+
+/** Signed twice-area in tile-space XY; canonical faces are counterclockwise. */
+function cross(first: readonly number[], second: readonly number[], third: readonly number[]): number {
+    return (second[0] - first[0]) * (third[1] - first[1]) - (second[1] - first[1]) * (third[0] - first[0]);
+}
+
+/** Build a mesh-local broad phase instead of scanning every terrain cell for every source face. */
+function buildNode(faces: FaceBounds[]): FaceNode {
+    const bounds: FaceNode['bounds'] = [Infinity, Infinity, -Infinity, -Infinity];
+    for (const face of faces) for (let axis = 0; axis < 2; axis++) {
+        bounds[axis] = Math.min(bounds[axis], face.bounds[axis]);
+        bounds[axis + 2] = Math.max(bounds[axis + 2], face.bounds[axis + 2]);
+    }
+    if (faces.length <= 8) return {bounds, faces};
+    const axis = bounds[2] - bounds[0] >= bounds[3] - bounds[1] ? 0 : 1;
+    faces.sort((first, second) => first.bounds[axis] + first.bounds[axis + 2] - second.bounds[axis] - second.bounds[axis + 2] || first.offset - second.offset);
+    const middle = Math.floor(faces.length / 2);
+    return {bounds, children: [buildNode(faces.slice(0, middle)), buildNode(faces.slice(middle))]};
+}
+
+/** Intersect source faces with complete DEM triangles, preserving holes, walls and feature identity.
+ * Heights are interpolated from the terrain face, not resampled from a different bilinear surface.
+ * The caller owns DEM validation, physical sampling and final draw-byte admission.
+ */
+export function conformTerrainStyledMesh(options: {
+    /** Floating-position authored records before terrain channels are appended. */
+    vertices: Uint8Array;
+    /** Valid source triangles in authored draw order. */
+    indices: Uint16Array | Uint32Array;
+    /** Original packed attribute interpolation semantics. */
+    layout: VertexLayout;
+    /** Canonical terrain nodes in the same tile-local coordinate system. */
+    surfacePositions: Float64Array;
+    /** Counterclockwise canonical terrain triangles. */
+    surfaceIndices: Uint32Array;
+    /** Nominal expanded corner, including road width and offset. */
+    getPosition: (record: DataView) => [number, number];
+    /** Authored elevation, used to retain vertical walls rather than discarding XY degenerates. */
+    getElevation: (record: DataView) => number;
+    /** Maximum completed output vertices; a failed admission never returns partial geometry. */
+    maxVertices: number;
+}): TerrainStyledTopology {
+    const {layout, surfacePositions, surfaceIndices} = options;
+    const point = (index: number): [number, number] => [surfacePositions[index * 2], surfacePositions[index * 2 + 1]];
+    const edgeCounts = new Map<string, number>();
+    const edgeKey = (first: number, second: number) => `${Math.min(first, second)}:${Math.max(first, second)}`;
+    const faces: FaceBounds[] = [];
+    for (let offset = 0; offset < surfaceIndices.length; offset += 3) {
+        const corners = [0, 1, 2].map(corner => point(surfaceIndices[offset + corner]));
+        faces.push({offset, bounds: [Math.min(...corners.map(vertex => vertex[0])), Math.min(...corners.map(vertex => vertex[1])),
+            Math.max(...corners.map(vertex => vertex[0])), Math.max(...corners.map(vertex => vertex[1]))]});
+        for (let edge = 0; edge < 3; edge++) {
+            const key = edgeKey(surfaceIndices[offset + edge], surfaceIndices[offset + (edge + 1) % 3]);
+            edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
+        }
+    }
+    const root = faces.length ? buildNode(faces) : null;
+    const records: Uint8Array[] = [], indices: number[] = [], references: number[] = [], weights: number[] = [];
+    const view = (record: Uint8Array) => new DataView(record.buffer, record.byteOffset, layout.stride);
+    const intersects = (first: readonly number[], second: readonly number[]) => first[0] <= second[2] && first[2] >= second[0] && first[1] <= second[3] && first[3] >= second[1];
+    for (let offset = 0; offset < options.indices.length; offset += 3) {
+        const source = [0, 1, 2].map(corner => {
+            const index = options.indices[offset + corner];
+            const record = options.vertices.subarray(index * layout.stride, (index + 1) * layout.stride);
+            return {record, position: options.getPosition(view(record))};
+        });
+        // Validate flat/custom channels even when a face happens not to need clipping.
+        interpolatePackedVertex(source[0].record, source[1].record, layout, 0);
+        interpolatePackedVertex(source[0].record, source[2].record, layout, 0);
+        if (layout.offset.a_extrude !== undefined) {
+            // Width/offset scale products must remain affine within an authored face.
+            for (const corner of source.slice(1)) {
+                if (view(corner.record).getFloat32(layout.offset.a_position + 8, true) !== view(source[0].record).getFloat32(layout.offset.a_position + 8, true) ||
+                    layout.offset.a_z_and_offset_scale !== undefined && view(corner.record).getInt16(layout.offset.a_z_and_offset_scale + 2, true) !== view(source[0].record).getInt16(layout.offset.a_z_and_offset_scale + 2, true)) {
+                    throw new Error('Canonical terrain roads require uniform per-face width and offset scales');
+                }
+            }
+        }
+        const bounds = [Math.min(...source.map(vertex => vertex.position[0])), Math.min(...source.map(vertex => vertex.position[1])),
+            Math.max(...source.map(vertex => vertex.position[0])), Math.max(...source.map(vertex => vertex.position[1]))];
+        const plane = selectTrianglePlane(source.map(vertex => [...vertex.position, options.getElevation(view(vertex.record))] as const));
+        const candidates: FaceBounds[] = [], pending = root ? [root] : [];
+        while (pending.length) {
+            const node = pending.pop()!;
+            if (!intersects(bounds, node.bounds)) continue;
+            if (node.faces) for (const face of node.faces) {if (intersects(bounds, face.bounds)) candidates.push(face);}
+            else pending.push(...node.children!);
+        }
+        candidates.sort((first, second) => first.offset - second.offset);
+        for (const face of candidates) {
+            const corners = [0, 1, 2].map(corner => point(surfaceIndices[face.offset + corner]));
+            let polygon: ClipVertex[] = source;
+            for (let edge = 0; edge < 3 && polygon.length; edge++) {
+                const first = corners[edge], second = corners[(edge + 1) % 3];
+                // A wall on a shared terrain edge belongs to just one incident face.
+                if (polygon.every(vertex => cross(first, second, vertex.position) === 0) &&
+                    edgeCounts.get(edgeKey(surfaceIndices[face.offset + edge], surfaceIndices[face.offset + (edge + 1) % 3])) === 2 &&
+                    !(second[1] > first[1] || second[1] === first[1] && second[0] < first[0])) {polygon = []; break;}
+                const clipped: ClipVertex[] = [];
+                for (let index = 0; index < polygon.length; index++) {
+                    let start = polygon[index], end = polygon[(index + 1) % polygon.length];
+                    let startDistance = cross(first, second, start.position), endDistance = cross(first, second, end.position);
+                    if (startDistance >= 0) clipped.push(start);
+                    if (startDistance < 0 && endDistance > 0 || startDistance > 0 && endDistance < 0) {
+                        // Stable geometric orientation gives reversed/shared edges identical intersections.
+                        if (start.position[0] > end.position[0] || start.position[0] === end.position[0] && start.position[1] > end.position[1]) {
+                            [start, end] = [end, start]; [startDistance, endDistance] = [endDistance, startDistance];
+                        }
+                        const fraction = startDistance / (startDistance - endDistance);
+                        clipped.push({record: interpolatePackedVertex(start.record, end.record, layout, fraction), position: [
+                            start.position[0] + (end.position[0] - start.position[0]) * fraction,
+                            start.position[1] + (end.position[1] - start.position[1]) * fraction]});
+                    }
+                }
+                polygon = clipped;
+            }
+            if (polygon.length < 3) continue;
+            const positions = polygon.map(vertex => [...vertex.position, options.getElevation(view(vertex.record))] as const);
+            const area = (first: number, second: number, third: number) => cross(
+                [positions[first][plane[0]], positions[first][plane[1]]], [positions[second][plane[0]], positions[second][plane[1]]], [positions[third][plane[0]], positions[third][plane[1]]]);
+            if (!polygon.slice(2).some((_vertex, index) => area(0, index + 1, index + 2) !== 0)) continue;
+            if (records.length + polygon.length > options.maxVertices) throw new Error('Canonical styled terrain vertex/mesh budget exceeded');
+            const base = records.length, denominator = cross(corners[0], corners[1], corners[2]);
+            for (const vertex of polygon) {
+                const record = vertex.record.slice(), packed = view(record), actual = options.getPosition(packed);
+                // Preserve the road's dynamic extrusion; only correct roundoff in its centerline.
+                packed.setFloat32(layout.offset.a_position, packed.getFloat32(layout.offset.a_position, true) + vertex.position[0] - actual[0], true);
+                packed.setFloat32(layout.offset.a_position + 4, packed.getFloat32(layout.offset.a_position + 4, true) + vertex.position[1] - actual[1], true);
+                const position = options.getPosition(packed);
+                const first = cross(corners[1], corners[2], position) / denominator;
+                const second = cross(corners[2], corners[0], position) / denominator;
+                records.push(record); references.push(...surfaceIndices.subarray(face.offset, face.offset + 3)); weights.push(first, second, 1 - first - second);
+            }
+            for (let index = 1; index + 1 < polygon.length; index++) if (area(0, index, index + 1) !== 0) indices.push(base, base + index, base + index + 1);
+        }
+    }
+    const vertices = new Uint8Array(records.length * layout.stride);
+    records.forEach((record, index) => vertices.set(record, index * layout.stride));
+    return {vertices, indices: Uint32Array.from(indices), surfaceIndices: Uint32Array.from(references), surfaceWeights: Float64Array.from(weights)};
+}

package/src/procedures/web-mercator-legacy.ts

@@ -0,0 +1,24 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+const HALF_CIRCUMFERENCE_METERS = 20037508.342789244;
+
+/** Project longitude/latitude degrees to Web Mercator meters using Tangram's established formula. */
+export function projectLngLatToMetersLegacy(coordinates: readonly [number, number]): [number, number] {
+  const longitude = coordinates[0] * (HALF_CIRCUMFERENCE_METERS / 180);
+  const latitude =
+    (Math.log(Math.tan((coordinates[1] * Math.PI) / 360 + Math.PI / 4)) / Math.PI) *
+    HALF_CIRCUMFERENCE_METERS;
+  return [longitude, latitude];
+}
+
+/** Unproject Web Mercator meters to longitude/latitude degrees using Tangram's established formula. */
+export function unprojectMetersToLngLatLegacy(coordinates: readonly [number, number]): [number, number] {
+  const longitude = (coordinates[0] / HALF_CIRCUMFERENCE_METERS) * 180;
+  const normalizedLatitude = coordinates[1] / HALF_CIRCUMFERENCE_METERS;
+  const latitude =
+    ((2 * Math.atan(Math.exp(normalizedLatitude * Math.PI)) - Math.PI / 2) / Math.PI) * 180;
+  return [longitude, latitude];
+}

package/src/procedures/web-mercator-math.ts

@@ -0,0 +1,50 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {lngLatToWorld, worldToLngLat} from '@math.gl/web-mercator';
+import {projectLngLatToMetersLegacy} from './web-mercator-legacy';
+
+const WORLD_SIZE = 512;
+const HALF_CIRCUMFERENCE_METERS = 20037508.342789244;
+const CIRCUMFERENCE_METERS = HALF_CIRCUMFERENCE_METERS * 2;
+
+/** Return whether a normalized world coordinate lies on a slippy-map tile edge. */
+function isTileBoundary(worldCoordinate: number): boolean {
+  // Every boundary through zoom 30 is an integer at zoom 30, so one check
+  // avoids a zoom loop on the per-coordinate projection hot path.
+  const tileCoordinate = worldCoordinate * 2 ** 30;
+  const nearestBoundary = Math.round(tileCoordinate);
+  const floatingPointTolerance = Number.EPSILON * Math.max(1, Math.abs(tileCoordinate)) * 4;
+  return Math.abs(tileCoordinate - nearestBoundary) <= floatingPointTolerance;
+}
+
+/** Project longitude/latitude degrees to Tangram Web Mercator meters using math.gl. */
+export function projectLngLatToMetersWithMath(
+  coordinates: readonly [number, number]
+): [number, number] {
+  const [worldX, worldY] = lngLatToWorld([coordinates[0], coordinates[1]]);
+  const normalizedWorldX = worldX / WORLD_SIZE;
+  const normalizedWorldY = worldY / WORLD_SIZE;
+  const legacyMeters =
+    isTileBoundary(normalizedWorldX) || isTileBoundary(normalizedWorldY)
+      ? projectLngLatToMetersLegacy(coordinates)
+      : undefined;
+  return [
+    legacyMeters?.[0] ?? normalizedWorldX * CIRCUMFERENCE_METERS - HALF_CIRCUMFERENCE_METERS,
+    // math.gl world Y is north-positive: latitude +40 maps above WORLD_SIZE / 2.
+    legacyMeters?.[1] ?? normalizedWorldY * CIRCUMFERENCE_METERS - HALF_CIRCUMFERENCE_METERS
+  ];
+}
+
+/** Unproject Tangram Web Mercator meters to longitude/latitude degrees using math.gl. */
+export function unprojectMetersToLngLatWithMath(
+  coordinates: readonly [number, number]
+): [number, number] {
+  const worldX =
+    ((coordinates[0] + HALF_CIRCUMFERENCE_METERS) / CIRCUMFERENCE_METERS) * WORLD_SIZE;
+  // Preserve math.gl's north-positive world-Y convention for the inverse transform.
+  const worldY =
+    ((coordinates[1] + HALF_CIRCUMFERENCE_METERS) / CIRCUMFERENCE_METERS) * WORLD_SIZE;
+  return worldToLngLat([worldX, worldY]) as [number, number];
+}

package/src/scene/camera.ts

@@ -0,0 +1,298 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import Utils from '../utils/utils';
+import ShaderProgram from '../gl/shader_program';
+import CameraBase, {type CameraView, type CameraConfiguration, type Program, type UniformBuffer} from './camera_base';
+import ExternalCamera from './external_camera';
+
+/** Classic Tangram camera factory, intentionally absent from the core entry. */
+export default class Camera extends CameraBase {
+    // Create a camera by type name, factory-style
+    static create(name: string, view: CameraView, config: CameraConfiguration): Camera {
+        switch (config.type) {
+        case 'external':
+            return new ExternalCamera(name, view, config);
+        case 'isometric':
+            return new IsometricCamera(name, view, config);
+        case 'flat':
+            return new FlatCamera(name, view, config);
+        case 'perspective':
+            /* falls through */
+        default:
+            return new PerspectiveCamera(name, view, config);
+        }
+    }
+
+}
+
+/**
+    Perspective matrix projection
+
+    This is a specialized perspective camera that, given a desired camera focal length (which can also vary by zoom level),
+    constrains the camera height above the ground plane such that the displayed ground area of the map matches that of
+    a traditional web mercator map. This means you can set the camera location by [lat, lng, zoom] as you would a typical
+    web mercator map, then adjust the focal length as needed.
+
+    Vanishing point can also be adjusted to achieve different 'viewing angles', e.g. instead of looking straight down into
+    the center of the viewport, the camera appears to be tilted at an angle. For example:
+
+    [0, 0] = looking towards center of viewport
+    [-250, -250] = looking 250 pixels from the viewport center to the lower-left corner
+    [400, 0] = looking 400 pixels to the right of the viewport center
+*/
+export class PerspectiveCamera extends Camera {
+    focal_length: number | number[][] | undefined;
+    fov: number | number[][] | undefined;
+    vanishing_point: number[];
+    vanishing_point_skew: number[];
+
+    constructor(name: string, view: CameraView, options: CameraConfiguration = {}) {
+        super(name, view, options);
+        this.type = 'perspective';
+
+        // a single scalar, or pairs of stops mapping zoom levels, e.g. [zoom, focal length]
+        this.focal_length = options.focal_length;
+        this.fov = options.fov;
+        if (!this.focal_length && !this.fov) {
+            // Default focal length ranges by zoom
+            this.focal_length = [[16, 2], [17, 2.5], [18, 3], [19, 4], [20, 6]];
+        }
+
+        this.vanishing_point = options.vanishing_point || [0, 0]; // [x, y]
+        this.vanishing_point = this.vanishing_point.map(value => parseFloat(String(value))); // we implicitly only support px units here
+        this.vanishing_point_skew = [];
+
+        this.position_meters = [];
+        this.view_matrix = new Float64Array(16);
+        this.projection_matrix = new Float32Array(16);
+
+        // 'camera' is the name of the shader block, e.g. determines where in the shader this code is injected
+        ShaderProgram.replaceBlock('camera', `
+            uniform mat4 u_projection;
+            uniform vec3 u_eye;
+            uniform vec2 u_vanishing_point;
+
+            void cameraProjection (inout vec4 position) {
+                position = u_projection * position;
+            }`
+        );
+    }
+
+    // Constrains the camera so that the viewable area matches given the viewport height
+    // (in world space, e.g. meters), given either a camera focal length or field-of-view
+    // (focal length is used if both are passed).
+    constrainCamera({view_height, height, focal_length, fov}: {
+        view_height: number;
+        height?: number;
+        focal_length?: number;
+        fov?: number;
+    }): {view_height: number; height: number; focal_length: number; fov: number} {
+        // Solve for camera height
+        if (!height) {
+            // We have focal length, calculate FOV
+            if (focal_length) {
+                fov = Math.atan(1 / focal_length) * 2;
+            }
+            // We have FOV, calculate focal length
+            else if (fov) {
+                fov = fov * Math.PI / 180; // convert FOV degrees to radians
+                focal_length = 1 / Math.tan(fov / 2);
+            }
+
+            // Distance that camera should be from ground such that it fits the field of view expected
+            // for a conventional web mercator map at the current zoom level and camera focal length
+            height = view_height / 2 * (focal_length ?? 0);
+        }
+        // Solve for camera focal length / field-of-view
+        else {
+            focal_length = 2 * height / view_height;
+            fov = Math.atan(1 / focal_length) * 2;
+        }
+
+        return {
+            view_height,
+            height: height as number,
+            focal_length: focal_length as number,
+            fov: fov as number
+        };
+    }
+
+    updateMatrices(): void {
+        // TODO: only re-calculate these vars when necessary
+
+        // Height of the viewport in meters at current zoom
+        var viewport_height = this.view.size.css.height * this.view.meters_per_pixel;
+
+        // Compute camera properties to fit desired view
+        var { height, fov } = this.constrainCamera({
+            view_height: viewport_height,
+            focal_length: Utils.interpolate(this.view.zoom, this.focal_length) as number | undefined,
+            fov: Utils.interpolate(this.view.zoom, this.fov) as number | undefined
+        });
+
+        // View matrix
+        var position = [this.view.center.meters.x, this.view.center.meters.y, height];
+        this.position_meters = position;
+
+        // Exclude camera height from view matrix
+        this.matrix4.identity().lookAt({
+            eye: [position[0], position[1], 0],
+            center: [position[0], position[1], -1],
+            up: [0, 1, 0]
+        }).toArray(this.view_matrix);
+
+        // Projection matrix
+        this.matrix4.identity().perspective({fovy: fov, aspect: this.view.aspect, near: 1, far: height * 2})
+            .toArray(this.projection_matrix);
+
+        // Convert vanishing point from pixels to viewport space
+        this.vanishing_point_skew[0] = this.vanishing_point[0] / this.view.size.css.width;
+        this.vanishing_point_skew[1] = this.vanishing_point[1] / this.view.size.css.height;
+
+        // Adjust projection matrix to include vanishing point skew
+        this.projection_matrix[8] = -this.vanishing_point_skew[0] * 2; // z column of x row, e.g. amount z skews x
+        this.projection_matrix[9] = -this.vanishing_point_skew[1] * 2; // z column of y row, e.g. amount z skews y
+
+        // Translate geometry into the distance so that camera is appropriate height above ground
+        // Additionally, adjust xy to compensate for any vanishing point skew, e.g. move geometry so that the displayed g
+        // plane of the map matches that expected by a traditional web mercator map at this [lat, lng, zoom].
+        this.matrix4.copy(this.projection_matrix).translate(
+            [
+                viewport_height/2 * this.view.aspect * (-this.vanishing_point_skew[0] * 2),
+                viewport_height/2 * (-this.vanishing_point_skew[1] * 2),
+                0
+            ]
+        ).toArray(this.projection_matrix);
+
+        // Include camera height in projection matrix
+        this.matrix4.copy(this.projection_matrix).translate([0, 0, -height]).toArray(this.projection_matrix);
+    }
+
+    update(): void {
+        super.update();
+        this.updateMatrices();
+    }
+
+    setupProgram(program: Program, uniform_buffer?: UniformBuffer): void {
+        if (uniform_buffer) {
+            uniform_buffer.setUniforms({
+                u_projection: this.projection_matrix,
+                u_eye: [0, 0, this.position_meters[2]],
+                u_vanishing_point: this.vanishing_point_skew
+            });
+        }
+        else {
+            program.uniform('Matrix4fv', 'u_projection', this.projection_matrix);
+            program.uniform('3f', 'u_eye', [0, 0, this.position_meters[2]]);
+            program.uniform('2fv', 'u_vanishing_point', this.vanishing_point_skew);
+        }
+    }
+
+}
+
+// Isometric-style projection
+// Note: this is actually an 'axonometric' projection, but I'm using the colloquial term isometric because it is more recognizable.
+// An isometric projection is a specific subset of axonometric projections.
+// 'axis' determines the xy skew applied to a vertex based on its z coordinate, e.g. [0, 1] axis causes buildings to be drawn
+// straight upwards on screen at their true height, [0, .5] would draw them up at half-height, [1, 0] would be sideways, etc.
+export class IsometricCamera extends Camera {
+    axis: {x: number; y: number};
+    viewport_height: number | null;
+
+    constructor(name: string, view: CameraView, options: CameraConfiguration = {}) {
+        super(name, view, options);
+        this.type = 'isometric';
+        const axis = options.axis;
+        this.axis = Array.isArray(axis)
+            ? {x: axis[0], y: axis[1]}
+            : axis || {x: 0, y: 1};
+
+        this.position_meters = [];
+        this.viewport_height = null;
+
+        this.view_matrix = new Float64Array(16);
+        this.projection_matrix = new Float32Array(16);
+
+        // 'camera' is the name of the shader block, e.g. determines where in the shader this code is injected
+        ShaderProgram.replaceBlock('camera', `
+            uniform mat4 u_projection;
+            uniform vec3 u_eye;
+            uniform vec2 u_vanishing_point;
+
+            void cameraProjection (inout vec4 position) {
+                position = u_projection * position;
+                // position.xy += position.z * u_isometric_axis;
+
+                // Reverse z for depth buffer so up is negative,
+                // and scale down values so objects higher than one screen height will not get clipped
+                // pull forward slightly to avoid going past far clipping plane
+                position.z = -position.z / 100. + 1. - 0.001;
+            }`
+        );
+    }
+
+    update(): void {
+        super.update();
+
+        this.viewport_height = this.view.size.css.height * this.view.meters_per_pixel;
+        var position = [this.view.center.meters.x, this.view.center.meters.y, this.viewport_height];
+        this.position_meters = position;
+
+        // View
+        this.matrix4.identity().translate([-position[0], -position[1], 0]).toArray(this.view_matrix);
+
+        // Projection
+        this.matrix4.identity().toArray(this.projection_matrix);
+
+        // apply isometric skew
+        this.projection_matrix[8] = this.axis.x / this.view.aspect; // z column of x row, e.g. amount z skews x
+        this.projection_matrix[9] = this.axis.y;                    // z column of x row, e.g. amount z skews y
+
+        // convert meters to viewport
+        this.matrix4.copy(this.projection_matrix).scale(
+            [
+                2 / this.view.size.meters.x,
+                2 / this.view.size.meters.y,
+                2 / this.view.size.meters.y
+            ]
+        ).toArray(this.projection_matrix);
+    }
+
+    setupProgram(program: Program, uniform_buffer?: UniformBuffer): void {
+        if (uniform_buffer) {
+            uniform_buffer.setUniforms({
+                u_projection: this.projection_matrix,
+                u_eye: [0, 0, this.viewport_height ?? 0],
+                u_vanishing_point: [0, 0]
+            });
+        }
+        else {
+            program.uniform('Matrix4fv', 'u_projection', this.projection_matrix);
+            program.uniform('3fv', 'u_eye', [0, 0, this.viewport_height ?? 0]);
+            // program.uniform('3f', 'u_eye', this.viewport_height * this.axis.x, this.viewport_height * this.axis.y, this.viewport_height);
+            program.uniform('2fv', 'u_vanishing_point', [0, 0]);
+        }
+    }
+
+}
+
+// Flat projection (e.g. just top-down, no perspective) - a degenerate isometric camera
+export class FlatCamera extends IsometricCamera {
+
+    constructor(name: string, view: CameraView, options: CameraConfiguration = {}) {
+        super(name, view, options);
+        this.type = 'flat';
+    }
+
+    update(): void {
+        // Axis is fixed to (0, 0) for flat camera
+        this.axis.x = 0;
+        this.axis.y = 0;
+
+        super.update();
+    }
+
+}