`@bendyline/molen-terrain/kernel`

PmtilesArchiveOptions.bounds

Properties

cellSize

readonly cellSize: [number, number];

Grid cell size in meters [x, z]; satisfies the kernel's GroundField contract.

cols

readonly cols: number;

heightRange

readonly heightRange: object;

The height range the normalized grid maps onto.

max

max: number;

min

min: number;

origin

readonly origin: [number, number];

World XZ of the field's (0,0) corner.

rows

readonly rows: number;

worldSize

readonly worldSize: [number, number];

World size in meters [width(x), depth(z)].

Methods

copySamples()

copySamples(): Float32Array;

Independent normalized samples for transfer to a worker; the resident field stays intact.

Returns

Float32Array

normalAt()

normalAt(x, z): [number, number, number];

Approximate surface normal at world (x, z) from the height gradient.

Parameters

x

number

z

number

Returns

[number, number, number]

raycastDown()

raycastDown(x, z): number;

The terrain surface height directly below/above (x, z) — same as sampleHeight for a heightmap.

Parameters

x

number

z

number

Returns

number

sampleHeight()

sampleHeight(x, z): number;

Bilinear-sampled terrain height (world Y in meters) at world (x, z).

Parameters

x

number

z

number

Returns

number

slopeAt()

slopeAt(x, z): number;

Slope at (x,z): 0 = flat, 1 = vertical.

Parameters

x

number

z

number

Returns

number

toRapierHeightfield()

toRapierHeightfield(): HeightfieldCollider;

The field as a physics heightfield collider: denormalized meters, transposed to the column-major layout rigid-body engines (Rapier/parry) expect, with the world center so the collider can be placed without an authored offset.

Returns

HeightfieldCollider

Interfaces

BridgeDeckOptions

Properties

approachLift

approachLift: number;

