three-loader-3dtiles

Demos — Usage — Roadmap — Contributing — Docs — Alternatives

This is a Three.js loader module for handling OGC 3D Tiles, created by Cesium. It currently supports the two main formats:

Batched 3D Model (b3dm) - based on glTF.
Point cloud.

Internally, the loader uses the loaders.gl library, which is part of the vis.gl platform, openly governed by the Urban Computing Foundation. Cesium has worked closely with loaders.gl to create a platform-independent implementation of their 3D Tiles viewer.

Development of this library started at The New York Times R&D as an effort to create a clean bridge between the 3D Tiles specification and the widely used 3D library Three.js. The library helps us deliver massive 3D and Geographical journalism to desktops and mobile readers alike. From Reporting to Teleporting!

Demos

Basic Usage

Here is a simple example using the Loader3DTiles module to view a tileset.json containing a 3d tile hierarchy.

import { 
  Scene, 
  PerspectiveCamera, 
  WebGLRenderer, 
  Clock 
} from 'three'
import { Loader3DTiles } from 'three-loader-3dtiles';

const scene = new Scene()
const camera = new PerspectiveCamera()
const renderer = new WebGLRenderer()
const clock = new Clock()

renderer.setSize(window.innerWidth, window.innerHeight)
document.body.appendChild(renderer.domElement)

let tilesRuntime = null;

async function loadTileset() {
  const result = await Loader3DTiles.load(
      url: 'https://<TILESET URL>/tileset.json',
      viewport: {
        width: window.innerWidth,
        height: window.innerHeight,
        devicePixelRatio: window.devicePixelRatio
      }
      options: {
        dracoDecoderPath: 'https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/libs/draco',
        basisTranscoderPath: 'https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/libs/basis',
      }
  )
  const {model, runtime} = result
  tilesRuntime = runtime
  scene.add(model)
}

function render() {
  const dt = clock.getDelta()
  if (tilesRuntime) {
    tilesRuntime.update(dt, window.innerHeight, camera)
  }
  renderer.render(scene, camera)
  window.requestAnimationFrame(render)
}

loadTileset()
render()

Installation

The library supports three.js r160 and uses its GLTF, Draco, and KTX2/Basis loaders. Refer to the browserslist field in package.json for target browsers.

1. ES Module

Use an importmap to import the dependencies from the npm. See here for a full example.

`index.html`

  <script type="importmap">
    {
      "imports": {
        "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
        "three/examples/jsm/": "https://unpkg.com/three@0.160.0/examples/jsm/",
        "three-loader-3dtiles" : "https://unpkg.com/three-loader-3dtiles/dist/lib/three-loader-3dtiles.js"
      }
    }
  </script>
  <script src='index.js' type='module'>

`index.js`

  import { Scene, PerspectiveCamera } from 'three';
  import { Loader3DTiles } from 'three-loader-3dtiles';

3. NPM

If you use a build system such as Webpack / Vite / Rollup etc, you should also install the library along with three.js from npm:

npm install -s three three-loader-3dtiles

The application script would be the same as in the ES Module example (when using importmap).

See here for a complete webpack example.

4. A-Frame

Refer to our dedicated A-Frame component: aframe-loader-3dtiles-component.

5. React-Three-Fiber

Refer to examples/r3f.

Roadmap

Supporting 3D Tiles Next

The 3D Tiles Next specification is in the works, with some of the features already supported in loaders.gl. Supporting the new extensions opens up possibilities for new applications.

Skip-traversal

Implementing the Skip traversal mechanism could greatly improve performance of b3dm (mesh) tiles, but requires a shader/Stencil buffer-based implementation which manually manges Z-culling. This is a very wanted feature and contributions would be greatly appreciated.

Contributing

Refer to CONTRIBUTING.MD for general contribution instructions.

Developing

The library is built using rollup. To run a simple development server type:

npm run dev

It is also possible to develop the library while developing loaders.gl. Just clone the source of loaders.gl and run:

LOADERS_GL_SRC=<path to loaders.gl> npm run dev

Building

To build the library run:

npm run build

To build the production minified version run:

npm run build:production

And to build the API documentation run:

npm run docs

Tests

A rudimentary test spec is available at ./test. To run it type:

npm run test

Docs

API documentation is available here.
Code for the demos is in examples/demos.

Alternatives

To our knowledge, this is the only loaders.gl-based Three.js library, but there are several implementations of 3D Tiles for Three.js. Notable examples:

This repository is maintained by the Research & Development team at The New York Times and is provided as-is for your own use. For more information about R&D at the Times visit rd.nytimes.com

nytimes / three-loader-3dtiles

readme