@mapmap/points reference

Generated from the published @mapmap/points 0.6.0 type declarations by website/scripts/sdk-reference.mjs. Do not edit by hand: change the JSDoc in the package, or the examples in website/content/sdk-reference/points.examples.md, and regenerate.

Every public export of the point-cloud SDK, as declared in the package. The guide, with the format, budgets and the streaming walkthrough, is Point clouds in SDKs & installation.

npm install @mapmap/points@0.6.0 @mapmap/maps@0.25.1 maplibre-gl three

Other SDK references: @mapmap/maps, @mapmap/core, @mapmap/tile, @mapmap/react-native, @mapmap/voice, MapMapKit, ai.mapmap:core.

101 exports across 2 entry points: 2 classes, 30 functions, 39 interfaces, 20 types, 10 constants.

How to read this page

Each entry gives the declaration as published, the JSDoc description, and a table of parameters or properties with their types. The Default column quotes the default the source states (an @default tag or a "Default ..." sentence in the JSDoc). "required" means the property must be given; "not stated" means the source gives no default, so none is claimed here. Classes, factories and the main entry functions each carry a minimal example; examples marked from the source are the package's own @example.

Contents

• @mapmap/points: 99 exports
• @mapmap/points/worker: 2 exports

@mapmap/points

import { /* … */ } from "@mapmap/points";

Classes (@mapmap/points)

CopcTransportError, UnsupportedCrsError

CopcTransportError

Class

class CopcTransportError extends Error { … }

Every error this layer throws, so a caller can catch one type.

Extends Error.

Constructor and methods

• constructor(code: CopcTransportErrorCode, message: string, options?: { status?: number | null; url?: string | null; cause?: unknown; })

Example

import { CopcTransportError, isAbortError, openCopc } from "@mapmap/points";

try {
  await openCopc("https://example.com/scan.copc.laz");
} catch (err) {
  if (isAbortError(err)) {
    // cancelled, not failed
  } else if (err instanceof CopcTransportError && err.code === "range-unsupported") {
    console.error("The server ignores Range requests:", err.url);
  } else {
    throw err;
  }
}

UnsupportedCrsError

Class

class UnsupportedCrsError extends Error { … }

Thrown when a CRS is outside the v1 set and no crs hook was supplied.

Extends Error.

Constructor and methods

• constructor(message: string, crsName: string, epsg?: number, family?: string)

Example

import { UnsupportedCrsError, openCopc } from "@mapmap/points";

try {
  await openCopc("https://example.com/scan.copc.laz");
} catch (err) {
  if (err instanceof UnsupportedCrsError) {
    // Supply a crs hook (proj4 satisfies it) for this CRS.
    console.error(err.crsName, err.epsg);
  } else {
    throw err;
  }
}

Functions (@mapmap/points)

absoluteHeightsFromMeta, asprsClassLabel, autoFogRange, cacheBytesForBudget, clampHeightRange, classesFromMeta, classTableProblems, createPointCloudLayer, decodePointCloud, defaultHeightRange, deviceMemoryGb, encodePointCloud, eyePosition, formatClearance, formatLateral, isAbortError, isStreamingSource, localOffset, metresPerPixel, openCopc, payloadBytes, pointBudgetForDevice, pointSizeScale, reportToGeoJson, resolveClasses, stickyElevation, validateMeta, visiblePointCount

absoluteHeightsFromMeta

Function

function absoluteHeightsFromMeta(meta: Pick<PointCloudMeta, "absoluteHeights" | "terrainRelative">): boolean;

Resolve a sidecar's height datum to the one boolean the layer needs.

absoluteHeights is the field; terrainRelative is the 0.1.0 spelling of the same thing, kept as an alias so an existing sidecar renders identically. They share a polarity, terrainRelative: true always meant absolute heights, whatever its docstring claimed, so the alias needs no inversion, only a rename. See #678.

Absent from both is true: that is what 0.1.0 did with an unset field, and it is the right default anyway, since a cloud georeferenced well enough to sit on a map is nearly always in absolute metres.

The deprecation warning fires once per process rather than per call: the layer resolves this inside its render loop, and a warning on every frame would bury the console it is trying to be seen in.

Options and types: PointCloudMeta.

asprsClassLabel

Function

function asprsClassLabel(value: number): string | undefined;

A label for a class byte, or undefined when the standard does not name one. Never invents a name for a user-definable byte.

autoFogRange

Function

function autoFogRange(box: LocalBox): FogRange;

Fog distances derived from a cloud's horizontal extent.

nearM is 0.6 of the horizontal diagonal, floored at 120 m so a tiny cloud is not fogged from the doorstep; farM is three times that, which keeps the far end beyond the point where a viewer has pulled back far enough to see the whole cloud. The vertical extent is deliberately not in the calculation: fog is about how far away things are on the ground, and a single tall mast should not push a street scene's fog out by 80 m.

Options and types: LocalBox.

cacheBytesForBudget

Function

function cacheBytesForBudget(pointBudget: number, override?: number): number;

Decoded-cache byte budget: 50 % headroom over the point budget, capped.

The headroom is what stops a small camera wobble evicting and immediately refetching; the cap stops a 32 GB desktop filling a quarter of a gigabyte for no visible benefit.

clampHeightRange

Function

function clampHeightRange(minM: number, maxM: number): MetreRange;

Put a caller's height range into a state the shader can divide by.

Throws on a non-finite bound, because there is no sane clamp for NaN and silently substituting one hides the caller's own arithmetic bug. An inverted or degenerate range is repaired rather than thrown: the caller is usually a slider, and a slider whose handles meet should not take the viewer's cloud down with it.

classesFromMeta

Function

function classesFromMeta(table: MetaClassTable | null | undefined): PointClass[];

