@uzmaps/engine

@uzmaps/engine is the JavaScript engine behind uzmaps.ndc.uz. It exports a UzMap class that wraps a MapLibre GL JS map with the UzMap cartography, an @uzmaps/api client, and overlays for markers, shapes, routes, a selected place and the user's location. It has no framework dependency; the React components in @uzmaps/ui are built on it. This page describes version 0.1.1 as it stands in the repository source; where the copy published to npm as 0.1.1 differs, it says so.

Installation#

npm install @uzmaps/engine maplibre-gl

packages/engine/package.json lists maplibre-gl@^6.7.0 under dependencies (so does the published 0.1.1), alongside pmtiles, @uzmaps/api and @uzmaps/cartography. The package README describes maplibre-gl as a peer dependency; it is not declared as one. Add it to your own package.json anyway: the engine does not inject any CSS, so you import MapLibre's stylesheet yourself, and under package managers that do not hoist transitive dependencies (pnpm by default) that import only resolves when maplibre-gl is a direct dependency.

import { UzMap } from '@uzmaps/engine';
import 'maplibre-gl/dist/maplibre-gl.css';

Creating a map#

const map = new UzMap({
  container: 'map',                 // element id or HTMLElement
  serverUrl: 'https://uzmaps.ndc.uz',
  apiKey: 'YOUR_KEY',
  center: [69.2401, 41.2995],       // [lon, lat]
  zoom: 12,
  theme: 'auto',
  language: 'uz',
});

map.on('ready', () => {
  // basemap loaded; safe to fit, select, draw
});

The MapLibre map is created in the constructor. load and ready fire once, at the same moment, when MapLibre reports its load event.

UzMapOptions#

Every field is optional except container. Defaults are the values applied in map.ts.

Container and server#

Camera#

The maximum pitch is fixed at 70° and is not an option.

Appearance#

3D and tilt#

With both pitch angles at their default of 0 the curve is flat everywhere, so the resting camera is overhead unless a project opts in.

Terrain#

Interaction#

The default interactive layers are uz-poi, uz-poi-places, uz-poi-transit, uz-aerodrome, uz-peak, uz-place-city, uz-place-town, uz-place-village, uz-place-suburb and uz-place-neighbourhood.

Not on the type#

map.ts also reads a route field (RouteOverlayOptions) from the options object and passes it to the RouteOverlay constructor, but UzMapOptions does not declare it. In TypeScript you need a cast to pass it; see Routes.

Properties#

Methods#

UzMap extends Emitter, so it also has on(event, fn) (returns an unsubscribe function), once, off, emit and clear. Listener exceptions are caught and logged, so one failing listener does not stop the others.

Camera#

CameraOptions is { center?, zoom?, bearing?, pitch?, duration?, padding?, offset?, animate? }; only the fields listed against each method are read.

map.setPadding({ bottom: 280 }, false);   // keep a bottom sheet clear of every framing
map.fitBounds([69.1, 41.2, 69.4, 41.4], { padding: 24, maxZoom: 15 });
map.flyTo({ center: [69.28, 41.31], zoom: 15 });
map.easeTo({ center: [69.28, 41.31], offset: [0, -60], duration: 500 });

Appearance and mode#

Places and routes#

Overlays#

Lifecycle#

Events#

Payload types are from UzMapEvents in types.ts; the "fires when" column is from map.ts.

BasemapFeature:

const off = map.on('click', ({ feature }) => {
  if (feature) return;          // poi:click handles it
  map.selectPlace(null);
});

map.on('poi:click', async (f) => {
  const { result } = await map.api.lookup(f.lngLat[1], f.lngLat[0], f.name ?? '');
  if (result) map.selectPlace(result, { fly: false });
});

off();

Forwarded from the overlays#

In the repository source, UzMap forwards marker:click, marker:hover and cluster:click from every MarkerLayer created with addMarkers (adding the layer id to the payload), and route:select from map.route. The forwarders are released in removeMarkers and destroy. The overlay objects still emit their own events when you only care about one layer.

The package published to npm as 0.1.1 predates this: its dist/map.js contains no forwarding, so on that copy map.on('marker:click', …) type-checks and never fires. Listen on the overlay objects there.

Declared but never emitted#

UzMapEvents also declares userlocation and userlocation:error. UzMap does not emit either, in the source or on npm: map.on('userlocation', …) type-checks and never fires. Use map.userLocation.on('update' | 'error' | 'stop', …) instead.

