Treelet

A lightweight 3D terrain & overlay map library for the web - inspired by Leaflet and powered by Three.js.

Treelet renders tiled elevation data as 3D terrain with drape overlays, LOD scheduling, and shader-based visualization - in the spirit of Leaflet's simple high-level API, solid low-level access, and zero bloat.

Live Demo

Features

Tile sources — XYZ, OGC WMS, OGC WMTS (RESTful + KVP)
Elevation decoding — Terrain-RGB, Terrarium, Mapbox, custom decoders
Visualization modes — Elevation, slope, aspect, contours, wireframe
Drape layers — Overlay satellite, OSM, or any raster imagery onto terrain
LOD scheduling — Nadir-based quadtree with cross-LOD seam resolution
Web Workers — Off-thread tile fetch, decode, and mesh generation
Fluent API — Chainable setters, Leaflet-style factory, EventEmitter

This had been a project related to my PHD and that I needed to keep private until now - thoroughly overhauled and elevated to current tech standards. 3D terrain rendering has become more commonly supported, but this library still shines with simplicity, ease-of-use and performance. It's especially useful for self-hosted elevation and overlay data.

Quick Start

Installation

npm install @geozelot/treelet three

CDN / Script Tag

For direct browser use without a bundler, use the standalone build which bundles Three.js:

<script src="https://unpkg.com/@geozelot/treelet/dist/treelet.cdn.standalone.js"></script>
<script>
  const map = Treelet.map('map', {
    center: { lng: 11.39, lat: 47.27 },
    zoom: 10,
  });
  // ...
  map.start();
</script>

Minimal Example

import { Treelet } from '@geozelot/treelet';

const map = Treelet.map('map', {
  center: { lng: 11.39, lat: 47.27 },
  zoom: 10,
});

map.addBaseLayer({
  id: 'terrain',
  name: 'AWS Terrain',
  source: {
    type: 'xyz',
    url: 'https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png',
    tileSize: 512,
    maxZoom: 15,
  },
  decoder: 'terrarium',
});

map.addDrapeLayer({
  id: 'osm',
  name: 'OpenStreetMap',
  source: {
    type: 'xyz',
    url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
    tileSize: 512,
    maxZoom: 19,
  },
});

map.start();

API Reference

Factory

`Treelet.map(container, options)`

Create a new Treelet map instance (static factory).

Param	Type	Description
`container`	`string \| HTMLElement`	DOM element or element ID
`options`	`TreeletOptions`	Map configuration

Returns Treelet. Equivalent to new Treelet(container, options).

`Treelet.version`

Library version string (static).

TreeletOptions

Option	Type	Default	Description
`center`	`LngLat`	required	Initial map center `{ lng, lat }`
`zoom`	`number`	required	Initial zoom level
`minZoom`	`number`	`0`	Minimum allowed zoom
`maxZoom`	`number`	`20`	Maximum allowed zoom
`tileSegments`	`number`	`128`	Mesh subdivisions per tile
`worldScale`	`number`	`40075.02`	CRS meters → scene units scale
`exaggeration`	`number`	`1.0`	Vertical exaggeration factor
`elevationRange`	`[number, number]`	`[0, 4000]`	Min/max elevation for color mapping
`contourInterval`	`number`	`100`	Contour line spacing in meters
`antialias`	`boolean`	`true`	WebGL antialiasing
`gui`	`boolean`	`true`	Show compass + layer panel
`minPitch`	`number`	`25`	Minimum pitch (most tilted) in degrees
`maxPitch`	`number`	`90`	Maximum pitch (top-down) in degrees
`compassPosition`	`UICorner`	`'top-right'`	Compass widget corner
`layerPosition`	`UICorner`	`'bottom-right'`	Layer panel corner
`workerCount`	`number`	`navigator.hardwareConcurrency`	Web Worker pool size

Treelet

The main map class. Extends EventEmitter.

View

Method	Returns	Description
`setView(center, zoom)`	`this`	Set map center and zoom
`getCenter()`	`LngLat`	Get current map center
`getZoom()`	`number`	Get current zoom level
`getBounds()`	`{ sw, ne } \| null`	Get visible bounding box
`getTileCount()`	`number`	Get number of cached tiles