Build a class table from a sidecar's classes, in either shape.

Two shapes are read because two shapes exist in the wild. A map of byte → label is the compact one; a list of { byte, label, colour } is what most bakers emit, because a list survives a round trip through a language whose object keys are not strings. Accepting only the map meant the list decoded to NaN-valued rows that threw at first render, a long way from the sidecar that caused it.

• Map: ordered by class byte, since a JSON object has no order worth trusting. Non-numeric keys are dropped rather than coerced to NaN.
• List: kept in the producer's own order, because they chose it and it drives the default palette. colour and color are both read.

Your byte values survive as your byte values in both: 40 stays 40. A table longer than MAX_CLASSES is truncated with a warning rather than thrown, so a viewer handed a 20-class sidecar still draws something, resolveClasses would refuse it outright.

Anything that is neither shape throws, naming both.

Options and types: MetaClassTable.

classTableProblems

Function

function classTableProblems(classes: unknown): string[];

Check a classes value against both accepted shapes.

Returns the problems rather than throwing, so validateMeta can report them alongside everything else it found. A wrong shape used to surface as a NaN-keyed class table and a throw at first render, which is a long way from the sidecar that caused it.

createPointCloudLayer

Function

function createPointCloudLayer(source: PointCloudSource, options?: PointCloudLayerOptions): PointCloudLayer;

Create the layer. Add it with map.addLayer(...) once the style is loaded.

source is either a decoded cloud or a { meta, raw } pair, which is decoded (and validated) here.

Options and types: PointCloudSource, PointCloudLayerOptions.

Example

import "maplibre-gl/dist/maplibre-gl.css";
import { createMap } from "@mapmap/maps";
import { createPointCloudLayer, openCopc } from "@mapmap/points";

const map = createMap({ container: "map", apiKey: "snk_…", center: [-0.1276, 51.5072], zoom: 16 });
const source = await openCopc("https://example.com/scan.copc.laz");
const layer = createPointCloudLayer(source, { colourMode: "rgb", pointSizeM: 0.15 });
map.map.on("load", () => map.map.addLayer(layer));

decodePointCloud

Function

function decodePointCloud(meta: PointCloudMeta, raw: ArrayBuffer): DecodedPointCloud;

Point two typed arrays at a payload, after checking it is the right size.

Throws rather than returning a partial view: a truncated download that silently renders its first 300 000 points is far harder to diagnose than one that refuses.

Options and types: PointCloudMeta.

defaultHeightRange

Function

function defaultHeightRange(box: LocalBox): MetreRange;

The height range a cloud gets when the caller does not steer it: its own vertical extent, widened if that extent is flatter than the ramp can use.

Options and types: LocalBox.

deviceMemoryGb

Function

function deviceMemoryGb(): number | undefined;

Read navigator.deviceMemory without assuming a DOM.

encodePointCloud

Function

function encodePointCloud(input: {
    anchor: [number, number];
    xyz: Float64Array | Float32Array | number[];
    rgb: Uint8Array | number[];
    classes?: Uint8Array | number[];
    quant?: number;
    sensor?: string;
}): {
    buffer: ArrayBuffer;
    meta: PointCloudMeta;
};

Encode points into the wire format, for producers written in TypeScript.

xyz is metres in the local frame; rgb is 0–255; classes is one byte per point. Returns the buffer plus the origin, quant and bboxLocal to write into the sidecar, so the two cannot disagree.

Most production baking happens offline in Python or Rust, this exists so a small cloud can be built in the browser, and so the decoder has an encoder to be tested against.

eyePosition

Function

function eyePosition(view: CameraView, centre: LocalCentre): EyePosition;

Where the eye is, in the cloud's local frame.

The camera sits distanceM behind the map centre, opposite the bearing, lifted by the pitch, and, when terrain is on, raised by the terrain height at the centre (see 1 in the module docs).

Options and types: CameraView, LocalCentre.

formatClearance

Function

function formatClearance(c: MeasuredClearance): ClearanceText;

Format a measured clearance as "4.62 m measured (safe bound 4.48 m, surveyed Jan 2026)".

The bound is not optional, not appended by a caller and not dropped when the string is short on space. If a surface has no room for the full string it needs a shorter design, not a shorter truth.

A non-structure overhead class is named in the text, because a figure limited by vegetation or by a wire behaves differently from one limited by concrete: foliage is seasonal and compressible, and a wire is a thin target measured from few returns. Both are still real obstructions, so the figure stands; the reader is simply told what it is a figure about.

Options and types: MeasuredClearance.

Throws: if any figure is non-finite, if a bound is negative, or if the safe bound exceeds the measured value. Each of those means the arithmetic upstream is wrong, and every one of them would otherwise render as a confident, plausible label.

formatLateral

Function

function formatLateral(l: MeasuredLateral): ClearanceText;

Format a measured lateral clearance as "2.90 m clear width measured (safe bound 2.71 m, surveyed Jan 2026)".

A separate function rather than a flag on formatClearance, because it takes a separate type. There is no argument anybody can get wrong: a MeasuredLateral has no headroom to caption, and a MeasuredClearance has no clear width.

The wording says "clear width" every time, including for a structure, where the vertical formatter stays silent about the class. A figure with no unit noun beside it defaults in a reader's head to headroom, because that is what a clearance report is mostly about.

Options and types: MeasuredLateral.

Throws: on the same three arithmetic impossibilities.

isAbortError

Function

function isAbortError(error: unknown): boolean;

True for the DOM AbortError and for our own aborted-code error.

isStreamingSource

Function

function isStreamingSource(source: unknown): source is StreamingSource;

Narrow a layer source to a streamed one.

localOffset

Function

