Skip to content

Surface styles and parameterized line features ​

Night lighting adds dusk-driven lamp heads and pavement pools to modern street fixtures, with separate lamp budgets and matching direct/worker output.

The terrain client renders roads, parking areas, pedestrian surfaces, and street fixtures from normalized semantic tiles. World explorer exposes Surfaces → Modern traffic / Circa 1910 / Simple surfaces in Human mode. Styles change in place, preserving the camera, streamed data, and generated buildings. Expand Surface details to control markings, sidewalks, crossings, streetlights, signals, parked cars, and inferred parking. The URL preserves these choices: ?surfaces=1910, ?surfaces=modern&parkedCars=0, or ?inferParking=0.

Shared rendering API ​

ts
import {
  createTerrainSurfaceRenderer,
  createDefaultTerrainSemanticRenderer,
} from '@bendyline/molen-terrain/client';

const surfaces = createTerrainSurfaceRenderer({
  style: 'modern',
  details: {
    maxFixturesPerTile: 160,
    maxDetailElements: 16_000,
    parkingOccupancy: 0.7,
  },
});
const renderer = createDefaultTerrainSemanticRenderer({ surfaceRenderer: surfaces });
// Supply renderer to createTerrainSemanticPyramidLayer, or featuresLayer.renderer
// in createTerrainPackageSemanticLayers.

await surfaces.setOptions({ style: '1910' });
// Call once per frame with absolute simulation time (seconds).
surfaces.updateSignals(tick / tickRate);
// And with the scene camera's world position: far tiles' small detail stops drawing.
surfaces.updateDetail(camera.position);
console.log(surfaces.stats());
// Dispose the stream/layers, then the shared controller when the experience closes.
surfaces.dispose();

Worldgen's createWorldgenSemanticRenderers(pack, { roads: { surfaceRenderer: surfaces } }) uses the same controller. Static consumers can pass { surfaces: { style: '1910', details: { streetlights: false } } } to createTerrainSemanticObject or the default semantic renderer. createTerrainSurfaceObject also works directly with a tile and TerrainPyramidTileLayerContext.

setOptions replaces the options, validates them, and cooperatively rebuilds resident surface groups. New tiles use the latest options immediately. A newer update supersedes an older update. The default semantic disposer unregisters controller-owned tiles and frees their geometry and instance buffers. Caller-supplied materials remain caller-owned; materials.road applies to the static renderer, while the shared controller uses its style palette.

For streamed worlds, run surface generation in a module worker. World explorer enables this by default (diagnostic opt-out: ?surfaceWorker=0, or ?worker=0 for all generation workers). The worker handles road topology, intersections, parking inference, draping, fixture transforms, and culling bounds. It transfers typed geometry and instance buffers; the main thread creates render objects and uploads them to the GPU. The geometry and style match synchronous generation.

ts
// surface-worker.ts
import { installTerrainSurfaceWorker } from '@bendyline/molen-terrain/client';
installTerrainSurfaceWorker(self);

// viewer.ts
import {
  createTerrainSurfaceWorkerBridge,
  createTerrainSurfaceRenderer,
} from '@bendyline/molen-terrain/client';
const generator = createTerrainSurfaceWorkerBridge(
  new Worker(new URL('./surface-worker.ts', import.meta.url), { type: 'module' }),
);
const surfaces = createTerrainSurfaceRenderer({ style: 'modern' }, generator);

The default semantic renderer awaits surfaces.createTileAsync(tile, context) before publishing a tile, so pending-layer counts and whenIdle() include surface work. Custom streamed renderers should await that method too. createTile and createTerrainSurfaceObject remain synchronous for static callers. The worker runs one job at a time; aborted queued jobs are removed before height samples are copied. Cancellation settles the caller immediately; a job already executing in the worker finishes before the next job starts. setOptions cancels older queued revisions, keeps existing surfaces visible until their replacement arrives, and makes initial tile readiness follow the newest style. stats().loading counts pending resident replacements, and stats().geometryRevision advances when rendered geometry changes. A host using terrain memory budgets can call the stream's refreshMemoryUsage() after a new revision finishes loading. Disposing the controller also disposes its generator; do not share that generator between separately owned controllers.

Pavement material ​

By default the surfaces draw in a plain vertex-color material. For textured asphalt, concrete and paint, give the controller the pavement material for the renderer's backend once the renderer exists; resident tiles switch in place and later tiles use it too:

ts
import {
  createTerrainPavementMaterialAsync,
  setTerrainGroundOrigin,
} from '@bendyline/molen-terrain/client';

const pavement = await createTerrainPavementMaterialAsync({}, renderer.backend);
surfaces.setMaterial(pavement);
// Each frame, or whenever the floating origin moves, keep the pattern on the ground:
setTerrainGroundOrigin(pavement, [worldOrigin[0], worldOrigin[2]]);

The material reads a surfaceDetail attribute the surface builder writes on every road, sidewalk, curb, marking and lot: meters along the band, meters across it from its edge, the surface kind and band width, and a road's lane width and wear grade or the surface a marking is painted on. Roads and lots get asphalt aggregate (within a few meters, crisp pale chips and dark pits a few centimeters across), blotchy wear, polished wheel tracks and an oil line in each lane, grit in the gutters, storm-drain grates, manhole covers and the odd darker repaired section; asphalt and concrete both get hairline cracks. Worn roads also get potholes in the wheel tracks, each with a ragged lip and a halo of alligator cracking, plus more patches and cracks: none on freeways, trunk and primary roads (grade 0), a few on secondary and tertiary roads (1), more on residential streets (2) and most on service roads and alleys (3). A band sets its grade with wear beside lanes; lots get oil stains; sidewalks and footways get 1.5 m saw-cut slabs and curbs 3 m ones, each slab its own tone, weathered with water stains and, close up, the odd spot of gum; plazas and pedestrian areas get a half-meter paver grid; markings wear through to the asphalt. A marking narrower than a pixel fades into the color and shading of the surface it lies on (beneath on a paint TerrainLineBand, a road's by default; a parking lot's lines take on its oil stains), so from the air lines and rows of bays melt into the asphalt instead of breaking into dashes that beat into moiré. A mark drawn with surfaceSince passes its narrowest dimension as the width, which sets that fade. Detail fades to the plain swatch with distance, so it never shimmers, and each layer's noise is evaluated only where it still shows: distant pavement skips the fine layers, and only fragments within 2 m of a frayed edge evaluate the fray. setMaterial(undefined) restores the plain material. Your own geometry can opt in with TerrainSurfaceMeshBuilder.surfaceSince(start, TERRAIN_SURFACE_KIND.road, …), or a surface (and lanes) on a TerrainLineBand.