Base Layers

Only one base layer is active at a time. The active base layer provides elevation data for the terrain mesh.

Method	Returns	Description
`addBaseLayer(options)`	`this`	Add an elevation data layer
`removeBaseLayer(id)`	`this`	Remove a base layer by ID
`setActiveBaseLayer(id)`	`this`	Switch active base layer
`getBaseLayers()`	`BaseLayer[]`	Get all registered base layers

BaseLayerOptions

Option	Type	Default	Description
`id`	`string`	required	Unique layer identifier
`name`	`string`	required	Display name
`source`	`LayerSourceOptions`	required	Tile source configuration
`decoder`	`DecoderType`	`'terrain-rgb'`	Elevation decoder
`decoderFn`	`CustomDecoderFn`	—	Custom per-pixel decoder function
`exaggeration`	`number`	`1.0`	Per-layer exaggeration multiplier
`active`	`boolean`	`true`	Set as active on add

Drape Layers

Drape layers overlay raster imagery on the terrain mesh. Only one drape (external or BaseDrape) is active at a time.

Method	Returns	Description
`addDrapeLayer(options)`	`this`	Add an imagery overlay layer
`removeDrapeLayer(id)`	`this`	Remove a drape layer by ID
`activateDrapeLayer(id)`	`this`	Activate an external drape
`activateBaseDrape(mode?)`	`this`	Switch to elevation-derived visualization
`setBaseDrapeMode(mode)`	`this`	Change BaseDrape mode
`getBaseDrapeMode()`	`BaseDrapeMode`	Get current BaseDrape mode
`getActiveDrapeId()`	`string \| null`	Active drape ID (`'__base_drape__'` for BaseDrape)
`isBaseDrapeActive()`	`boolean`	Check if BaseDrape is active
`setDrapeOpacity(id, opacity)`	`this`	Set drape opacity (0–1)
`getDrapeOpacity(id)`	`number`	Get drape opacity
`getDrapeLayers()`	`DrapeLayer[]`	Get all registered drape layers

DrapeLayerOptions

Option	Type	Default	Description
`id`	`string`	required	Unique layer identifier
`name`	`string`	required	Display name
`source`	`LayerSourceOptions`	required	Tile source configuration
`opacity`	`number`	`1.0`	Layer opacity
`blendMode`	`BlendMode`	`'normal'`	Blend mode: `'normal'`, `'multiply'`, `'screen'`
`active`	`boolean`	`true`	Set as active on add

BaseDrapeMode

Elevation-derived visualization modes:

Mode	Description
`'wireframe'`	Mesh wireframe (normals-colored or flat white)
`'elevation'`	Elevation-colored with lighting
`'slope'`	Slope angle visualization
`'aspect'`	Cardinal direction coloring
`'contours'`	Elevation coloring with contour line overlay

Visualization

Method	Returns	Description
`setColorRamp(ramp)`	`this`	Set color ramp for current BaseDrape mode
`getColorRamp()`	`ColorRamp`	Get current color ramp
`setExaggeration(value)`	`this`	Set global vertical exaggeration
`getExaggeration()`	`number`	Get exaggeration factor
`setContourInterval(meters)`	`this`	Set contour line spacing
`getContourInterval()`	`number`	Get contour interval
`setContourThickness(value)`	`this`	Set contour line thickness
`getContourThickness()`	`number`	Get contour thickness
`setContourColor(r, g, b)`	`this`	Set contour color (RGB, 0–1 each)
`getContourColor()`	`[r, g, b]`	Get contour color
`setWireframeWhite(white)`	`this`	Toggle wireframe flat-white mode
`getWireframeWhite()`	`boolean`	Get wireframe white state

ColorRamp

Ramp	Description
`'hypsometric'`	Green → tan → brown → white (elevation default)
`'viridis'`	Purple → teal → yellow (perceptually uniform)
`'inferno'`	Black → purple → orange → white (high contrast)
`'grayscale'`	Black → white

Camera