function localOffset(anchor: [number, number], lngLat: [number, number]): {
    x: number;
    z: number;
};

Local offset in metres (x east, z south) of a lng/lat from an anchor.

metresPerPixel

Function

function metresPerPixel(lat: number, zoom: number): number;

Ground metres one CSS pixel covers at a given latitude and zoom.

512 is MapLibre's tile size in CSS pixels, so this is a CSS-pixel scale and multiplying it by a device-pixel height is wrong by the device pixel ratio. camera.test.ts pins it against MapLibre's own transform.cameraToCenterDistance, which is likewise in CSS pixels.

openCopc

Function

function openCopc(source: string | RangeGetter, options?: CopcOpenOptions): Promise<CopcSource>;

Read a COPC's header and hierarchy root. Fetches no points.

Options and types: RangeGetter, CopcOpenOptions.

Example

import { openCopc } from "@mapmap/points";

const source = await openCopc("https://example.com/scan.copc.laz", {
  onWarn: (message) => console.warn(message),
});
console.log(source.meta.totalPoints, source.channels);
source.dispose(); // a source owns a worker pool: always dispose of it

payloadBytes

Function

function payloadBytes(count: number): number;

Byte length a payload with count points must have.

pointBudgetForDevice

Function

function pointBudgetForDevice(deviceMemoryGb?: number, override?: number): number;

Resident point budget for a device.

At 10 bytes a point the three tiers are 120 / 60 / 30 MB of GPU buffer, which leaves ample room beside a MapLibre basemap with terrain on the weakest device in each tier.

navigator.deviceMemory is Chromium-only, so undefined takes the conservative tier rather than the optimistic one. An app that knows better passes override, and an explicit override always wins, including over a device that reports plenty of memory.

pointSizeScale

Function

function pointSizeScale(worldSizeM: number, bufferHeightPx: number, fovDeg?: number): number;

Device pixels a point of worldSizeM metres subtends at one metre.

The shader divides this by the distance to the point, which is what makes points shrink with depth like real surfaces instead of staying a fixed screen size and turning distant geometry into a solid slab.

reportToGeoJson

Function

function reportToGeoJson(report: RouteClearanceReport): ClearanceGeoJson;

Turn a route clearance report into map geometry.

The collection contains, in order:

1. the route ribbon, one LineString decoded from route.geometry_polyline6, statused by the height verdict. Omitted when the report carries no drawable shape;
2. coverage gaps, not_surveyed then insufficient_data, for the height axis and then the width axis;
3. advisory runs;
4. measurement points, height axis then width axis.

The width axis contributes nothing when it reports not_assessed: there is no lateral geometry to draw, and the reason belongs in the panel beside the report rather than on the map as an unplaced label.

Options and types: RouteClearanceReport.

Throws: if a coverage or advisory section carries fewer than two positions, or if the encoded route or section geometry is malformed.

resolveClasses

Function

function resolveClasses(classes: readonly PointClass[]): ResolvedClasses;

Turn a caller's class table into the flat arrays the shader wants.

Throws on a table the shader cannot represent, duplicate class bytes, a byte outside 0–255, or more classes than MAX_CLASSES. These are all producer mistakes that would otherwise render as points quietly taking a neighbour's colour.

Options and types: PointClass.

stickyElevation

Function

function stickyElevation(sampled: number | null | undefined, remembered: number | null): number | null;

Carry the last known terrain elevation across frames the DEM has not answered for yet.

map.queryTerrainElevation returns null until the DEM tile covering the point has loaded, on the first frames after terrain is switched on, and again after a pan into un-cached tiles. Defaulting those frames to 0 puts the eye at sea level, so on a hill the point sizes and the fog distance jump the moment the tile arrives: a first-paint pop with no visible cause. Holding the previous value is wrong by however far the camera has moved since, which is a metre or two, instead of by the height of the hill.

Returns null only when nothing has ever been sampled, there is no real elevation to hold yet, and the caller falls back to 0 for those frames alone. Once a real value has been seen this never returns to null, so the eye never snaps back to sea level mid-session.

Pure, so the layer's memory is one variable it passes in and stores back.

validateMeta

Function

function validateMeta(meta: PointCloudMeta): string[];

Validate a sidecar. Returns the problems; an empty array means usable.

Separate from decodePointCloud so a build pipeline can check a sidecar it has just written without holding the (large) binary.

Options and types: PointCloudMeta.

visiblePointCount

Function

function visiblePointCount(classes: ResolvedClasses, classCounts: Record<string, number> | undefined): number | null;

How many points the currently visible classes account for, or null if that cannot be known from the sidecar.

null rather than a guess, and rather than a count of our own: the only other way to answer is to walk the class byte of every point in the payload, which is a multi-megabyte scan on the main thread for a number a producer could have written into classCounts at bake time. A readout that shows nothing is honest; one that stalls a viewer for a second per toggle, or quietly reports the wrong figure, is not.

A visible class the producer did not count contributes nothing, so a partial classCounts under-reports rather than throwing. Non-finite and negative counts are ignored for the same reason.

Options and types: ResolvedClasses.

Interfaces (@mapmap/points)

AdaptiveBudget, CameraView, ChangeEvent, ChangeReport, ClearanceEnforcement, ClearanceFieldSidecar, ClearanceGeoJson, CopcCloudMeta, CopcDataStats, CopcOpenOptions, CopcSource, DatumBlock, DecodedPointCloud, EpochRegistration, EyePosition, FogRange, LateralPoint, LimitingPoint, LocalBox, LocalCentre, MeasuredClearance, MeasuredLateral, MetaClassEntry, MetreRange, ObservedClass, OsmDraftEdit, PointClass, PointCloudLayer, PointCloudLayerOptions, PointCloudMeta, ResolvedClasses, RouteClearanceReport, RouteSection, StreamCloudMeta, StreamingSource, StreamStats, TagAuditReport, TagComparison, VehicleQuery