Edges that meet bare ground fray into it rather than ending on a ruled line: the lawn side of a sidewalk, both sides of a footpath, dirt road or track bed, a road's shoulder, and a narrow fringe traced around each lot and plaza (skipped where a road, footway, other paved area or building meets it). The material discards a ragged margin so the ground shows through, and inside it a patchy brown soil margin about a third of a meter wide, where soil washes and is tracked onto the paving; it fades out by twenty or thirty meters away, where it would draw a ruled outline round each lawn. Cast paving keeps its formed edge; grass blades creep up to 3 cm over it, and on the lawn side of a street sidewalk or parking lot tufts of lawn about 35 cm across grow up to 10 cm over it, so from mid distance that edge wanders rather than ending on a ruled line. Footpaths and plazas, which often abut other paving, keep only the blades. Where a driveway, footway or paved lot crosses a sidewalk's lawn side, that stretch stays clean (the builder clears the fray flag on its vertices, TerrainSurfaceMeshBuilder.unfraySince), so no ragged seam runs between two slabs. Loose surfaces (dirt, gravel, shoulders) break up to 0.1 m deep, a gentle waviness with blade-scale tufts rather than blob islands. With multisampling the ragged edge is antialiased through alpha to coverage. The margin shrinks away as its noise falls below a pixel, leaving the band's own antialiased edge, and it also closes up within the last few meters of the camera, where its cells would grow to dozens of pixels and read as torn paper. A band opts in with fray: 'outer' | 'inner' | 'both' on its TerrainLineBand (outer is the edge away from the line); bridge decks keep their edges whole.

Maps often stop a cul-de-sac street at the bulb's near edge, or simply stop it, and trace only the sidewalk wrapping round the end. Where a street dead-ends and a mapped footway rings most of a circle about its end (rays from candidate centers meet the footway's inner edge at similar distances, all but the mouth the street enters by), that circle is paved as plain asphalt: a turning circle, or for a tight wrap a rounded end. Footway pieces inside it are clipped away, and footways that merely connect to the street's end do not count as the ring, so a circle never spills past a footway onto a lawn (SurfaceNetwork.findTurningCircles).

Roads overlap wherever they meet: at a junction, at the corners of their sidewalks, across a narrow median. Their paving never shares a plane there, or which road drew on top would change pixel by pixel as the camera moved: the widest road keeps its nominal heights, and each road overlapping another sits one or more 2 mm steps lower, asphalt, sidewalks, curbs and paint alike (SurfaceNetwork.stackRoads). A mapped line that would lie on itself becomes separate roads: where it doubles back more sharply than a band can miter, as two one-way carriageways joined where a divided road narrows do, and at the vertex its own end returns to, as a cul-de-sac mapped up the street and round a loop back to its middle does. A stall line two parking bays share is painted once.

Curbs are a step, not a stripe: a 15 cm vertical face drops from the curb's road-side edge to the asphalt, split finer than the ground grid so it follows the draped ground, and jointed like the curb top. Any draped band can have one with riser (meters) on its TerrainLineBand.

Markings follow US practice (MUTCD), with center lines yellow where the sign profile's countries use yellow (the Americas and Korea) and white elsewhere. Lines are about 11 cm wide (edge lines 15 cm), and broken lines are 3 m of paint in every 12 m.

  • Center lines: residential streets have none unless mapped with lanes. Multilane roads and city arterials get a double solid line. A two-lane country road gets a broken line where passing is allowed, and a double line round curves (more than about 11° of turn over 90 m), within 60 m of a junction, on bridges, and in passing zones too short to use (under about 120 m). Roads with an odd lane count get a two-way left-turn lane down the middle: each edge is solid on the outside and broken toward the turn lane.
  • Lane and edge lines: white broken lines separate lanes going the same way, turning solid over the last 30 m into a signal. Lane counts match the traffic simulation's. Edge lines run along freeways and ramps (yellow on a one-way carriageway's left), country roads, and city arterials at least 8 m wide.
  • Junctions: marked crosswalks (high-visibility bars, laddered with transverse lines at signals) cross every arm of a signal. At stop or yield signs they appear only where an arterial meets the junction or at a mapped all-way stop. Where two quiet streets meet, the corner stays unmarked. Stop lines stand about 1.2 m short of a crosswalk, yield lines are rows of triangles, and signal approaches with two or more lanes get lane arrows. Lines run up to the stop line or crosswalk, or to the crossing road's edge. A road with the right of way past side streets that join from one side only (a tee) keeps its center line across their mouths, and its edge line breaks only where each side street meets it. Where a track crosses a road, a crossing panel carries the rails across it (see Railways).

Sidewalks follow built-up frontage, not every street. Stations every 10 m along a street look for buildings within about 70 m (five for an arterial, eight otherwise) or mapped commercial or retail land. A sidewalk then runs about 40 m past the last house, bridges gaps under about 120 m, and skips stretches shorter than about 80 m. A tile without building footprints reads mapped residential land as built up, and a tile with no land data at all keeps sidewalks on every street. Where a sidewalk mapped as its own footway runs alongside a street, the inferred one on that side is left out (the curb stays). Streetlights, poles, hydrants and mailboxes stand only where there is a sidewalk. Living streets have none.