Method	Returns	Description
`setMinPitch(degrees)`	`this`	Set minimum pitch (most tilted), 0–90
`getMinPitch()`	`number`	Get minimum pitch
`setMaxPitch(degrees)`	`this`	Set maximum pitch (top-down), 0–90
`getMaxPitch()`	`number`	Get maximum pitch
`getCameraController()`	`CameraController`	Direct camera access

Lifecycle

Method	Returns	Description
`start()`	`this`	Begin rendering and tile loading
`stop()`	`this`	Pause rendering
`destroy()`	`void`	Clean up all resources

Events

map.on('ready', () => { /* initial tiles loaded */ });
map.on('move', ({ center }) => { /* camera moving */ });

Event	Data	Description
`'ready'`	`{}`	Initial tiles loaded
`'zoom'`	`{ zoom }`	Zoom level changed
`'move'`	`{ center: LngLat }`	Camera moving
`'moveend'`	`{ center, zoom }`	Camera movement complete
`'tileload'`	`{ coord: TileCoord }`	Tile loaded
`'tileunload'`	`{ coord: TileCoord }`	Tile unloaded
`'layeradd'`	`{ id }`	Layer added
`'layerremove'`	`{ id }`	Layer removed
`'layerchange'`	`{}`	Layer configuration changed

Tile Sources

All layers accept a source object conforming to LayerSourceOptions.

LayerSourceOptions

Option	Type	Default	Used by	Description
`type`	`'xyz' \| 'wms' \| 'wmts'`	required	all	Source type
`url`	`string`	required	all	Endpoint URL or template
`subdomains`	`string[]`	`[]`	XYZ, WMTS	Subdomain rotation via `{s}`
`tileSize`	`number`	`256`	all	Tile pixel size
`maxZoom`	`number`	`22`	all	Maximum zoom level
`attribution`	`string`	`''`	all	Attribution text
`layers`	`string`	`''`	WMS, WMTS	Layer name(s)
`format`	`string`	`'image/png'`	WMS, WMTS	Image format
`crs`	`string`	`'EPSG:3857'`	WMS	Coordinate reference system
`style`	`string`	`'default'`	WMTS	WMTS style
`tilematrixSet`	`string`	`'EPSG:3857'`	WMTS	WMTS TileMatrixSet

XYZ Source

Standard slippy-map tiles with {z}/{x}/{y} URL placeholders.

source: {
  type: 'xyz',
  url: 'https://{s}.tile.example.com/{z}/{x}/{y}.png',
  subdomains: ['a', 'b', 'c'],
  tileSize: 256,
  maxZoom: 19,
}

WMS Source

OGC WMS GetMap requests. Computes BBOX from tile coordinates with CRS reprojection.

source: {
  type: 'wms',
  url: 'https://example.com/geoserver/wms',
  layers: 'elevation',
  format: 'image/png',
  crs: 'EPSG:4326',
  tileSize: 256,
}

Supported CRS values: EPSG:3857, EPSG:900913, EPSG:4326, CRS:84.

WMTS Source

OGC WMTS GetTile requests. Two modes, auto-detected:

RESTful — URL contains {z} placeholder (treated like XYZ):

source: {
  type: 'wmts',
  url: 'https://example.com/wmts/rest/dem/default/EPSG3857/{z}/{y}/{x}.png',
}

KVP — URL without placeholders (constructs GetTile query):

source: {
  type: 'wmts',
  url: 'https://example.com/wmts',
  layers: 'dem',
  tilematrixSet: 'EPSG:3857',
  style: 'default',
  format: 'image/png',
}

Elevation Decoders

Built-in decoders for common DEM tile formats:

Decoder	Formula	Precision
`'terrain-rgb'`	`-10000 + (R×65536 + G×256 + B) × 0.1`	0.1 m
`'mapbox'`	Alias for `terrain-rgb`	0.1 m
`'terrarium'`	`R×256 + G + B/256 - 32768`	~0.004 m

Custom Decoder

import { createCustomDecoder, registerDecoder } from '@geozelot/treelet';