AdaptiveBudget

Interface

interface AdaptiveBudget

Turn the adaptive-budget option on, and bound it.

See PointCloudLayerOptions.adaptiveBudget. Off by default: a library must not govern a caller's frame budget silently. true is a safe, PROTECTIVE default, the budget may shrink to a floor to hold the frame rate but never grows above where it started (allowGrow: false), so turning it on can only ever make a struggling machine smoother, never fetch more than the app already asked for. The object form is the real control: a floor, a hard ceiling and an optional target frame rate. GROW is enabled only when the ceiling is above the starting budget, that is the one gate that keeps a phone (which the demo hands max === its tier budget) protective-only while a desktop (max well above its start) may earn more detail.

CameraView

Interface

interface CameraView

The parts of a MapLibre map this module reads.

ChangeEvent

Interface

interface ChangeEvent

One clustered difference between two epochs.

ChangeReport

Interface

interface ChangeReport

A whole-corridor comparison between two epochs.

ClearanceEnforcement

Interface

interface ClearanceEnforcement

The enforcement block, present on every response including, especially, the clear one, because the clear answer is the one that reads as a certificate.

It mirrors the tunnel enforcement block the routing API already ships on every truck route, and for the same reason: basis and caveat are constants defined once in the sn-clearance crate, so the gateway, the MCP tools and the docs cannot describe the same guarantee three different ways. This SDK deliberately does not define its own copy of the caveat text. A second definition is a second thing to drift; the literal types below pin the fields that must not vary, and the prose arrives from the one place that owns it.

Asymmetry with the Rust side, stated so nobody assumes otherwise. There, route_certified is a type with exactly one inhabitant and basis is a literal tag, so true is not writable and deserialising a report that claims otherwise fails at the boundary. Here the literal types below give the same guarantee at compile time and none at all at runtime: TypeScript types are erased, so a JSON document parsed into one of these can carry route_certified: true and nothing will notice. Anything consuming an enforcement block from the wire, rather than from code that typechecked, has to check it itself.

ClearanceFieldSidecar

Interface

interface ClearanceFieldSidecar

The .clr.json sidecar written beside the binary field.

sources exists for staleness: the dataset manifest holds the same hashes, and a field baked from a source that has since been republished is served with stale: true and can never carry a pass.

ClearanceGeoJson

Interface

interface ClearanceGeoJson

What reportToGeoJson returns: a FeatureCollection, narrowed so a consumer gets the property names checked instead of any.

Assignable to GeoJSON's own FeatureCollection, which invariants.ts asserts at compile time, so anything expecting the standard type still takes it.

CopcCloudMeta

Interface

interface CopcCloudMeta extends StreamCloudMeta

Everything a COPC file tells us about itself, in PointCloudMeta shape.

Extends StreamCloudMeta.

CopcDataStats

Interface

interface CopcDataStats

Counters for getStats() and for a proof run's request ledger.

CopcOpenOptions

Interface

interface CopcOpenOptions

CopcSource

Interface

interface CopcSource extends StreamingSource

A streamed COPC, as createPointCloudLayer consumes it.

Extends StreamingSource.

Methods

• setChannel(channel: CopcChannel): Promise<void>: Switch it. Re-decodes; no new range requests with the cache warm.
• dispose(): void: Release workers, abort in-flight requests, drop caches.

DatumBlock

Interface

interface DatumBlock

The mandatory datum block. A bake without one must not exist.

crs.wkt_source records where the CRS came from, and the ordering is a quality ranking rather than a preference: a CRS read from the data's own WKT VLR is a fact, one from a sidecar is a claim, and one declared by an operator is a hope. It is never taken from a filename. The Montreal delivery that was MTM and looked like UTM is why.

DecodedPointCloud

Interface

interface DecodedPointCloud

Two zero-copy views over one payload, ready to hand to the GPU.

EpochRegistration

Interface

interface EpochRegistration

The alignment applied to one epoch before it can be compared to another.

EyePosition

Interface

interface EyePosition

Eye position in the cloud's local east/up/south frame, in metres.

FogRange

Interface

interface FogRange

Fog distances in metres from the eye.

LateralPoint

Interface

interface LateralPoint

A place on the route where a lateral measurement constrains the answer.

The measurement is on lateral, not clearance. Two field names for two quantities: code that reaches for .clearance on one of these does not compile, which is the point.

LimitingPoint

Interface

interface LimitingPoint

A place on the route where an overhead measurement constrains the answer.

LocalBox

Interface

interface LocalBox

Local bounding box in metres, in the cloud's own east/up/south frame.

LocalCentre

Interface

interface LocalCentre

Where the centre of the map sits in the cloud's local frame.

MeasuredClearance

Interface

interface MeasuredClearance

One measured clearance. The uncertainty is not optional, and that is the point of the type.

A headroom figure without an error bound is the number somebody drives a lorry at a bridge on. Making sigma_m and sampling_gap_m required means the bound cannot be dropped in transit, and pairing that with a single formatter means it cannot be dropped in display either.

The two bounds are different animals and are kept apart deliberately:

• sigma_m is the combined fit residual of the road estimate, the overhead estimate and the differential georeferencing between them. It is a spread.
• sampling_gap_m is a one-sided bias bound, not a sigma. A sample spacing of g on a structure's underside means the true low point can hang up to about g below the lowest sample that was actually caught. No amount of averaging recovers it, so it is subtracted rather than combined in quadrature.

safe_headroom_m is the verdict input: headroom_m less a multiple of sigma_m less sampling_gap_m. Both figures are reported, because a caller is entitled to see what was measured as well as what it is safe to conclude.

