Appearance
@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
Returns
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
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
center?
ts
optional center?: readonly [number, number, number];[longitude, latitude, zoom]; defaults to the bounds center at minZoom.
Inherited from
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
Returns
void
finish()
ts
finish(): Heightfield;The graded field, or the field given when nothing moved.
Returns
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
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[];transportationLink
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
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<TerrainSemanticTile>
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
signal
AbortSignal
Returns
Promise<TerrainSemanticTile | undefined>
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<TerrainArchiveHeader>
getZxy()
ts
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
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[];link?
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
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
address
grid
Returns
assertTerrainPyramidAddress()
ts
function assertTerrainPyramidAddress(descriptor, address): void;Parameters
descriptor
address
Returns
void
assertTerrainSemanticTile()
ts
function assertTerrainSemanticTile(tile): void;Parameters
tile
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
reference
(x, z) => number
options?
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
groundAt
(x, z) => number
options
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
clampBounds()
ts
function clampBounds(
bounds,
lo?,
hi?
): TerrainSemanticBounds;Clamp bounds into [lo, hi] on both axes.
Parameters
bounds
lo?
number
hi?
number
Returns
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
box
readonly [number, number, number, number]
outside?
boolean
Returns
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
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
detail
options
Returns
createEmptyTerrainSemanticTile()
ts
function createEmptyTerrainSemanticTile(): TerrainSemanticTile;Allocate a normalized empty tile without sharing mutable collection instances.
Returns
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
maxLevel
number
options?
TerrainSemanticOverzoomOptions & object
Returns
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
Returns
Uint8Array
createProtomapsTerrainMvtDecoder()
ts
function createProtomapsTerrainMvtDecoder(options?): TerrainMvtSemanticDecoder;Preset matching the world.pmtiles Protomaps basemap this repo's sample package ships.
Parameters
options?
Omit<TerrainMvtSemanticDecoderOptions, "layers"> & object
Returns
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
Returns
createTerrainMvtSemanticDecoder()
ts
function createTerrainMvtSemanticDecoder(options?): TerrainMvtSemanticDecoder;Decode configured MVT source layers into renderer-neutral tile-local semantic geometry.
Parameters
options?
TerrainMvtSemanticDecoderOptions
Returns
decodeAgricultureGrid()
ts
function decodeAgricultureGrid(grid): Uint8Array;Parameters
grid
Returns
Uint8Array
decodePng16()
ts
function decodePng16(png): Gray16;Decode a 16-bit grayscale PNG to a normalized [0,1] grid.
Parameters
png
Uint8Array
Returns
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
tile
from
to
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
derived
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
derived
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
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<string>
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<number>
Returns
string
generateHeightmap()
ts
function generateHeightmap(opts): Gray16;Generate a normalized heightmap grid.
Parameters
opts
Returns
generateHeightmapPng()
ts
function generateHeightmapPng(opts): Uint8Array;Generate a heightmap and encode it as a 16-bit grayscale PNG.
Parameters
opts
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
lines
readonly RoadEarthworkLine[]
reference
(x, z) => number
options?
Returns
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 mappedlayerdecides 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?
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?
Returns
Generator<undefined, readonly TerrainTransportationFeature[], undefined>
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
png
Uint8Array
Returns
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
address
png
Uint8Array
subdivision
number
offset
Returns
heightfieldTileFromPng()
ts
function heightfieldTileFromPng(
descriptor,
address,
png
): Heightfield;Build one tile-scoped Heightfield from a streamed height tile.
Parameters
descriptor
address
png
Uint8Array
Returns
inferLaneCount()
ts
function inferLaneCount(feature, width): number;Total lane count across both directions, matching the painted lane lines.
Parameters
feature
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
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
options
sidewalks
boolean
Returns
boolean
isTransportLink()
ts
function isTransportLink(feature): boolean;True for slip roads and ramps.
Parameters
feature
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
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
Returns
() => TerrainSemanticTile
landcoverAppearance()
ts
function landcoverAppearance(feature): string;Physical subclasses (garden, gravel, wood) outrank broad land-use classes.
Parameters
feature
Returns
string
lineSegmentIndex()
ts
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()
ts
function normalizeRing(ring): TerrainSemanticRing;Drop a repeated closing vertex and consecutive duplicates.
Parameters
ring
Returns
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
from
to
options?
TerrainSemanticOverzoomOptions
Returns
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
Returns
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
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
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
polygon
Returns
boolean
pointInRing()
ts
function pointInRing(point, ring): boolean;Even-odd containment test against one ring.
Parameters
point
ring
readonly TerrainSemanticPoint[]
Returns
boolean
polygonArea()
ts
function polygonArea(polygon): number;Outer area minus hole areas, never negative.
Parameters
polygon
Returns
number
polygonBounds()
ts
function polygonBounds(polygon): TerrainSemanticBounds;Unclamped bounds of the outer ring (buffered geometry may exceed [0, 1]).
Parameters
polygon
Returns
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
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<TerrainTransportationFeature, "network" | "shieldText" | "ref">
profile
Readonly<TerrainRoadSignProfile>
library?
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
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
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
distance
number
offset?
number
Returns
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
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
size?
number
Returns
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
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
tileSize
number
Returns
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
frame?
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
frame?
Returns
number
terrainPyramidAddressAt()
ts
function terrainPyramidAddressAt(
descriptor,
level,
x,
z
): TerrainPyramidTileAddress | undefined;Parameters
descriptor
level
number
x
number
z
number
Returns
TerrainPyramidTileAddress | undefined
terrainPyramidAncestor()
ts
function terrainPyramidAncestor(address, level): TerrainPyramidTileAddress;Parameters
address
level
number
Returns
terrainPyramidParent()
ts
function terrainPyramidParent(address): TerrainPyramidTileAddress | undefined;Parameters
address
Returns
TerrainPyramidTileAddress | undefined
terrainPyramidTileCount()
ts
function terrainPyramidTileCount(level): number;Parameters
level
number
Returns
number
terrainPyramidTileKey()
ts
function terrainPyramidTileKey(address): string;Parameters
address
Returns
string
terrainPyramidTileOrigin()
ts
function terrainPyramidTileOrigin(descriptor, address): [number, number];Parameters
descriptor
address
Returns
[number, number]
terrainPyramidTileSize()
ts
function terrainPyramidTileSize(descriptor, level): number;Parameters
descriptor
level
number
Returns
number
terrainRailElectrified()
ts
function terrainRailElectrified(track, policy?): boolean;Whether a track carries overhead catenary under an electrification policy.
Parameters
track
policy?
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<TerrainTransportationFeature, "class" | "subclass" | "service" | "name">
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
Returns
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
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
Returns
string
terrainTileOrigin()
ts
function terrainTileOrigin(descriptor, address): [number, number];Parameters
descriptor
address
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
Returns
transportSurfaceLift()
ts
function transportSurfaceLift(kind, bridge?): number;Nominal painted surface elevation above terrain (bridges add BRIDGE_SURFACE_LIFT).
Parameters
kind
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
kind?
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
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
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
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
Returns
Uint8Array