// Inline: pass directly as decoderFn
map.addBaseLayer({
  id: 'dem',
  name: 'Custom DEM',
  source: { type: 'xyz', url: '...' },
  decoder: 'custom',
  decoderFn: (r, g, b, a) => r * 100 + g,
});

// Or register globally by name
registerDecoder('myformat', createCustomDecoder((r, g, b, a) => r * 100 + g));
map.addBaseLayer({
  id: 'dem',
  name: 'Custom DEM',
  source: { type: 'xyz', url: '...' },
  decoder: 'myformat' as any,
});

Types

interface LngLat { lng: number; lat: number }
interface WorldPoint { x: number; y: number }
interface TileCoord { z: number; x: number; y: number }
interface TileBounds { west: number; south: number; east: number; north: number }

type BaseDrapeMode = 'wireframe' | 'elevation' | 'slope' | 'aspect' | 'contours';
type ColorRamp = 'hypsometric' | 'viridis' | 'inferno' | 'grayscale';
type BlendMode = 'normal' | 'multiply' | 'screen';
type DecoderType = 'terrain-rgb' | 'mapbox' | 'terrarium' | 'custom';
type UICorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

Low-Level API

For advanced use, treelet re-exports its internal building blocks:

Export	Description
`Treelet`	Main class with static `Treelet.map()` factory
`LayerSource`	Abstract source base class
`createSource()`	Factory: create a source from `LayerSourceOptions`
`XYZSource`, `WMSSource`, `WMTSSource`	Concrete tile sources
`BaseLayer`, `DrapeLayer`	Layer wrappers
`LayerRegistry`	Layer management registry
`DrapeCompositor`	Multi-resolution drape compositing
`SeamResolver`	Cross-LOD edge seam resolution
`CameraController`	Camera state + controls
`WebMercator`	EPSG:3857 projection utilities
`TileGrid`	Tile math (world ↔ tile coordinate conversion)
`EventEmitter`	Base event system
`createTerrainMaterial()`	Unified shader material factory
`terrainRGBDecoder`, `terrariumDecoder`	Decoder instances
`createCustomDecoder()`, `registerDecoder()`	Decoder registration

Controls

Input	Action
Left-click drag	Pan
Scroll wheel	Zoom
Right-click drag	Orbit (rotate + tilt)
Compass click	Reset orientation

Bundles

Treelet ships two minified bundles:

File	Format	Three.js	Use case
`treelet.es.js`	ESM	External	Bundlers (Vite, Webpack, Rollup)
`treelet.cdn.standalone.js`	IIFE	Included	`<script>` tag, CDN, no dependencies

Slim (treelet.es.js) — ~140 KB minified. Three.js is a peer dependency; install it alongside treelet via npm. Best for projects that already use Three.js or want control over the Three.js version.

Standalone (treelet.cdn.standalone.js) — ~580 KB minified. Bundles only the Three.js modules treelet actually uses (tree-shaken). Drop-in ready for CDN or direct <script> tag usage — zero external dependencies.

Both bundles require the tileWorker asset file (dist/assets/tileWorker-*.js) to be served from the same origin.

Browser Support

Modern browsers with WebGL2 and Web Workers. Requires ES2020+.

What's next

compositional overlay blend modes
additional elevation-derived visualization modes
support for more sources and formats
responsive UI

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
assets		assets
demo		demo
src		src
tests/core		tests/core
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.standalone.ts		vite.config.standalone.ts
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Treelet

A lightweight 3D terrain & overlay map library for the web - inspired by Leaflet and powered by Three.js.

Live Demo

Features

Quick Start

Installation

CDN / Script Tag

Minimal Example

API Reference

Factory

Treelet.map(container, options)

Treelet.version

TreeletOptions

Treelet

View

Base Layers

BaseLayerOptions

Drape Layers

DrapeLayerOptions

BaseDrapeMode

Visualization

ColorRamp

Camera

Lifecycle

Events

Tile Sources

LayerSourceOptions

XYZ Source

WMS Source

WMTS Source

Elevation Decoders

Custom Decoder

Types

Low-Level API

Controls

Bundles

Browser Support

What's next

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`Treelet.map(container, options)`

`Treelet.version`

Packages