MeasuredLateral

Interface

interface MeasuredLateral

One measured lateral clearance. A separate type from MeasuredClearance, with no headroom field anywhere on it.

The obvious alternative was one measurement type with an axis discriminant, and it is worse: a discriminant is something a reader has to remember to check, and the whole discipline of this module is that dangerous states are unrepresentable rather than merely detectable. A clear width of 2.90 m sitting in a field called headroom_m is a mislabelled safety figure one careless line away from a bridge strike, so the field does not exist to be misread. The Rust crate makes the same choice and asserts that a serialised width answer contains the string "headroom" nowhere; invariants.ts asserts the same against the type, and format.test.ts and geojson.test.ts against the values, so the guarantee holds for every width answer rather than for the one a test happened to build.

The uncertainty is derived laterally rather than borrowed from the vertical, because it comes from different geometry:

• sigma_m is sqrt(2) * sigma_rel_georef_m. Both corridor edges are measured, and a width is the difference between them, so the differential georeferencing term enters twice.
• sampling_gap_m is 2 * cell_size, one cell of ambiguity at each edge. It is a one-sided bias bound like its vertical counterpart: the true edge can sit up to a cell inboard of the last sample that caught it, and no averaging recovers that.

MetaClassEntry

Interface

interface MetaClassEntry

One class as an array-shaped sidecar writes it.

Bakers that emit a list rather than a map tend to spell the field byte and, being written in Python or against a US style guide, color. Both spellings are accepted; neither is preferred, and colour wins if a producer somehow writes both.

MetreRange

Interface

interface MetreRange

A closed range in metres.

ObservedClass

Interface

interface ObservedClass

One class byte and how many resident points carry it.

OsmDraftEdit

Interface

interface OsmDraftEdit

A proposed OSM edit, in draft.

set is typed to the single tag this product is ever allowed to draft. Widening it is not a refactor: maxheight is a legal claim and we do not hold the evidence to make one.

PointClass

Interface

interface PointClass

One entry in the class table.

PointCloudLayer

Interface

interface PointCloudLayer extends CustomLayerInterface

Extends CustomLayerInterface.

Methods

• setClassVisible(value: number, visible: boolean): void: Show or hide one class, by its byte value.
• setAllClassesVisible(visible: boolean): void: Show or hide every class at once.
• setColourMode(mode: ColourMode): void
• setPointSize(metres: number, maxPx?: number): void: World size in metres; maxPx optionally lifts the screen-size cap.
• setHeightRange(minM: number, maxM: number): void: Steer the "height" colour ramp to a band of local metres, live. The bounds are sorted if they arrive the wrong way round, and a collapsed range is widened rather than dividing by zero in the shader. Non-finite bounds throw. Takes effect on the next frame whatever the current colour mode.
• resetHeightRange(): void: Put the ramp back to the cloud's own vertical extent.
• getHeightRange(): MetreRange: The band the ramp currently spans, for a slider to start from.
• getFps(): number: Frames per second, averaged over the last second.
• getClasses(): ResolvedClasses | null: The class table as resolved, for building a legend. visible is live: it is the array the shader itself reads, so it always reflects the last PointCloudLayer.setClassVisible or PointCloudLayer.setAllClassesVisible call rather than the state the table declared at construction. A legend can therefore read its checked state off the layer instead of shadowing it. null when the layer was created without a classes table.
• getVisiblePointCount(): number | null: How many points are currently drawn, for a stat readout. meta.count when the layer has no class table, since nothing is being culled. Otherwise the sum of meta.classCounts over the visible classes, or null when the sidecar carries no classCounts: the only other way to answer is to walk the class byte of every point in the payload on the main thread, which is too expensive to do per toggle for a number the producer could have baked in.
• getStats(): StreamStats | null: Streaming counters, for a loading readout. null for a static payload. residentPoints / totalPoints is what the loading UI shows. It never reaches 1 and it should not pretend to: the honest label is "2.1M of 940M points drawn", not a progress bar to 100 %.
• observedClasses(): ObservedClass[]: Classes actually seen in the resident set, by descending count. Empty for a static payload, whose class table is declared rather than discovered. For a streamed source this is a sample and a viewer should say so: it describes the nodes decoded so far, not the file. COPC carries no class histogram and LAS 1.4 defines no statistics VLR, so the alternative is not a better number, it is no number at all.
• setClasses(classes: readonly PointClass[]): void: Replace the class table live. Streamed sources only. This is what makes PointCloudLayer.observedClasses usable rather than merely interesting: discover which bytes the file actually uses, then name and colour them. Throws above MAX_CLASSES, and throws for a static payload, whose shader was compiled for exactly the table it was given. The table is read, never mutated, so a readonly array such as the exported ASPRS_LAS14_CLASSES is accepted as it stands: cloud.setClasses(ASPRS_LAS14_CLASSES) typechecks under strict TypeScript with no cast.
• setChannel(channel: string): Promise<void>: Switch the scalar in the colour bytes. Streamed sources only. Re-decodes the resident set, and issues no new range requests while the compressed-node cache still holds the bytes. Resolves once the re-decode is done; the map repaints as nodes arrive, so the scene never blanks.
• setTargetSse(px: number): void: Change the target screen-space error live, for a quality slider.
• setPointBudget(points: number): void: Change the resident point budget live.

PointCloudLayerOptions

Interface

interface PointCloudLayerOptions

PointCloudMeta

Interface

interface PointCloudMeta

The sidecar that describes a cloud. Written alongside the binary, usually as <name>.json next to <name>.bin.

Deliberately small: it carries what is needed to draw the cloud, plus two free-form provenance strings (source, sensor) that the SDK never renders. Licence terms, survey dates and processing history belong in your own metadata, not in a rendering payload.

