bim-tile-overlay

Overlay web map tiles (OSM, aerial imagery, custom XYZ) onto an Autodesk APS Viewer as a camera-synced 3D ground plane.

By Infra Plan

The Problem

Placing geographic map tiles under a BIM model in Autodesk Viewer requires:

1. Extracting the camera frustum and projecting it onto a ground plane
2. Converting between the viewer's internal coordinate system and WGS84
3. Figuring out which map tiles cover the visible area at the right zoom level
4. Fetching, stitching, and caching those tiles into a GPU-friendly texture
5. Positioning a THREE.js plane in 3D space aligned with the geographic bounds
6. Updating everything in real-time as the camera moves

This library handles all of that in ~500 lines of code.

Quick Start

npm install bim-tile-overlay proj4

import { TileOverlay, CoordinateTransformer } from 'bim-tile-overlay';

// After viewer has loaded a model:
const transformer = CoordinateTransformer.fromAPSViewer(
    viewer,
    // proj4 definition for your local CRS (this example uses Croatia HTRS96/TM)
    '+proj=tmerc +lat_0=0 +lon_0=16.5 +k=0.9999 +x_0=500000 +y_0=0 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs'
);

const overlay = new TileOverlay(viewer, transformer, {
    urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
    zoomRange: [14, 19],
    maxBounds: transformer.getModelBoundsLL84(),
});

await overlay.enable();

How It Works

Camera frustum corners
  → Ray-cast to ground plane (Z elevation)
  → Convert hit points to WGS84 lon/lat
  → Determine visible geographic bounds
  → Calculate optimal tile zoom level
  → Fetch XYZ tiles in parallel
  → Stitch into single canvas texture
  → Map onto THREE.js plane in viewer space
  → Update on camera change (debounced)

Coordinate pipeline:

WGS84 (lon, lat)
  ↔ Local CRS (meters) → via proj4
  ↔ CRS in feet → × 3.28084
  ↔ BIM internal coords → via refPointTransform rotation + translation
  ↔ Viewer display coords → minus globalOffset

API Reference

TileOverlay

Main class. Creates a map tile overlay on the viewer.

const overlay = new TileOverlay(viewer, transformer, options);

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | urlTemplate | string | required | Tile URL with {z}, {x}, {y} placeholders | | zoomRange | [number, number] | required | Min and max zoom levels | | maxBounds | GeoBounds | required | Geographic bounds to clip tile fetching | | groundZ | number | modelBBox.min.z - 5 | Z elevation of the ground plane | | debounceMs | number | 150 | Camera change debounce delay (ms) | | maxCacheSize | number | 6 | Max cached stitched tile canvases | | zoomScaleFactor | number | 12 | Tile detail vs. camera distance. Higher = more detail | | progressInterval | number | 5 | Texture refresh frequency during tile loading (every N tiles). Always fires on the last tile. Set to 1 for per-tile updates. | | sceneName | string | 'bim-tile-overlay' | Viewer overlay scene name |

Methods:

| Method | Description | |--------|-------------| | enable() | Show the overlay and start tracking camera | | disable() | Hide the overlay, preserve cache for re-enabling | | destroy() | Fully dispose all GPU resources and cache | | update() | Force an immediate tile refresh |

CoordinateTransformer

Converts between WGS84 and the viewer's coordinate system.

// From viewer (recommended):
const transformer = CoordinateTransformer.fromAPSViewer(viewer, crsDefinition);

// Manual config:
const transformer = new CoordinateTransformer({
    crs: '+proj=tmerc +lat_0=0 +lon_0=16.5 ...',
    refPointTransform: [...],  // From model metadata
    globalOffset: { x, y, z },
    modelBBox: { min: { x, y, z }, max: { x, y, z } },
});

Methods:

| Method | Description | |--------|-------------| | lonLatToViewer(lon, lat, z?) | WGS84 → viewer coordinates | | viewerToLonLat(x, y, z?) | Viewer coordinates → WGS84 | | getModelBoundsLL84() | Model bounding box in WGS84 |

Utility Functions

import { lonLatToTile, tileToLonLat, getViewportBounds, createTileCache } from 'bim-tile-overlay';

| Function | Description | |----------|-------------| | lonLatToTile(lon, lat, zoom) | WGS84 → tile {x, y} coordinates | | tileToLonLat(x, y, zoom) | Tile coordinates → WGS84 (NW corner) | | getViewportBounds(camera, transformer, options) | Camera frustum → geographic bounds + zoom | | createTileCache(maxSize?) | LRU cache that frees bitmap memory on eviction |

Finding Your CRS

Your BIM model needs a local Coordinate Reference System (CRS) for accurate positioning. Common ones:

| Region | CRS | Code | |--------|-----|------| | Croatia | HTRS96/TM | EPSG:3765 | | UK | British National Grid | EPSG:27700 | | Germany | ETRS89/UTM zone 32N | EPSG:25832 | | US (New York) | NAD83/NY Long Island | EPSG:2263 |

Find your CRS definition at epsg.io and pass the proj4 string.

Requirements

• Autodesk Viewer (APS / Forge) with a loaded, georeferenced model — the Viewer script provides THREE.js and Autodesk globals that this library uses internally; you do not need to install them separately
• proj4 (peer dependency) — npm install proj4
• The BIM model must have refPointTransform in its metadata (set via Revit's survey/project point)

Contributing

Contributions are welcome! Please open an issue or pull request.

License

MIT - Infra Plan