Styling and Filtering 3D Tiles

This guide explains how to use CesiumJS to style and filter 3D Tiles to highlight important features of your dataset.

melbourneHeatmap Heatmap of Melbourne created with 3D Tiles Styling. Left: OSM Buildings 3D Tiles. Right: Point cloud 3D Tiles.

Prerequisites

  • Have A 3D Tileset with properties or classification. You can upload your own data or use one of Cesium’s curated 3D Tilesets such as OSM Buildings or Montreal Point Cloud, which can be found in the Cesium ion Asset Depot. To turn your dataset into 3D Tiles, check out our quick guides for importing data.

Cesium ion’s tiling pipeline currently supports per-feature data for 3d buildings and point clouds, and we’re working on adding more.

  • Basic knowledge about CesiumJS. For beginners, visit the Quickstart tutorial.
  • A Cesium ion account to generate an access token for JSFiddle code examples (step 1 of the Quickstart tutorial).

The styling language for 3D Tiles

The 3D Tiles styling language lets you define rules for how features in your dataset should appear, for instance the color of buildings or the types of building that are shown. This is helpful for identifying patterns in a city or to create a more informative visualization.

Styles are defined with JSON and JavaScript expressions. Additionally, the styling language provides a set of built-in functions to support common math operations, such as min, distance, and log.

This guide includes examples of these commonly used parts of the 3D Tiles styling language:

  • Styling options show and color
  • Tests for conditions, including feature property tests, null check, and Classification checks for points in point clouds
  • Creating new variables with defines
  • The distance function
  • Creating new color definitions

For in-depth documentation for styling and filtering 3D Tiles, see the 3D Tiles Styling Specification. More examples are also available in Sandcastle (search for “styling”).

What is a 3D Tiles feature?

Features can be things like individual buildings, doors, windows, valves, or points in a point cloud.

Apply a basic style

There are two common ways we can apply styles to a 3D tileset: via the show and color visual properties. Once we have determined what the styling rule is, we can apply it to our features by setting the style member variable of the 3D tileset to a new Cesium3DTileStyle.

For the code snippet below, we use the Cesium OSM Buildings 3D Tiles and the Crown Entertainment Complex in Melbourne, Australia. The rule is to color the building named “Crown Entertainment Complex” red and all other buildings white. The CesiumJS will efficiently apply this rule to every feature, replacing any existing styles on the feature. The feature property we chose is name, which already exists in the dataset.

Copy to clipboard. Data copied clipboard.
osmBuildingsTileset.style = new Cesium.Cesium3DTileStyle({
  color: {
    conditions: [
      ["${name} === 'Crown Entertainment Complex'", "color('red')"],
      ["true", "color('white')"],
    ],
  },
});

Open in JSFiddle

We can see a list of feature properties by clicking on a feature in the viewer:

CrownEntertainment

Show features based on a property

In addition to coloring, the 3D Tiles styling language allows you to show and hide features based on their metadata properties.

Here are all the buildings in Melbourne from the Cesium OSM Buildings tileset.

ShowAllBuildings Melbourne prior to showing only residential buildings.

Let’s say we wanted to find all the residential buildings in Melbourne, which are classified using the building property as “residential” or “apartment” in OSM Buildings.

Copy to clipboard. Data copied clipboard.
osmBuildingsTileset.style = new Cesium.Cesium3DTileStyle({
  show: "${feature['building']} === 'residential' || ${feature['building']} === 'apartments'",
});

Open in JSFiddle

ShowOnlyResidentialBuildings Melbourne after showing only residential buildings.

Color features using conditions

You can also use conditions to determine what color to assign to features.

For example, you might want to design a bus route for tourists in a zone around Melbourne’s Crown Entertainment Complex. What buildings are within a given distance from the complex?

This code snippet assigns each building a color based on its distance from the Crown Entertainment Complex:

