Skip to content

@bendyline/molen-terrain/kernel ​

Molen terrain capability: heightfield sampling (kernel) and chunked LOD meshing (client).

ts
import { /* … */ } from '@bendyline/molen-terrain/kernel';

Classes ​

Heightfield ​

Constructors ​

Constructor ​
ts
new Heightfield(
   grid, 
   cols, 
   rows, 
   opts
): Heightfield;

grid holds normalized [0,1] heights, row-major, length = cols*rows.

Parameters ​
grid ​

Float32Array

cols ​

number

rows ​

number

opts ​

HeightfieldOptions

Returns ​

Heightfield

Properties ​

cellSize ​
ts
readonly cellSize: [number, number];

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

cols ​
ts
readonly cols: number;
heightRange ​
ts
readonly heightRange: object;

The height range the normalized grid maps onto.

max ​
ts
max: number;
min ​
ts
min: number;
origin ​
ts
readonly origin: [number, number];

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

rows ​
ts
readonly rows: number;
worldSize ​
ts
readonly worldSize: [number, number];

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

Methods ​

copySamples() ​
ts
copySamples(): Float32Array;

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

Returns ​

Float32Array

heightExtent() ​
ts
heightExtent(): object;

The lowest and highest ground actually in this field, unlike the range it is encoded in.

Returns ​

object

max ​
ts
max: number;
min ​
ts
min: number;
normalAt() ​
ts
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() ​
ts
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() ​
ts
sampleHeight(x, z): number;

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

Parameters ​
x ​

number

z ​

number

Returns ​

number

slopeAt() ​
ts
slopeAt(x, z): number;

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

Parameters ​
x ​

number

z ​

number

Returns ​

number

toRapierHeightfield() ​
ts
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 ​
ts
approachLift: number;

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

approachProfile? ​
ts
optional approachProfile?: readonly object[];

Absolute along-path deck/approach samples, shared by painted surfaces and traffic graphs.

bounds? ​
ts
optional bounds?: readonly [number, number, number, number];

Where groundAt is the real ground, [minX, minZ, maxX, maxZ] in the path's frame (a tile's own square). Anchored samples beyond it follow the nearest sample inside, so two tiles that share an edge move a deck crossing it by the same amount.

clearance ​
ts
clearance: number;

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

connections? ​
ts
optional connections?: readonly object[];

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

connects ​
ts
connects: readonly [boolean, boolean];

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

deckElevation? ​
ts
optional deckElevation?: number;

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

groundApproach? ​
ts
optional groundApproach?: boolean;

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


GradeSeparationOptions ​

Properties ​

anchored? ​
ts
optional anchored?: boolean;

groundAt is not the ground the roads will be drawn on (it reads one elevation level for a tile and its neighbors alike): record with each sample the ground it was graded over, so the profile can be moved onto the real ground where it rests on it. See TerrainBridgeProfileSample.anchor.

context? ​
ts
optional context?: readonly TerrainTransportationFeature[];

Ways that cross, join and carry approaches like any other but are not returned: the neighboring tiles' roads, in the frame of features.

endTolerance? ​
ts
optional endTolerance?: number;

Join line ends lying within this many meters of each other without sharing a vertex, as the two halves of a road cut at a tile edge do (default 0: only shared vertices join).

extend? ​
ts
optional extend?: number;

Carry each returned way's profile on into the context way joined to its end, this many meters: a tile's road reaches a little past its edge, into the half its neighbor holds.

spacing? ​
ts
optional spacing?: number;

Meters between profile samples (default 4).


Gray16 ​

Properties ​

data ​
ts
data: Float32Array;

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

height ​
ts
height: number;
width ​
ts
width: number;

HeightfieldCollider ​

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

Properties ​

center ​
ts
center: [number, number, number];

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

heights ​
ts
heights: Float32Array;

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

ncols ​
ts
ncols: number;
nrows ​
ts
nrows: number;
scale ​
ts
scale: [number, number, number];

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


HeightfieldOptions ​

Properties ​

height ​
ts
height: object;

Height value range the normalized grid maps onto.

max ​
ts
max: number;
min ​
ts
min: number;
origin ​
ts
origin: [number, number];

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

validated? ​
ts
optional validated?: boolean;

