Reference
JavaScript API.
Every public symbol exported from @xgis/runtime.
Most apps only need XGISMap;
the rest is here for advanced extension.
Runtime support
- WebGPUSupported— Chrome 113+ · Safari 17.4+ · Firefox 130+ · Edge 113+
- Canvas 2D fallbackLimited— Activates when no WebGPU adapter is present. GeoJSON paths only — PMTiles and extruded buildings unsupported.
- MobileLimited— iOS Safari 17.4+ · Android Chrome with WebGPU enabled. Heavier scenes may throttle.
- Web workersSupported— Required — used for off-main-thread MVT decode + GeoJSON tessellation.
Core
The map class is the only entry point most apps need.
XGISMap
new XGISMap(canvas: HTMLCanvasElement)Owns the GPU device, the camera, the renderers, and the source catalog. Construct once per canvas.
Parameters
| Name | Type | Description |
|---|---|---|
canvas | HTMLCanvasElement | Target canvas to render into. Must already be attached to the DOM — the constructor reads its `clientWidth` / `clientHeight` to size the WebGPU swap chain. |
Example
import { XGISMap } from "@xgis/runtime"const map = new XGISMap(canvas)await map.run(source, baseUrl)XGISMap.run
map.run(source: string, baseUrl: string): Promise<void>Compile the .xgis source string, resolve relative `url:` references against `baseUrl`, allocate GPU resources, and start the render loop. Resolves once the first frame is composed.
Parameters
| Name | Type | Description |
|---|---|---|
source | string | A valid `.xgis` source. Typically loaded via Vite's `?raw` import. |
baseUrl | string | Used to resolve relative `url:` references inside source blocks. Pass `"/"` when the assets sit at site root. |
Returns
Promise<void> — Resolves after WebGPU resources are allocated and the first frame is composed. Rejects if the source fails to compile or a required resource (e.g. PMTiles header) returns 4xx/5xx. See also
XGISMap.getCamera
map.getCamera(): CameraReturns the live camera. Mutate `.lon`, `.lat`, `.zoom`, `.bearing`, `.pitch` — the runtime picks up changes on the next frame.
Returns
Camera — The live camera instance — same object across calls, mutating it directly drives the next frame. See also
XGISMap.setProjection
map.setProjection(proj: Projection): voidSwitch the active projection. No re-tessellation; a single uniform write flips Mercator → Orthographic → Natural Earth.
Parameters
| Name | Type | Description |
|---|---|---|
proj | Projection | A projection record from one of the seven built-in projections, or `getProjection(name, …)`. |
See also
Camera
Direct camera control — most code interacts via the input controllers, not the camera class.
Camera
class CameraHolds `lon`, `lat`, `zoom`, `bearing`, `pitch`, plus derived MVP matrices. `zoomAt(delta, x, y, w, h)` zooms toward a screen-space point.
Projections
Seven projections in CPU-mirror form. Each returns a Projection record the runtime wires into the shader uniform.
mercator
const mercator: ProjectionWeb Mercator (EPSG:3857). The default — used unless `setProjection` is called.
equirectangular
const equirectangular: ProjectionPlate carrée — latitude maps directly to y.
naturalEarth
const naturalEarth: ProjectionPseudo-cylindrical, polynomial. Low-distortion world overview.
orthographic
orthographic(lon: number, lat: number): ProjectionGlobe view centered on (lon, lat). Hemispherical visibility, back-face culled.
getProjection
getProjection(name: string, ...args: number[]): ProjectionLook up a projection by name with optional center coordinates. Names: mercator, equirectangular, natural_earth, orthographic, azimuthal_equidistant, stereographic, oblique_mercator.
Example
import { getProjection } from "@xgis/runtime"const proj = getProjection("orthographic", 127, 37.5)map.setProjection(proj)Loaders
Source-loading helpers used by the .xgis runtime under the hood. Most apps don't call these directly — declare a `source` block in the .xgis source instead.
loadGeoJSON
loadGeoJSON(url: string, baseUrl?: string): Promise<GeoJSON>Fetch a GeoJSON file. Resolves to the parsed FeatureCollection.
loadPMTilesSource
loadPMTilesSource(opts: PMTilesSourceOptions): Promise<TileSource>Construct a streaming PMTiles backend. Reads the archive header + vector_layers metadata via HTTP Range Requests; returns a TileSource that can be attached to a TileCatalog.
attachPMTilesSource
attachPMTilesSource(catalog: TileCatalog, source: TileSource): voidWire a PMTiles backend into a tile catalog. The .xgis `type: pmtiles` runtime handler does this for you.
lonLatToMercator
lonLatToMercator(lon: number, lat: number): [number, number]Project lon/lat to global Web Mercator meters. Useful for placing custom overlays at known coordinates.
GPU compute
Public compute infrastructure for advanced layer types (color ramps, vector field visualizations, etc.).
ComputeDispatcher
class ComputeDispatcherHelper around WebGPU compute pipelines. Wrap a WGSL compute shader + bind groups, then `dispatch(workgroups)` per frame.
createColorRampTexture
createColorRampTexture(device: GPUDevice, name: string): GPUTextureCreate a 1D color-ramp texture from a registered ramp name (viridis, magma, plasma, etc.). Sampled by gradient layers.
availableRamps
availableRamps(): string[]List the registered color ramp names — useful for building UI selectors.
Stats + diagnostics
Optional UI panel and underlying tracker for performance/diagnostic information.
StatsPanel
class StatsPanelOn-screen FPS / draw-call / triangle-count overlay. Mount once near the canvas; the panel polls live values from the shared StatsTracker.
StatsTracker
class StatsTrackerSingleton that the runtime feeds frame stats into. Read directly from custom UI when StatsPanel doesn't fit.
Custom element
Web Components wrapper for declarative usage in plain HTML.
XGISMapElement
class XGISMapElement extends HTMLElementA `<x-gis-map src="…">` element. Fetches the .xgis source, mounts an XGISMap inside its shadow root, and reflects basic camera attributes.
registerXGISElement
registerXGISElement(): voidCall once during app bootstrap to register the `<x-gis-map>` custom element with the global registry.