Where a road continues into another feature (for example where its tags change at a bridge's end), the two lines' ends share a miter (TerrainLinePath.startJoin and endJoin), so their bands meet on one seam instead of leaving a wedge on the outside of the bend. Paint is drawn a few centimeters above the asphalt and is marked walkIgnore, so walkers and cars do not collide with it.

Styles with streetlights also furnish their blocks: utility poles every 38 m on one side of each street with sidewalks, set back behind the sidewalk with a crossarm and a pair of sagging lines between neighbors, and a hydrant at the other curb about every 100 m. Residential streets that run through residential land also get a mailbox on a post behind the sidewalk every 22–30 m on both sides (on a mounting board, a top vaulted in stepped courses, a door with a handle facing the curb and a red flag), about a third of them with a pair of wheeled bins beside it. Poles and hydrants (1,200 boxes) and mailboxes and bins (4,800) have per-tile budgets of their own, enough to furnish every street of a dense suburban tile. Placement is fixed per road, skips junctions, buildings and other roads, and draws in the same instanced box batch as the lights (streetFurniture in the surface stats).

TERRAIN_SURFACE_STYLES provides immutable presets. Pass a custom TerrainSurfaceStyle to change colors, inferred road widths, sidewalk width, and defaults for each detail class:

ts
import { TERRAIN_SURFACE_STYLES } from '@bendyline/molen-terrain/client';
await surfaces.setOptions({
  style: {
    ...TERRAIN_SURFACE_STYLES['1910'],
    id: 'quiet-country',
    label: 'Country lanes',
    dirt: '#a99069',
    roadWidthScale: 0.7,
  },
});

What is drawn ​

  • Modern streets use asphalt, exposed shoulder strips, curb/sidewalk bands, lane dividers, edge paint, stop bars and zebra crossings. Shoulders, like the other street details, are drawn on the finest detail tiles only: local shoulders are a few decimeters wide, below a pixel on the coarser tiles kilometers away, where draping them segment by segment once cost more memory than the roads themselves. Mapped paths are cut at same-grade carriageway edges, so footway fills cannot compete with asphalt at walking height; paths beneath bridges remain continuous. Nearby nodes on divided roads form one junction; crossings follow the external approaches, and short turning links receive no independent crossings. Same-grade junctions leave their centers clear of lane paint. Mapped signal junctions and inferred crossings of two substantial arterials can receive curbside masts with bars over the incoming lanes, yellow backplates, shaded round lenses, and one signal head per lane (up to three). Red, amber and green lenses are self-lit, remaining visible at night. Instanced streetlights occupy eligible corners outside road corridors, buildings, and water: mast arms where an arterial meets the junction, post-top lanterns otherwise (see night lighting).
  • Freeways receive wider paved shoulders, longer lane dashes, a yellow left edge on one-way carriageways, and white ramp edges. Green overhead boards use mapped route references or destinations. At a connected outgoing ramp, an advance gantry and roadside exit board use its exit number and destination when supplied; otherwise the board says only EXIT. Speed-limit boards require a literal numeric maxspeed and display its units. No exit numbers, destinations, or numeric speed limits are invented. Supports sit outside the carriageway; overhead panels retain at least six meters of inferred road clearance.
  • Local intersections use octagonal stop signs by default. A local street meeting an arterial receives stops only on the side street; an all-local junction receives all-way plaques. Mapped traffic_signals, approach stop/give_way points and central stop=all controls override this inference, with grade-separated points excluded. A broad major_road class alone no longer puts lights at every residential intersection. Stop bars cover incoming lanes. This is a North American visual fallback, not a survey of local regulations; disable details.inferStopSigns to retain only mapped stops, or details.roadSigns to hide all signs. Historical and minimal styles omit signs. Sign faces and lettering are batched geometry with host-supplied fonts and no per-sign textures; the worker produces the same geometry as the direct renderer.
  • Street names come from the roads' mapped name, styled by the sign profile's streetNames. Each junction names the two streets that form one of its corners; the corner varies from junction to junction. With mount: "post" (the default) both names share one corner post, each panel running along the street it names and lettered on both faces: narrow blades as in North America, or taller plates as on German and Swiss posts. With mount: "wall" each street gets a plate on the corner building's wall that runs along and faces it, as in Britain, France and Italy; where no wall stands near the corner, the plate stands on a low two-legged frame at the back of the footway. A style with mastArms also hangs a panel from each signal mast arm naming the street its traffic is about to cross (the named arm most nearly perpendicular to the approach), beside the signal heads or past them on a longer arm, and leaves those junctions' corners bare. letterCase: "upper" letters names in capitals. The style's abbreviations turn spelled-out map names into what signs post ("Northeast 45th Street" becomes "NE 45th St"); a direction or street type that is the whole name stays spelled out ("North Street" becomes "North St"). The content catalog's U.S. profiles use white blades and mast panels on green; Britain and Italy black capitals on white wall plates, France white on blue; Germany Zeichen 437 plates and Switzerland white-on-blue plates on posts; the generic fallbacks neutral plates on posts. Unnamed roads, paths, ramps, freeways and compound connector labels ("A Street & B Avenue") get no sign, nor does a name the host's sign font cannot letter (a Japanese name in a Latin face), and junctions on bridges or in tunnels get no corner name. Names are never invented. Street names are a separate surface:street-names mesh drawn within 250 m of the tile, nearer than the other boards' 900 m, since their lettering is a pixel or two tall beyond that.
  • Parking, plazas, and pedestrian polygons are filled, with holes retained. Pedestrian polygons and mapped paths use distinct heights above parking pavement, including inferred lots, so overlapping sidewalk and asphalt fills remain stable at walking height. Land cover, paved polygons, roads, and markings are clipped to the same rendered terrain grid and cell diagonals, so large footprints follow dips and hills without covering streets or intersecting each other. Parking receives rows of bays aligned to mapped aisles (or a regular fallback grid) and deterministic parked cars; layout checks keep bays out of mapped aisles, holes, buildings and water. Cars are drawn from details.parkedVehicles, a list of { id, spec } a host builds from loaded vehicle types (the world explorer uses the molen.entities pack's, in type order); without it no cars are parked.
  • Some basemaps omit parking polygons. Service-aisle pairs can infer pavement inside mapped commercial/retail sites, near large buildings outside mapped residential areas, or with explicit parking_aisle metadata. These pairs can be angled and 9–60 world units apart, with at least 12 units of overlap and half the shorter run. This also fills wedges where access roads meet. Without this evidence, the fallback requires three parallel runs at least 28 units long, 9–26 units apart, with at least 20 units of overlap and half the shorter run. Nearly straight fragments are joined before measuring; aisle pairs across ordinary streets are rejected.
  • Bounded service-road loops also infer pavement when their connected courts have parking tags, a commercial site, or a nearby building of at least 240 square world units outside residential land use. This covers office loops and small entrance courts without paving an entire property. Faces must be 80–12,000 square units and no more than 240 units across. Junctions tolerate up to 0.6 units of source simplification error; larger gaps and clipped tile boundaries remain open. Tagged driveways, alleys, unpaved roads, bridges, tunnels and other road layers do not supply inference geometry.
  • Inferred areas are clipped to the site or tile and cut around buildings, water, existing parking, and mapped vegetation, playgrounds and sports fields. New loop fills also exclude residential land use. This is a visual inference, not surveyed parking geometry; disable inferParking to use only mapped lots. Large unclassified buildings can still be mistaken for commercial premises, and repeated aisle patterns can occur in residential developments too.
  • Circa 1910 uses earth-colored roads, narrower inferred widths, and wheel tracks. Its defaults omit road paint, sidewalks, signals, streetlights, parking stripes, and modern parked cars. It retains the present-day map layout and buildings; this is an art treatment rather than a historical reconstruction. Individual details can be overridden.
  • Simple surfaces retain road and parking fills with decoration disabled.

The decoder preserves road subclass, service, link (including Protomaps is_link), surface, lanes, oneway, layer, bridge, tunnel and explicit width. Properties absent from the source use class-based defaults. Tunnel roads are excluded from the ground painter; Earth views add separate underground bores as described below. Bridges and differing layers do not form surface junctions. Tagged bridges receive inferred decks, slabs, barriers and supports, at heights that clear whatever they cross (see Road grading). A deck that reaches its end still raised hands the rest of the descent to the roads joined to it there, which climb on retaining walls with a parapet along any drop of a meter or more. Curved profiles follow distance along the mapped road. Barriers sit outside paved shoulders and open at merges where the adjoining carriageway is at the same height; edge paint also clears these openings. Traffic uses the same grading samples. Surveyed deck heights and authored bridge connections take precedence. Inferred grades depend on the available tile geometry and terrain, so they are not surveyed engineering profiles. Crossing paint, inferred sidewalks, signal placement and parking occupancy are decorative, not surveyed traffic-control or navigation data. Ambient life builds its own lane graph from the same features for NPC traffic. Earth view and world explorer match signal heads to that graph, displaying the same phase that controls approaching cars. Without a matching simulation junction, signals use a deterministic cycle: 24 seconds green, 3 seconds amber, and 2 seconds all-red clearance, with opposing approaches sharing a phase. Custom hosts call surfaces.updateSignals(elapsedSeconds, resolver?); a resolver receives a world-space junction, outward approach direction, and junction radius, and returns 'red', 'amber', 'green', or undefined for the default cycle. Direct/static consumers can call updateTerrainSurfaceSignals(object, elapsedSeconds, resolver?) on the surface object instead. Here object is the group returned by createTerrainSurfaceObject.

surfaces.updateDetail(position) hides each tile's small detail beyond its draw distance from the camera (the scene camera's world position), measured to the tile's footprint: road signs, street fixtures and signal lenses beyond 900 m, lane markings and parked cars beyond 1.5 km. There they span a pixel or less, yet from a jet a view held a few hundred such draws for tiles kilometers away. Each mesh carries its distance as userData.detailDistance; the call does nothing until the camera has moved 25 m or tiles have changed, and detail shows again as the camera nears.

Signage data in PMTiles ​

PMTiles is the archive format, so its contents depend on the tile producer. OSM supports highway=motorway_junction with ref for an exit number; ramps can carry junction:ref, destination and destination:ref. Road ref identifies the route, not the exit. The decoder preserves these fields as ref, junctionRef, destination and destinationRef, plus maxspeed; exit POIs retain ref and legacy exit_to as exitTo. oneway=-1 reverses the decoded geometry, and one-way fragments join without reversing their travel direction. Motorways are implicitly one-way unless the source explicitly says otherwise.

OSM also records highway=stop and stop=all, highway=traffic_signals, and highway=give_way. These need point features in the configured POI layer; merely having an OSM-derived basemap does not guarantee their presence. The Protomaps layer reference describes a selective context map. Its current road producer retains route/shield text and high-zoom one-way cues, but does not emit the destination, junction-reference or maxspeed attributes consumed here. Accurate numbered exits and posted limits therefore require an enriched tile source that retains those tags. There are no live Overpass requests or extra network lookups during rendering.

Numeric OSM speeds without a unit are km/h; explicit mph stays mph. Variable, conditional and country-code speed values are not interpreted. Road signs, gantry positions and sparse spacing are visual approximations, using a right-hand-traffic layout, with a maximum of 48 signs per detail tile inside its shared fixture budget. Street names sit outside both limits: 64 named corners per tile, and one mast panel per signal mast, so names never crowd out signals or lights. Labels fit uniformly within the panel (bounded to 80 characters); unsupported glyphs use a question mark. stats().roadSigns counts the placed boards, and stats().streetNameSigns how many of them are street names. Ambient traffic uses the more conservative signal inference and treats mapped stop controls as give-way controls; this change does not add a full-stop/dwell simulation for the decorative signs.

Ground surfaces render at all available semantic levels. Fine markings and fixtures default to the finest pyramid level; detailLevelsBelowMax extends them to coarser levels. Fixture/car and detail-work budgets bound each tile. A portion of the detail budget is reserved for parking. maxDetailElements counts the quads drawn for sidewalks, curbs and paint (dash gaps cost nothing), and roads are furnished in order of importance: freeways and arterials first, so on a tile that runs out the side streets go without, not the main roads. Geometry is batched by surface role, broad land-cover meshes share indexed vertices, and fixture/car parts are instanced. Stats cover resident surface tiles, including temporarily hidden tiles.

Parking data in PMTiles ​

PMTiles is an archive format; the encoded tile schema determines which features it contains. The local Sammamish archive retains service aisles but has no parking polygons in the nine zoom-15 tiles around the shopping center. The reported shopping and office courts also lack parking_aisle road subtypes: their roads carry kind=minor_road, kind_detail=service, so geometry and nearby buildings supply the missing evidence. The renderer consumes polygon features classified as parking or car_park when supplied, including holes; those footprints take priority over inferred fills. A parking POI alone does not supply a boundary.

Protomaps deliberately includes a subset of OSM features. Its documented landuse polygon kinds do not currently include parking, while roads may carry parking_aisle detail. See the Protomaps layer reference.

Parking garages ​

The same archive identifies multi-storey car parks, though it drops building=parking and parking=multi-storey. A parking POI keeps the source id of its OSM element, so a footprint that shares its id is one element tagged both building=* and amenity=parking. Failing that, a POI inside exactly one footprint counts if its name claims a structure ("garage", "car park", "Parkhaus", "立体駐車場"), since an unnamed one is as likely a tower's basement. Footprints under 450 m² or over 48 m tall are left alone: small roofed lots, and towers with parking in them.

Height gives the number of decks: Protomaps derives a missing height as 3 × levels + 2, so (height - 2) / 3 recovers building:levels. An unmapped height is assumed to be three decks. parking_entrance POIs within 6 m of the walls place the doors. applyParkingStructure then requests the molen.worldgen.use.parking_garage style and modeled decks, ramps and cars; see Inferred building interiors. A style pack without that style keeps its usual architecture.

Building use ​

Stock Protomaps footprints say only building. kind_detail is empty on all of them, and in the regional archives between 3% and 22% carry a height. So the use of a building is argued from what surrounds it, strongest evidence first:

  1. A POI with the footprint's source id is the same OSM element, so the building is that thing: a hotel, school, place_of_worship, fire_station and so on.
  2. A POI inside exactly one footprint names it when it is an institution (hotel, hospital, school, mall, library, museum). A cinema or a chapel inside a tower does not.
  3. Eight or more shops and restaurants in a footprint of 5,000 m² or more make a mall.
  4. The land use under it: school, university, college and hospital land.
  5. Its shape on that land: at 15 m or more on commercial land it is offices, at 12 m or more on residential land it is flats, at 45 m or more a tower, and at 60 m or more on anything but residential land a skyscraper.

associateBuildingUses returns the use and which of these decided it, and applyBuildingUse puts the use ahead of any tenant in the interior's labels, so a cafe in the lobby does not make the tower a cafe. It also requests a matching style from the molen.worldgen.use.* family, and a style pack without one keeps its usual architecture. Styles in that family are chosen by a building's use, so they are not part of the structure library.

Everything else, most buildings by far, stays with the style rules. Use ?synthetic=1&uses=1 in world explorer for a street with one of each.

Road grading ​

A digital elevation model is sampled every ten meters or so and knows nothing of roads, and many basemaps keep neither a bridge's height nor the OpenStreetMap layer tag that says which of two crossing bridges is on top. Draped as mapped, a street tilts with every hillside it runs along and ripples with the samples, and every bridge of an interchange stands at one height, through the others. Two passes put that right. World explorer and mountEarthView run both by default; compare with ?roadGrading=0 (neither) or ?earthworks=0 (bridges only).

Leveled ground ​

The ground is graded for roads the way it is for an airfield, before the terrain is meshed, so the terrain, everything draped on it and everything that drives on it agree:

  • Profile. A road's height at a point is the elevation averaged 30 m either way along the road's own direction, weighted toward the point: bumps shorter than a block go, the hill stays. It is read from one elevation level, two below the finest (about the resolution elevation is surveyed at), so every tile and every level of detail gets the same answer.
  • Cross-section. The road is level from edge to edge at that height: the carriageway with its curbs and sidewalks, a freeway with its shoulders, a track with its ballast.
  • Bench. A road draped on the ground grid is only as level as the grid vertices around it, so the level ground reaches 1.25 grid cells past the road's edge. Beyond that it blends back to the surveyed ground over 1.6 cells (at least 8 m). At High detail that is about 16 m and 21 m; at Ultra, half as much.
  • Between roads the nearest one decides. Two streets on one slope each keep their own bench and the block between them takes up the difference, as a graded city block does.
  • Bridges and tunnels are not graded for (the ground under a deck is the river's or the lower road's), nor are footpaths, which take the ground as they find it. Mapped water keeps its bed beside a road. No point moves more than 12 m.

Grading runs for the two finest feature levels, where the rendered grid is no coarser than 28 m between vertices; coarser tiles are seen from too far to tell. Adjacent tiles agree on their shared edge exactly: each reads the roads of the eight tiles around it as well as its own.

Clearance ​

Every inferred bridge gets a height profile, and so does every road that has to climb to one:

  • A deck meets the roads at its ends where they stand and spans straight between them. Over ground with nothing mapped beneath it (water, mostly) it rises toward 6 m, 3 m for a footbridge, no faster than its class of road climbs.
  • Where it crosses another way without sharing a vertex, it clears that way's surface by a clear height plus 1.4 m of girder and slab: 6.5 m over a road (5.1 m clear, the 16 ft 9 in of US practice and well over the 14 ft legal minimum), 8.4 m over a railway (7 m clear, for double-stack trains and wires) and 4.4 m over a footpath. The height holds across the lower way's whole width.
  • Two bridges that cross are stacked. The mapped layer decides which is on top when the source keeps it. Otherwise: the deck whose span already stands 3 m or more above the other's (a bridge between two hilltops is over a ramp in the valley); else by what they carry (ramps over streets, streets over freeway carriageways and railways); else the one farther along its structure from where it lands; else the one running more nearly north and south. Only the two structures near the crossing enter into it, so every tile that sees the crossing decides alike.
  • A deck falls away from a crossing no faster than its class allows: 5% for a freeway, 7% for its ramps, 6 to 8% for streets, 10% for service roads and footpaths, 3% for heavy rail and as stairs do for steps. Breaks in grade are rounded over about 20 m.
  • A road climbing to a structure lies on the ground wherever that same structure passes over it: an approach never lifts what its own bridge has to clear. Lift passes down the ranks only, so a footbridge's steps come down to the street and the street does not rise to the footbridge; a footpath beside a climbing road rides on its embankment.
  • Decks side by side (twin carriageways, a sidewalk mapped along a road bridge) stand level with each other.

A vertex shared by a bridge and a road beneath it is taken for a junction or a mapper's tie, never a flyover, and a way's end lying on another way is joined to it even where the tile dropped the shared vertex. Surveyed deck heights and authored bridge connections are left alone. The stacking order where nothing is mapped is an inference that produces a buildable interchange, not a survey of the real one.

Using it ​

createTerrainPackageSemanticLayers wires both passes with one option and hands back the ground transform for the stream:

ts
const semantic = await createProfiledTerrainPackageSemanticLayers(pkg, {
  roadGrading: { heights: elevationSource }, // the stream's elevation source
  featuresLayer: { renderer },
});
const stream = await createTerrainPackagePyramidStream(pkg, {
  layers: semantic.layers,
  ...(semantic.roadGrading
    ? { transformHeightfield: semantic.roadGrading.transformHeightfield }
    : {}),
});

Pass earthworks: false to keep the ground as surveyed, and maxSpacing to change the coarsest grid that is leveled. A host with its own transform (an airport's leveling) applies the road grading first; composeEarthGroundGrading(roads, airports) from @bendyline/molen-earth/client does that. The pieces are public for custom hosts: createTerrainRoadGrading and withTerrainRoadGrading (client), and the pure gradeRoadEarthworks, roadProfileHeight and gradeTransportSeparations (kernel), which need neither three.js nor a tile stream.

Without the option, each tile's bridges are still graded from that tile alone, with the same clearances. A bridge cut by a tile edge then cannot see what it crosses in the next tile and assumes a free clearance at the cut.

Both passes run on the main thread in slices of about 2 ms, so a tile arriving under a fast camera does not hold a frame. A town tile's earthworks take 3 to 10 ms in all; an interchange and its surroundings, 15 to 35 ms.

Tunnels ​

World explorer and mountEarthView render mapped tunnel: true corridors in Human mode. Roads, paths and railways receive an open-ended floor, walls and ceiling. Portal cuts remove terrain and draped paving only below the bore ceiling, leaving the hill above it intact. Visible mesh collision includes the lining. World explorer's free flight slows near the ground, can descend to 2 m above a road, and uses the bore floor and ceiling while underground. Aircraft ground support also uses the bore floor at the aircraft's altitude; its existing body collision still determines whether an aircraft fits.

The Seattle PMTiles fixture contains is_tunnel centerlines for the Mount Baker Ridge road and bicycle/pedestrian tunnels. It supplies neither surveyed floor elevations nor clearances. The default infers a straight grade between terrain heights at the complete route's endpoints, with 6.5 m road, 6 m rail and 3.5 m path clearance and the existing transport width defaults. These are approximate interiors, not surveyed tunnel geometry. Semantic providers can supply tunnelFloorElevation (absolute world Y) and tunnelClearance; the MVT decoder accepts tunnel_floor_elevation and tunnel_clearance/tunnel_height, or configurable property names.

Fragments are clipped out of their tile buffers and joined across neighboring tiles before grading, so tile boundaries do not create portals or conflicting floor heights. Searches are bounded to 16 tiles. Unresolved long routes and branches are omitted rather than assigning a terrain height to an underground tile boundary. A route end counts as a portal only where an ordinary (non-tunnel) line continues from it: a gap between fragments of a longer buried line, such as a city subway split into thousands of pieces, would otherwise grade the bore to the street there and open the ground along its whole length. Tunnel inference runs at the finest source feature level and above. Hiding the Human layer also removes its portal cuts and navigation support; the original elevation heightfield always remains available for surface anchoring.

Custom package hosts opt in with createTerrainPackageSemanticLayers (or its profiled variant), passing tunnels: { heights: elevationSource } alongside their feature renderer. Share the elevation source returned by openTerrainPackagePyramid with the terrain stream. withTerrainTunnels wraps a custom semantic renderer, and sampleTerrainTunnel(root, x, y, z) returns a visible bore's floor and ceiling in the root's coordinate frame. Observers above the ceiling continue using the surface height. Static hosts can use createTerrainTunnelObject with complete route lines and a ground sampler that covers both portals.

Railways ​

Railway lines in the transportation layer (a class, subclass or service that names rail, tram or train) are drawn as track rather than as roads, by the same surface renderer and worker. Everything below is inferred from the map's classes and points and placed by fixed rules, so a tile draws the same railway on every load and neighboring tiles agree.

  • Track beds. Each track is a ballast band as wide as its sleepers plus a shoulder each side: about 3.6 m on a main line, 3.3 m on a siding and 3 m on yard, spur and crossover tracks. Main lines and sidings in the open stand on a prism whose shoulders slope about a meter down to the ground wherever no other track runs alongside. Yard ballast is darker and browner, and mapped railway land (the railway land use of yards and corridors) is ballast grey rather than lawn.
  • Sleepers and rails in the pavement material. A track band is TERRAIN_SURFACE_KIND.track. With the pavement material (see Pavement material) it draws sleepers and a pair of rails across the band's middle: concrete sleepers every 0.6 m on main lines and light rail, timber every 0.52 m on sidings, yards, spurs, heritage and disused track, and rails at the track's gauge with a polished head over a rusty web and foot. Both are box-filtered, so they stay antialiased at every distance and settle, as they shrink below a pixel, to the averaged dark stripe a track makes in an aerial photograph: a yard reads from the air as many parallel tracks on grey ballast. Track is standard gauge unless the style's railGauge gives the region's main-line gauge (1.067 m for Japan's conventional lines, 1.676 m for India's); light rail, trams, subways and lines named as Shinkansen stay standard gauge, and lines mapped as narrow_gauge are 1 m.
  • Rails in 3D. On the finest tiles each rail is also modeled: a 72 mm polished steel head on a rusty web 0.17 m deep, its head TERRAIN_RAIL_HEIGHT (0.21 m) above the ballast top. Rails run on unbroken through level crossings and over bridges and stay out of walking and driving collision. They are TERRAIN_SURFACE_KIND.rail: the pavement material polishes the heads and drops a rail wherever it would be under about a pixel and a half wide, where the track's drawn rails beneath it take over, so a yard seen from a plane never sparkles with broken rails. Rails and wires also stop drawing for tiles more than 260 m (rails) or 200 m (wires) away, counting the camera's height above the ground as well as its distance.
  • Level crossings. Where a road crosses tracks on the same layer, neither on a bridge nor in a tunnel, a concrete panel level with the rail heads covers the crossing, with short ramps down to the road; tracks within 30 m of each other along one road share one crossing. A main line or siding crossing a public road gets active warning: a crossbuck (R15-1) with a plate counting the tracks (R15-2P) when there is more than one, a pair of flashing lights (dark until a train comes), a raised gate arm on roads at least 5 m wide, and an equipment house beside the track. Yard, spur and service-road crossings get crossbucks only, and disused track nothing. Each approach also gets an advance warning sign 45 to 75 m up the road: the round yellow W10-1 in the United States, Canada and Mexico, a red-bordered triangle elsewhere. Signs stand on the side the region's sign profile drives on, and a one-way carriageway has a single approach.
  • Turnouts. Where a track's end meets another track's side at a shallow angle, where three or more track ends meet, and at mapped switch points, a turnout gets a powered switch machine on a main line or a hand-thrown stand with its target and lamp elsewhere, beside the points and opposite the diverging track. Mapped buffer_stop and derail points get a buffer stop across the track's end and a yellow derail on its rail.
  • Signals. Mapped signal points become color-light signals: a mast with three lenses on main lines, a dwarf signal beside yard, siding and tram tracks, and a signal bridge where three or more stand abreast over parallel tracks. Map data keeps no direction, so a signal faces the trains heading toward the nearest turnout it stands short of, or governs the trains it is mapped to the driving side of. Aspects are mostly green, yellow approaching a junction, and the odd red. Each lit lens is a self-lit lamp in one instanced draw per tile; object.userData.railLamps lists them.
  • Lineside signs. Whistle posts ("W") stand 400 m ahead of crossings with active warning on main lines, unless another crossing comes first. Mileposts stand at mapped milestone points and, where none is mapped nearby, wherever a main line crosses a north-south line of a world grid a mile apart. "YARD LIMIT" boards stand on a main line about 150 m outside each stretch it runs beside yard tracks. Like road signs, they need fonts for their lettering.
  • Overhead catenary. railElectrification on the surface style (or in details, which overrides it) decides which tracks are wired: 'light', the default, wires light rail, trams and subways in the open; 'all' also wires heavy rail, for regions whose main lines are electrified (Japan, India, much of Europe, Sydney's suburban network); 'none' draws no wires. Masts stand about every 60 m on heavy rail, 50 m on light rail and 35 m beside trams, at stations fixed in the world so wires run on across tile edges, and on the outside of a pair of tracks. Each mast's arms carry a messenger wire sagging between masts, droppers every 5.5 m and a level contact wire 5.2 to 5.6 m up, staggered from side to side; street trams carry a single contact wire. With WebGL, each wire segment also stops drawing beyond 140 m, where it would be far thinner than a pixel.
  • Platforms. Mapped platform land is a raised slab with walls down to the ground: 0.36 m beside light rail and trams, 1 m beside subways, 0.4 m beside heavy rail in North America and 0.9 m elsewhere, and curb height with no track within 40 m. Edges that face a track get a yellow tactile strip. Platforms on viaducts are left to the viaduct.
  • Disused lines keep their track, with rusted rails, weeds through the ballast and the odd missing sleeper, but get no signals, crossing equipment or wires.
  • Rolling stock in yards. With details.railCars (rail vehicle types: specs with a rail block), yard, siding and spur tracks hold cuts of coupled cars. Freight cars and the odd idle locomotive stand on heavy rail, and light-rail cars stand in light-rail yards. A cut is a unit train's cars of one kind and paint, or a mixed manifest in blocks. Cuts keep 32 m clear of each turnout's points and 14 m clear of road crossings. Tracks are split into blocks at stations fixed in the world, about 75 m apart. That way neighbouring tiles, and the coarser tile one level up (yards are filled that far out, for the view from the air), agree on which blocks hold cars and what they hold. railCarOccupancy scales how full they are (default 1: about three yard blocks in four, half of the sidings). The cars are ordinary parked-vehicle placements (kind, spec, color, standing on the rail heads), drawn with the parked cars when parkedCars is on. Far off each stands in as a silhouette of its spec.rail.profile (railVehicleProxyGeometry in @bendyline/molen-client/vehicles), and a host makes the near ones entities as it does a street's.

railEquipment: false (on the style or in details) keeps the beds and rails and drops the equipment: signals, switch stands, crossing signs, lights and gates, lineside signs and catenary. The Simple surfaces style turns it off.

ts
import {
  createTerrainSurfaceRenderer,
  TERRAIN_SURFACE_STYLES,
} from '@bendyline/molen-terrain/client';

// A region whose main lines are electrified and on 1,067 mm gauge.
const surfaces = createTerrainSurfaceRenderer({
  style: { ...TERRAIN_SURFACE_STYLES.modern, railElectrification: 'all', railGauge: 1.067 },
});
// Later: tracks only, no equipment.
await surfaces.setOptions({ details: { railEquipment: false } });

Equipment has budgets of its own, scaled by maxFixturesPerTile: 25 boxes per fixture for signals, stands, crossing gear and masts, as many again for wire segments, and up to 48 lineside signs a tile. Rails in 3D take up to three quarters of maxDetailElements, in segments a few meters long. Tracks are furnished most important first: main lines, then light rail, sidings, trams, yards and spurs, then disused track. stats() counts railTracks, railCrossings, railSwitches and railSignals. placeTerrainYardCars is the yard placement on its own. terrainRailTrack(feature, countries) (a line's mode, service, gauge and sleepers) and TERRAIN_RAIL_HEIGHT are exported from @bendyline/molen-terrain/kernel as well, for anything that must run on the rails the renderer draws.

The Protomaps layer reference keeps a railway's kind_detail (rail, light_rail, tram, subway, disused and others) and service (yard, siding, spur, crossover), and its points layer keeps railway nodes: switch, signal, level_crossing, railway_crossing, buffer_stop, derail and milestone. It keeps no electrification, voltage, gauge, signal direction or aspect; those are inferred as described above, not surveyed.

Lines beyond roads ​

createTerrainLinearObject(lines, context, profile) is independent of road semantics. Lines use normalized tile-local [u,v] points; profile dimensions use world units (meters in metric Earth packages). A profile combines offset bands with optional dash patterns and repeated fixtures. Compatible degree-two fragments join before rendering. The path sampler handles duplicate points, arc-length spacing, continuous offset edges, bounded joins at bends, closed-loop seams, and tile clipping. Bands can follow terrain or use absolute elevations. Streamed layer contexts provide surfaceResolution, the actual ground-grid resolution after quality capping; custom contexts may supply it when their rendered grid is coarser than the source heightfield. Ground overlays use this grid without changing the logical heightfield used by simulation and collision.

For example, a rail profile combines ballast, two raised rails, and repeated sleepers:

ts
import { createTerrainLinearObject } from '@bendyline/molen-terrain/client';
const track = createTerrainLinearObject(lines, context, {
  bands: [
    { width: 3.2, color: '#837f70', elevation: 0.25 },
    { width: 0.08, offset: -0.72, color: '#b8b8b2', elevation: 0.46 },
    { width: 0.08, offset: 0.72, color: '#b8b8b2', elevation: 0.46 },
  ],
  repeaters: [
    { spacing: 0.65, size: [2.4, 0.16, 0.22], color: '#76604b', elevation: 0.28 },
  ],
  maxElements: 20_000,
});

For a utility corridor, use narrow elevated bands and widely spaced pole repeaters. size is width across the route, height, and length along it. Band dash: [length, gap] and phase use world units along the path; callers can carry phase across tile fragments when their source provides route chainage. terrainLinePath and sampleTerrainLine are exported for custom attachment/model placement. The surface renderer's railways are built on it, and traffic simulation is ambient life.

Road sign fonts ​

Pass fonts and optional signFont in surface options. The default Earth font catalog supplies Overpass for highway, exit, speed and stop signs; source case and accents are preserved. Font geometry is batched into the sign mesh and the worker receives font data only when it changes. See Fonts and lettering for the shared layout engine and custom typefaces.

Road sign pattern library ​

The world-explorer sample includes Road sign library (road-signs.html), linked from its main view. It renders twelve patterns in the United States and ten elsewhere (route markers and mast-arm names are U.S. conventions; each region shows its own corner street names) from synthetic semantic tiles through the production detector, with country/state selectors, a 50-state route-marker collection, searchable cards, rotatable 3D previews, and source-cue annotations. The samples are demonstrations, not records of surveyed signs. All hardware positions are estimated.

Pattern IDSupported cuesMissing-data behavior
highway-overheadConnected motorway departure; destination, destination:ref, junction:ref, or nearby motorway_junction metadataRegional exit label, if configured, only when topology establishes a departure
highway-exitSame departure cues; smaller roadside assemblyNo invented exit numbers
all-way-stopCentral stop=all or mapped controls on every incoming approachLocal junctions may infer all-way stops; explicit signals override them
minor-stopMapped approach stopMinor approaches to an arterial may infer stops
street-speedLiteral maxspeedOmit unknown, conditional, or variable limits
freeway-speedMotorway plus literal maxspeedSame rule, with a 40% larger panel outside the shoulder
yieldMapped highway=give_way approachNo inference from ramps or roundabouts alone
attractionRamp destination with aligned destination:colour=brownNearby tourism POIs alone do not establish an exit or driving distance
route-guideMotorway ref/shield_text, name, or destinationOmit when labels are unknown
route-markerExact supported network plus shield_text/ref; explicit state reference; local SR/SH plus state geographyOmit ambiguous or unsupported networks; never invent a route number
street-name-mastSignal junction plus a named cross street; a streetNames style with mastArmsNo panel without a named cross street at 30 degrees or more
street-name-bladeTwo differently named streets forming a corner (at signals too, unless mast arms carry the names)No post for unnamed roads, ramps, paths, freeways or junctions on structures
street-name-wallThe same corner cues, a mount: "wall" style, and building footprintsA low frame where no wall runs along and faces the street near the corner

The MVT decoder retains destination:colour as destinationColour. Semicolon entries align with the destination list, including empty entries. A single brown colour applies to the whole destination list. Mixed green/brown destinations become separate boards, keeping only the brown names on the attraction board. Exit numbers are included only when mapped. See OSM destination colours and FHWA recreational sign guidance. Global pattern identities are independent of the regional appearance described below. Directional/lane-specific destination suffixes, service logos, temporary restrictions, and exact hardware surveys are not supported yet.

TERRAIN_ROAD_SIGN_PATTERNS from @bendyline/molen-terrain/client exposes the catalog. Each SurfaceSign in object.userData.roadSigns carries pattern, evidence, source, the resolved appearance, and an optional roadId. For an overhead exit or attraction board, that ID identifies the ramp providing the legend. source: 'mapped' means the control or legend comes from mapped data; it does not mean the gantry, pole, or exact sign location was surveyed. This metadata also survives the surface-worker path. createTerrainRoadSignObject(sign, context, { fonts }) renders one detected sign with the same batched face/support geometry; dispose it with disposeTerrainSurfaceObject. Coordinates remain local to the supplied tile context.

Regional sign appearances ​

Patterns describe what a sign means and which map cues support it. A TerrainRoadSignProfile supplies guide colours, speed-sign shape, native units, exit wording, stop/yield legends, roadside placement and a font role. The first Earth presets are:

CountryMotorway guidesPosted speed panelRoadside placement
United StatesGreenRectangular, mphRight
Great BritainBlueCircular, mphLeft
GermanyBlueCircular, km/hRight
FranceBlueCircular, km/hRight
ItalyGreenCircular, km/hRight
SwitzerlandGreenCircular, km/hRight

Europe has no single guide colour. Destination category also matters: British primary routes use green and local destinations white; French major destinations use green and other destinations white; Italian non-motorway interurban routes use blue. The British and French side-exit presets use white when the destination category is unknown. A uniform mapped destination:colour of green, blue, white or yellow overrides the default panel colour; light panels receive dark lettering. Mixed-colour panels remain approximate. The catalog's sources link the relevant national references, and its notes state each preset's limits.

The Earth pack provides road-signs (signs/catalog.json) and road-sign-regions (signs/regions.atlas.json). loadEarthContent loads these independently of buildings and fonts. World explorer and mountEarthView select a profile from the terrain tile's centre, using dedicated country and U.S. state outlines in the same Mercator coordinate frame. Exact containment wins; a bounded 2.5 km nearest-outline fallback fills coastal gaps. Right-driving countries are included too, so their interiors cannot inherit a nearby left-driving rule. Architectural regions do not select signs. These simplified outlines can be imprecise near borders and coasts. Countries without a preset use the neutral generic profile; it is not a national standard and keeps source units visible. Country coverage is deliberately explicit.

Posted values are never converted or guessed from the profile: 50 means 50 km/h, while 50 mph remains 50 mph even under a metric preset. Circular signs omit the unit only when it matches the country's convention. All presets except the U.S. require mapped stop controls by default; a local crossroad alone does not establish an all-way stop. Explicit mapped signals still win. details.inferStopSigns can override the profile's inference default. The same regional driving side controls roadside signs, approach stop lines, signal heads and the inner edge of a one-way motorway. Mapped one-way direction is preserved. Marking colours and sign hardware remain medium-fi approximations rather than complete national standards.

Earth uses these country outlines for ambient traffic too. Japan, Australia, New Zealand, Ireland, India, Thailand, South Africa and other left-driving countries and territories use the generic-left profile where a national sign appearance is not supplied. It retains neutral panels and explicit source units while placing signs on the left. Hong Kong and Macao have separate outlines from mainland China. Selection uses the same terrain tile centre for roads and traffic; simplified borders and coastal outlines can be imprecise.

Custom hosts can pass signProfile in TerrainSurfaceOptions. It takes precedence over the optional fourth argument to createTerrainSurfaceRenderer, a (x, z) => profile resolver. The host resolves the profile before dispatching a serializable worker job. To share Earth's selection, call createEarthRoadSigns(content.roadSigns, metersPerUnit) from @bendyline/molen-earth/client and pass its profileAt callback. Without sign content or an explicit profile, standalone terrain rendering keeps its existing U.S. appearance.

TerrainSurfaceOptions.drivingSide overrides handedness for markings, signals and signs together. mountEarthView({ ambient: { drivingSide: 'left' } }) applies this override to its surfaces as well as its traffic. Without an override, the Earth sign content selects the rule automatically; without that content, the default remains right. Custom hosts can share createEarthRoadSigns(...).drivingSideAt with EarthAmbient.

Profiles request roles such as sign.gb or sign.de; hosts can bind those roles to additional compiled font faces. The shipped catalog currently falls back to Overpass for every country.

The Earth pack also provides road-sign-profiles (signs/us-states.json) and route-shields (signs/route-shields.json). All 50 U.S. states have primary route-marker artwork and subdivision profiles, which override the country appearance. U.S. regulatory panels stay shared; municipal street-name blade styles are not inferred from state identity. View all state markers at road-signs.html?view=states, or use ?region=us-wa for Washington's full pattern set.

The decoder retains network and shield_text independently as network and shieldText. Exact network identity takes precedence over geography. County, Interstate, U.S. highway, business, toll and unsupported secondary networks are not mapped to primary state shields. Tennessee specifically requires US:TN:primary. Missing/compound route numbers are omitted. For custom hosts, pass routeShields: content.roadSigns.shields with the profile resolver. The worker caches this vector library just like fonts; sign annotations retain network and number without copying the artwork into every detection record. profileForSubdivision provides explicit subdivision lookup alongside profileForCountry.

Artwork is a medium-fi adaptation of CC0 OpenStreetMap Americana symbols and authored shapes; state borders use public-domain Natural Earth data. It is not a set of exact DOT fabrication drawings. See content/earth/signs/README.md for licenses, source pins and offline regeneration. It approximates Highway Gothic and does not supply exact Transport, DIN or Frutiger faces. Route shields, detailed national panel layouts, lane arrows and multilingual exit plaques remain future extensions. Source destination names are preserved rather than translated.

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