Markers#

Markers are managed as named layers, not one at a time. Each layer is one GeoJSON source rendered with symbol layers, so thousands of markers are cheap and collision is resolved across the whole set. Pin images are drawn on a canvas at the device pixel ratio and registered with MapLibre on demand.

A MarkerFeature is a GeoJSON Feature<Point, MarkerFeatureProps>:

MarkerLayerOptions, with the defaults from markers.ts:

MarkerLayer:

Events on a MarkerLayer:

const offices = map.addMarkers('offices', [
  {
    type: 'Feature',
    geometry: { type: 'Point', coordinates: [69.24, 41.29] },
    properties: { id: 'hq', label: 'Head office', color: '#e11d48', priority: 10 },
  },
  {
    type: 'Feature',
    geometry: { type: 'Point', coordinates: [69.28, 41.31] },
    properties: { id: 'branch-1', label: 'Chilonzor' },
  },
], { cluster: true, clusterRadius: 60 });

offices.on('click', ({ feature, lngLat }) => {
  offices.select(feature.properties.id);
  map.easeTo({ center: lngLat, duration: 400 });
});

map.addMarkers('offices', newFeatures);   // replaces the data; options unchanged
map.removeMarkers('offices');

Shapes#

addShape(id, data, style) draws polygons and lines: zones, regions, boundaries, tracks. data (ShapeData) is a FeatureCollection, a single Feature or a bare Geometry. Polygons get a fill layer and a line layer; lines get the line layer. A feature can override its colour with properties.fillColor, properties.lineColor or properties.color. Any CSS colour works here, because these values go straight into paint expressions.

ShapeStyle, with the defaults from shapes.ts:

ShapeLayer:

ShapeLayer emits no events.

const zones = map.addShape('delivery-zones', {
  type: 'FeatureCollection',
  features: [{
    type: 'Feature',
    properties: { id: 'north', name: 'Shimoliy zona', fillColor: '#16a34a' },
    geometry: { type: 'Polygon', coordinates: [[[69.20, 41.33], [69.30, 41.33], [69.30, 41.38], [69.20, 41.38], [69.20, 41.33]]] },
  }],
}, { color: '#E8712B', fillOpacity: 0.15, belowRoads: true, labelProperty: 'name' });

zones.setStyle({ lineDash: [2, 2] });
zones.setVisible(false);
map.removeShape('delivery-zones');

Routes#

showRoutes takes the routes array from map.api.route() (each Route has id, mode, geometry as [lon, lat][], bbox, recommended, legs, distance, duration and summary). The selected route is selectedId if given, otherwise the first route with recommended: true, otherwise the first route. Alternatives are drawn in the theme's alternative colour with a wide invisible hit line, so clicking one selects it and emits select on map.route. Origin, via and destination pins use the sprite icons route-start, route-via and route-end; when fewer than two waypoints are passed, the selected route's first and last coordinates are used. A selected route in foot mode gets a dotted white overlay. Drawing in is animated over 650 ms with a moving line-gradient stop.

map.route (RouteOverlay):

Event: select with the route id as a string.

const points = [[69.24, 41.29], [69.28, 41.31]];
const { routes } = await map.api.route({ points, mode: 'car' });

map.showRoutes(routes, points, { fitPadding: { top: 40, bottom: 240, left: 40, right: 40 } });
map.route.on('select', (id) => console.log('selected', id));
map.route.setStep([69.26, 41.30]);
map.route.setStep(null);
map.clearRoutes();

RouteOverlayOptions is read from the undeclared route constructor option. Only animate (default true), endpoints (default true) and colors are used. colors has primary, primaryCasing, alt and altCasing, each defaulting to the theme's route tokens (light: #2F7CF6, #1E5DC4, #9DB6D8, #7F98BB; dark: #4D8DFF, #1E4FA8, #5D6B85, #465267). fit, fitPadding and dotted are declared but not read; use the fit and fitPadding arguments of showRoutes.

const map = new UzMap({
  container: 'map',
  route: { animate: false, colors: { primary: '#0f766e' } },
} as UzMapOptions & { route: RouteOverlayOptions });

Selected place#

selectPlace and flyToPlace drive map.highlight (Highlight): a pin of size 34 in the selected style (which draws at 1.25×) with a soft pulse ring, plus a fill and cased line for a street or area geometry. The colour is the theme's selection token (#2F7CF6 light, #4D8DFF dark) unless a hex colour is given.

