/cesiumjs-3d-tiles

name: cesiumjs-3d-tiles
description: "CesiumJS 3D Tiles - Cesium3DTileset, compressed and CAD-style glTF content, MVTDataProvider, styling, metadata, feature picking, voxels, point clouds, I3S, Gaussian splats, clipping. Use when loading 3D Tiles or Mapbox Vector Tiles, rendering KHR meshopt/CAD content, styling or querying features, working with voxels or point clouds, or clipping spatial data."

CesiumJS 3D Tiles

Version baseline: CesiumJS v1.143 (ES module imports, async factory methods).

Loading a Tileset

Always use async factory methods -- never call the constructor directly.

import { Cesium3DTileset, HeadingPitchRange, Math as CesiumMath } from "cesium";

// From a URL
const tileset = await Cesium3DTileset.fromUrl(
  "https://example.com/tileset.json",
  { maximumScreenSpaceError: 16 }, // lower = higher quality
);
viewer.scene.primitives.add(tileset);
viewer.zoomTo(tileset, new HeadingPitchRange(
  0.0, CesiumMath.toRadians(-25.0), tileset.boundingSphere.radius * 2.0,
));

CesiumJS 1.143 applies standalone model loading to glTF embedded in tilesets. Read the [glTF compatibility matrix](../cesiumjs-models-particles/REFERENCE.md) for automatic `KHR_meshopt_compression`, CAD extension behavior, and the unsupported planar-fill boundary.

// From Cesium ion
const tileset = await Cesium3DTileset.fromIonAssetId(75343);
viewer.scene.primitives.add(tileset);

// Google Photorealistic 3D Tiles
import { createGooglePhotorealistic3DTileset } from "cesium";
const google3D = await createGooglePhotorealistic3DTileset({
  onlyUsingWithGoogleGeocoder: true,
});
viewer.scene.primitives.add(google3D);

// OSM Buildings
import { createOsmBuildingsAsync } from "cesium";
const osmBuildings = await createOsmBuildingsAsync();
viewer.scene.primitives.add(osmBuildings);

Key Constructor Options

| Option | Default | Purpose | |--------|---------|---------| | `maximumScreenSpaceError` | 16 | LOD quality threshold (pixels) | | `cacheBytes` | 536870912 | Tile cache trim target (bytes) | | `maximumCacheOverflowBytes` | 536870912 | Extra cache headroom | | `shadows` | ShadowMode.ENABLED | Shadow casting/receiving | | `modelMatrix` | Matrix4.IDENTITY | Root transform | | `clippingPlanes` | undefined | ClippingPlaneCollection | | `clippingPolygons` | undefined | ClippingPolygonCollection (WebGL 2) | | `enableCollision` | false | Camera collision with tileset surface | | `pointCloudShading` | undefined | Point attenuation options object | | `classificationType` | undefined | TERRAIN, CESIUM_3D_TILE, or BOTH | | `dynamicScreenSpaceError` | true | Horizon LOD optimization | | `foveatedScreenSpaceError` | true | Center-screen tile priority | | `preloadFlightDestinations` | true | Prefetch tiles at flight target | | `featureIdLabel` | "featureId_0" | EXT_mesh_features ID set label | | `backFaceCulling` | true | Cull back faces per glTF material | | `edgeDisplayMode` | EdgeDisplayMode.SURFACES_ONLY | Render glTF edge-visibility data when present |

Mapbox Vector Tiles as Runtime 3D Tiles (Experimental, 1.142+)

`MVTDataProvider` loads `{z}/{x}/{y}` Mapbox Vector Tile `.mvt`/`.pbf` templates and converts tile payloads into runtime 3D Tiles. Use it when vector data is naturally tiled and you want 3D Tiles styling, metadata picking, and LOD instead of a single GeoJSON primitive.

For one in-memory or URL-backed GeoJSON object, prefer `GeoJsonPrimitive` in `cesiumjs-primitives`. For Entity/DataSource conveniences, prefer `GeoJsonDataSource` in `cesiumjs-entities`.

import {
  Cesium3DTileStyle,
  MVTDataProvider,
  Rectangle,
} from "cesium";

const provider = await MVTDataProvider.fromUrl(
  "https://example.com/tiles/{z}/{x}/{y}.pbf",
  {
    minZoom: 4,
    maxZoom: 14,
    extent: Rectangle.fromDegrees(-125, 24, -66, 50),
    featureIdProperty: "id",
  },
);

viewer.scene.primitives.add(provider);

// The provider owns a generated Cesium3DTileset.
provider.tileset.style = new Cesium3DTileStyle({
  color: {
    conditions: [
      ["${kind} === 'park'", "color('seagreen', 0.65)"],
      ["${kind} === 'water'", "color('steelblue', 0.55)"],
      ["true", "color('white', 0.45)"],
    ],
  },
});

Feature properties are encoded as `EXT_structural_metadata`, so standard 3D Tiles styling and picking patterns apply:

const picked = viewer.scene.pick(windowPosition);
if (picked && typeof picked.getProperty === "function") {
  console.log(picked.getProperty("name"));
}

Notes:

• URL templates must contain `{z}`, `{x}`, and `{y}` placeholders; tile URLs are parsed from `/z/x/y`.
• Empty 204/404 tiles are treated as missing instead of hard failures.
• `provider.show` proxies visibility to the generated tileset.
• Runtime vector glTF content uses draft `EXT_mesh_polygon` and `3DTILES_content_gltf_vector` support; treat this path as experimental.

Tileset Events

tileset.loadProgress.addEventListener((pending, processing) => {
  if (pending === 0 && processing === 0) console.log("Loaded");
});
tileset.initialTilesLoaded.addEventListener(() => { /* first view ready */ });
tileset.allTilesLoaded.addEventListener(() => { /* all visible tiles ready */ });
tileset.tileLoad.addEventListener((tile) => { /* tile content loaded */ });
tileset.tileUnload.addEventListener((tile) => { /* tile evicted from cache */ });
tileset.tileFailed.addEventListener(({ url, message }) => {
  console.error(`Tile ${url}: ${message}`);
});
// Per-frame manual styling
tileset.tileVisible.addEventListener((tile) => {
  const content = tile.content;
  for (let i = 0; i < content.featuresLength; i++) {
    content.getFeature(i).color = Cesium.Color.fromRandom();
  }
});

Runtime Properties

tileset.show = false;                     // toggle visibility
tileset.maximumScreenSpaceError = 8;      // increase quality
const { center, radius } = tileset.boundingSphere;

import { Matrix4, Cartesian3 } from "cesium";
tileset.modelMatrix = Matrix4.fromTranslation(new Ca