ResolvedClasses

Interface

interface ResolvedClasses

A class table normalised for the shader: dense arrays, resolved colours.

RouteClearanceReport

Interface

interface RouteClearanceReport

The full report for one route and one vehicle.

width is either a verdict of its own or an explicit refusal. Lateral obstruction distance can only be measured where both corridor edges have adequate return density, and where they do not the width axis says not_assessed while the height axis still answers. It does not guess.

RouteSection

Interface

interface RouteSection

A contiguous run of route stations, by distance along the route.

The gateway sends the run's shape as polyline6, a six-digit encoded polyline (latitude first, like route.geometry_polyline6), and for one release also as the older polyline array of [lng, lat] pairs, which it has marked deprecated. A report from a gateway older than polyline6 carries only the array. reportToGeoJson reads polyline6 when it is present and non-empty and falls back to polyline otherwise, so both shapes draw the same line.

StreamCloudMeta

Interface

interface StreamCloudMeta extends PointCloudMeta

Metadata a streamed source synthesises. Task E fills this from the file.

Extends PointCloudMeta.

StreamingSource

Interface

interface StreamingSource

A streamed point cloud, as createPointCloudLayer consumes it.

Methods

• setChannel?(channel: string): Promise<void>: Switch the channel. Absent when the container has only one.

StreamStats

Interface

interface StreamStats

Counters a loading readout can show without lying.

TagAuditReport

Interface

interface TagAuditReport

The audit over a dataset, or over one route corridor.

TagComparison

Interface

interface TagComparison

One structure's tagged height against its measured clearance.

osm.value_raw is kept verbatim, and osm.value_m is null when the value could not be parsed. That pairing is the same doctrine the dimension parser already applies elsewhere in the stack: a tag reading 13'6" normalises cleanly, a tag reading about 4m does not, and the second one is reported as unparseable rather than turned into a number somebody might act on.

VehicleQuery

Interface

interface VehicleQuery

The vehicle the question was asked about.

Types (@mapmap/points)

ChangeKind, ClearanceFeature, ClearanceLineProperties, ClearancePointProperties, ClearanceStatus, ClearanceText, ColourMode, CopcChannel, CopcTransportErrorCode, Coverage, IndeterminateReason, LateralPointProperties, MetaClassTable, ObstructionClass, OverheadClass, PointCloudSource, RangeGetter, RouteVerdict, VerticalBasis, WidthVerdict

ChangeKind

Type

type ChangeKind = "appeared" | "vanished" | "moved" | "grew" | "shrank";

What happened to a cluster of cells between two epochs.

ClearanceFeature

Type

type ClearanceFeature = {
    type: "Feature";
    geometry: LineString;
    properties: ClearanceLineProperties;
} | {
    type: "Feature";
    geometry: Point;
    properties: ClearancePointProperties;
} | {
    type: "Feature";
    geometry: Point;
    properties: LateralPointProperties;
};

One feature of a clearance collection.

ClearanceLineProperties

Type

type ClearanceLineProperties = {
    kind: "route" | "coverage_gap" | "advisory";
    axis: "height" | "width" | null;
    status: ClearanceStatus;
    start_m: number;
    end_m: number;
    note: string | null;
};

Properties on the line features: the route ribbon, coverage gaps and advisory runs.

Written as a type alias rather than an interface so it keeps its implicit index signature and stays assignable to GeoJSON's GeoJsonProperties. An interface here compiles until the moment someone passes the collection to a typed GeoJSON API, and then does not.

ClearancePointProperties

Type

type ClearancePointProperties = MeasurementPointCommon & {
    axis: "height";
    headroom_m: number;
    safe_headroom_m: number;
    overhead_class: ObstructionClass;
};

Properties on an overhead measurement point.

axis is still here, and still useful: a style expression filters on it to give the two axes different symbols. What it is no longer doing is telling a reader which of two possible meanings headroom_m has, because the width features do not have a headroom_m to disambiguate.

ClearanceStatus

Type

type ClearanceStatus = "pass" | "fail" | "indeterminate" | "no_verdict" | "not_surveyed" | "insufficient_data" | "advisory";

What a style expression keys colour off.

not_surveyed and insufficient_data are separate from every verdict on purpose. They are not weaker verdicts; they are the absence of one, and a palette that renders them as a paler version of pass has reintroduced by styling exactly the confusion the report types spend their whole existence preventing.

ClearanceText

Type

type ClearanceText = string & {
    readonly __clearanceText: "a measured value and its bound, together";
};

Display text for a clearance measurement, carrying its bound.

A branded string: it is a string and can be assigned to one, passed to a DOM API or put in a GeoJSON property, but a plain string cannot be assigned back to it. That asymmetry is the whole point. Produced only by formatClearance and formatLateral.

ColourMode

Type

type ColourMode = "rgb" | "class" | "height";

How points are coloured.

CopcChannel

Type

type CopcChannel = "rgb" | "intensity";

Which scalar lands in the three colour bytes.

CopcTransportErrorCode

Type

type CopcTransportErrorCode = "range-unsupported" | "network" | "stalled" | "http-status" | "retries-exhausted" | "aborted" | "laz-perf-missing" | "invalid-request";

Machine-readable discriminator on CopcTransportError.

Coverage

Type

type Coverage = {
    kind: "complete";
    assessed_m: number;
} | {
    kind: "partial";
    assessed_m: number;
    not_surveyed: RouteSection[];
    insufficient_data: RouteSection[];
};

How much of the route was actually assessed.

The two variants are distinct shapes on purpose. complete has no field for gaps, so a consumer holding a complete coverage cannot ask about unsurveyed ground and get a plausible-looking empty array back; it has to narrow first, and narrowing is where it learns that gaps exist.

