Teluala.js / 0.1.0-beta.3

A lighter, faster globe engine for the web

Teluala is a small, framework-independent WebGPU engine for rendering a WGS84 ellipsoid and composing independently installed globe layers in the browser.

Public beta: 0.1.0-beta.3. APIs may change before the first stable release.

At a glance

Install

Install the public beta from npm:

npm install teluala@0.1.0-beta.3

Install the optional packages you need alongside the core:

npm install @teluala/terrain@0.1.0-beta.3 @teluala/raster@0.1.0-beta.3 @teluala/vector@0.1.0-beta.3

Teluala requires a browser with WebGPU in a secure context (HTTPS or localhost). @webgpu/types is a type-only peer dependency; add it as a development dependency if your package manager does not install peers automatically.

Quick start

import { GlobeEngine } from 'teluala';

const canvas = document.querySelector('#globe');
if (!GlobeEngine.supported()) {
  throw new Error('This browser does not support WebGPU.');
}

const globe = await GlobeEngine.create(canvas);
globe.onPick = ({ lon, lat }) => console.log({ lon, lat });
globe.flyTo({ lon: 0, lat: 0, range: 0.3 }, 1500);

You get an untextured ellipsoid without map imagery or labels. Drag to pan, scroll to zoom, and right-drag or Shift-drag to orbit. create() can still reject if GPU initialization fails, so handle that error in your UI. Call globe.destroy() when removing the canvas.

Camera and drawing

The camera is a plain object with lon, lat, range, heading, pitch, and roll. Drawing is on demand: change the camera, then call invalidate().

globe.camera.heading = Math.PI / 4;
globe.camera.pitch = -Math.PI / 3;
globe.invalidate();

Longitude and latitude are degrees; heading, pitch, and roll are radians. range is measured in world units, where one unit is the WGS84 semi-major axis (6,378,137 metres).

Extend with layers

GlobeLayer is the rendering extension point. A layer creates its GPU resources once, receives a FrameState, and draws into the engine's shared render pass.

globe.attachLayer(layer);
globe.detachLayer('example');

The core owns one shared GPU picking pass, so independently installed layers take part in picking without coupling to one another. Format-specific feature tables stay in their layer packages.

Packages

The first beta includes core, terrain, raster, and vector. APIs may change between beta releases.

Resources

• Source on GitHub
• Full setup guide
• Issues
• Brand assets — or right-click the logo to download the brand kit.