Lift above terrain at an end that meets a grade road (the road's surface lift).

clearance

clearance: number;

Clearance above terrain at an unconnected (clipped or free) end, in metres (6 roads, 3 paths).

connections?

optional connections?: readonly object[];

Authored deck endpoints in the path's frame, blended in over radius.

connects

connects: readonly [boolean, boolean];

Whether each end meets a grade road: [start, end].

deckElevation?

optional deckElevation?: number;

Surveyed absolute deck height; when present the deck is flat at this Y.

groundApproach?

optional groundApproach?: boolean;

A connected ground approach follows terrain, with only a local endpoint correction.

Gray16

Properties

data

data: Float32Array;

Normalized [0,1] values, row-major, length = width*height.

height

height: number;

width

width: number;

HeightfieldCollider

What a physics engine needs to build a heightfield collider from this field.

Properties

center

center: [number, number, number];

World position of the field's center (the collider is centered on its local origin).

heights

heights: Float32Array;

Denormalized heights (meters), column-major: heights[col * nrows + row].

ncols

ncols: number;

nrows

nrows: number;

scale

scale: [number, number, number];

Local x/y/z scale: [worldWidth, 1, worldDepth] (heights already carry meters).

HeightfieldOptions

Properties

height

height: object;

Height value range the normalized grid maps onto.

max

max: number;

min

min: number;

origin

origin: [number, number];

World XZ of the field's (0,0) corner.

worldSize

worldSize: [number, number];

World size in meters [width(x), depth(z)].

HeightmapGenOptions

Properties

frequency?

optional frequency?: number;

Base noise frequency across the map.

island?

optional island?: boolean;

Radial island falloff: heights taper to 0 at the edges.

octaves?

optional octaves?: number;

seed

seed: number;

size

size: number;

PmtilesArchiveOptions

Extended by

PmtilesPrefixOptions

Properties

bounds

bounds: readonly [number, number, number, number];

[west, south, east, north] in degrees.

center?

optional center?: readonly [number, number, number];

[longitude, latitude, zoom]; defaults to the bounds center at minZoom.

metadata?

optional metadata?: Record<string, unknown>;

JSON metadata (TileJSON-like). Stored gzip-compressed, like every directory.

tileCompression?

optional tileCompression?: PmtilesTileCompression;

Compression of the tile payloads themselves (default 'none').

tileType

tileType: PmtilesTileType;

PmtilesDirectories

Properties

leafDirectoryCount

leafDirectoryCount: number;

leaves

leaves: Uint8Array;

Concatenated gzip-compressed leaf directories (empty when the root holds every entry).

root

root: Uint8Array;

gzip-compressed root directory, sized to fit the reader's initial fetch.

PmtilesDirectoryEntry

A directory entry: one tile run, or (with runLength 0) a pointer to a leaf directory.

Properties

length

length: number;

offset

offset: number;

runLength

runLength: number;

tileId

tileId: number;

PmtilesPrefixOptions

Extends

PmtilesArchiveOptions

Properties

bounds

bounds: readonly [number, number, number, number];

[west, south, east, north] in degrees.

Inherited from

center?

optional center?: readonly [number, number, number];

[longitude, latitude, zoom]; defaults to the bounds center at minZoom.

Inherited from

PmtilesArchiveOptions.center

maxZoom

maxZoom: number;

metadata?

optional metadata?: Record<string, unknown>;

JSON metadata (TileJSON-like). Stored gzip-compressed, like every directory.

Inherited from

PmtilesArchiveOptions.metadata

minZoom

minZoom: number;

tileCompression?

optional tileCompression?: PmtilesTileCompression;

Compression of the tile payloads themselves (default 'none').

Inherited from

PmtilesArchiveOptions.tileCompression

tileType

tileType: PmtilesTileType;

Inherited from

PmtilesArchiveOptions.tileType

PmtilesTileRecord

One tile's position in a caller-streamed tile-data block, sorted by tileId.

Properties

byteLength

byteLength: number;

tileId

tileId: number;

PmtilesWriterTile

One tile to archive. data is stored verbatim (already compressed if tileCompression says so).

Properties

data

data: Uint8Array;

x

x: number;

y

y: number;

z

z: number;

RenderedGroundSource

The part of a heightfield the sampler reads.

Properties

cols

readonly cols: number;

Methods

sampleHeight()

sampleHeight(x, z): number;

Parameters

x

number

z

number

Returns

number

TerrainArchiveHeader

Properties

maxZoom

maxZoom: number;

minZoom

minZoom: number;

tileType?

optional tileType?: number;

TerrainArchiveSetBase

The coarse archive serving every level from minLevel through maxLevel.

Properties

bytes?

optional bytes?: number;

maxLevel

maxLevel: number;

minLevel

minLevel: number;

sha256?

optional sha256?: string;

url

url: string;

Archive URL, relative to the archive-set document or absolute.

TerrainArchiveSetDescriptor

Properties

base?

optional base?: TerrainArchiveSetBase;

format

format: "molen/archive-set@1";

geohash?

optional geohash?: TerrainArchiveSetGeohashTier[];

Geohash-partitioned tiers, each over its own band of levels.

name

name: string;

partitionLevel?

optional partitionLevel?: number;

Level whose tiles partition the archives (at most 10: a 1M-cell lookup). Required when archives is not empty.

tileType

tileType: TerrainArchiveSetTileType;

Payload type shared by every archive in the set.

TerrainArchiveSetEntry

One detail archive and the partition cells it owns.

Properties

bounds?

optional bounds?: [number, number, number, number];

Informational [west, south, east, north] in degrees.

bytes?

optional bytes?: number;

id

id: string;

maxLevel

maxLevel: number;

minLevel

minLevel: number;

partitions

partitions: string;

Run-length list of partition indices (y * 2^partitionLevel + x), e.g. "40-44,60".

sha256?

optional sha256?: string;

url

url: string;

Archive URL, relative to the archive-set document or absolute.

TerrainArchiveSetGeohashTier

One archive per geohash cell for a band of levels.

Properties

cells

cells: string;

Run-length list of the cells that have an archive, as geohash indices (geohashIndex).

maxLevel

maxLevel: number;

minLevel

minLevel: number;

precision

precision: number;

Geohash length of a cell, 1-6 (3 is 1.40625° square, about 156 km at the equator).

url

url: string;

Archive URL template, relative to the document or absolute; {cell} becomes the geohash.

TerrainArchiveSetRouter

Properties

descriptor

readonly descriptor: TerrainArchiveSetDescriptor;

maxLevel

readonly maxLevel: number;

minLevel

readonly minLevel: number;

Coarsest and finest levels any archive in the set serves.

Methods

resolve()

resolve(
   level, 
   x, 
   y
): TerrainArchiveSetRoute | undefined;

The archive holding XYZ tile level/x/y, or undefined when no archive covers it.

Parameters

level

number

x

number

y

number

Returns

TerrainArchiveSetRoute | undefined

TerrainArchiveTile

Properties

data

data: ArrayBuffer;

TerrainBuildingDetailChild

One descendant at the detail level and its tile, or undefined where the sidecar has none.

Properties

tile

tile: TerrainSemanticTile | undefined;

x

x: number;

z

z: number;

TerrainBuildingDetailOptions

Properties

cacheSize?

optional cacheSize?: number;

Recently loaded detail tiles kept for overlapping requests (default 48).

level

level: number;

The level the detail sidecar serves (e.g. 15 for Protomaps).

maxDepth?

optional maxDepth?: number;

How many levels coarser than level a tile may be and still be composed from it (default 2: a tile two levels up reads 16 detail tiles). Coarser tiles keep their own buildings.

TerrainBuildingFeature

Source identity and a bounded set of public map classification tags.

Extends

TerrainStructureIdentity

Properties

brand?

optional brand?: string;

brandId?

optional brandId?: string;

class?

optional class?: string;

heading?

optional heading?: number;

Rotation about +Y in radians; authored model front is +Z.

Inherited from

TerrainStructureIdentity.heading

height?

optional height?: number;

World-space height above the building base.

id?

optional id?: string | number;

layer?

optional layer?: number;

Source stacking layer (negative = underground); informational.

levels?

optional levels?: number;

minHeight?

optional minHeight?: number;

World-space offset of the building base above terrain.

name?

optional name?: string;

polygons

polygons: TerrainSemanticPolygon[];

subclass?

optional subclass?: string;

Finer source category when the schema carries one (e.g. Protomaps kind_detail).

tags?

optional tags?: Record<string, string>;

Inherited from

TerrainStructureIdentity.tags

wikidata?

optional wikidata?: string;

Inherited from

TerrainStructureIdentity.wikidata

TerrainDescriptor

Properties

chunkSize

chunkSize: number;

Meters per chunk edge.

collision

collision: object;

When enabled, the tooling registers the heightfield as the scene's ground/collision.

enabled

enabled: boolean;

format

format: "molen/terrain@2";

gridSize

gridSize: [number, number];

Chunks in X,Z.

height

height: object;

max

max: number;

min

min: number;

layers

layers: TerrainLayer[];

lod

lod: object;

distanceBands

distanceBands: number[];

levels

levels: number;

skirts

skirts: boolean;

metersPerUnit?

optional metersPerUnit?: number;

World meters per unit of the source's projected space. Projected-Earth packages set this to cos(center latitude) and pre-multiply origin/chunkSize by it, so world XZ is metric; absent = 1 (local/invented worlds).

name

name: string;

origin

origin: [number, number];

World XZ of tile (0,0) corner.

streaming

streaming: TerrainStreamingOptions;

tileResolution

tileResolution: number;

Height samples per chunk edge (shared borders).

tiles

tiles: object;

heightUrl

heightUrl: string;

splatUrl?

optional splatUrl?: string;

TerrainLandcoverFeature

Properties

class

class: string;

density?

optional density?: number;

Optional normalized vegetation/decorator density multiplier.

id?

optional id?: string | number;

polygons

polygons: TerrainSemanticPolygon[];

subclass?

optional subclass?: string;

Finer source category when the schema carries one (e.g. Protomaps kind_detail).

TerrainLayer

Properties

auto?

optional auto?: object;

Optional height/slope auto-banding (terrain-owned, not matgraph nodes).

heightMax?

optional heightMax?: number;

heightMin?

optional heightMin?: number;

slopeMax?

optional slopeMax?: number;

slopeMin?

optional slopeMin?: number;

color?

optional color?: string;

Flat color for vertex-color splat banding (v1 shading).

materialRef?

optional materialRef?: string;

name

name: string;

tiling

tiling: number;

TerrainLinePath

Properties

distances

distances: number[];

length

length: number;

points

points: TerrainSemanticPoint[];

TerrainLineSample

Properties

dx

dx: number;

dz

dz: number;

x

x: number;

z

z: number;

TerrainMvtSemanticDecoderLimits

Properties

maxFeaturesPerTile?

optional maxFeaturesPerTile?: number;

maxGeometryPointsPerTile?

optional maxGeometryPointsPerTile?: number;

TerrainMvtSemanticDecoderOptions

Properties

layers?

optional layers?: Partial<TerrainMvtSemanticLayerNames>;

limits?

optional limits?: TerrainMvtSemanticDecoderLimits;

linearUnitScale?

optional linearUnitScale?: number;

Convert source height/width properties into terrain world units.

properties?

optional properties?: Partial<TerrainMvtSemanticPropertyNames>;

TerrainMvtSemanticLayerNames

Properties

building

building: readonly string[];

landcover

landcover: readonly string[];

poi

poi: readonly string[];

transportation

transportation: readonly string[];

water

water: readonly string[];

TerrainMvtSemanticPropertyNames

Properties

bridge

bridge: readonly string[];

buildingClass

buildingClass: readonly string[];

buildingHeight

buildingHeight: readonly string[];

buildingLayer

buildingLayer: readonly string[];

buildingLevels

buildingLevels: readonly string[];

buildingMinHeight

buildingMinHeight: readonly string[];

buildingName

buildingName: readonly string[];

buildingSubclass

buildingSubclass: readonly string[];

landcoverClass

landcoverClass: readonly string[];

landcoverDensity

landcoverDensity: readonly string[];

landcoverSubclass

landcoverSubclass: readonly string[];

transportationClass

transportationClass: readonly string[];

transportationLanes

transportationLanes: readonly string[];

transportationLayer

transportationLayer: readonly string[];

transportationLink

transportationLink: readonly string[];

transportationOneway

transportationOneway: readonly string[];

transportationService

transportationService: readonly string[];

transportationSubclass

transportationSubclass: readonly string[];

transportationSurface

transportationSurface: readonly string[];

transportationWidth

transportationWidth: readonly string[];

tunnel

tunnel: readonly string[];

waterClass

waterClass: readonly string[];

waterWidth

waterWidth: readonly string[];

TerrainPackageAttribution

Properties

license

license: string;

licenseUrl?

optional licenseUrl?: string;

sourceUrl?

optional sourceUrl?: string;

text

text: string;

TerrainPackageDescriptor

Properties

attribution

attribution: TerrainPackageAttribution[];

coordinateSpace

coordinateSpace: TerrainPackageCoordinateSpace;

elevation

elevation: object;

encoding

encoding: "png16";

height

height: object;

height.max

max: number;

height.min

min: number;

source

source: TerrainPackageArchiveSource;

features?

optional features?: object;

buildingDetail?

optional buildingDetail?: object;

Finer tiles for building footprints and places, same encoding and profile. Basemaps merge and drop buildings below their last zoom (Protomaps keeps almost none below 15), so a package may carry that zoom separately, often only where people look. Feature tiles a level or two coarser take their buildings from it; tiles it does not cover keep their own.

buildingDetail.level

level: number;

buildingDetail.source

source: TerrainPackageArchiveSource;

encoding

encoding: "mvt";

layers

layers: ("water" | "transportation" | "building" | "poi")[];

profile?

optional profile?: "protomaps-basemap@1";

source

source: TerrainPackageArchiveSource;

files

files: TerrainPackageFileRecord[];

format

format: "molen/terrain-package@1";

landcover?

optional landcover?: object;

encoding

encoding: "mvt" | "png8";

layer

layer: "landcover";

profile?

optional profile?: "protomaps-basemap@1";

source

source: TerrainPackageArchiveSource;

models?

optional models?: object;

index

index: string;

name

name: string;

preset?

optional preset?: "1gb" | "5gb" | "20gb";

provenance

provenance: object;

compiler

compiler: string;

compilerVersion

compilerVersion: string;

sources

sources: TerrainPackageSourceRecord[];

surface?

optional surface?: object;

layers?

optional layers?: TerrainLayer[];

seaLevel?

optional seaLevel?: number;

tileMatrix

tileMatrix: object;

maxLevel

maxLevel: number;

minLevel

minLevel: number;

rootTiles

rootTiles: [number, number];

scheme

scheme: "xyz" | "tms";

tileResolution

tileResolution: number;

version

version: string;

TerrainPackageFileRecord

Properties

bytes

bytes: number;

path

path: string;

sha256

sha256: string;

TerrainPackageFrame

The local metric frame a host renders a projected-Earth package in. World X/Z are Web Mercator meters multiplied by cos(latitude), which is exact at latitude and drifts by about 1.75% × tan(latitude) per degree of latitude away from it (1% at 30°, 2% at 48°, 3% at 60°). Omitted, the frame sits at the center latitude of the package bounds: right for a regional package, but a worldwide package centers on the equator, so a host viewing a place should pass that place's latitude and re-anchor (rebuild its streams on a new frame) after moving more than about a degree north or south.

Properties

latitude

latitude: number;

TerrainPackageSourceRecord

Properties

id

id: string;

release

release: string;

sha256?

optional sha256?: string;

TerrainPoiFeature

A mapped business, amenity, or individual outdoor object.

Extends

TerrainStructureIdentity

Properties

brand?

optional brand?: string;

brandId?

optional brandId?: string;

Stable source brand identifier, when supplied by an enriched source.

capacity?

optional capacity?: number;

class

class: string;

crownDiameter?

optional crownDiameter?: number;

heading?

optional heading?: number;

Rotation about +Y in radians; local model front is +Z.

Overrides

TerrainStructureIdentity.heading

height?

optional height?: number;

Measurements in world units; absence means unknown.

id?

optional id?: string | number;

leafType?

optional leafType?: string;

name?

optional name?: string;

point

point: TerrainSemanticPoint;

subclass?

optional subclass?: string;

tags?

optional tags?: Record<string, string>;

Inherited from

TerrainStructureIdentity.tags

wikidata?

optional wikidata?: string;

Inherited from

TerrainStructureIdentity.wikidata

TerrainPyramidDescriptor

Coordinate-independent contract for a square planar terrain pyramid.

Earth packages, invented worlds, and generated game maps all adapt to this shape. Geographic projection and archive addressing deliberately stay outside this type.

Properties

coverage?

optional coverage?: [number, number, number, number];

Optional data coverage inside the root square: [minX,minZ,maxX,maxZ].

height

height: object;

max

max: number;

min

min: number;

layers

layers: TerrainLayer[];

maxLevel

maxLevel: number;

metersPerUnit?

optional metersPerUnit?: number;

World meters per unit of the source's projected space (see TerrainDescriptor). Origin, rootSize, and coverage are already multiplied by it; absent = 1.

minLevel

minLevel: number;

name

name: string;

origin

origin: [number, number];

World X/Z of the north-west/root minimum corner.

rootSize

rootSize: number;

Width and depth of the level-zero square, in world units.

skirts

skirts: boolean;

tileResolution

tileResolution: number;

TerrainPyramidTileAddress

Address of one square tile in a root-quad terrain pyramid.

Properties

level

level: number;

x

x: number;

z

z: number;

TerrainSemanticOverzoomOptions

Properties

buffer?

optional buffer?: number;

Clip margin around the descendant in tile units (default 1/64, about one road width).

TerrainSemanticPolygon

Properties

holes?

optional holes?: TerrainSemanticRing[];

outer

outer: TerrainSemanticRing;

Closed or open outer ring. The renderer closes it implicitly.

TerrainSemanticTile

Properties

buildings

buildings: TerrainBuildingFeature[];

buildingsGeneralized?

optional buildingsGeneralized?: boolean;

Source merged/generalized footprints cannot reliably identify individual premises.

buildingSourceLevel?

optional buildingSourceLevel?: number;

Level the building footprints were read at, when finer than the tile (composed from a building-detail sidecar). Their clip buffer is the source's buffer divided by 2^(buildingSourceLevel - tile level); tile-edge ownership rules should narrow theirs to match.

format

format: "molen/terrain-semantics@1";

landcover

landcover: TerrainLandcoverFeature[];

pois?

optional pois?: TerrainPoiFeature[];

transportation

transportation: TerrainTransportationFeature[];

water

water: TerrainWaterFeature[];

TerrainSemanticTileDecodeContext

Properties

address

address: TerrainPyramidTileAddress;

Logical XYZ-style address used by the terrain renderer (+Z south).

content

content: 
  | TerrainPackageSemanticContent
  | "all";

encoding

encoding: "mvt" | "png8";

layers

layers: readonly string[];

Source layer names declared by terrain-package.json.

TerrainSemanticTileDecoder

Source-format adapter implemented by a pipeline/app-specific MVT or PNG8 decoder.

Extended by

TerrainMvtSemanticDecoder

Methods

decode()

decode(data, context): 
  | TerrainSemanticTile
| Promise<TerrainSemanticTile>;

Parameters

data

Uint8Array

context

TerrainSemanticTileDecodeContext

Returns

| TerrainSemanticTile | Promise<TerrainSemanticTile>

TerrainSemanticTileLoader

Anything that loads semantic tiles by pyramid address.

Methods

load()

load(address, signal): Promise<TerrainSemanticTile | undefined>;

Parameters

address

TerrainStructureIdentity.heading

signal

AbortSignal

Returns

Promise<TerrainSemanticTile | undefined>

TerrainStreamingOptions

Properties

loadRadius

loadRadius: number;

Radius around the camera, measured in chunks, that should be resident.

maxConcurrentLoads

maxConcurrentLoads: number;

Maximum number of height-tile requests in flight at once.

maxResidentTiles

maxResidentTiles: number;

Hard ceiling for decoded resident height tiles and their meshes.

unloadRadius

unloadRadius: number;

Larger hysteresis radius; resident tiles outside it may be evicted.

TerrainStructureIdentity

Source identity and a bounded set of public map classification tags.

Properties

heading?

optional heading?: number;

Rotation about +Y in radians; authored model front is +Z.

tags?

optional tags?: Record<string, string>;

wikidata?

optional wikidata?: string;

TerrainTileAddress

Address of one fixed-grid terrain chunk.

Properties

x

x: number;

z

z: number;

TerrainTileArchive

Extended by

TerrainArchiveSetArchive

Methods

getHeader()?

optional getHeader(): Promise<TerrainArchiveHeader>;

Returns

Promise<TerrainArchiveHeader>

getZxy()

getZxy(
   level, 
   x, 
   y, 
   signal?
): Promise<TerrainArchiveTile | undefined>;

Parameters

level

number

x

number

y

number

signal?

AbortSignal

Returns

Promise<TerrainArchiveTile | undefined>

TerrainTransportationFeature

Source identity and a bounded set of public map classification tags.

Extends

TerrainStructureIdentity

Properties

bridge?

optional bridge?: boolean;

bridgeConnections?

optional bridgeConnections?: object[];

Join an inferred bridge or connected ground approach to an authored deck. Ground approaches blend back to terrain without generating bridge slabs. Points use normalized tile coordinates.

elevation

elevation: number;

point

point: TerrainSemanticPoint;

radius

radius: number;

class

class: string;

deckElevation?

optional deckElevation?: number;

Optional surveyed bridge deck elevation in absolute world Y units.

heading?

optional heading?: number;

Rotation about +Y in radians; authored model front is +Z.

Inherited from

id?

optional id?: string | number;

lanes?

optional lanes?: number;

layer?

optional layer?: number;

Grade separation; different layers do not form junctions.

lines

lines: TerrainSemanticLine[];

link?

optional link?: boolean;

Turning connector or ramp, rather than an independent junction approach.

name?

optional name?: string;

oneway?

optional oneway?: boolean;

service?

optional service?: string;

Source service subtype, for example parking_aisle or driveway.

subclass?

optional subclass?: string;

Finer category, e.g. residential, parking_aisle or footway.

surface?

optional surface?: string;

tags?

optional tags?: Record<string, string>;

Inherited from

TerrainStructureIdentity.tags

tunnel?

optional tunnel?: boolean;

width?

optional width?: number;

Suggested rendered width in world units (meters for Earth packages).

wikidata?

optional wikidata?: string;

Inherited from

TerrainStructureIdentity.wikidata

TerrainWaterFeature

Properties

class?

optional class?: string;

id?

optional id?: string | number;

lines?

optional lines?: TerrainSemanticLine[];

polygons?

optional polygons?: TerrainSemanticPolygon[];

width?

optional width?: number;

Suggested rendered width for linear waterways, in world units.

WebMercatorTileAddress

Properties

level

level: number;

x

x: number;

y

y: number;

Type Aliases

PmtilesTileCompression

type PmtilesTileCompression = "none" | "gzip" | "brotli" | "zstd";

Compression already applied to every tile payload.

PmtilesTileType

type PmtilesTileType = "mvt" | "png" | "jpeg" | "webp" | "avif" | "unknown";

Tile payload types, with their PMTiles header codes.

TerrainArchiveSetRoute

type TerrainArchiveSetRoute = 
  | {
  base: TerrainArchiveSetBase;
  kind: "base";
}
  | {
  entry: TerrainArchiveSetEntry;
  kind: "archive";
}
  | {
  cell: string;
  id: string;
  kind: "cell";
  tier: TerrainArchiveSetGeohashTier;
  url: string;
};

Which archive serves a tile: the base, one detail entry, or one geohash cell's archive.

TerrainArchiveSetTileType

type TerrainArchiveSetTileType = "png" | "mvt";

Payload type shared by every archive in a set.

TerrainPackageArchiveSource

type TerrainPackageArchiveSource = 
  | {
  kind: "pmtiles";
  path: string;
}
  | {
  kind: "pmtiles";
  url: string;
}
  | {
  kind: "pmtiles-set";
  path: string;
}
  | {
  kind: "pmtiles-set";
  url: string;
};

TerrainPackageCoordinateSpace

type TerrainPackageCoordinateSpace = 
  | {
  bounds: [number, number, number, number];
  kind: "local";
  units: "meters";
}
  | {
  bounds: [number, number, number, number];
  crs: "EPSG:3857" | "EPSG:4326";
  ellipsoid: "WGS84";
  kind: "geospatial";
};

TerrainPackageSemanticContent

type TerrainPackageSemanticContent = "landcover" | "features";

TerrainPackageSemanticProfile

type TerrainPackageSemanticProfile = "protomaps-basemap@1";

TerrainSemanticBounds

type TerrainSemanticBounds = [number, number, number, number];

TerrainSemanticLine

type TerrainSemanticLine = TerrainSemanticPoint[];

TerrainSemanticPoint

type TerrainSemanticPoint = [number, number];

TerrainSemanticRing

type TerrainSemanticRing = TerrainSemanticPoint[];

TransportKind

type TransportKind = "street" | "service" | "path" | "rail" | "motorway";

Painter/simulation class of a transportation feature.

Variables

BRIDGE_SURFACE_LIFT

const BRIDGE_SURFACE_LIFT: 4 = 4;

Extra height the painter adds to a bridge road's nominal elevation, in metres.

DEGENERATE_RING_AREA

const DEGENERATE_RING_AREA: number;

Normalized-area floor below which a ring encloses nothing a triangulator can use. Tile-local [u, v] units, so this is ~1e-6 of a tile edge squared — far below any mapped real feature at any zoom, and above the float noise of a collinear ring.

GEOHASH_MAX_PRECISION

const GEOHASH_MAX_PRECISION: 6 = 6;

Longest geohash these helpers accept (32^6 cells, about 1.2 × 0.6 km).

PATH_SURFACE_LIFT

const PATH_SURFACE_LIFT: 0.43 = .43;

Height of a painted path surface above the rendered terrain, in metres.

PMTILES_HEADER_BYTES

const PMTILES_HEADER_BYTES: 127 = 127;

PMTiles v3 header size in bytes.

ROAD_SURFACE_LIFT

const ROAD_SURFACE_LIFT: 0.32 = .32;

Height of a painted street surface above the rendered terrain, in metres.

WEB_MERCATOR_EARTH_RADIUS_METERS

const WEB_MERCATOR_EARTH_RADIUS_METERS: number;

Navigation/data-projection helpers for the projected-Earth terrain adapter.

These functions map WGS84 longitude/latitude to the engine's planar convention: +X east, +Z south, meters. They are intended for package compilation, navigation, and rendering—not as deterministic simulation math. The renderer rebases this large projected frame near the camera.

WEB_MERCATOR_HALF_WORLD_METERS

const WEB_MERCATOR_HALF_WORLD_METERS: number;

WEB_MERCATOR_MAX_LATITUDE

const WEB_MERCATOR_MAX_LATITUDE: number;

Functions

assertTerrainPyramidAddress()

function assertTerrainPyramidAddress(descriptor, address): void;

Parameters

descriptor

address

Returns

void

assertTerrainSemanticTile()

function assertTerrainSemanticTile(tile): void;

Fail early when a source decoder violates the renderer's normalized semantic contract.

Parameters

tile

Returns

void

bridgeDeckHeightFn()

function bridgeDeckHeightFn(
   path, 
   groundAt, 
   options
): (x, z) => number;

A tile fragment cannot establish the elevation of an entire bridge. Use a bank-to-bank profile for complete spans and deterministic terrain clearance at clipped ends. groundAt samples terrain in the same frame as path.

Parameters

path

groundAt

(x, z) => number

options

BridgeDeckOptions

Returns

(x, z) => number

buildPmtilesDirectories()

function buildPmtilesDirectories(entries, rootBudget?): PmtilesDirectories;

Split directory entries (sorted by tile id) into a root that fits the reader's initial fetch plus leaf directories. rootBudget is the compressed-root byte budget.

Parameters

entries

readonly PmtilesDirectoryEntry[]

rootBudget?

number

Returns

PmtilesDirectories

clampBounds()

function clampBounds(
   bounds, 
   lo?, 
   hi?
): TerrainSemanticBounds;

Clamp bounds into [lo, hi] on both axes.

Parameters

bounds

TerrainSemanticBounds

lo?

number

hi?

number

Returns

TerrainSemanticBounds

composeTerrainBuildingDetail()

function composeTerrainBuildingDetail(
   base, 
   address, 
   detailLevel, 
   children
): TerrainSemanticTile | undefined;

Compose base's buildings and places from its descendants at detailLevel. children lists every descendant of address at that level (missing tiles as tile: undefined). With no descendant present, base is returned unchanged.

Parameters

base

TerrainSemanticTile | undefined

address

detailLevel

number

children

readonly TerrainBuildingDetailChild[]

Returns

TerrainSemanticTile | undefined

createBuildingDetailTerrainSemanticSource()

function createBuildingDetailTerrainSemanticSource(
   base, 
   detail, 
   options
): TerrainSemanticTileLoader;

Wrap a feature source so tiles within maxDepth levels of the detail level take their buildings and places from detail (see the module comment). Tiles at or finer than the detail level take them from the covering detail tile; coarser tiles, and tiles the sidecar does not cover, are served by base unchanged.

Parameters

createEmptyTerrainSemanticTile()

function createEmptyTerrainSemanticTile(): TerrainSemanticTile;

Allocate a normalized empty tile without sharing mutable collection instances.

Returns

TerrainSemanticTileLoader

createOverzoomTerrainSemanticSource()

function createOverzoomTerrainSemanticSource(
   source, 
   maxLevel, 
   options?
): TerrainSemanticTileLoader;

Wrap a semantic source so levels above maxLevel load their maxLevel ancestor and overzoom it. Recently decoded ancestors are kept (cacheSize, default 32), since a camera refining one ancestor asks for its descendants within moments of each other.

Parameters

source

maxLevel

number

options?

TerrainSemanticOverzoomOptions & object

Returns

TerrainSemanticTileLoader

createPmtilesPrefix()

function createPmtilesPrefix(
   tiles, 
   tileDataLength, 
   options
): Uint8Array;

Everything that precedes the tile data of a clustered archive: header, root directory, metadata and leaf directories. Write the returned bytes, then the tile payloads in tiles order — the streaming path for archives too large to hold in memory.

Parameters

tiles

readonly PmtilesTileRecord[]

tileDataLength

number

options

PmtilesPrefixOptions

Returns

Uint8Array

createProtomapsTerrainMvtDecoder()

function createProtomapsTerrainMvtDecoder(options?): TerrainMvtSemanticDecoder;

Preset matching the world.pmtiles Protomaps basemap this repo's sample package ships.

Parameters

options?

Omit<TerrainMvtSemanticDecoderOptions, "layers"> & object

Returns

TerrainMvtSemanticDecoder

createTerrainArchiveSetRouter()

function createTerrainArchiveSetRouter(descriptor): TerrainArchiveSetRouter;

Build the tile → archive router. Throws when two archives claim one partition cell, when a quadtree-partitioned set has no partitionLevel, or when geohash tiers overlap.

Parameters

descriptor

TerrainArchiveSetDescriptor

Returns

TerrainArchiveSetRouter

createTerrainMvtSemanticDecoder()

function createTerrainMvtSemanticDecoder(options?): TerrainMvtSemanticDecoder;

Decode configured MVT source layers into renderer-neutral tile-local semantic geometry.

Parameters

options?

TerrainMvtSemanticDecoderOptions

Returns

TerrainMvtSemanticDecoder

decodePng16()

function decodePng16(png): Gray16;

Decode a 16-bit grayscale PNG to a normalized [0,1] grid.

Parameters

png

Uint8Array

Returns

Gray16

encodeGeohash()

function encodeGeohash(
   longitude, 
   latitude, 
   precision
): string;

The geohash of precision characters holding a point (west and south edges are inside).

Parameters

longitude

number

latitude

number

precision

number

Returns

string

encodePng16()

function encodePng16(img): Uint8Array;

Encode a normalized grayscale grid as a 16-bit grayscale PNG.

Parameters

img

Gray16

Returns

Uint8Array

encodeTerrainArchiveSetCells()

function encodeTerrainArchiveSetCells(cells): string;

Encode geohash cells (all of one precision) as a tier's run-length cells list.

Parameters

cells

Iterable<string>

Returns

string

encodeTerrainArchiveSetPartitions()

function encodeTerrainArchiveSetPartitions(indices): string;

Encode partition indices as a sorted run-length list ([9, 3, 4, 5] → "3-5,9").

Parameters

indices

Iterable<number>

Returns

string

generateHeightmap()

function generateHeightmap(opts): Gray16;

Generate a normalized heightmap grid.

Parameters

opts

HeightmapGenOptions

Returns

Gray16

generateHeightmapPng()

function generateHeightmapPng(opts): Uint8Array;

Generate a heightmap and encode it as a 16-bit grayscale PNG.

Parameters

opts

HeightmapGenOptions

Returns

Uint8Array

geohashBounds()

function geohashBounds(hash): [number, number, number, number];

A geohash's [west, south, east, north] in degrees.

Parameters

hash

string

Returns

[number, number, number, number]

geohashFromIndex()

function geohashFromIndex(index, precision): string;

The geohash of precision characters with this index.

Parameters

index

number

precision

number

Returns

string

geohashIndex()

function geohashIndex(hash): number;

A geohash's characters read as one base-32 number.

Parameters

hash

string

Returns

number

groupTransportationFeatures()

function groupTransportationFeatures(features): TerrainTransportationFeature[];

Merge features whose properties are identical (ignoring id), concatenating their lines. Protomaps splits one road into many features; grouping lets fragments join end to end.

Parameters

features

readonly TerrainTransportationFeature[]

Returns

TerrainTransportationFeature[]

heightfieldFromPng()

function heightfieldFromPng(descriptor, png): Heightfield;

Build a Heightfield covering the whole terrain from a single decoded heightmap PNG.

Parameters

descriptor

png

Uint8Array

Returns

heightfieldSubtileFromPng()

function heightfieldSubtileFromPng(
   descriptor, 
   address, 
   png, 
   subdivision, 
   offset
): Heightfield;

Decode one ancestor PNG16 tile and crop/resample the requested descendant into a tile-scoped heightfield. Adjacent descendants share the same ancestor samples at their common border.

Parameters

descriptor

address

png

Uint8Array

subdivision

number

offset

Returns

heightfieldTileFromPng()

function heightfieldTileFromPng(
   descriptor, 
   address, 
   png
): Heightfield;

Build one tile-scoped Heightfield from a streamed height tile.

Parameters

descriptor

address

png

Uint8Array

Returns

inferLaneCount()

function inferLaneCount(feature, width): number;

Total lane count across both directions, matching the painted lane lines.

Parameters

feature

width

number

Returns

number

isDegenerateRing()

function isDegenerateRing(ring): boolean;

A ring that cannot bound a face: fewer than three distinct vertices, or an enclosed area below DEGENERATE_RING_AREA (collinear or repeated points). Triangulators — three.js earcut among them — fault or emit nothing for these, so contract validation and mesh adapters share this one definition.

Parameters

ring

readonly TerrainSemanticPoint[]

Returns

boolean

isPaintedTransport()

function isPaintedTransport(feature, options): boolean;

Whether the painter draws this feature at all (tunnels, crossings and unstyled sidewalks are skipped).

Parameters

feature

options

sidewalks

boolean

Returns

boolean

isTransportLink()

function isTransportLink(feature): boolean;

True for slip roads and ramps.

Parameters

feature

Returns

boolean

joinTerrainLines()

function joinTerrainLines(lines): TerrainSemanticLine[];

Join degree-two source fragments so profiles and dash phases continue through tile features.

Parameters

lines

readonly TerrainSemanticLine[]

Returns

TerrainSemanticLine[]

lineSegmentIndex()

function lineSegmentIndex(path, distance): number;

Index of the segment [i, i + 1] containing distance (clamped to the path).

Parameters

path

distance

number

Returns

number

normalizeRing()

function normalizeRing(ring): TerrainSemanticRing;

Drop a repeated closing vertex and consecutive duplicates.

Parameters

ring

TerrainSemanticRing

Returns

TerrainSemanticRing

overzoomTerrainSemanticTile()

function overzoomTerrainSemanticTile(
   tile, 
   from, 
   to, 
   options?
): TerrainSemanticTile;

Re-express an ancestor's semantic tile for one of its descendants. from must be an ancestor of (or equal to) to.

Parameters

tile

from

to

TerrainSemanticOverzoomOptions

options?

Returns

parseTerrainArchiveSetPartitions()

function parseTerrainArchiveSetPartitions(ranges): number[];

Parse a run-length partition list ("3-5,9" → [3, 4, 5, 9]).

Parameters

ranges

string

Returns

number[]

pathBounds()

function pathBounds(path): [number, number, number, number];

Axis-aligned bounds [minX, minZ, maxX, maxZ] of a path's vertices.

Parameters

path

Returns

[number, number, number, number]

pmtilesTileId()

function pmtilesTileId(
   z, 
   x, 
   y
): number;

The PMTiles v3 tile id (Hilbert order across zoom levels) of an XYZ tile.

Parameters

z

number

x

number

y

number

Returns

number

pointInPolygon()

function pointInPolygon(point, polygon): boolean;

Inside the outer ring and outside every hole.

Parameters

point

TerrainSemanticPoint

polygon

TerrainSemanticPolygon

Returns

boolean

pointInRing()

function pointInRing(point, ring): boolean;

Even-odd containment test against one ring.

Parameters

point

TerrainSemanticPoint

ring

readonly TerrainSemanticPoint[]

Returns

boolean

polygonArea()

function polygonArea(polygon): number;

Outer area minus hole areas, never negative.

Parameters

polygon

TerrainSemanticPolygon

Returns

number

polygonBounds()

function polygonBounds(polygon): TerrainSemanticBounds;

Unclamped bounds of the outer ring (buffered geometry may exceed [0, 1]).

Parameters

polygon

TerrainSemanticPolygon

Returns

TerrainSemanticBounds

projectedToWorld()

function projectedToWorld(
   metersPerUnit, 
   x, 
   z
): [number, number];

Projected (Mercator) X/Z → world meters, given the package's metersPerUnit.

Parameters

metersPerUnit

number

x

number

z

number

Returns

[number, number]

registerTerrainSchemas()

function registerTerrainSchemas(): void;

Returns

void

renderedGroundSampler()

function renderedGroundSampler(
   heightfield, 
   origin, 
   tileSize, 
   surfaceResolution?
): (x, z) => number;

Build a world-space sampler for one tile's rendered ground. Points outside the tile clamp to its edge cells. Vertex heights are cached, so the sampler is cheap after the first queries.

Parameters

heightfield

RenderedGroundSource

origin

readonly [number, number]

tileSize

number

surfaceResolution?

number

Returns

(x, z) => number

ringArea()

function ringArea(ring): number;

Parameters

ring

readonly TerrainSemanticPoint[]

Returns

number

ringSignedArea()

function ringSignedArea(ring): number;

Twice-signed shoelace area halved; positive when the ring winds +u then +v.

Parameters

ring

readonly TerrainSemanticPoint[]

Returns

number

roadWidth()

function roadWidth(className, explicit?): number;

Road ribbon width in world units for a transportation class.

Parameters

className

string

explicit?

number

Returns

number

sampleTerrainLine()

function sampleTerrainLine(
   path, 
   distance, 
   offset?
): TerrainLineSample;

Sample a path by arc length; offset edges interpolate shared, bounded miter joins. Closed paths use the same join at both ends, avoiding a wedge at the closure.

Parameters

path

TerrainArchiveSetGeohashTier

distance

number

offset?

number

Returns

TerrainLineSample

serializePmtilesDirectory()

function serializePmtilesDirectory(entries): Uint8Array;

Encode a directory in the uncompressed PMTiles v3 column layout.

Parameters

entries

readonly PmtilesDirectoryEntry[]

Returns

Uint8Array

terrainArchiveSetTierCells()

function terrainArchiveSetTierCells(tier): string[];

The cells of a geohash tier, as geohashes (expands the run-length list).

Parameters

tier

Returns

string[]

terrainLinePath()

function terrainLinePath(line, tileSize): TerrainLinePath;

Convert normalized tile geometry once; collapse duplicate vertices.

Parameters

line

TerrainSemanticLine

tileSize

number

Returns

TerrainPackageDescriptor

terrainPackageFrameLatitude()

function terrainPackageFrameLatitude(pkg, frame?): number | undefined;

Latitude the package's metric frame is exact at: frame.latitude when given, else the center of the package bounds. Undefined for a local (already metric) package.

Parameters

pkg

frame?

TerrainPackageFrame

Returns

number | undefined

terrainPackageMetersPerUnit()

function terrainPackageMetersPerUnit(pkg, frame?): number;

Ground meters per projected unit for a package in a frame: cos(frame latitude) for a projected-Earth package, 1 for a local package.

Parameters

pkg

TerrainPackageDescriptor

frame?

TerrainPackageFrame

Returns

number

terrainPyramidAddressAt()

function terrainPyramidAddressAt(
   descriptor, 
   level, 
   x, 
   z
): TerrainPyramidTileAddress | undefined;

Parameters

descriptor

level

number

x

number

z

number

Returns

TerrainPyramidTileAddress | undefined

terrainPyramidAncestor()

function terrainPyramidAncestor(address, level): TerrainPyramidTileAddress;

Parameters

address

level

number

Returns

terrainPyramidParent()

function terrainPyramidParent(address): TerrainPyramidTileAddress | undefined;

Parameters

address

Returns

TerrainPyramidTileAddress | undefined

terrainPyramidTileCount()

function terrainPyramidTileCount(level): number;

Parameters

level

number

Returns

number

terrainPyramidTileKey()

function terrainPyramidTileKey(address): string;

Parameters

address

Returns

string

terrainPyramidTileOrigin()

function terrainPyramidTileOrigin(descriptor, address): [number, number];

Parameters

descriptor

address

Returns

[number, number]

terrainPyramidTileSize()

function terrainPyramidTileSize(descriptor, level): number;

Parameters

descriptor

level

number

Returns

number

terrainTileGeohash()

function terrainTileGeohash(
   level, 
   x, 
   y, 
   precision
): string;

The geohash cell a Web Mercator XYZ tile (+y south) belongs to in a geohash-partitioned archive set: the cell holding the tile's center.

Parameters

level

number

x

number

y

number

precision

number

Returns

string

terrainTileKey()

function terrainTileKey(address): string;

Parameters

address

Returns

string

terrainTileOrigin()

function terrainTileOrigin(descriptor, address): [number, number];

Parameters

descriptor

address

Returns

[number, number]

transportKind()

function transportKind(feature): TransportKind;

Classify a feature from its class, subclass and service tags.

Parameters

feature

Returns

TransportKind

transportSurfaceLift()

function transportSurfaceLift(kind, bridge?): number;

Nominal painted surface elevation above terrain (bridges add BRIDGE_SURFACE_LIFT).

Parameters

kind

TransportKind

bridge?

boolean

Returns

number

transportWidth()

function transportWidth(
   feature, 
   kind?, 
   scale?
): number;

Carriageway width in metres, matching the painter (capped at 80 m).

Parameters

feature