The samples came from another field (copySamples, a worker's reply), so they are known to be finite: skip checking each one. A full-resolution tile is a quarter of a million samples, checked on the main thread as each tile arrived.

worldSize ​
ts
worldSize: [number, number];

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


HeightmapGenOptions ​

Properties ​

frequency? ​
ts
optional frequency?: number;

Base noise frequency across the map.

island? ​
ts
optional island?: boolean;

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

octaves? ​
ts
optional octaves?: number;
seed ​
ts
seed: number;
size ​
ts
size: number;

PmtilesArchiveOptions ​

Extended by ​

Properties ​

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

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

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

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

metadata? ​
ts
optional metadata?: Record<string, unknown>;

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

tileCompression? ​
ts
optional tileCompression?: PmtilesTileCompression;

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

tileType ​
ts
tileType: PmtilesTileType;

PmtilesDirectories ​

Properties ​

leafDirectoryCount ​
ts
leafDirectoryCount: number;
leaves ​
ts
leaves: Uint8Array;

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

root ​
ts
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 ​
ts
length: number;
offset ​
ts
offset: number;
runLength ​
ts
runLength: number;
tileId ​
ts
tileId: number;

PmtilesPrefixOptions ​

Extends ​

Properties ​

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

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

Inherited from ​

PmtilesArchiveOptions.bounds

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

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

Inherited from ​

PmtilesArchiveOptions.center

maxZoom ​
ts
maxZoom: number;
metadata? ​
ts
optional metadata?: Record<string, unknown>;

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

Inherited from ​

PmtilesArchiveOptions.metadata

minZoom ​
ts
minZoom: number;
tileCompression? ​
ts
optional tileCompression?: PmtilesTileCompression;

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

Inherited from ​

PmtilesArchiveOptions.tileCompression

tileType ​
ts
tileType: PmtilesTileType;
Inherited from ​

PmtilesArchiveOptions.tileType


PmtilesTileRecord ​

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

Properties ​

byteLength ​
ts
byteLength: number;
tileId ​
ts
tileId: number;

PmtilesWriterTile ​

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

Properties ​

data ​
ts
data: Uint8Array;
x ​
ts
x: number;
y ​
ts
y: number;
z ​
ts
z: number;

RenderedGroundSource ​

The part of a heightfield the sampler reads.

Properties ​

cols ​
ts
readonly cols: number;

Methods ​

sampleHeight() ​
ts
sampleHeight(x, z): number;
Parameters ​
x ​

number

z ​

number

Returns ​

number


RoadEarthworkLine ​

A way to grade, in world meters: stations along its centerline and the bench it wants.

Properties ​

bounds ​
ts
bounds: [number, number, number, number];

[minX, minZ, maxX, maxZ] of the stations.

halfWidth ​
ts
halfWidth: number;

Half the width leveled: the carriageway with its shoulders or sidewalks.

heights ​
ts
heights: Float32Array;

Profile height at each station, read on first use and kept (NaN until then): the lines of one tile are graded into that tile and each of its neighbors.

points ​
ts
points: Float64Array;

World X/Z of each station: x0, z0, x1, z1, and so on, a few meters apart.


RoadEarthworkOptions ​

Properties ​

maxChange? ​
ts
optional maxChange?: number;

Greatest cut or fill at one point, meters (default 12).

maxSpacing? ​
ts
optional maxSpacing?: number;

Coarsest rendered grid (meters between vertices) still graded. A coarser grid cannot hold a bench narrower than a city block, and is seen from too far to tell. Default 28.

surfaceResolution? ​
ts
optional surfaceResolution?: number;

Vertices along a side of the rendered ground grid, which roads are draped on (the stream's surfaceResolution). The bench reaches a grid cell past the road's edge, since a draped road is only as level as the vertices of the cells it touches. Default: the field's columns.

water? ​
ts
optional water?: (x, z) => boolean;

Where the map has water: left as it is, except under a road's own footprint.

Parameters ​
x ​

number

z ​

number

Returns ​

boolean


RoadEarthworkPass ​

One tile's grading in steps, so a host can let a frame through between them.

Methods ​

add() ​
ts
add(line): void;

Weigh one way into the ground around it.

Parameters ​
line ​

RoadEarthworkLine

Returns ​

void

finish() ​
ts
finish(): Heightfield;

The graded field, or the field given when nothing moved.

Returns ​

Heightfield


TerrainAgricultureGrid ​

Properties ​

format ​
ts
format: "molen/agriculture-grid@1";
level ​
ts
level: number;
palette ​
ts
palette: object[];

Zero is unknown/non-crop. Other entries are conservative majority observations.

confidence? ​
ts
optional confidence?: number;
crop? ​
ts
optional crop?: string;
harvestMonth? ​
ts
optional harvestMonth?: number;
irrigated? ​
ts
optional irrigated?: boolean;
sowingMonth? ​
ts
optional sowingMonth?: number;
resolution ​
ts
resolution: number;
runs ​
ts
runs: number[];

[run length, palette index, ...], row-major north to south.

source ​
ts
source: string;
x ​
ts
x: number;
year ​
ts
year: number;
z ​
ts
z: number;

TerrainAgricultureObservation ​

Properties ​

anchor? ​
ts
optional anchor?: [number, number];

Full-field representative WGS84 longitude/latitude, retained across tile clipping.

confidence? ​
ts
optional confidence?: number;

Classification confidence in [0,1], when provided by the source.

fieldId ​
ts
fieldId: string;
harvestMonth? ​
ts
optional harvestMonth?: number;
rowAngle? ​
ts
optional rowAngle?: number;

Degrees from east towards south, modulo 180.

source ​
ts
source: string;
sowingMonth? ​
ts
optional sowingMonth?: number;

Local crop calendar from the source, when available (no hemisphere shift).

year? ​
ts
optional year?: number;

TerrainAgricultureSource ​

Properties ​

level ​
ts
level: number;
maxTileBytes? ​
ts
optional maxTileBytes?: number;

Maximum uncompressed response size; defaults to 128 KiB, at most 1 MiB.

source ​
ts
source: string;
urlTemplate ​
ts
urlTemplate: string;

Versioned XYZ JSON URL; includes {z}, {x}, {y}. Relative to the terrain package.

year ​
ts
year: number;

TerrainArchiveHeader ​

Properties ​

maxZoom ​
ts
maxZoom: number;
minZoom ​
ts
minZoom: number;
tileType? ​
ts
optional tileType?: number;

TerrainArchiveSetBase ​

The coarse archive serving every level from minLevel through maxLevel.

Properties ​

bytes? ​
ts
optional bytes?: number;
maxLevel ​
ts
maxLevel: number;
minLevel ​
ts
minLevel: number;
sha256? ​
ts
optional sha256?: string;
url ​
ts
url: string;

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


TerrainArchiveSetDescriptor ​

Properties ​

archives ​
ts
archives: TerrainArchiveSetEntry[];
base? ​
ts
optional base?: TerrainArchiveSetBase;
format ​
ts
format: "molen/archive-set@1";
geohash? ​
ts
optional geohash?: TerrainArchiveSetGeohashTier[];

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

name ​
ts
name: string;
partitionLevel? ​
ts
optional partitionLevel?: number;

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

tileType ​
ts
tileType: TerrainArchiveSetTileType;

Payload type shared by every archive in the set.


TerrainArchiveSetEntry ​

One detail archive and the partition cells it owns.

Properties ​

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

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

bytes? ​
ts
optional bytes?: number;
id ​
ts
id: string;
maxLevel ​
ts
maxLevel: number;
minLevel ​
ts
minLevel: number;
partitions ​
ts
partitions: string;

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

sha256? ​
ts
optional sha256?: string;
url ​
ts
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 ​
ts
cells: string;

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

maxLevel ​
ts
maxLevel: number;
minLevel ​
ts
minLevel: number;
precision ​
ts
precision: number;

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

url ​
ts
url: string;

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


TerrainArchiveSetRouter ​

Properties ​

descriptor ​
ts
readonly descriptor: TerrainArchiveSetDescriptor;
maxLevel ​
ts
readonly maxLevel: number;
minLevel ​
ts
readonly minLevel: number;

Coarsest and finest levels any archive in the set serves.

Methods ​

resolve() ​
ts
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 ​
ts
data: ArrayBuffer;

TerrainBridgeProfileSample ​

One sample of a bridge deck or of a road climbing to one; see bridgeApproachProfile.

Properties ​

anchor? ​
ts
optional anchor?: number;

How much of that difference the sample takes, 0 to 1: all of it on the ground, less and less along a deck away from where it lands.

elevation ​
ts
elevation: number;

Absolute Y of the road surface.

flatness ​
ts
flatness: number;

0 where the cross-section follows the ground's crossfall, 1 where it is level.

ground? ​
ts
optional ground?: number;

The ground height the profile was worked out over at this point, when that was not the ground the road is drawn on (a profile graded with neighboring tiles reads one elevation level for all of them). With anchor, whoever draws the road moves the sample by the difference, so a deck still lands exactly on the road at its end.

point ​
ts
point: TerrainSemanticPoint;

TerrainBuildingCoverage ​

Share of ground under building footprints in size x size cells across a tile.

Properties ​

cells ​
ts
cells: Float32Array;
size ​
ts
size: number;

TerrainBuildingDetailChild ​

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

Properties ​

tile ​
ts
tile: TerrainSemanticTile | undefined;
x ​
ts
x: number;
z ​
ts
z: number;

TerrainBuildingDetailOptions ​

Properties ​

cacheSize? ​
ts
optional cacheSize?: number;

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

level ​
ts
level: number;

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

maxDepth? ​
ts
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 ​

Properties ​

brand? ​
ts
optional brand?: string;
brandId? ​
ts
optional brandId?: string;
class? ​
ts
optional class?: string;
heading? ​
ts
optional heading?: number;

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

Inherited from ​

TerrainStructureIdentity.heading

height? ​
ts
optional height?: number;

World-space height above the building base.

id? ​
ts
optional id?: string | number;
layer? ​
ts
optional layer?: number;

Source stacking layer (negative = underground); informational.

levels? ​
ts
optional levels?: number;
minHeight? ​
ts
optional minHeight?: number;

World-space offset of the building base above terrain.

name? ​
ts
optional name?: string;
polygons ​
ts
polygons: TerrainSemanticPolygon[];
subclass? ​
ts
optional subclass?: string;

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

tags? ​
ts
optional tags?: Record<string, string>;
Inherited from ​

TerrainStructureIdentity.tags

wikidata? ​
ts
optional wikidata?: string;
Inherited from ​

TerrainStructureIdentity.wikidata


TerrainCultivation ​

Properties ​

color ​
ts
color: string;
crop ​
ts
crop: string;
evidence ​
ts
evidence: "mapped" | "inferred" | "classified";
fieldId ​
ts
fieldId: string;
pattern ​
ts
pattern: "plain" | "rows" | "grove";
rowAngle ​
ts
rowAngle: number;
soil ​
ts
soil: string;
source ​
ts
source: string;
spacing ​
ts
spacing: number;
stage ​
ts
stage: "sown" | "growing" | "mature" | "ripe" | "stubble";
year? ​
ts
optional year?: number;

TerrainDescriptor ​

Properties ​

chunkSize ​
ts
chunkSize: number;

Meters per chunk edge.

collision ​
ts
collision: object;

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

enabled ​
ts
enabled: boolean;
format ​
ts
format: "molen/terrain@2";
gridSize ​
ts
gridSize: [number, number];

Chunks in X,Z.

height ​
ts
height: object;
max ​
ts
max: number;
min ​
ts
min: number;
layers ​
ts
layers: TerrainLayer[];
lod ​
ts
lod: object;
distanceBands ​
ts
distanceBands: number[];
levels ​
ts
levels: number;
skirts ​
ts
skirts: boolean;
metersPerUnit? ​
ts
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 ​
ts
name: string;
origin ​
ts
origin: [number, number];

World XZ of tile (0,0) corner.

streaming ​
ts
streaming: TerrainStreamingOptions;
tileResolution ​
ts
tileResolution: number;

Height samples per chunk edge (shared borders).

tiles ​
ts
tiles: object;
heightUrl ​
ts
heightUrl: string;
splatUrl? ​
ts
optional splatUrl?: string;

TerrainGroundCrown ​

Properties ​

brush ​
ts
brush: number;

The least ground brush (landcoverDetail x, 0..1) at which this crown is painted.

radius ​
ts
radius: number;
x ​
ts
x: number;

Center, in the ground's pattern frame (world X and Z meters).

z ​
ts
z: number;

TerrainLandcoverFeature ​

Properties ​

agriculture? ​
ts
optional agriculture?: TerrainAgricultureObservation;

Agricultural observation carried by a detailed map or a retrieval sidecar.

class ​
ts
class: string;
crop? ​
ts
optional crop?: string;

Optional observed cultivation tags. Absence is unknown, never inferred irrigation.

cultivation? ​
ts
optional cultivation?: TerrainCultivation;

Resolved display recipe; generated by the regional adapter, never an observation.

density? ​
ts
optional density?: number;

Optional normalized vegetation/decorator density multiplier.

id? ​
ts
optional id?: string | number;
irrigated? ​
ts
optional irrigated?: boolean;
polygons ​
ts
polygons: TerrainSemanticPolygon[];
subclass? ​
ts
optional subclass?: string;

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

trees? ​
ts
optional trees?: string;

TerrainLayer ​

Properties ​

auto? ​
ts
optional auto?: object;

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

heightMax? ​
ts
optional heightMax?: number;
heightMin? ​
ts
optional heightMin?: number;
slopeMax? ​
ts
optional slopeMax?: number;
slopeMin? ​
ts
optional slopeMin?: number;
color? ​
ts
optional color?: string;

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

materialRef? ​
ts
optional materialRef?: string;
name ​
ts
name: string;
tiling ​
ts
tiling: number;

TerrainLinePath ​

Properties ​

distances ​
ts
distances: number[];
endJoin? ​
ts
optional endJoin?: TerrainSemanticPoint;
length ​
ts
length: number;
points ​
ts
points: TerrainSemanticPoint[];
startJoin? ​
ts
optional startJoin?: TerrainSemanticPoint;

Offset normals at the first and last vertex where the line continues into another one (a road split into two features where its tags change, such as a bridge's ends): the miter a single line would have there, so the two lines' bands meet on one seam instead of leaving a wedge on the outside of the bend. Absent, an end is square. Set before the path is first sampled.


TerrainLineSample ​

Properties ​

dx ​
ts
dx: number;
dz ​
ts
dz: number;
x ​
ts
x: number;
z ​
ts
z: number;

TerrainMvtSemanticDecoderLimits ​

Properties ​

maxFeaturesPerTile? ​
ts
optional maxFeaturesPerTile?: number;
maxGeometryPointsPerTile? ​
ts
optional maxGeometryPointsPerTile?: number;

TerrainMvtSemanticDecoderOptions ​

Properties ​

layers? ​
ts
optional layers?: Partial<TerrainMvtSemanticLayerNames>;
limits? ​
ts
optional limits?: TerrainMvtSemanticDecoderLimits;
linearUnitScale? ​
ts
optional linearUnitScale?: number;

Convert source height/width properties into terrain world units.

properties? ​
ts
optional properties?: Partial<TerrainMvtSemanticPropertyNames>;

TerrainMvtSemanticLayerNames ​

Properties ​

building ​
ts
building: readonly string[];
landcover ​
ts
landcover: readonly string[];
poi ​
ts
poi: readonly string[];
transportation ​
ts
transportation: readonly string[];
water ​
ts
water: readonly string[];

TerrainMvtSemanticPropertyNames ​

Properties ​

bridge ​
ts
bridge: readonly string[];
buildingClass ​
ts
buildingClass: readonly string[];
buildingHeight ​
ts
buildingHeight: readonly string[];
buildingLayer ​
ts
buildingLayer: readonly string[];
buildingLevels ​
ts
buildingLevels: readonly string[];
buildingMinHeight ​
ts
buildingMinHeight: readonly string[];
buildingName ​
ts
buildingName: readonly string[];
buildingSubclass ​
ts
buildingSubclass: readonly string[];
landcoverClass ​
ts
landcoverClass: readonly string[];
landcoverDensity ​
ts
landcoverDensity: readonly string[];
landcoverSubclass ​
ts
landcoverSubclass: readonly string[];
transportationClass ​
ts
transportationClass: readonly string[];
transportationLanes ​
ts
transportationLanes: readonly string[];
transportationLayer ​
ts
transportationLayer: readonly string[];
ts
transportationLink: readonly string[];
transportationOneway ​
ts
transportationOneway: readonly string[];
transportationService ​
ts
transportationService: readonly string[];
transportationSubclass ​
ts
transportationSubclass: readonly string[];
transportationSurface ​
ts
transportationSurface: readonly string[];
transportationWidth ​
ts
transportationWidth: readonly string[];
tunnel ​
ts
tunnel: readonly string[];
tunnelClearance ​
ts
tunnelClearance: readonly string[];
tunnelFloorElevation ​
ts
tunnelFloorElevation: readonly string[];
waterClass ​
ts
waterClass: readonly string[];
waterWidth ​
ts
waterWidth: readonly string[];

TerrainPackageAttribution ​

Properties ​

license ​
ts
license: string;
licenseUrl? ​
ts
optional licenseUrl?: string;
sourceUrl? ​
ts
optional sourceUrl?: string;
text ​
ts
text: string;

TerrainPackageDescriptor ​

Properties ​

agriculture? ​
ts
optional agriculture?: TerrainAgricultureSource;
attribution ​
ts
attribution: TerrainPackageAttribution[];
coordinateSpace ​
ts
coordinateSpace: TerrainPackageCoordinateSpace;
elevation ​
ts
elevation: object;
encoding ​
ts
encoding: "png16";
height ​
ts
height: object;
height.max ​
ts
max: number;
height.min ​
ts
min: number;
source ​
ts
source: TerrainPackageArchiveSource;
features? ​
ts
optional features?: object;
buildingDetail? ​
ts
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 ​
ts
level: number;
buildingDetail.source ​
ts
source: TerrainPackageArchiveSource;
encoding ​
ts
encoding: "mvt";
layers ​
ts
layers: ("water" | "transportation" | "building" | "poi")[];
profile? ​
ts
optional profile?: "protomaps-basemap@1";
source ​
ts
source: TerrainPackageArchiveSource;
files ​
ts
files: TerrainPackageFileRecord[];
format ​
ts
format: "molen/terrain-package@1";
landcover? ​
ts
optional landcover?: object;
encoding ​
ts
encoding: "mvt" | "png8";
layer ​
ts
layer: "landcover";
profile? ​
ts
optional profile?: "protomaps-basemap@1";
source ​
ts
source: TerrainPackageArchiveSource;
models? ​
ts
optional models?: object;
index ​
ts
index: string;
name ​
ts
name: string;
preset? ​
ts
optional preset?: "1gb" | "5gb" | "20gb";
provenance ​
ts
provenance: object;
compiler ​
ts
compiler: string;
compilerVersion ​
ts
compilerVersion: string;
sources ​
ts
sources: TerrainPackageSourceRecord[];
surface? ​
ts
optional surface?: object;
layers? ​
ts
optional layers?: TerrainLayer[];
seaLevel? ​
ts
optional seaLevel?: number;
tileMatrix ​
ts
tileMatrix: object;
maxLevel ​
ts
maxLevel: number;
minLevel ​
ts
minLevel: number;
rootTiles ​
ts
rootTiles: [number, number];
scheme ​
ts
scheme: "xyz" | "tms";
tileResolution ​
ts
tileResolution: number;
version ​
ts
version: string;

TerrainPackageFileRecord ​

Properties ​

bytes ​
ts
bytes: number;
path ​
ts
path: string;
sha256 ​
ts
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 ​
ts
latitude: number;

TerrainPackageSourceRecord ​

Properties ​

id ​
ts
id: string;
release ​
ts
release: string;
sha256? ​
ts
optional sha256?: string;

TerrainPoiFeature ​

A mapped business, amenity, or individual outdoor object.

Extends ​

Properties ​

brand? ​
ts
optional brand?: string;
brandId? ​
ts
optional brandId?: string;

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

bridge? ​
ts
optional bridge?: boolean;
capacity? ​
ts
optional capacity?: number;
class ​
ts
class: string;
crownDiameter? ​
ts
optional crownDiameter?: number;
exitTo? ​
ts
optional exitTo?: string;
genus? ​
ts
optional genus?: string;
heading? ​
ts
optional heading?: number;

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

Overrides ​

TerrainStructureIdentity.heading

height? ​
ts
optional height?: number;

Measurements in world units; absence means unknown.

id? ​
ts
optional id?: string | number;
layer? ​
ts
optional layer?: number;

Source grade; controls on another level must not affect a ground junction.

leafType? ​
ts
optional leafType?: string;
name? ​
ts
optional name?: string;

The source's own name, in its local script and whole (see createTerrainMvtSemanticDecoder).

nameLatin? ​
ts
optional nameLatin?: string;

An English or Latin-script name, when the source has one besides name.

point ​
ts
point: TerrainSemanticPoint;
ref? ​
ts
optional ref?: string;

Exit number on a motorway_junction node.

species? ​
ts
optional species?: string;
stop? ​
ts
optional stop?: "all" | "minor";

All approaches stop, or only the approach carrying this node.

subclass? ​
ts
optional subclass?: string;
tags? ​
ts
optional tags?: Record<string, string>;
Inherited from ​

TerrainStructureIdentity.tags

tunnel? ​
ts
optional tunnel?: boolean;
wikidata? ​
ts
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? ​
ts
optional coverage?: [number, number, number, number];

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

height ​
ts
height: object;
max ​
ts
max: number;
min ​
ts
min: number;
layers ​
ts
layers: TerrainLayer[];
maxLevel ​
ts
maxLevel: number;
metersPerUnit? ​
ts
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 ​
ts
minLevel: number;
name ​
ts
name: string;
origin ​
ts
origin: [number, number];

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

rootSize ​
ts
rootSize: number;

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

skirts ​
ts
skirts: boolean;
tileResolution ​
ts
tileResolution: number;

TerrainPyramidTileAddress ​

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

Properties ​

level ​
ts
level: number;
x ​
ts
x: number;
z ​
ts
z: number;

TerrainRailTrack ​

Properties ​

bed ​
ts
bed: number;

Width of the ballast's top, meters: the sleepers' length and a shoulder each side.

concrete ​
ts
concrete: boolean;

Concrete sleepers (ties); otherwise timber.

disused ​
ts
disused: boolean;

Out of use: rusted rails, weeds in the ballast, no signals or crossing equipment.

gauge ​
ts
gauge: number;

Track gauge between the rails' running edges, meters.

mode ​
ts
mode: TerrainRailMode;
prism ​
ts
prism: boolean;

Raised on a ballast prism with sloped shoulders (main lines and sidings in the open).

rank ​
ts
rank: number;

Smaller is more important: budgets furnish main lines first.

service ​
ts
service: TerrainRailService;

TerrainRoadSignCatalog ​

Properties ​

fallback ​
ts
fallback: string;
format ​
ts
format: "molen/road-sign-catalog@1";
profiles ​
ts
profiles: TerrainRoadSignProfile[];

TerrainRoadSignProfile ​

A serializable visual convention, independent of the detected road-sign pattern.

Properties ​

allWayLabel ​
ts
allWayLabel: string;
attractionColor ​
ts
attractionColor: string;
countries ​
ts
countries: string[];
drivingSide ​
ts
drivingSide: "left" | "right";
exitColor ​
ts
exitColor: string;
exitLabel ​
ts
exitLabel: string;
font? ​
ts
optional font?: string;

Optional host font role or face id; falls back to the library's highway role.

id ​
ts
id: string;
inferStopSigns ​
ts
inferStopSigns: boolean;

Conservative regional default; an explicit surface option can override it.

motorwayColor ​
ts
motorwayColor: string;
notes ​
ts
notes: string;
showSpeedUnit ​
ts
showSpeedUnit: boolean;
sources ​
ts
sources: string[];
speedSign ​
ts
speedSign: "rectangle" | "circle";
speedUnit ​
ts
speedUnit: "MPH" | "KM/H";

Only determines whether a redundant unit legend is hidden. Never converts a posted limit.

stateNetwork? ​
ts
optional stateNetwork?: string;
stopLabel ​
ts
stopLabel: string;
streetNames? ​
ts
optional streetNames?: TerrainStreetNameStyle;

Street-name signs at junctions; a region without this style gets none.

subdivisions? ​
ts
optional subdivisions?: string[];

ISO subdivision codes; specific profiles override country defaults.

title ​
ts
title: string;
yieldLabel ​
ts
yieldLabel: string;

TerrainRouteMarker ​

Properties ​

network ​
ts
network: string;
ref ​
ts
ref: string;

TerrainRouteShieldLibrary ​

Properties ​

format ​
ts
format: "molen/route-shields@1";
shields ​
ts
shields: Record<string, {
  subdivision: string;
  title: string;
  variants: object[];
}>;

TerrainSemanticOverzoomOptions ​

Properties ​

buffer? ​
ts
optional buffer?: number;

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


TerrainSemanticPolygon ​

Properties ​

holes? ​
ts
optional holes?: TerrainSemanticRing[];
outer ​
ts
outer: TerrainSemanticRing;

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


TerrainSemanticTile ​

Properties ​

buildings ​
ts
buildings: TerrainBuildingFeature[];
buildingsGeneralized? ​
ts
optional buildingsGeneralized?: boolean;

Source merged/generalized footprints cannot reliably identify individual premises.

buildingSourceLevel? ​
ts
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 ​
ts
format: "molen/terrain-semantics@1";
landcover ​
ts
landcover: TerrainLandcoverFeature[];
pois? ​
ts
optional pois?: TerrainPoiFeature[];
transportation ​
ts
transportation: TerrainTransportationFeature[];
water ​
ts
water: TerrainWaterFeature[];

TerrainSemanticTileDecodeContext ​

Properties ​

address ​
ts
address: TerrainPyramidTileAddress;

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

content ​
ts
content: 
  | "all"
  | TerrainPackageSemanticContent;
encoding ​
ts
encoding: "mvt" | "png8";
layers ​
ts
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 ​

Methods ​

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

Uint8Array

context ​

TerrainSemanticTileDecodeContext

Returns ​

| TerrainSemanticTile | Promise&lt;TerrainSemanticTile&gt;


TerrainSemanticTileEdit ​

A derived tile's replacement for a collection: each entry the feature at that index of the collection as it stood, or a new feature (cloned with the message).

Properties ​

buildings? ​
ts
optional buildings?: readonly (number | TerrainBuildingFeature)[];
landcover? ​
ts
optional landcover?: readonly (number | TerrainLandcoverFeature)[];
pois? ​
ts
optional pois?: readonly (number | TerrainPoiFeature)[];

Indexes count into the tile's POIs after any land-cover tile's were joined (none: empty).

transportation? ​
ts
optional transportation?: readonly (
  | number
  | TerrainTransportationFeature)[];

TerrainSemanticTileLoader ​

Anything that loads semantic tiles by pyramid address.

Methods ​

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

TerrainPyramidTileAddress

signal ​

AbortSignal

Returns ​

Promise&lt;TerrainSemanticTile | undefined&gt;


TerrainSemanticTilePacket ​

A tile packed by packTerrainSemanticTile: the skeleton as JSON (or, failing that, as an object) and every line's points in points.

Properties ​

edits? ​
ts
optional edits?: readonly TerrainSemanticTileEdit[];

Collections a derived tile replaced, applied in order (see deriveTerrainSemanticTilePacket).

json? ​
ts
optional json?: string;
landcover? ​
ts
optional landcover?: TerrainSemanticTilePacket;

A tile composed with another's land cover (see composeTerrainSemanticTile).

landcoverPois? ​
ts
optional landcoverPois?: boolean;

...and its POIs too, where the tile has none.

overzoom? ​
ts
optional overzoom?: object;

The packed tile is an ancestor's, re-expressed for a descendant on unpacking (see overzoomTerrainSemanticTile), before any land cover or edits.

buffer? ​
ts
optional buffer?: number;
from ​
ts
from: TerrainPyramidTileAddress;
to ​
ts
to: TerrainPyramidTileAddress;
points ​
ts
points: Float64Array;
tile? ​
ts
optional tile?: unknown;

TerrainStreamingOptions ​

Properties ​

loadRadius ​
ts
loadRadius: number;

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

maxConcurrentLoads ​
ts
maxConcurrentLoads: number;

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

maxResidentTiles ​
ts
maxResidentTiles: number;

Hard ceiling for decoded resident height tiles and their meshes.

unloadRadius ​
ts
unloadRadius: number;

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


TerrainStructureIdentity ​

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

Extended by ​

Properties ​

heading? ​
ts
optional heading?: number;

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

tags? ​
ts
optional tags?: Record<string, string>;
wikidata? ​
ts
optional wikidata?: string;

TerrainTileAddress ​

Address of one fixed-grid terrain chunk.

Properties ​

x ​
ts
x: number;
z ​
ts
z: number;

TerrainTileArchive ​

Extended by ​

Methods ​

getHeader()? ​
ts
optional getHeader(): Promise<TerrainArchiveHeader>;
Returns ​

Promise&lt;TerrainArchiveHeader&gt;

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

number

x ​

number

y ​

number

signal? ​

AbortSignal

Returns ​

Promise&lt;TerrainArchiveTile | undefined&gt;


TerrainTransportationFeature ​

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

Extends ​

Properties ​

bridge? ​
ts
optional bridge?: boolean;
bridgeApproachProfile? ​
ts
optional bridgeApproachProfile?: TerrainBridgeProfileSample[];

Sampled bridge deck or bounded, connected approach grading. Points are normalized tile coordinates; elevation is absolute Y and flatness (0..1) suppresses terrain crossfall at the deck.

bridgeConnections? ​
ts
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 ​
ts
elevation: number;
point ​
ts
point: TerrainSemanticPoint;
radius ​
ts
radius: number;
class ​
ts
class: string;
deckElevation? ​
ts
optional deckElevation?: number;

Optional surveyed bridge deck elevation in absolute world Y units.

destination? ​
ts
optional destination?: string;

Signposted destinations, separated by semicolons in OSM.

destinationColour? ​
ts
optional destinationColour?: string;

Destination colours, aligned with semicolon-separated destination names.

destinationRef? ​
ts
optional destinationRef?: string;
heading? ​
ts
optional heading?: number;

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

Inherited from ​

TerrainStructureIdentity.heading

id? ​
ts
optional id?: string | number;
junctionRef? ​
ts
optional junctionRef?: string;

Explicit exit number from junction:ref; never inferred from the road ref.

lanes? ​
ts
optional lanes?: number;
layer? ​
ts
optional layer?: number;

Grade separation; different layers do not form junctions.

lines ​
ts
lines: TerrainSemanticLine[];
ts
optional link?: boolean;

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

maxspeed? ​
ts
optional maxspeed?: string;

OSM maxspeed, including units; unitless numeric values mean km/h.

name? ​
ts
optional name?: string;
network? ​
ts
optional network?: string;

Source network and literal route legend (e.g. Protomaps US:WA + 520).

oneway? ​
ts
optional oneway?: boolean;
ref? ​
ts
optional ref?: string;

Source route reference (not an exit number).

service? ​
ts
optional service?: string;

Source service subtype, for example parking_aisle or driveway.

shieldText? ​
ts
optional shieldText?: string;
subclass? ​
ts
optional subclass?: string;

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

surface? ​
ts
optional surface?: string;
tags? ​
ts
optional tags?: Record<string, string>;
Inherited from ​

TerrainStructureIdentity.tags

tunnel? ​
ts
optional tunnel?: boolean;
tunnelClearance? ​
ts
optional tunnelClearance?: number;

Interior floor-to-ceiling clearance in world units. Otherwise class-based.

tunnelFloorElevation? ​
ts
optional tunnelFloorElevation?: number;

Surveyed tunnel road-floor height in absolute world Y units. Otherwise inferred from portals.

width? ​
ts
optional width?: number;

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

wikidata? ​
ts
optional wikidata?: string;
Inherited from ​

TerrainStructureIdentity.wikidata


TerrainWaterFeature ​

Properties ​

class? ​
ts
optional class?: string;
id? ​
ts
optional id?: string | number;
lines? ​
ts
optional lines?: TerrainSemanticLine[];
polygons? ​
ts
optional polygons?: TerrainSemanticPolygon[];
width? ​
ts
optional width?: number;

Suggested rendered width for linear waterways, in world units.


TerrainYardCarInput ​

Properties ​

cars ​
ts
cars: readonly TerrainParkedVehicle[];

The rail vehicle types to stand in yards (specs with rail).

crossings ​
ts
crossings: readonly TerrainRailCrossing[];
lines ​
ts
lines: readonly TerrainRailLine[];
max ​
ts
max: number;

Most cars this tile places.

occupancy? ​
ts
optional occupancy?: number;

Scales the share of blocks holding cars (default 1).

origin ​
ts
origin: readonly [number, number];
size ​
ts
size: number;
tracks ​
ts
tracks: readonly (TerrainRailTrack | undefined)[];
turnouts ​
ts
turnouts: readonly TerrainRailTurnout[];

Methods ​

railHead() ​
ts
railHead(
   line, 
   x, 
   z
): number;

Absolute height of track line's rail heads at tile-local X/Z.

Parameters ​
line ​

number

x ​

number

z ​

number

Returns ​

number


WebMercatorTileAddress ​

Properties ​

level ​
ts
level: number;
x ​
ts
x: number;
y ​
ts
y: number;

Type Aliases ​

PmtilesTileCompression ​

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

Compression already applied to every tile payload.


PmtilesTileType ​

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

Tile payload types, with their PMTiles header codes.


TerrainArchiveSetRoute ​

ts
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 ​

ts
type TerrainArchiveSetTileType = "png" | "mvt";

Payload type shared by every archive in a set.


TerrainGradeFamily ​

ts
type TerrainGradeFamily = "road" | "rail" | "path";

What a way carries, for the room it needs overhead.


TerrainPackageArchiveSource ​

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

TerrainPackageCoordinateSpace ​

ts
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 ​

ts
type TerrainPackageSemanticContent = "landcover" | "features";

TerrainPackageSemanticProfile ​

ts
type TerrainPackageSemanticProfile = "protomaps-basemap@1";

TerrainRailElectrification ​

ts
type TerrainRailElectrification = "none" | "light" | "all";

Which tracks carry overhead catenary: light (default) electrifies light rail, trams and subways that run in the open; all also heavy rail, as in Japan, India or a European region; none draws no wires at all.


TerrainRailMode ​

ts
type TerrainRailMode = "heavy" | "light" | "tram" | "subway" | "monorail" | "funicular";

Broad railway mode, from the source's kind detail.


TerrainRailService ​

ts
type TerrainRailService = "main" | "siding" | "yard" | "spur" | "crossover";

How a track is used: main line, or a siding, yard, spur or crossover track off it.


TerrainSemanticBounds ​

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

TerrainSemanticLine ​

ts
type TerrainSemanticLine = TerrainSemanticPoint[];

TerrainSemanticPoint ​

ts
type TerrainSemanticPoint = [number, number];

TerrainSemanticRing ​

ts
type TerrainSemanticRing = TerrainSemanticPoint[];

TransportKind ​

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

Painter/simulation class of a transportation feature.

Variables ​

BRIDGE_SURFACE_LIFT ​

ts
const BRIDGE_SURFACE_LIFT: 4 = 4;

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


DEFAULT_ROAD_SIGN_PROFILE ​

ts
const DEFAULT_ROAD_SIGN_PROFILE: Readonly<TerrainRoadSignProfile>;

Backward-compatible default for non-geographic hosts. Earth supplies content profiles.


DEGENERATE_RING_AREA ​

ts
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 ​

ts
const GEOHASH_MAX_PRECISION: 6 = 6;

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


PATH_SURFACE_LIFT ​

ts
const PATH_SURFACE_LIFT: 0.43 = .43;

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


PMTILES_HEADER_BYTES ​

ts
const PMTILES_HEADER_BYTES: 127 = 127;

PMTiles v3 header size in bytes.


ROAD_PROFILE_WINDOW ​

ts
const ROAD_PROFILE_WINDOW: 30 = 30;

Meters either way along a road over which its profile is averaged.


ROAD_SURFACE_LIFT ​

ts
const ROAD_SURFACE_LIFT: 0.32 = .32;

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


TERRAIN_GRADE_SEPARATION ​

ts
const TERRAIN_GRADE_SEPARATION: Readonly<Record<TerrainGradeFamily, number>>;

Meters from the surface of a way to the surface of a deck crossing over it: the clear height its traffic needs (5.1 m over a road, the 16 ft 9 in of US practice with resurfacing allowance and well over the 14 ft legal minimum; 7 m over a railway, for double-stack trains and wires; 3 m over a footpath) plus 1.4 m of girder and slab.


TERRAIN_GROUND_CROWN_FULL ​

ts
const TERRAIN_GROUND_CROWN_FULL: number;

Ground covered when every cell holds a crown: the mean crown area over the cell area.


TERRAIN_GROUND_CROWNS ​

ts
const TERRAIN_GROUND_CROWNS: object;

Half-meter orthophotos of Yuma's open desert show separate round creosote and mesquite crowns, 2 to 5 m across, over about 4% of vacant ground. The ground paints one candidate crown per cell-meter cell, its radius drawn from radius and kept inside the cell, and shows it with probability brush * share / full: at full brush, crowns cover share of the ground.

Type Declaration ​

cell ​
ts
readonly cell: 8;
radius ​
ts
readonly radius: readonly [1, 2.6];
share ​
ts
readonly share: 0.1;

TERRAIN_GROUND_LATTICE_SIZE ​

ts
const TERRAIN_GROUND_LATTICE_SIZE: 512 = 512;

Texels across the ground's random lattice; it wraps, so cells repeat every this many.


TERRAIN_RAIL_HEIGHT ​

ts
const TERRAIN_RAIL_HEIGHT: 0.21 = .21;

Height of a ballasted track's rail heads above the ballast top, meters.


TERRAIN_URBAN_GROUND_CLASSES ​

ts
const TERRAIN_URBAN_GROUND_CLASSES: readonly string[];

Land-cover appearances whose ground paves over as building coverage rises (the default of TerrainUrbanGround.classes): unmapped ground and broad urban uses.


TERRAIN_URBAN_GROUND_COVERAGE ​

ts
const TERRAIN_URBAN_GROUND_COVERAGE: object;

Building coverage at which urban ground starts to pave over, and is paved (the defaults).

Type Declaration ​

from ​
ts
readonly from: 0.15;
full ​
ts
readonly full: 0.45;

terrainRoadSignCatalogSchema ​

ts
const terrainRoadSignCatalogSchema: z.ZodType<TerrainRoadSignCatalog>;

terrainRoadSignProfileSchema ​

ts
const terrainRoadSignProfileSchema: z.ZodType<TerrainRoadSignProfile>;

terrainRoadSignProfilesSchema ​

ts
const terrainRoadSignProfilesSchema: z.ZodType<{
  format: "molen/road-sign-profiles@1";
  profiles: TerrainRoadSignProfile[];
}>;

Additional jurisdiction profiles supplied by content packs.


terrainRouteShieldLibrarySchema ​

ts
const terrainRouteShieldLibrarySchema: z.ZodType<TerrainRouteShieldLibrary>;

WEB_MERCATOR_EARTH_RADIUS_METERS ​

ts
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 ​

ts
const WEB_MERCATOR_HALF_WORLD_METERS: number;

WEB_MERCATOR_MAX_LATITUDE ​

ts
const WEB_MERCATOR_MAX_LATITUDE: number;

Functions ​

applyAgricultureGrid() ​

ts
function applyAgricultureGrid(
   tile, 
   address, 
   grid
): TerrainSemanticTile;

Parameters ​

tile ​

TerrainSemanticTile

address ​

TerrainPyramidTileAddress

grid ​

TerrainAgricultureGrid

Returns ​

TerrainSemanticTile


assertTerrainPyramidAddress() ​

ts
function assertTerrainPyramidAddress(descriptor, address): void;

Parameters ​

descriptor ​

TerrainPyramidDescriptor

address ​

TerrainPyramidTileAddress

Returns ​

void


assertTerrainSemanticTile() ​

ts
function assertTerrainSemanticTile(tile): void;

Parameters ​

tile ​

TerrainSemanticTile

Returns ​

void


beginRoadEarthworks() ​

ts
function beginRoadEarthworks(
   heightfield, 
   reference, 
   options?
): RoadEarthworkPass | undefined;

gradeRoadEarthworks a line at a time. Undefined when the tile's rendered grid is too coarse to grade (maxSpacing).

Parameters ​

heightfield ​

Heightfield

reference ​

(x, z) => number

options? ​

RoadEarthworkOptions

Returns ​

RoadEarthworkPass | undefined


bridgeDeckHeightFn() ​

ts
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 ​

TerrainLinePath

groundAt ​

(x, z) => number

options ​

BridgeDeckOptions

Returns ​

(x, z) => number


buildPmtilesDirectories() ​

ts
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() ​

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

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

Parameters ​

bounds ​

TerrainSemanticBounds

lo? ​

number

hi? ​

number

Returns ​

TerrainSemanticBounds


clipRoadLine() ​

ts
function clipRoadLine(
   line, 
   box, 
   outside?
): TerrainSemanticLine[];

The parts of a line inside a box, or with outside the parts beyond it (Liang-Barsky per segment, rejoined where they continue). Splitting lines by the same box from either side leaves no overlap: what one tile keeps, its neighbor drops.

Parameters ​

line ​

TerrainSemanticLine

box ​

readonly [number, number, number, number]

outside? ​

boolean

Returns ​

TerrainSemanticLine[]


composeTerrainBuildingDetail() ​

ts
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 ​

TerrainPyramidTileAddress

detailLevel ​

number

children ​

readonly TerrainBuildingDetailChild[]

Returns ​

TerrainSemanticTile | undefined


createBuildingDetailTerrainSemanticSource() ​

ts
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 ​

base ​

TerrainSemanticTileLoader

detail ​

TerrainSemanticTileLoader

options ​

TerrainBuildingDetailOptions

Returns ​

TerrainSemanticTileLoader


createEmptyTerrainSemanticTile() ​

ts
function createEmptyTerrainSemanticTile(): TerrainSemanticTile;

Allocate a normalized empty tile without sharing mutable collection instances.

Returns ​

TerrainSemanticTile


createOverzoomTerrainSemanticSource() ​

ts
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 ​

TerrainSemanticTileLoader

maxLevel ​

number

options? ​

TerrainSemanticOverzoomOptions & object

Returns ​

TerrainSemanticTileLoader


createPmtilesPrefix() ​

ts
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() ​

ts
function createProtomapsTerrainMvtDecoder(options?): TerrainMvtSemanticDecoder;

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

Parameters ​

options? ​

Omit&lt;TerrainMvtSemanticDecoderOptions, "layers"&gt; & object

Returns ​

TerrainMvtSemanticDecoder


createTerrainArchiveSetRouter() ​

ts
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() ​

ts
function createTerrainMvtSemanticDecoder(options?): TerrainMvtSemanticDecoder;

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

Parameters ​

options? ​

TerrainMvtSemanticDecoderOptions

Returns ​

TerrainMvtSemanticDecoder


decodeAgricultureGrid() ​

ts
function decodeAgricultureGrid(grid): Uint8Array;

Parameters ​

grid ​

TerrainAgricultureGrid

Returns ​

Uint8Array


decodePng16() ​

ts
function decodePng16(png): Gray16;

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

Parameters ​

png ​

Uint8Array

Returns ​

Gray16


deriveOverzoomTerrainSemanticTilePacket() ​

ts
function deriveOverzoomTerrainSemanticTilePacket(
   ancestor, 
   tile, 
   from, 
   to, 
   buffer?
): void;

Remember a packet and content hash for tile, overzoomed from ancestor (see overzoomTerrainSemanticTile): the ancestor's, with the overzoom to apply. A tile finer than its source was otherwise cloned whole to each worker and serialized whole for cache keys.

Parameters ​

ancestor ​

TerrainSemanticTile

tile ​

TerrainSemanticTile

from ​

TerrainPyramidTileAddress

to ​

TerrainPyramidTileAddress

buffer? ​

number

Returns ​

void


deriveTerrainSemanticTileContentHash() ​

ts
function deriveTerrainSemanticTileContentHash(
   base, 
   derived, 
   key
): void;

Remember a content hash for derived, made from base by an edit that key names completely (what was removed and added, and the tile geometry it was worked out in): base's hash and the key. A cache keyed by tile content then need not serialize the edited tile, 8-20 ms of main thread for a dense town's. Nothing is remembered when base has no hash or derived has one.

Parameters ​

base ​

TerrainSemanticTile

derived ​

TerrainSemanticTile

key ​

string

Returns ​

void


deriveTerrainSemanticTilePacket() ​

ts
function deriveTerrainSemanticTilePacket(base, derived): void;

Remember a packet for derived, made from base by replacing its buildings, transportation, land cover or POIs while keeping most features as they are: base's packet and the edit. A footprint-filtered or road-replaced town tile then crosses to a worker without being cloned whole, 7-10 ms of main thread each time. Nothing is remembered when base has no packet, when anything else differs, when the derived tile drops its POI list altogether, or when a new feature shares a line, ring or object with a kept one: a clone keeps that sharing and an edit would not.

Parameters ​

base ​

TerrainSemanticTile

derived ​

TerrainSemanticTile

Returns ​

void


encodeGeohash() ​

ts
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() ​

ts
function encodePng16(img): Uint8Array;

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

Parameters ​

img ​

Gray16

Returns ​

Uint8Array


encodeTerrainArchiveSetCells() ​

ts
function encodeTerrainArchiveSetCells(cells): string;

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

Parameters ​

cells ​

Iterable&lt;string&gt;

Returns ​

string


encodeTerrainArchiveSetPartitions() ​

ts
function encodeTerrainArchiveSetPartitions(indices): string;

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

Parameters ​

indices ​

Iterable&lt;number&gt;

Returns ​

string


generateHeightmap() ​

ts
function generateHeightmap(opts): Gray16;

Generate a normalized heightmap grid.

Parameters ​

opts ​

HeightmapGenOptions

Returns ​

Gray16


generateHeightmapPng() ​

ts
function generateHeightmapPng(opts): Uint8Array;

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

Parameters ​

opts ​

HeightmapGenOptions

Returns ​

Uint8Array


geohashBounds() ​

ts
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() ​

ts
function geohashFromIndex(index, precision): string;

The geohash of precision characters with this index.

Parameters ​

index ​

number

precision ​

number

Returns ​

string


geohashIndex() ​

ts
function geohashIndex(hash): number;

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

Parameters ​

hash ​

string

Returns ​

number


gradeHighwayBridges() ​

ts
function gradeHighwayBridges(
   features, 
   tileSize, 
   groundAt
): readonly TerrainTransportationFeature[];

Grade every inferred bridge and the roads that climb to it; see gradeTransportSeparations, which this forwards to. It once graded motorways only, at a fixed 6 m a layer, so decks that crossed each other shared a height.

Parameters ​

features ​

readonly TerrainTransportationFeature[]

tileSize ​

number

groundAt ​

(x, z) => number

Returns ​

readonly TerrainTransportationFeature[]


gradeRoadEarthworks() ​

ts
function gradeRoadEarthworks(
   heightfield, 
   lines, 
   reference, 
   options?
): Heightfield;

Grade a tile's ground for the roads on it. Each road's cross-section is leveled at the height of its profile (roadProfileHeight of reference, read along its centerline), out to a grid cell past its edge; beyond that the ground blends back to what it was. Where roads are close the nearest one decides, so two streets at different heights each keep their own bench and the block between them takes up the difference, as a graded city block does. On a fine enough grid a vertex between roads at very different heights is not shared at all: the road whose centerline is nearer keeps it, and the cell beyond it stands in for the retaining wall.

reference is the natural ground as a function of world X/Z alone (the same elevation level for every tile, reaching past this tile's edges), so adjacent tiles grade their shared edge alike; lines keep the profile read from it. Returns the field itself when nothing changes.

Parameters ​

heightfield ​

Heightfield

lines ​

readonly RoadEarthworkLine[]

reference ​

(x, z) => number

options? ​

RoadEarthworkOptions

Returns ​

Heightfield


gradeTransportSeparations() ​

ts
function gradeTransportSeparations(
   features, 
   tileSize, 
   groundAt, 
   options?
): readonly TerrainTransportationFeature[];

Give every inferred bridge, and every road that must climb to one, a sampled height profile (bridgeApproachProfile), leaving surveyed and authored heights alone.

  • A deck meets the roads at its ends where they stand, spans straight between them, and rises toward a free clearance over ground with nothing mapped beneath it.
  • Wherever it crosses another way without sharing a vertex it clears that way's surface by TERRAIN_GRADE_SEPARATION, held across the lower way's width. Between two bridges the mapped layer decides which is on top; without one, the deck whose span already stands well above the other's, then what each carries (ramps over streets over freeway carriageways and railways), then the one farther along its structure from where it lands.
  • A deck falls away from that height no faster than its class allows, and where it reaches its end still raised, the roads joined to it there carry the rest of the descent, each at its own grade.

groundAt takes tile-local meters and, for callers that level roads along their own direction, the unit direction of the way at that point. Coordinates and profiles stay tile-normalized.

Parameters ​

features ​

readonly TerrainTransportationFeature[]

tileSize ​

number

groundAt ​

(x, z, dx, dz) => number

options? ​

GradeSeparationOptions

Returns ​

readonly TerrainTransportationFeature[]


gradeTransportSeparationSteps() ​

ts
function gradeTransportSeparationSteps(
   features, 
   tileSize, 
   groundAt, 
   options?
): Generator<undefined, readonly TerrainTransportationFeature[], undefined>;

gradeTransportSeparations as resumable steps of a few milliseconds each: a host on the main thread runs them until its time for the frame is up and carries on in the next. An interchange with its neighbors is tens of thousands of stations, too long to hold a frame for.

Parameters ​

features ​

readonly TerrainTransportationFeature[]

tileSize ​

number

groundAt ​

(x, z, dx, dz) => number

options? ​

GradeSeparationOptions

Returns ​

Generator&lt;undefined, readonly TerrainTransportationFeature[], undefined&gt;


groupTransportationFeatures() ​

ts
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() ​

ts
function heightfieldFromPng(descriptor, png): Heightfield;

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

Parameters ​

descriptor ​

TerrainDescriptor

png ​

Uint8Array

Returns ​

Heightfield


heightfieldSubtileFromPng() ​

ts
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 ​

TerrainDescriptor

address ​

TerrainTileAddress

png ​

Uint8Array

subdivision ​

number

offset ​

TerrainTileAddress

Returns ​

Heightfield


heightfieldTileFromPng() ​

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

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

Parameters ​

descriptor ​

TerrainDescriptor

address ​

TerrainTileAddress

png ​

Uint8Array

Returns ​

Heightfield


inferLaneCount() ​

ts
function inferLaneCount(feature, width): number;

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

Parameters ​

feature ​

TerrainTransportationFeature

width ​

number

Returns ​

number


isAeroway() ​

ts
function isAeroway(feature): boolean;

Airside pavement has its own markings and must never enter the street/parking network.

Parameters ​

feature ​

TerrainTransportationFeature

Returns ​

boolean


isArterialRoad() ​

ts
function isArterialRoad(category, width): boolean;

Conservative arterial cue for decorative junction controls; local tags beat broad classes.

Parameters ​

category ​

string

width ​

number

Returns ​

boolean


isDegenerateRing() ​

ts
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() ​

ts
function isPaintedTransport(feature, options): boolean;

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

Parameters ​

feature ​

TerrainTransportationFeature

options ​
sidewalks ​

boolean

Returns ​

boolean


ts
function isTransportLink(feature): boolean;

True for slip roads and ramps.

Parameters ​

feature ​

TerrainTransportationFeature

Returns ​

boolean


joinTerrainLines() ​

ts
function joinTerrainLines(lines, directed?): TerrainSemanticLine[];

Join degree-two fragments; directed preserves one-way travel instead of reversing neighbors.

Parameters ​

lines ​

readonly TerrainSemanticLine[]

directed? ​

boolean

Returns ​

TerrainSemanticLine[]


keepTerrainSemanticTile() ​

ts
function keepTerrainSemanticTile(tile): () => TerrainSemanticTile;

A tile to come back to later, kept as the packet it arrived as when it can be decoded again from it (see terrainSemanticTilePacket): the returned call answers the tile while it lives, else decodes it afresh, with its packet, content hash and check. A layer keeping every displayed tile whole for a rebuild that seldom comes kept every point of them on the heap that each collection walks. Other tiles are kept as they are.

Parameters ​

tile ​

TerrainSemanticTile

Returns ​

() => TerrainSemanticTile


landcoverAppearance() ​

ts
function landcoverAppearance(feature): string;

Physical subclasses (garden, gravel, wood) outrank broad land-use classes.

Parameters ​

feature ​

TerrainLandcoverFeature

Returns ​

string


lineSegmentIndex() ​

ts
function lineSegmentIndex(path, distance): number;

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

Parameters ​

path ​

TerrainLinePath

distance ​

number

Returns ​

number


normalizeRing() ​

ts
function normalizeRing(ring): TerrainSemanticRing;

Drop a repeated closing vertex and consecutive duplicates.

Parameters ​

ring ​

TerrainSemanticRing

Returns ​

TerrainSemanticRing


overzoomTerrainSemanticTile() ​

ts
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 ​

TerrainSemanticTile

from ​

TerrainPyramidTileAddress

to ​

TerrainPyramidTileAddress

options? ​

TerrainSemanticOverzoomOptions

Returns ​

TerrainSemanticTile


packTerrainSemanticTile() ​

ts
function packTerrainSemanticTile(tile): TerrainSemanticTilePacket;

A copy of tile whose lines (arrays of [u, v] points) are moved into one Float64Array; the rest goes as JSON (numbers JSON would lose marked, see NUM) unless an undefined array entry or a non-plain object would not survive it, else as an object. A browser parses JSON several times faster than it deserializes the same objects from a structured clone. unpackTerrainSemanticTile rebuilds every point and number exactly.

Parameters ​

tile ​

TerrainSemanticTile

Returns ​

TerrainSemanticTilePacket


parseTerrainArchiveSetPartitions() ​

ts
function parseTerrainArchiveSetPartitions(ranges): number[];

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

Parameters ​

ranges ​

string

Returns ​

number[]


pathBounds() ​

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

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

Parameters ​

path ​

TerrainLinePath

Returns ​

[number, number, number, number]


placeTerrainYardCars() ​

ts
function placeTerrainYardCars(input): VehiclePlacement[];

Cars standing on the yard, siding and spur tracks of a tile (heavy rail: freight cars and the odd idle locomotive; light rail: its own cars in its yards), clear of turnouts and road crossings. Placements are absolute world positions, keyed by where each car stands.

Parameters ​

input ​

TerrainYardCarInput

Returns ​

VehiclePlacement[]


pmtilesTileId() ​

ts
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() ​

ts
function pointInPolygon(point, polygon): boolean;

Inside the outer ring and outside every hole.

Parameters ​

point ​

TerrainSemanticPoint

polygon ​

TerrainSemanticPolygon

Returns ​

boolean


pointInRing() ​

ts
function pointInRing(point, ring): boolean;

Even-odd containment test against one ring.

Parameters ​

point ​

TerrainSemanticPoint

ring ​

readonly TerrainSemanticPoint[]

Returns ​

boolean


polygonArea() ​

ts
function polygonArea(polygon): number;

Outer area minus hole areas, never negative.

Parameters ​

polygon ​

TerrainSemanticPolygon

Returns ​

number


polygonBounds() ​

ts
function polygonBounds(polygon): TerrainSemanticBounds;

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

Parameters ​

polygon ​

TerrainSemanticPolygon

Returns ​

TerrainSemanticBounds


projectedToWorld() ​

ts
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() ​

ts
function registerTerrainSchemas(): void;

Register the terrain descriptor schema into the shared registry (idempotent).

Returns ​

void


renderedGroundSampler() ​

ts
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


resolveTerrainRouteMarker() ​

ts
function resolveTerrainRouteMarker(
   road, 
   profile, 
   library?
): 
  | {
  evidence: string[];
  marker: TerrainRouteMarker;
}
  | undefined;

Exact networks only: never turn a county, federal, secondary, toll or business route into a primary state route.

Parameters ​

road ​

Pick&lt;TerrainTransportationFeature, "network" | "shieldText" | "ref"&gt;

profile ​

Readonly&lt;TerrainRoadSignProfile&gt;

library? ​

TerrainRouteShieldLibrary

Returns ​

| { evidence: string[]; marker: TerrainRouteMarker; } | undefined


ringArea() ​

ts
function ringArea(ring): number;

Parameters ​

ring ​

readonly TerrainSemanticPoint[]

Returns ​

number


ringSignedArea() ​

ts
function ringSignedArea(ring): number;

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

Parameters ​

ring ​

readonly TerrainSemanticPoint[]

Returns ​

number


roadEarthworkLines() ​

ts
function roadEarthworkLines(
   features, 
   origin, 
   tileSize, 
   clip?
): RoadEarthworkLine[];

The ways of one tile to grade, as world-space lines. clip (tile-normalized, default the tile itself) drops the tile's buffer, so lines gathered from neighboring tiles do not overlap: the same world geometry then reaches every tile that grades it, whichever tile it came from.

Parameters ​

features ​

readonly TerrainTransportationFeature[]

origin ​

readonly [number, number]

tileSize ​

number

clip? ​

readonly [number, number, number, number]

Returns ​

RoadEarthworkLine[]


roadProfileHeight() ​

ts
function roadProfileHeight(
   reference, 
   x, 
   z, 
   dx, 
   dz, 
   window?
): number;

Height of a road's graded profile at a point on its centerline: the reference ground averaged along the road's own direction (dx, dz, a unit vector), weighted toward the point. It depends on nothing but the point, the direction and the reference ground, so every tile and every level of detail that grades the same road agrees, wherever the road was cut by a tile.

Parameters ​

reference ​

(x, z) => number

x ​

number

z ​

number

dx ​

number

dz ​

number

window? ​

number

Returns ​

number


roadWidth() ​

ts
function roadWidth(className, explicit?): number;

Road ribbon width in world units for a transportation class.

Parameters ​

className ​

string

explicit? ​

number

Returns ​

number


sampleTerrainBuildingCoverage() ​

ts
function sampleTerrainBuildingCoverage(
   coverage, 
   u, 
   v
): number;

Bilinear coverage at normalized tile coordinates, between cell centers.

Parameters ​

coverage ​

TerrainBuildingCoverage

u ​

number

v ​

number

Returns ​

number


sampleTerrainLine() ​

ts
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 ​

TerrainLinePath

distance ​

number

offset? ​

number

Returns ​

TerrainLineSample


serializePmtilesDirectory() ​

ts
function serializePmtilesDirectory(entries): Uint8Array;

Encode a directory in the uncompressed PMTiles v3 column layout.

Parameters ​

entries ​

readonly PmtilesDirectoryEntry[]

Returns ​

Uint8Array


terrainArchiveSetTierCells() ​

ts
function terrainArchiveSetTierCells(tier): string[];

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

Parameters ​

tier ​

TerrainArchiveSetGeohashTier

Returns ​

string[]


terrainBuildingCoverage() ​

ts
function terrainBuildingCoverage(tile, size?): TerrainBuildingCoverage;

Building coverage on a coarse grid (default 16 x 16), each footprint counted in the cell holding its outline's mean point, then box-blurred over neighboring cells so a block's coverage reaches the streets around it.

Parameters ​

tile ​

TerrainSemanticTile

size? ​

number

Returns ​

TerrainBuildingCoverage


terrainGroundCell() ​

ts
function terrainGroundCell(i, j): number;

One integer cell's lattice value in [0, 1], as the shader reads it at the texel center.

Parameters ​

i ​

number

j ​

number

Returns ​

number


terrainGroundCrown() ​

ts
function terrainGroundCrown(i, j): TerrainGroundCrown;

The crown of pattern cell (i, j): the cell spans [i, i + 1) * TERRAIN_GROUND_CROWNS.cell in world X, and likewise j in Z. The pattern is periodic with the lattice (4,096 m), so any world frame whose coordinates agree modulo that period sees the same crowns.

Parameters ​

i ​

number

j ​

number

Returns ​

TerrainGroundCrown


terrainGroundLattice() ​

ts
function terrainGroundLattice(): Uint8Array;

Random bytes at integer lattice points (xorshift32: uncorrelated neighbours, the same lattice on every run). The ground material uploads these as its noise texture; shared, never mutated.

Returns ​

Uint8Array


terrainLinePath() ​

ts
function terrainLinePath(line, tileSize): TerrainLinePath;

Convert normalized tile geometry once; collapse duplicate vertices.

Parameters ​

line ​

TerrainSemanticLine

tileSize ​

number

Returns ​

TerrainLinePath


terrainPackageFrameLatitude() ​

ts
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 ​

TerrainPackageDescriptor

frame? ​

TerrainPackageFrame

Returns ​

number | undefined


terrainPackageMetersPerUnit() ​

ts
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() ​

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

Parameters ​

descriptor ​

TerrainPyramidDescriptor

level ​

number

x ​

number

z ​

number

Returns ​

TerrainPyramidTileAddress | undefined


terrainPyramidAncestor() ​

ts
function terrainPyramidAncestor(address, level): TerrainPyramidTileAddress;

Parameters ​

address ​

TerrainPyramidTileAddress

level ​

number

Returns ​

TerrainPyramidTileAddress


terrainPyramidParent() ​

ts
function terrainPyramidParent(address): TerrainPyramidTileAddress | undefined;

Parameters ​

address ​

TerrainPyramidTileAddress

Returns ​

TerrainPyramidTileAddress | undefined


terrainPyramidTileCount() ​

ts
function terrainPyramidTileCount(level): number;

Parameters ​

level ​

number

Returns ​

number


terrainPyramidTileKey() ​

ts
function terrainPyramidTileKey(address): string;

Parameters ​

address ​

TerrainPyramidTileAddress

Returns ​

string


terrainPyramidTileOrigin() ​

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

Parameters ​

descriptor ​

TerrainPyramidDescriptor

address ​

TerrainPyramidTileAddress

Returns ​

[number, number]


terrainPyramidTileSize() ​

ts
function terrainPyramidTileSize(descriptor, level): number;

Parameters ​

descriptor ​

TerrainPyramidDescriptor

level ​

number

Returns ​

number


terrainRailElectrified() ​

ts
function terrainRailElectrified(track, policy?): boolean;

Whether a track carries overhead catenary under an electrification policy.

Parameters ​

track ​

TerrainRailTrack

policy? ​

TerrainRailElectrification

Returns ​

boolean


terrainRailOffset() ​

ts
function terrainRailOffset(gauge): number;

Lateral offset of each rail's centerline from the track's, meters (head 72 mm wide).

Parameters ​

gauge ​

number

Returns ​

number


terrainRailTrack() ​

ts
function terrainRailTrack(feature, heavyGauge?): TerrainRailTrack | undefined;

Classify a mapped railway line, or undefined for lines that carry no track to draw (abandoned, proposed or under construction, and station or platform outlines). heavyGauge is the gauge of the region's heavy-rail network (default standard, 1.435 m; Japan's conventional lines are 1.067 m, India's 1.676 m); lines named as Shinkansen keep standard gauge, and light rail, trams and subways are standard gauge everywhere.

Parameters ​

feature ​

Pick&lt;TerrainTransportationFeature, "class" | "subclass" | "service" | "name"&gt;

heavyGauge? ​

number

Returns ​

TerrainRailTrack | undefined


terrainSemanticTileFromPacket() ​

ts
function terrainSemanticTileFromPacket(packet): TerrainSemanticTile;

The tile a received packet carries. The packet must be the receiver's own copy.

Parameters ​

packet ​

TerrainSemanticTilePacket

Returns ​

TerrainSemanticTile


terrainSemanticTilePacket() ​

ts
function terrainSemanticTilePacket(tile): TerrainSemanticTilePacket | undefined;

The packet tile arrived as from a decoder worker, to post on to other workers as is (without transferring points: it is reused). Undefined for a tile made on this thread: post the tile itself, as packing it here would cost more than the structured clone it saves.

Parameters ​

tile ​

TerrainSemanticTile

Returns ​

TerrainSemanticTilePacket | undefined


terrainTileGeohash() ​

ts
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() ​

ts
function terrainTileKey(address): string;

Parameters ​

address ​

TerrainTileAddress

Returns ​

string


terrainTileOrigin() ​

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

Parameters ​

descriptor ​

TerrainDescriptor

address ​

TerrainTileAddress

Returns ​

[number, number]


terrainUrbanGroundPaved() ​

ts
function terrainUrbanGroundPaved(
   coverage, 
   from?, 
   full?
): number;

Paved share of urban ground at this building coverage: a smoothstep from from to full.

Parameters ​

coverage ​

number

from? ​

number

full? ​

number

Returns ​

number


transportKind() ​

ts
function transportKind(feature): TransportKind;

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

Parameters ​

feature ​

TerrainTransportationFeature

Returns ​

TransportKind


transportSurfaceLift() ​

ts
function transportSurfaceLift(kind, bridge?): number;

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

Parameters ​

kind ​

TransportKind

bridge? ​

boolean

Returns ​

number


transportWidth() ​

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

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

Parameters ​

feature ​

TerrainTransportationFeature

kind? ​

TransportKind

scale? ​

number

Returns ​

number


unpackTerrainSemanticTile() ​

ts
function unpackTerrainSemanticTile(packed, points): TerrainSemanticTile;

Rebuild a packed tile in place (it is the receiver's own copy).

Parameters ​

packed ​

unknown

points ​

Float64Array

Returns ​

TerrainSemanticTile


waterwayWidth() ​

ts
function waterwayWidth(className, explicit?): number;

Waterway ribbon width in world units for a water class.

Parameters ​

className ​

string | undefined

explicit? ​

number

Returns ​

number


webMercatorScaleAtLatitude() ​

ts
function webMercatorScaleAtLatitude(latitudeDegrees): number;

Ground meters per projected Web Mercator meter at a latitude: cos(lat). Mercator inflates horizontal distances by 1/cos(lat) (≈1.48× at 47.6°N), while heights stay in true meters; multiplying projected X/Z by this factor makes a scene metrically consistent. Latitude is clamped to the Mercator limit.

Parameters ​

latitudeDegrees ​

number

Returns ​

number


webMercatorTileBounds() ​

ts
function webMercatorTileBounds(address): [number, number, number, number];

Projected X/Z bounds for one XYZ Web Mercator tile.

Parameters ​

address ​

WebMercatorTileAddress

Returns ​

[number, number, number, number]


webMercatorToWgs84() ​

ts
function webMercatorToWgs84(x, z): [number, number];

Convert Web Mercator X/Z meters (+Z south) to WGS84 longitude/latitude degrees.

Parameters ​

x ​

number

z ​

number

Returns ​

[number, number]


wgs84ToWebMercator() ​

ts
function wgs84ToWebMercator(longitude, latitude): [number, number];

Convert WGS84 longitude/latitude degrees to Web Mercator X/Z meters (+Z south).

Parameters ​

longitude ​

number

latitude ​

number

Returns ​

[number, number]


wgs84ToWebMercatorTile() ​

ts
function wgs84ToWebMercatorTile(
   longitude, 
   latitude, 
   level
): WebMercatorTileAddress;

XYZ address containing a WGS84 point at a Web Mercator level.

Parameters ​

longitude ​

number

latitude ​

number

level ​

number

Returns ​

WebMercatorTileAddress


wgs84ToWorld() ​

ts
function wgs84ToWorld(
   metersPerUnit, 
   longitude, 
   latitude
): [number, number];

WGS84 longitude/latitude → metric world X/Z in a frame whose scale is metersPerUnit (see terrainPackageMetersPerUnit). This is where a host places a camera, marker or entity.

Parameters ​

metersPerUnit ​

number

longitude ​

number

latitude ​

number

Returns ​

[number, number]


worldToProjected() ​

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

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

Parameters ​

metersPerUnit ​

number

x ​

number

z ​

number

Returns ​

[number, number]


worldToWgs84() ​

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

Metric world X/Z in a frame of scale metersPerUnit → WGS84 longitude/latitude.

Parameters ​

metersPerUnit ​

number

x ​

number

z ​

number

Returns ​

[number, number]


writePmtilesArchive() ​

ts
function writePmtilesArchive(tiles, options): Uint8Array;

Build a complete clustered PMTiles v3 archive in memory. Tiles may arrive in any order; zooms are derived from them. Use createPmtilesPrefix to stream larger archives to disk.

Parameters ​

tiles ​

readonly PmtilesWriterTile[]

options ​

PmtilesArchiveOptions

Returns ​

Uint8Array

50 guides · 44 schema formats · 51 API entry points · 11 samples. API, CLI and schema pages are generated from the shipped build.