Copy to clipboard. Data copied clipboard.
osmBuildingsTileset.style = new Cesium.Cesium3DTileStyle({
  defines: {
    distanceFromComplex:
      "distance(vec2(${feature['cesium#longitude']}, ${feature['cesium#latitude']}), vec2(144.96007, -37.82249))",
  },
  color: {
    conditions: [
      ["${distanceFromComplex} > 0.010", "color('#d65c5c')"],
      ["${distanceFromComplex} > 0.006", "color('#f58971')"],
      ["${distanceFromComplex} > 0.002", "color('#f5af71')"],
      ["${distanceFromComplex} > 0.0001", "color('#f5ec71')"],
      ["true", "color('#ffffff')"],
    ],
  },
});

Open in JSFiddle

  • 3D Tiles styling conditions lets you define features like color in an array.
  • Conditions behave like if statements.
    • In this case, if the building is greater than 0.0001 but less than 0.002 degrees away from the Crown Entertainment Complex, its color is orange (0.0001 degree = 11.1 m).
  • The defines expression creates new variables.
    • Here, distanceFromComplex is a new variable defined as the relationship between the latitude and longitude properties of a building and those of the complex.
  • distance is a built-in function of the 3D Tiles styling language.
  • CSS-style color definitions are supported.
    • For instance, the hex code color('#ffffff') declares a new color equivalent to color('white').

The code snippet above produces the following styling result:

ColorByDistance

Style point clouds

A point cloud is a collection of points that follow the same styling rules above, with some additional options.

Point cloud styling options and properties

In addition to color and show visual properties, point cloud Tiles also support pointSize. The default pointSize is 1.0.

Point clouds in LAS files tiled on Cesium ion include two per-point properties: Classification and Intensity.

  • Classification is an integer mapping to the point’s data type, such as ground, low vegetation, or buildings.
  • Intensity is the reflectivity of the surface of your point, which is an integer between 0 and 255 inclusive.

Point cloud styling can also be applied to other point properties such as position, color, and normal. For instance, you can create a heatmap of point cloud tiles based on their distance from a central point using the POSITION_ABSOLUTE metadata property, similar to how we colored OSM buildings based on their distance from the Crown Entertainment Complex (see the heatmap Sandcastle).

Point cloud styling example

Let’s say you want to visualize the environment surrounding the Biosphere Museum in Montreal, Canada. The styling rule is to color points green if their Classification property is vegetation.

Copy to clipboard. Data copied clipboard.
pointCloudTileset.style = new Cesium.Cesium3DTileStyle({
  color: {
    conditions: [
      ["${Classification} === 2", "color('brown')"],       // ground
      ["${Classification} === 3", "color('greenyellow')"], // low vegetation
      ["${Classification} === 4", "color('green')"],       // medium vegetation
      ["${Classification} === 5", "color('darkgreen')"],   // high vegetation
      ["true", "color('white')"]
    ]
  }
});

Open in JSFiddle

With the styling rule applied, we can visualize how much of the museum’s surroundings are vegetation:

BioSphereMuseumPoststyling

Handle undefined properties

Sometimes buildings are missing properties. In such cases, we can add a null checker condition:

Copy to clipboard. Data copied clipboard.
osmBuildingsTileset.style = new Cesium.Cesium3DTileStyle({
    color: {
      conditions: [
        ["${material} === null", "color('white')"],
        ["${material} === 'glass'", "color('skyblue', 0.5)"],
        ["${material} === 'concrete'", "color('grey')"],
        ["${material} === 'brick'", "color('indianred')"],
        ["true", "color('white')"],
      ],
    },
  });
}

In this example, if any building doesn’t possess the material metadata property, its color is white.

Use the Style Editor in Cesium Stories

You can also style 3D Tiles using the styling editor in Cesium Stories. The same styling methods we covered above can be applied in the editor without having to write code. See the Styling 3D Tiles in Cesium Stories tutorial.

IonStyleEditor

Additional resources

Check out the styling examples in Sandcastle, including:

For in-depth documentation for styling and filtering 3D Tiles, see the 3D Tiles Styling Specification.