Layers data

Layers are the main data units rendered by autk-map. Each layer combines a dataset with a rendering type, allowing the map to interpret the input geometry, apply the appropriate visual rules, and compose multiple datasets in the same view.

Layer basics

Layers are loaded with loadCollection() and then rendered according to the selected type. The basic call has the following shape:

map.loadCollection(layerId, {
  collection,
  type,      // optional for inferred vector layers
  property,  // required for raster layers
});

Part	Description
layerId	Unique layer identifier used later to update thematic data, visibility, picking, and other rendering properties.
params.collection	Source FeatureCollection to load.
params.type	Optional when the geometry can be inferred for vector layers. Physical layers should usually pass type explicitly.
params.property	Required for raster layers so the renderer knows which numeric value to read from each cell.
params.loadConfig	Optional load-time building fallback settings; see Layer sizing and load-time options.

autk-map also assumes a few basic rules about how layer data is organized and loaded:

• Projected coordinates — autk-map expects projected coordinates. You may use any projected coordinate system, but all loaded layers must use the same selected system.
• Shared origin — the first loaded collection's geometry establishes the origin used by subsequent layers. For a packed raster with null geometry, load a vector context or extent first, as shown below.
• Raster bounds — a raster collection's projected bbox: [minX, minY, maxX, maxY] defines its rendering rectangle, but does not by itself establish a geometry-based origin.
• Camera framing — the default flat camera is city-sized. Small custom geometries may need an explicit camera position, as shown in the building examples. There is no map.boundingBox property; use the camera controls.

Physical layers

Physical layers are specialized layer types designed for common map components such as streets, buildings, parks, water, and ground surface. They are used to build the map context and are useful when the dataset already represents those physical urban elements. In most cases, physical layers should be loaded with type passed explicitly.

Type	Geometry	Description
surface	Polygon	Ground or land-cover surface
parks	Polygon	Parks and green areas
water	Polygon	Water bodies
roads	Polyline	Road network
buildings	Polygonal components / GeometryCollection	3D buildings rendered with extrusion

Physical layers are not limited to OSM

Physical layers are used to build the map context, but they are not restricted to OpenStreetMap data loaded using autk-db. You can also load GeoJSON files as surface, parks, water, roads, or buildings when your own data already matches those physical categories.

Building geometry and parts

In v4, one logical building is represented by one feature whose canonical geometry is a GeometryCollection. Coordinates live only in geometry.geometries; properties.parts stores attributes, not duplicate coordinates. Each part's geometryIndex identifies the corresponding component geometry.

The example uses projected coordinates in meters, matching the other layers in the map:

Common building attributes are inherited by parts; part-specific height/level tags override the corresponding common tags. A component without part metadata uses the common attributes.

normalizeBuildingFeature() also wraps a single polygonal or supported ring geometry in a GeometryCollection. It does not union footprints, repair geometries, clone coordinates, or combine independent features. Legacy positional parts metadata is accepted, but must not be mixed with indexed metadata. Duplicate/out-of-range indices, nested geometry collections, and unsupported geometries are rejected.

Layer sizing and load-time options

Sizes are render state in v4.1: use updateRenderInfo() after loading. In the example below, the slider changes road width without removing the layer. The building's missing-height fallback remains a loadConfig option.

• updateRenderInfo(id, { renderInfo: { polylinesWidth } }) sets the full visual width of roads/polylines in projected coordinate units. It updates an existing layer without rebuilding geometry; road category widths remain in effect until explicitly overridden.
• updateRenderInfo(id, { renderInfo: { pointSize } }) sets a point layer's radius in projected coordinate units. This is per layer, so point datasets at different map extents can use different sizes.
• buildingsZeroHeight: true gives parts without height metadata a random fallback height. It does not replace explicitly zero or invalid heights. For reproducible building heights, provide height/level metadata yourself; missing-height parts are skipped by default.

Sizing migration from 4.0

loadConfig.polylinesWidth, TriangulatorPoints.setPointSize() / getPointSize(), and LayerData.pointSize have been removed. Use per-layer LayerRenderInfo.polylinesWidth and LayerRenderInfo.pointSize through updateRenderInfo() instead. Flat render-state patches are also accepted. There is no lineWidth field.

The exported DEFAULT_POINT_SIZE is a radius of 64, and DEFAULT_LINE_WIDTH is a full width of 12 for generic polylines. Sizes are projected-coordinate units, not pixels; camera transforms determine their apparent size. Point rendering no longer applies an additional zoom multiplier.

Sizes must be finite positive float32 values. Invalid sizes preserve the previous setting and log a warning. Collection-based lines use butt caps, miter joins limited to four half-widths, and bevel fallback at acute turns; visible and picking passes use the same expansion. Prebuilt triangle meshes loaded through loadMesh() cannot be resized this way. The shared centerline utility is PolylineBuilder.

Vector layers

Vector layers are the generic layer types used for custom GeoJSON data. They map directly to the three main geometry families, so they are the right choice when the data is not meant to be interpreted as one of the physical layers. loadCollection() is the standard entry point for these collections.

Type	Geometry
points	Point / MultiPoint
polylines	LineString / MultiLineString
polygons	Polygon / MultiPolygon

Automatic inference

• When type is omitted, loadCollection() can infer vector layer types from geometry: Point and MultiPoint become points, LineString and MultiLineString become polylines, and Polygon and MultiPolygon become polygons.

• Physical types such as roads, buildings, surface, parks, and water are not inferred automatically. If a collection mixes geometry families, pass type explicitly.

Raster layers

Raster layers represent gridded data such as temperature, density, or any other cell-based surface. In practice, autk-map renders a raster layer from a FeatureCollection whose cell values are stored in feature properties, together with a property path telling the renderer which band or attribute to read.

Type	Description
raster	Grid-based data such as heatmaps or GeoTIFF-derived collections

Raster layers need a property path that tells the renderer which numeric value to use in each cell. The example below builds a heatmap raster from Manhattan noise events with autk-db and renders the result in autk-map. GeoTIFF files can also be loaded with autk-db. For now, autk-map renders raster collections returned by autk-db, including heatmaps created with buildHeatmap().

Updating raster values

updateRaster() changes the values of an existing raster layer without removing it. Run the example and use the button to switch between real elevation values and a derived inverted-height band, both on the same grid. The original GeoTIFF has one band; the code creates band_2 in memory.

The property path must resolve to a flat numeric array on collection.features[0].properties. The color domain is recomputed using the layer's current color-map configuration. Use updateColorMap() to choose a palette/domain strategy, and updateRaster() to refresh the values. An optional transferFunction controls opacity; see UpdateRasterParams.

Keep the raster's extent and grid resolution unchanged: updateRaster() replaces values, not the layer geometry. Remove and reload the layer if its grid changes. Missing/non-raster layers are ignored; invalid payloads are reported in the console.

Prebuilt 3D meshes

loadMesh() bypasses GeoJSON triangulation when you already have triangle buffers. It currently supports only type: 'buildings'.

Load a context collection first to establish the shared origin. Every mesh XY coordinate must be relative to map.layerManager.origin, not an absolute projected coordinate. For example, the shared core triangulator produces compatible local-space buffers:

Custom mesh generators should supply LayerGeometry position/index buffers and LayerComponent vertex/triangle counts and source feature metadata that describe those buffers in rendering order. A component can span multiple geometry chunks; their array lengths need not match. Optional thematic entries must correspond one-to-one with the components so picking and colors refer to the correct parts. Calling loadMesh() before the origin is initialized throws.