English | 简体中文

three-tile

A lightweight 3D tile map development framework

Documentation | GitHub Repository | Issues

1. Introduction

three-tile is an open-source, lightweight frontend 3D tile framework built on Three.js using TypeScript. It provides 3D terrain models and lets you easily add 3D tile maps to your applications. After dozens of iterations, the framework's features and effects meet production environment requirements and have been validated and applied in multiple projects.

three-tile is more like LOD terrain from game development, but it can use data from map service providers to render maps.

::: warning Disclaimer This framework does not contain any map data. Maps used in examples and demos directly reference third-party data and do not represent the position of this development framework. Developers should comply with relevant regulations and use legal maps. :::

2. Features

Feature	Description
Lightweight	Under 70KB (zip: 28KB) after bundling (excluding plugins), easy to integrate
Fast	Resource usage optimized to the extreme, low memory footprint, fast rendering, integrated graphics can easily achieve 60fps
Few Dependencies	Only one external dependency: threejs , all features self-implemented
Easy to Extend	Plugin-based architecture, tile data loading, parsing, modeling, and rendering are all independent from core
Simple to Use	Almost no learning curve if you're familiar with threejs

3. Use Cases

1. Add Terrain to Existing Applications

In threejs examples, most simple applications use a plane as ground. If you replace the plane with real terrain, the effect immediately improves.

2. Simple WebGIS

three-tile map models can directly use mainstream tile data sources to render realistic terrain; provides conversion from geographic coordinates (longitude, latitude, altitude) to 3D scene coordinates, allowing map elements (models, labels) to be overlaid at specified geographic locations.

3. Game Development

Fully supports all built-in Three.js controllers. Simply switch controllers to implement first-person, flight, and other game features.

4. Data Visualization

Data visualization scenarios like atmosphere, satellite cloud maps, wind field animations, and volume rendering.

4. Quick Start

Installation

npm

npm i three -S
npm i three-tile -S

Script Tag

<script type="importmap">
	{
		"imports": {
			"three": "https://unpkg.com/three@0.171.0/build/three.module.js",
			"three-tile": "https://unpkg.com/three-tile@0.12.1/dist",
			"three-tile/plugin": "https://unpkg.com/three-tile@0.12.1/dist/plugin"
		}
	}
</script>

Usage

1. Define map data source
2. Create map model
3. Add map model to 3D scene

import * as THREE from "three";
import * as tt from "three-tile";
import * as plugin from "three-tile/plugin";

// Create map
const map = tt.TileMap.create({
	// Image data source
	imgSource: new plugin.ArcGisSource(),
	// DEM data source
	demSource: new plugin.ArcGisDemSource(),
});
// Rotate map to xz plane
map.rotateX(-Math.PI / 2);

// Initialize viewer
const viewer = new plugin.GLViewer("#map");
// Add map to scene
viewer.scene.add(map);

5. Supported Map Data Sources

Built-in support for mainstream tile map services:

• ArcGIS
• Mapbox
• Bing
• Google
• Tianditu (China)
• Gaode (China)
• Tencent (China)

Also supports custom tile data source extensions.

6. API Documentation

• Core Library API - three-tile core library
• Plugin API - three-tile plugins

7. Applications

Basics

• Introduction - What is three-tile, features, use cases
• Quick Start - Installation and basic usage

Examples

Category	Examples
Basic Functions	Get Mouse Location · Get Loading Info · Set Map Zoom · Custom Map Source
Map Display	Fake Earth · Compass · Limit Camera Height · Skybox
Terrain Control	Add Mesh · Terrain Scale · Limit Pan · Set Map Bounds
Material Effects	Add Shadow · CSS Filter · Add Sky · Add Water
Data Overlay	GeoJSON · MVT · WMS Source · CSS2D Labels
Model Loading	Add Model · Icon Marker · Logo Marker · White Model
Terrain Effects	Mask · Single DEM · Single Image · Create Hole · Polygon Hole
Scene Config	Background · Switch Controls · Ground Group · 2D Map
Advanced	Non-Map Tile · 3DTiles Rendering · SplatLuma · SplatDrei

Application Examples

Example	Description
First Person	First-person view navigation
Flight Controls	Free flight mode
Walking	Ground walking navigation
Satellite Cloud Map	3D cloud map display
Contour Lines	Terrain contour lines
Atmosphere Effects	Atmospheric rendering effects
GeoJSON 3D	GeoJSON 3D building display

8. References

• https://threejs.org/
• https://github.com/CesiumGS/cesium
• https://github.com/mapbox/mapbox-gl-js
• https://leafletjs.com
• https://github.com/tentone/geo-three
• https://github.com/ebeaufay/threedtiles
• https://github.com/NASA-AMMOS/3DTilesRendererJS
• https://github.com/wlgys8/GPUDrivenTerrainLearn
• https://github.com/lijundacom/LeoGPUDriven
• https://github.com/mapbox/martini
• https://github.com/visgl/loaders.gl/blob/master/modules/terrain/src/lib/helpers/skirt.ts