Open sky is not a gap. A station over a cell with adequate road density and no validated overhead cluster is a measurement of no obstruction, and it counts toward assessed_m. A station outside every field, or over cells flagged NO_ROAD, is the absence of a measurement and lands in not_surveyed.

IndeterminateReason

Type

type IndeterminateReason = "inside_uncertainty_band" | "vegetation_age_exceeded" | "artefact_stale" | "artefact_freshness_unchecked";

Why an answer stopped short of a verdict, as a machine-readable set.

It travels beside the human sentence, not instead of it. A caller that wants to branch on the cause should not be parsing prose, and a person reading the answer should not be handed an enum variant. The list is sorted and de-duplicated by the producer, so two identical answers serialise identically.

• inside_uncertainty_band, the margin landed between the measured value and the safe bound. The measurement is fine; the question is too close to call.
• vegetation_age_exceeded, the limiting return is vegetation on a survey old enough that foliage has had time to move.
• artefact_stale, the clearance field is behind the sources it was baked from. A pass is refused rather than served with a warning.
• artefact_freshness_unchecked, staleness could not be established either way, which is not the same as fresh.

LateralPointProperties

Type

type LateralPointProperties = MeasurementPointCommon & {
    axis: "width";
    clear_width_m: number;
    safe_clear_width_m: number;
    limited_by: ObstructionClass;
};

Properties on a lateral measurement point.

No headroom field, matching MeasuredLateral. The Rust crate asserts that a serialised width answer contains the string "headroom" nowhere; geojson.test.ts asserts the same of this collection, so the guarantee survives the trip through the SDK and onto the map.

MetaClassTable

Type

type MetaClassTable = Record<string, string> | MetaClassEntry[];

The two class-table shapes a sidecar may use.

A map keyed by the class byte is the compact form; a list of entries is what most bakers produce, because it survives a round trip through a language whose object keys are not strings. Both mean the same thing, so both are read, see classesFromMeta.

ObstructionClass

Type

type ObstructionClass = "structure" | "vegetation" | "wire" | "unknown";

What the survey found in the way, as a class prior rather than a certainty.

vegetation and wire are labelled, never dropped: a branch across a lane is a real obstruction, and a catenary is a real obstruction to a high load. What the label buys is honesty about what the figure will do next, vegetation is compressible and seasonal, and a wire is a thin target measured from few returns.

This taxonomy IS shared between the two axes, deliberately, and that is not a contradiction of the rule that keeps their measurements apart. A headroom metre and a clear-width metre are different physical quantities; "vegetation" is the same material whether it is above the vehicle or beside it.

OverheadClass

Type

type OverheadClass = ObstructionClass;

The obstruction class at its vertical use site, where "overhead" reads correctly. An alias, not a copy: one definition, two names, so the two axes cannot drift apart on what vegetation means.

PointCloudSource

Type

type PointCloudSource = DecodedPointCloud | {
    meta: PointCloudMeta;
    raw: ArrayBuffer;
} | StreamingSource;

Where a layer's points come from.

The first two are the existing signature, so adding the third is a widening and not a break.

RangeGetter

Type

type RangeGetter = (begin: number, end: number, signal?: AbortSignal) => Promise<Uint8Array>;

The byte-range reader every COPC read goes through. The whole I/O seam.

end is exclusive, matching Uint8Array.prototype.subarray and the public API in the streaming design §11.2. HTTP's Range header is inclusive at both ends, so the fetch implementation subtracts one; that conversion happens in exactly one place (:transport/http).

RouteVerdict

Type

type RouteVerdict = {
    verdict: "pass";
    coverage: Extract<Coverage, {
        kind: "complete";
    }>;
    tightest?: LimitingPoint;
} | {
    verdict: "fail";
    coverage: Coverage;
    limiting: LimitingPoint;
    all_failures: LimitingPoint[];
} | {
    verdict: "indeterminate";
    coverage: Coverage;
    contested: LimitingPoint[];
    reasons: IndeterminateReason[];
    resolution_hint: string;
} | {
    verdict: "no_verdict";
    coverage: Extract<Coverage, {
        kind: "partial";
    }>;
    reason: "no_survey_coverage" | "insufficient_data";
};

The verdict on the vehicle's height.

A passing route CANNOT carry coverage gaps: pass narrows Coverage to its complete variant, and no_verdict narrows it to partial. Those two Extracts are the invariant. Everything else about the honesty of a clearance answer is prose that somebody can ignore; this is arithmetic the compiler does.

tightest is optional, and that is not a loosening. A fully surveyed stretch of open road has no tightest point, because nothing overhead was ever measured on it: overhead_z is NaN across the whole corridor, which is a measurement of clear sky rather than a very large headroom. The alternatives were both worse than an absent field, fabricate a number for a safety report, or refuse to pass the safest possible route. Where a constraint does exist it is always named, because "yes" is not an answer a dispatcher can act on and "yes, with 0.11 m to spare under the railway bridge at 4.2 km" is.

VerticalBasis

Type

type VerticalBasis = {
    kind: "ellipsoidal";
    ellipsoid: "WGS84";
    undulation_applied_m: number | null;
} | {
    kind: "orthometric";
    geoid: string;
} | {
    kind: "dem_referenced";
    dem: "terrarium_z14";
};

How a survey's heights relate to a physical vertical datum.

Recorded so a reader can say what the absolute numbers mean, never so the clearance arithmetic can use them. dem_referenced is listed because reheighted payloads exist and their basis has to be stateable; it is not a clearance source, and a bake reading one is a bug rather than a degraded mode.

WidthVerdict

Type