const { results } = await map.api.search('Chorsu');
const place = results[0];
const geometry = await map.api.geometry(place.id);
map.selectPlace(place, { geometry });

User location#

map.userLocation (UserLocation) draws a blue dot with an accuracy halo sized in metres and, when the fix carries a heading, a direction cone. Fixes are interpolated over 500 ms so the dot glides rather than jumps. Nothing starts automatically; destroy() stops it.

Events:

map.userLocation.on('update', ({ lngLat, accuracy }) => console.log(lngLat, accuracy));
map.userLocation.on('error', (err) => console.warn(err.code, err.message));
map.userLocation.start();

const pos = map.userLocation.position;
if (pos) map.easeTo({ center: pos.lngLat, zoom: 16 });

3D, tilt and terrain#

Extrusions follow the pitch#

Building extrusions are tied to the live camera pitch on every move event, whether or not auto-tilt is on: they switch on at 7° and off below 4°. MapLibre's camera is a perspective camera, so at pitch 0 a building away from the screen centre is still viewed obliquely and its walls show as a hard slab hanging off the footprint. A flat camera therefore always means flat footprints, and 3D expresses itself by tilting. In 2D the cartography draws an offset wall under each footprint instead, which reads as a subtle 2.5D volume.

set3D(true) sets the user's tilt offset so the target at the current zoom is tiltMax (50°) and eases the pitch there over 800 ms; the extrusions come on as the pitch crosses the threshold. set3D(false) sets the offset so the target at the current zoom is 0 and eases the pitch back to 0. The layer swap toggles visibility between the cartography's flat and extruded building layers without rebuilding the style, falling back to a rebuild only if none of those layers exists. With autoTilt: false, set3D swaps the layers without animating; set a pitch yourself, or the next camera move will flatten them again.

buildings3d: true in the constructor opens the map at the pitch the curve gives for the starting zoom (flat, with default angles), so it starts as footprints until the camera is tilted.

map.set3D(true);
map.on('tilt', (tilted) => button.classList.toggle('active', tilted));
console.log(map.mode);        // '3d' once the pitch has crossed 7°
map.toggle3D();

The auto-tilt curve#

With autoTilt on, the target pitch is a function of zoom: flat at or below autoTiltFlatZoom, smoothstepped up to autoTiltPitchSoft at autoTiltZoom, then on to autoTiltPitchMax at maxZoom. A deliberate pitch gesture (touch pitch, right-drag) is kept as an offset, clamped to ±70°, so zooming modulates perspective around the user's tilt rather than fighting it. The follower eases the pitch towards the target on its own animation-frame loop rather than with easeTo, because MapLibre camera animations are exclusive and it has to run during a wheel gesture without cancelling it.

Consequence: with auto-tilt on, a pitch passed to flyTo, easeTo or fitBounds holds only while that animation runs (the follower stays out of the way for its duration), and the pitch then eases back to the curve plus the user's offset. To hold a pitch, use set3D(true), pass pitch in the constructor (it becomes the offset when the map loads), or set autoTilt: false.

Terrain#

terrain: true or setTerrain(true) adds a raster-DEM source from terrainUrl. Adding or removing that source cannot be diffed by MapLibre, so setTerrain asks for a full style rebuild; overlays, camera and runtime images survive it.

After setTerrain(true) the engine listens on window for 8 s for an error event whose message or stack matches /terrain|shaderPrelude/i. Terrain renders inside MapLibre's own animation frame, and an exception there escapes the callback and stops the render loop for the life of the page with no way to catch it from outside. When the watcher fires, terrain is switched off, the style rebuilt, a repaint forced, a warning logged, and terrainunavailable emitted. The watcher is only installed by setTerrain(true), not by terrain: true in the constructor.

map.on('terrainunavailable', () => showNotice('Terrain is not available on this device'));
map.setTerrain(true);

Traffic#

There is no open real-time traffic feed for Uzbekistan, so the engine draws whatever an application supplies. setTraffic(true) shows the cartography's uz-traffic-casing and uz-traffic layers and fetches immediately; setTraffic(false) stops the timer and clears the data, so a hidden ribbon costs nothing.

A TrafficProvider is (req: { bbox: BBox; zoom: number }) => TrafficResponse | Promise<TrafficResponse>, where TrafficResponse is { features: TrafficFeature[]; refreshMs?: number }. The engine refreshes every refreshMs (default 60 000 ms, clamped to at least 5 000). A response that arrives after a newer request was issued is discarded. If the provider throws, the last good ribbon is kept, error is emitted, and the next attempt waits 120 s.

