3dtilesrenderer-styling-plugin

A plugin for 3DTilesRendererJS that applies Cesium 3D Tiles Styling Specification color conditions to 3D tile features. It reads feature properties from GLB tiles via EXT_structural_metadata, evaluates color conditions based on property values, and applies per-feature vertex colors using Three.js materials.

Original styling specs see https://github.com/CesiumGS/3d-tiles/tree/main/specification/Styling

Architecture

The plugin implements the TilesRenderer plugin pattern and intercepts the load-model event to style GLB tiles as they are loaded.

flowchart LR
    A["TilesRenderer<br/>loads GLB tile"] -->|load-model<br/>event| B["CesiumStylingPlugin<br/>intercepts"]
    B --> C["Read EXT_structural_metadata<br/>property tables"]
    C --> D["Extract _FEATURE_ID_0<br/>vertex attribute"]
    D --> E["Evaluate color conditions<br/>for each feature"]
    E --> F["Apply vertex colors<br/>to Three.js mesh"]
    F --> G["Browser renders<br/>styled tile"]

The plugin processes each tile independently. For every mesh in the loaded GLB:

1. It retrieves the feature ID for each vertex via the _FEATURE_ID_0 attribute
2. It looks up the feature's property values in the structural metadata tables
3. It evaluates the color conditions against the property value
4. It creates per-vertex colors in a Float32Array
5. It sets the vertex color attribute and enables vertexColors on the material

Demo

Color buildings by height

https://bertt.github.io/3dtilesrenderer-styling-plugin/sample/sibbe/

Installation

npm install @bertt/3dtilesrenderer-styling-plugin

Requires Three.js and 3d-tiles-renderer as peer dependencies.

Usage

Prerequisites

Before using the plugin, register the required GLTF extensions on your GLTFLoader:

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { GLTFMeshFeaturesExtension } from '3d-tiles-renderer';
import { GLTFStructuralMetadataExtension } from '3d-tiles-renderer';

const gltfLoader = new GLTFLoader();
gltfLoader.register(parser => new GLTFMeshFeaturesExtension(parser));
gltfLoader.register(parser => new GLTFStructuralMetadataExtension(parser));

Basic example

import { TilesRenderer } from '3d-tiles-renderer';
import { CesiumStylingPlugin } from '@bertt/3dtilesrenderer-styling-plugin';

// Create the tiles renderer
const tiles = new TilesRenderer('https://example.com/tileset.json');
tiles.setCamera(camera);
tiles.setResolutionFromRenderer(renderer);

// Define the style
const style = {
  color: {
    conditions: [
      ["${height} <= 10", "color('#430719')"],
      ["${height} > 10 && ${height} <= 20", "color('#740320')"],
      ["${height} > 20", "color('#f72585')"],
      ["true", "color('#ffffff')"]
    ]
  }
};

// Create and register the plugin
const plugin = new CesiumStylingPlugin({ style });
tiles.registerPlugin(plugin);

// Add to scene and render
scene.add(tiles.group);

How color conditions work

The plugin evaluates conditions in order. The first condition that evaluates to true determines the color for that feature.

Each condition is an array: [expression, colorFunction]

• Expression: A string that evaluates to boolean, using property names from the tileset's structural metadata
• Color function: A string like "color('#RRGGBB')" that specifies the output color

Style Syntax

Supported features

| Feature | Example | Status | |---------|---------|--------| | Property access (bracket) | ${feature['height']} | ✓ Supported | | Property access (shorthand) | ${height} | ✓ Supported | | Comparison operators | <=, >=, <, >, ===, !==, ==, != | ✓ Supported | | Boolean operators | &&, \|\| | ✓ Supported | | Catch-all condition | "true" | ✓ Supported | | RGB color | color('#RRGGBB') | ✓ Supported | | RGBA color | color('#RRGGBB', alpha) | ✓ Supported | | CSS rgb() | rgb(255, 0, 128) | ✓ Supported | | CSS rgba() | rgba(255, 0, 128, 0.5) | ✓ Supported |

Not supported in V1

| Feature | Reason | |---------|--------| | show property | Requires feature-level visibility control | | defines property | Not applicable to client-side rendering | | Mathematical functions | clamp(), min(), max() not yet implemented | | Regular expressions | Pattern matching not implemented | | meta property | Metadata about the style not supported | | String comparisons | Property values assumed to be numeric | | Ternary expressions | Syntax not parsed | | pointSize property | Not applicable to polygon/mesh rendering |

Color expression examples

// Hex colors
"color('#FF0000')"           // Solid red
"color('#00FF00', 0.5)"      // Half-transparent green

// RGB/RGBA functions
"rgb(255, 165, 0)"           // Orange
"rgba(0, 0, 255, 0.8)"       // Semi-transparent blue

// Conditional examples
"${height} > 100"            // Compare height property
"${type} === 'residential' && ${height} > 15"
"${population} >= 10000 || ${area} > 5000"

Options

Constructor options

new CesiumStylingPlugin(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | style | object | yes | Style object with color.conditions array |

The style object shape:

{
  color: {
    conditions: [
      [expression, colorFunction],
      [expression, colorFunction],
      // ...
      ["true", fallbackColor]  // Recommended catch-all
    ]
  }
}

Sample

A working sample is included in sample/sibbe/index.html. It demonstrates styling of BAG (Basisregistratie Adressen en Gebouwen) building data in Sibbe, Limburg, colored by building height.

The sample uses a color gradient:

• Dark navy (#430719) for buildings 0–10 meters
• Rose (#f72585) for buildings above 30 meters

Running the sample locally

1. Open a terminal in the repository root
2. Start a local HTTP server:

   npx http-server

3. Open http://localhost:8080/sample/sibbe/ in your browser

Or open sample/sibbe/index.html directly in your browser if using a modern browser with CORS enabled for file:// URLs (some browsers restrict this).

Publishing

To publish a new version to npm:

npm login
npm publish --access public

Notes:

• The package is configured as a public scoped package (@bertt/), so --access public is required
• Ensure you have permissions for the @bertt scope
• No build step is required; the source files are published as-is (ES modules)
• Update the version number in package.json before publishing

License

MIT