type WidthVerdict = {
    verdict: "pass";
    coverage: Extract<Coverage, {
        kind: "complete";
    }>;
    tightest?: LateralPoint;
} | {
    verdict: "fail";
    coverage: Coverage;
    limiting: LateralPoint;
    all_failures: LateralPoint[];
} | {
    verdict: "indeterminate";
    coverage: Coverage;
    contested: LateralPoint[];
    reasons: IndeterminateReason[];
    resolution_hint: string;
} | {
    verdict: "no_verdict";
    coverage: Extract<Coverage, {
        kind: "partial";
    }>;
    reason: "no_survey_coverage" | "insufficient_data";
};

The verdict on the vehicle's width. Structurally the shape of RouteVerdict, deliberately not the same type.

It carries LateralPoints, which carry MeasuredLaterals, which have no headroom field. Sharing one verdict type between the axes would have put a clear width inside a MeasuredClearance and undone the separation at the only level that matters.

The same coverage invariant applies, for the same reason: a width axis that passes over ground with no surveyed corridor edges is exactly as dangerous as a height axis that does.

Constants (@mapmap/points)

ASPRS_LAS14_CLASS_LABELS, ASPRS_LAS14_CLASSES, BYTES_PER_POINT, DEFAULT_FOV_DEG, DEFAULT_PALETTE, FOG_FAR_MULTIPLE, FOG_NEAR_DIAGONAL_FRACTION, MAX_CLASSES, MIN_FOG_NEAR_M, MIN_HEIGHT_SPAN_M

ASPRS_LAS14_CLASS_LABELS

Constant

const ASPRS_LAS14_CLASS_LABELS: Readonly<Record<number, string>>;

Every ASPRS name for PDRF 6–10, by class byte (LAS 1.4 R15 Table 17).

For labelling a byte ASPRS_LAS14_CLASSES leaves out, which is what observedClasses() will hand you the moment a file uses one. Bytes 23–63 are reserved and 64–255 are user-definable, so anything absent from this map is the producer's to name, not ours.

ASPRS_LAS14_CLASSES

Constant

const ASPRS_LAS14_CLASSES: readonly PointClass[];

The curated 14. Colours are chosen to read as a landscape rather than as a palette: ground is earth, vegetation greens by height, buildings are the one saturated colour, noise is a warning red, wires are pale.

BYTES_PER_POINT

Constant

const BYTES_PER_POINT = 10;

Bytes one point occupies: 3 * Uint16 + 4 * Uint8.

DEFAULT_FOV_DEG

Constant

const DEFAULT_FOV_DEG = 36.87;

MapLibre's default vertical field of view, in degrees.

DEFAULT_PALETTE

Constant

const DEFAULT_PALETTE: readonly string[];

Distinguishable, colour-blind-aware default palette.

Ordered so that the first few stay separable for viewers with the common forms of colour-vision deficiency: the early entries differ in lightness as well as hue, which is what survives a deuteranopic simulation.

FOG_FAR_MULTIPLE

Constant

const FOG_FAR_MULTIPLE = 3;

Fog is total at this multiple of where it starts.

FOG_NEAR_DIAGONAL_FRACTION

Constant

const FOG_NEAR_DIAGONAL_FRACTION = 0.6;

Fraction of the horizontal diagonal at which fog starts.

MAX_CLASSES

Constant

const MAX_CLASSES = 16;

Most classes any one cloud may declare.

The cap is a uniform-budget limit, not an arbitrary round number. The shader carries a vec3 colour, a visibility float and the class byte per class in uniform arrays, and WebGL1 only guarantees 128 vertex uniform vectors, array elements are not reliably packed, so each one can cost a full slot. Sixteen classes is 48 slots, which leaves comfortable room for everything else the vertex shader needs on the weakest conforming device.

It is also more than a legend can usefully hold: past roughly a dozen flat colours a viewer cannot tell them apart anyway.

MIN_FOG_NEAR_M

Constant

const MIN_FOG_NEAR_M = 120;

Fog never starts closer than this, however small the cloud.

MIN_HEIGHT_SPAN_M

Constant

const MIN_HEIGHT_SPAN_M = 8;

Shortest height range the ramp is allowed to span.

A zero-height range divides by zero in the ramp and paints every point the same colour, so a flat cloud (or a caller asking for min === max) is widened to this instead. Eight metres is roughly two storeys: enough that the ramp still says something about a nominally flat scene.

@mapmap/points/worker

import { /* … */ } from "@mapmap/points/worker";

Functions (@mapmap/points/worker)

onDecodeMessage, setLazPerfImporter

onDecodeMessage

Function

function onDecodeMessage(scope: WorkerScope, data: unknown): Promise<void>;

Handle one message. Exported so a test can drive it without a Worker.

setLazPerfImporter

Function

function setLazPerfImporter(fn: (() => Promise<unknown>) | null): void;

Hand the loader your own import() of laz-perf.

LoadLazPerfOptions.importModule says the same thing, and cannot be used where it is most needed: a worker is constructed from a URL and given no options, so there is no way to pass a function into one. This setter is that channel, called from inside the worker's own module scope, which is why worker.ts re-exports it.

The case it exists for is real and is not hypothetical. A bundler that processes this package's pre-built dist/worker.js may fail to map the bare specifier in its dynamic import, and the failure mode is the worst kind: the import neither resolves nor rejects, so every decode hangs, no error is ever logged, and the scene stays empty while the network, the octree and the georeferencing all work perfectly. An app-owned worker module can resolve laz-perf in its own graph, where its bundler knows what node_modules is, and hand the result over here.

// the app's own worker entry
import { setLazPerfImporter } from "@mapmap/points/worker";
setLazPerfImporter(() => import("laz-perf/lib/worker/index.js"));

Must be called before the first decode message is handled. Module scope in the worker entry is exactly that moment.