A TrafficFeature is a LineString feature whose properties.congestion is one of 'free' | 'moderate' | 'heavy' | 'severe' | 'closed', with optional speed and name.

map.setTrafficProvider(async ({ bbox, zoom }) => {
  const res = await fetch(`/traffic?bbox=${bbox.join(',')}&z=${zoom}`);
  return { features: await res.json(), refreshMs: 30_000 };
});
map.setTraffic(true);

// or push from your own loop
map.setTrafficFeatures(features);

Theme and language#

setTheme and setLanguage rebuild the style with MapLibre's diffing. The rebuild carries across every source that is not part of the generated style, together with the layers on those sources, inserting them at the overlay anchors by layer type; marker and shape layers are additionally re-mounted on style.load, district label points are re-applied, traffic is re-fetched, and runtime pin, cluster and chip images are regenerated. That is why overlays, camera and selection survive a theme or language change.

theme: 'auto' follows prefers-color-scheme and applies changes live; map.theme is always the resolved 'light' or 'dark'.

Using MapLibre directly#

map.ml is the maplibregl.Map. Anything the wrapper does not cover can be done there, with a few things worth knowing.

Fixed MapLibre settings. maxPitch: 70, dragRotate, touchPitch and pitchWithRotate on, cooperativeGestures off, fadeDuration: 250, antialiased high-performance canvas, no MapLibre logo.

Layer anchors. The style contains three empty anchor layers: uz-anchor-overlay-fill, uz-anchor-overlay-line and uz-anchor-overlay-symbol. Pass one as beforeId to map.ml.addLayer to slot your layer under labels, under roads, or on top. They are exported as anchors from @uzmaps/cartography.

Surviving restyles. A layer you add on your own source (one not in the generated style) is carried across every theme, language, 3D, terrain and source rebuild, inserted at the anchor matching its type (symbol, line, or fill for everything else). A layer added on a basemap source is not carried across; re-add it on styleready.

Reserved ids. The engine uses the uz- prefix for its own sources and layers: uz-markers-<id>, uz-shapes-<id>, uz-route, uz-route-points, uz-route-step, uz-highlight-pin, uz-highlight-geom, uz-user-location, and the layers built on them (uz-route-line, uz-route-alt-hit, uz-highlight-pin, uz-user-dot, and so on). Avoid the prefix for your own ids.

Runtime images. Pin, cluster and label-chip images are generated on MapLibre's styleimagemissing from their id alone, so your own symbol layer can reference one without registering it. Ids are uz-pin:<pin|dot>:<size>:<hex>[:sel][:hollow], uz-cluster:<hex> and uz-chip:<bg hex>:<border hex>; pinImageId builds the first form.

import { pinImageId } from '@uzmaps/engine';

map.ml.addSource('depots', { type: 'geojson', data: depots });
map.ml.addLayer({
  id: 'depots',
  type: 'symbol',
  source: 'depots',
  layout: {
    'icon-image': pinImageId({ color: '#e11d48', size: 30, shape: 'pin' }),
    'icon-anchor': 'bottom',
  },
}, 'uz-anchor-overlay-symbol');

Camera calls on ml. map.ml.flyTo and friends bypass the wrapper's stored padding and its tilt suppression. With auto-tilt on, the follower re-evaluates after any zoom and eases the pitch back to its curve; use the UzMap camera methods when that matters.

Other exports#

Geo helpers from geo.ts:

Also exported: the easing functions easeOutCubic and easeInOutQuint; the Emitter class; pinImageId and drawPin; the overlay classes MarkerLayer, ShapeLayer, RouteOverlay, Highlight and UserLocation; and, re-exported from @uzmaps/api, UzMapClient, createClient, formatDistance, formatDuration and every API type. The engine's own types (LngLat, BBox, Theme, CameraOptions, UzMapOptions, UzMapEvents, BasemapFeature, MarkerFeature, MarkerFeatureProps, MarkerLayerOptions, ShapeData, ShapeStyle, RouteOverlayOptions, TrafficProvider, TrafficRequest, TrafficResponse, TrafficFeature, CongestionLevel) are exported from the package root.

Errors in the published 0.1.1 README#

The README shipped inside @uzmaps/engine@0.1.1 on npm contains examples that do not match the code it shipped with. The repository copy and examples/engine.ts have been corrected; the npm copy will be right from the next publish.