autk-map

autk-map is a geospatial data renderer powered by WebGPU. It can handle GeoJSON, semantic OpenStreetMap layer types, and can display thematic values without a tile server.

Key capabilities:

• Render 2D and 3D geospatial layers directly from GeoJSON in the browser.
• Support OpenStreetMap layers such as surface, parks, water, roads, and buildings.
• Display thematic data using configurable color maps.
• Handle interactive exploration through picking, highlighting, and filtering features.
• Integrate directly with autk-db, autk-compute, and autk-plot.

Package installation

To install autk-map, you must install its NPM package.

npm install @urban-toolkit/autk-map

You can also install the full toolkit:

npm install @urban-toolkit/autk

Initialization

The entry point of autk-map is the AutkMap class. To create a map, you must pass to the constructor a HTML canvas as paramenter. After instantiating the map, you must await init(), load one or more layers, and finally call draw().

Coordinate system

autk-map expects data in projected coordinates. Any projected CRS may be used. For example, the default autk-db workspace uses EPSG:3395, also known as World Mercator.

WebGPU required

autk-map requires a browser with WebGPU support. We recommend using recent versions of Chrome, Edge, or Safari. See the browser support table in the Introduction.

Rendering mode

In v4.1, map.draw() renders once and then renders again only when the map observes a change. Camera navigation, resize, layer loading/removal, supported render-state updates, styles, picking, and terrain changes all request the next frame automatically.

Run this example and switch between on-demand rendering and a continuous 30 fps loop. Toggle borders demonstrates a supported update that redraws automatically in either mode:

Use map.draw(30) or map.draw({ fps: 30 }) for a continuous 30 fps loop; map.draw({ onDemand: false }) uses 60 fps. Calling draw() again replaces the active mode. Continuous rendering is useful for animation or other work that changes every frame.

Direct writes to GPU resources are not observed; call map.requestRender() afterward. Direct edits to cached uniforms/render state or CPU geometry also need layer.makeLayerRenderInfoDirty() or layer.makeLayerDataDirty(), respectively. These dirty marks already request a frame for attached layers. requestRender() alone does not upload CPU buffers or refresh cached uniforms; prefer the public update methods.

Migrating from 4.0

map.draw() no longer starts a continuous loop. Applications with unobserved per-frame mutations must request frames explicitly or opt into continuous rendering. Numeric FPS calls retain their previous continuous behavior.

Initialization and lifecycle

The optional second constructor argument controls the floating map UI. Pass false when your application provides its own controls:

showUi is a read-only property reflecting that constructor choice. Hiding the UI does not disable programmatic layer, selection, or camera controls. Every map still includes the bottom-right text-only made with autark watermark; it follows canvas resizing, does not intercept input, and is removed by destroy().

When removing the canvas, changing routes, or replacing the visualization, call destroy():

The Destroy map button above demonstrates disposal. After destroying the map, click Run to create a new instance.

This cancels the render loop, removes event bindings and floating UI, and releases layer/renderer GPU resources. Calling it again is safe, but a destroyed map should not be reused: create a new instance for the next mount. Also destroy the instance if initialization fails. If a component can unmount while init() is pending, defer final cleanup until that promise settles and do not load layers or start rendering after unmount.

For navigation and resetting the view, see Camera controls.

Core concepts

Autark is built over some core concepts, that guides data data loading, rendering and interactions. Next you can find a brief description of each concept and a reference to their detailed description in this guide.

• Layer ids — each layer is identified by an unique string id. This id must be used when the user wants to update rendering properties such as the layer's thematic data, rendering state, etc. See Layers data for details.
• Layer types — each layer has a type that can be either a physical type or a generic type. Physical types such as surface, parks, water, roads, and buildings are used to build the map context, while generic types such as points, polylines, polygons, and raster support custom datasets. See Layers data.
• Render state — each layer has render state controlling properties such as opacity, visibility, picking, and whether thematic coloring is active. These properties can be updated dynamically without reloading the layer. See Styling.
• Thematic data — thematic data rendering maps numeric or categorical feature attributes to colors. In practice, you configure a color map, point to a property path, and enable thematic display for the layer. See Thematic data.
• Interactions — interactions let users explore layers through picking, highlighting, filtering, and visibility control without changing the underlying data. See Interactions.
• Terrain data — terrain mode replaces the flat ground plane with a heightfield built from an elevation raster, draping the loaded layers over real topography. See Terrain data.