6.7.1.  Geometric error

Tiles are structured into a tree incorporating Hierarchical Level of Detail (HLOD) so that at runtime a client implementation will need to determine if a tile is sufficiently detailed for rendering and if the content of tiles should be successively refined by children tiles of higher resolution. An implementation will consider a maximum allowed Screen-Space Error (SSE), the error measured in pixels.

A tile’s geometric error defines the selection metric for that tile. Its value is a nonnegative number that specifies the error, in meters, of the tile’s simplified representation of its source geometry. The root tile, being the most simplified version of the source geometry, will have the greatest geometric error. Then each successive level of children will have a lower geometric error than its parent, with leaf tiles having a geometric error of or close to 0.

In a client implementation, geometric error is used with other screen space metrics—e.g., distance from the tile to the camera, screen size, and resolution— to calculate the SSE introduced if this tile is rendered and its children are not. If the introduced SSE exceeds the maximum allowed, then the tile is refined and its children are considered for rendering.

The geometric error is formulated based on a metric like point density, tile size in meters, or another factor specific to that tileset. In general, a higher geometric error means a tile will be refined more aggressively, and children tiles will be loaded and rendered sooner.

6.7.2.  Refinement

Refinement determines the process by which a lower resolution parent tile renders when its higher resolution children are selected to be rendered. Permitted refinement types are replacement (”REPLACE”) and additive (”ADD”). If the tile has replacement refinement, the children tiles are rendered in place of the parent, that is, the parent tile is no longer rendered. If the tile has additive refinement, the children are rendered in addition to the parent tile.

A tileset can use replacement refinement exclusively, additive refinement exclusively, or any combination of additive and replacement refinement.

A refinement type is required for the root tile of a tileset; it is optional for all other tiles. When omitted, a tile inherits the refinement type of its parent.

6.7.2.1.  Replacement

If a tile uses replacement refinement, when refined it renders its children in place of itself.

Parent Tile

Figure 2 — A parent tile with replacement refinement

Refined

Figure 3 — A refined child tile of a tile with replacement refinement

6.7.2.2.  Additive

If a tile uses additive refinement, when refined it renders itself and its children simultaneously.

Parent Tile

Figure 4 — A parent tile with additive refinement

Refined

Figure 5 — A refined child tile of a tile with additive refinement

6.7.3.  Bounding volumes

A bounding volume defines the spatial extent enclosing a tile or a tile’s content. To support tight fitting volumes for a variety of datasets such as regularly divided terrain, cities not aligned with a line of latitude or longitude, or arbitrary point clouds, the bounding volume types include an oriented bounding box, a bounding sphere, and a geographic region defined by minimum and maximum latitudes, longitudes, and heights.

Bounding box

Figure 6 — A bounding box

Bounding sphere

Figure 7 — A bounding sphere

Bounding region

Figure 8 — A bounding region

6.7.3.1.  Region

The boundingVolume.region property is an array of six numbers that define the bounding geographic region with latitude, longitude, and height coordinates with the order [west, south, east, north, minimum height, maximum height]. Latitudes and longitudes are in the WGS 84 datum as defined in EPSG 4979 and are in radians. Heights are in meters above (or below) the WGS 84 ellipsoid.

Figure 9 — A bounding region

"boundingVolume": {
  "region": [
     -1.3197004795898053,
     0.6988582109,
     -1.3196595204101946,
     0.6988897891,
     0,
     20
  ]
}

6.7.3.2.  Box

The boundingVolume.box property is an array of 12 numbers that define an oriented bounding box in a right-handed 3-axis $\left(x,y,z\right)$ Cartesian coordinate system where the $z$-axis is up. The first three elements define the $x$, $y$, and $z$ values for the center of the box. The next three elements (with indices 3, 4, and 5) define the $x$-axis direction and half-length. The next three elements (indices 6, 7, and 8) define the $y$-axis direction and half-length. The last three elements (indices 9, 10, and 11) define the $z$-axis direction and half-length.

Figure 10 — A bounding box

"boundingVolume": {
  "box": [
     0,0,10,
     100,0,0,
     0,100,0,
     0,0,10
  ]
}

6.7.3.3.  Sphere

The boundingVolume.sphere property is an array of four numbers that define a bounding sphere. The first three elements define the $x$, $y$, and $z$ values for the center of the sphere in a right-handed 3-axis $\left(x,y,z\right)$ Cartesian coordinate system where the $z$-axis is up. The last element (with index 3) defines the radius in meters.

Figure 11 — A bounding sphere

"boundingVolume": {
  "sphere": [
     0,
     0,
     10,
     141.4214
  ]
}

6.7.4.  Viewer request volume

A tile’s viewerRequestVolume can be used for combining heterogeneous datasets, and can be combined with External tilesets.

The following example has a building in a b3dm tile and a point cloud inside the building in a pnts tile. The point cloud tile’s boundingVolume is a sphere with a radius of 1.25. It also has a larger sphere with a radius of 15 for the viewerRequestVolume. Since the geometricError is zero, the point cloud tile’s content is always rendered (and initially requested) when the viewer is inside the large sphere defined by viewerRequestVolume.

{
  "children":[{
    "transform":[
      4.843178171884396,1.2424271388626869,0,0,
      -0.7993325488216595,3.1159251367235608,3.8278032889280675,0,
      0.9511533376784163,-3.7077466670407433,3.2168186118075526,0,
      1215001.7612985559,-4736269.697480114,4081650.708604793,1
    ],
    "boundingVolume":{
      "box":[
        0,0,6.701,
        3.738,0,0,
        0,3.72,0,
        0,0,13.402
      ]
    },
    "geometricError":32,
    "content":{
      "uri":"building.b3dm"
    }
  },{
    "transform":[
      0.968635634376879,0.24848542777253732,0,0,
      -0.15986650990768783,0.6231850279035362,0.7655606573007809,0,
      0.19023066741520941,-0.7415493329385225,0.6433637229384295,0,
      1215002.0371330238,-4736270.772726648,4081651.6414821907,1
    ],
    "viewerRequestVolume":{
      "sphere":[0,0,0,15]
    },
    "boundingVolume":{
      "sphere":[0,0,0,1.25]
    },
    "geometricError":0,
    "content":{
      "uri":"points.pnts"
    }
  }]
}

For more on request volumes, see the sample tileset and demo video.

6.7.5.  Transforms

[
1.0,0.0,0.0,0.0,
0.0,1.0,0.0,0.0,
0.0,0.0,1.0,0.0,
0.0,0.0,0.0,1.0
]

6.7.5.2.  glTF transforms

Batched 3D Model and Instanced 3D Model tiles embed glTF, which defines its own node hierarchy and uses a $y$-up coordinate system. Any transforms specific to a tile format and the tile.transform property are applied after these transforms are resolved.

6.7.5.2.1.  glTF node hierarchy

First, glTF node hierarchy transforms are applied according to the glTF specification.

6.7.5.2.2.  y-up to z-up

Next, for consistency with the $z$-up coordinate system of 3D Tiles, glTFs must be transformed from $y$-up to $z$-up at runtime. This is done by rotating the model about the $x$-axis by $\pi /2$ radians. Equivalently, apply the following matrix transform (shown here as row-major):

[
1.0,0.0,0.0,0.0,
0.0,0.0,-1.0,0.0,
0.0,1.0,0.0,0.0,
0.0,0.0,0.0,1.0
]

More broadly the order of transformations is:

1. glTF node hierarchy transformations

2. glTF y-up to z-up transform

3. Any tile format specific transforms.

   • Batched 3D Model Feature Table may define RTC_CENTER which is used to translate model vertices.

   • Instanced 3D Model Feature Table defines per-instance position, normals, and scales. These are used to create per-instance 4×4 affine transform matrices that are applied to each instance.

4. Tile transform

Implementation note: when working with source data that is inherently $z$-up, such as data in WGS 84 coordinates or in a local $z$-up coordinate system, a common workflow is:

• Mesh data, including positions and normals, are not modified — they remain $z$-up.

• The root node matrix specifies a column-major $z$-up to $y$-up transform. This transforms the source data into a $y$-up coordinate system as required by glTF.

• At runtime the glTF is transformed back from $y$-up to $z$-up with the matrix above. Effectively the transforms cancel out.

Example glTF root node:

“nodes”: [
  {
    “matrix”:[1,0,0,0,0,0,-1,0,0,1,0,0,0,0,0,1],
    “mesh”:0,
    “name”:”rootNode”
  }
]

6.7.5.2.3.  Example

For an example of the computed transforms (transformToRoot in the code above) for a tileset, consider:

Figure 12 — A tileset with transformed children tiles

The computed transform for each tile is:

• TO: [T0]

• T1: [T0][T1]

• T2: [T0][T2]

• T3: [T0][T1][T3]

• T4: [T0][T1][T4]

The positions and normals in a tile’s content may also have tile-specific transformations applied to them before the tile’s transform (before indicates post-multiplying for affine transformations). Some examples are:

• b3dm and i3dm tiles embed glTF, which defines its own node hierarchy and coordinate system. tile.transform is applied after these transforms are resolved. See glTF transforms.

• i3dm ‘s Feature Table defines per-instance position, normals, and scales. These are used to create per-instance 4×4 affine transform matrices that are applied to each instance before tile.transform.

• Compressed attributes, such as POSITION_QUANTIZED in the Feature Tables for i3dm and pnts, and NORMAL_OCT16P in pnts should be decompressed before any other transforms.

Therefore, the full computed transforms for the above example are:

• TO: [T0]

• T1: [T0][T1]

• T2: [T0][T2][pnts-specific transform, including RTC_CENTER (if defined)]

• T3: [T0][T1][T3][b3dm-specific transform, including RTC_CENTER (if defined), coordinate system transform, and glTF node hierarchy]

• T4: [T0][T1][T4][i3dm-specific transform, including per-instance transform, coordinate system transform, and glTF node hierarchy]

6.7.5.2.4.  Implementation example

This section is non-normative

The following JavaScript code shows how to compute this using Cesium’s Matrix4 and Matrix3 types.

function computeTransforms(tileset) {
    var t = tileset.root;
    var transformToRoot =defined(t.transform) ?Matrix4.fromArray(t.transform) : Matrix4.IDENTITY;

    computeTransform(t, transformToRoot);
}

function computeTransform(tile, transformToRoot) {
    // Apply 4x4 transformToRoot to this tile's positions and bounding volumes

    var inverseTransform =Matrix4.inverse(transformToRoot,*new*Matrix4());
    var normalTransform =Matrix4.getRotation(inverseTransform,*new*Matrix3());
    normalTransform =Matrix3.transpose(normalTransform, normalTransform);
    // Apply 3x3 normalTransform to this tile's normals_

    var children =tile.children;
    var length =children.length;
    for (var i =0; i < length; ++i) {
        var child = children[i];
        var childToRoot =defined(child.transform) ?Matrix4.fromArray(child.transform) : Matrix4.clone(Matrix4.IDENTITY);
        childToRoot =Matrix4.multiplyTransformation(transformToRoot, childToRoot, childToRoot);
        computeTransform(child, childToRoot);
    }
}

6.7.6.  Tile JSON

A tile JSON object consists of the following properties.

Figure 13 — Tile JSON properties

The following example shows one non-leaf tile.

{
  "boundingVolume":{
    "region":[
      -1.2419052957251926,
      0.7395016240301894,
      -1.2415404171917719,
      0.7396563300150859,
      0,
      20.4
    ]
  },
  "geometricError":43.88464075650763,
  "refine":"ADD",
  "content":{
    "boundingVolume":{
      "region":[
        -1.2418882438584018,
        0.7395016240301894,
        -1.2415422846940714,
        0.7396461198389616,
        0,
        19.4
      ]
    },
    "uri":"2/0/0.b3dm"
  },
  "children":[*...*]
}

The boundingVolume defines a volume enclosing the tile, and is used to determine which tiles to render at runtime. The above example uses a region volume, but other bounding volumes, such as box or sphere, may be used.

The geometricError property is a nonnegative number that defines the error, in meters, introduced if this tile is rendered and its children are not. At runtime, the geometric error is used to compute Screen-Space Error (SSE), the error measured in pixels. The SSE determines if a tile is sufficiently detailed for the current view or if its children should be considered, see Tiles consist of metadata used to determine if a tile is rendered, a reference to the renderable content, and an array of any children tiles.

Geometric error.

The optional viewerRequestVolume property (not shown above) defines a volume, using the same schema as boundingVolume, which the viewer must be inside of before the tile’s content will be requested and before the tile will be refined based on geometricError. See the Viewer request volume section.

The refine property is a string that is either “REPLACE” for replacement refinement or “ADD” for additive refinement, see Tiles are structured into a tree incorporating Hierarchical Level of Detail (HLOD) so that at runtime a client implementation will need to determine if a tile is sufficiently detailed for rendering and if the content of tiles should be successively refined by children tiles of higher resolution. An implementation will consider a maximum allowed Screen-Space Error (SSE), the error measured in pixels.

A tile’s geometric error defines the selection metric for that tile. Its value is a nonnegative number that specifies the error, in meters, of the tile’s simplified representation of its source geometry. The root tile, being the most simplified version of the source geometry, will have the greatest geometric error. Then each successive level of children will have a lower geometric error than its parent, with leaf tiles having a geometric error of or close to 0.

In a client implementation, geometric error is used with other screen space metrics—e.g., distance from the tile to the camera, screen size, and resolution— to calculate the SSE introduced if this tile is rendered and its children are not. If the introduced SSE exceeds the maximum allowed, then the tile is refined and its children are considered for rendering.

The geometric error is formulated based on a metric like point density, tile size in meters, or another factor specific to that tileset. In general, a higher geometric error means a tile will be refined more aggressively, and children tiles will be loaded and rendered sooner.

Refinement. It is required for the root tile of a tileset; it is optional for all other tiles. A tileset can use any combination of additive and replacement refinement. When the refine property is omitted, it is inherited from the parent tile.

The content property is an object that contains metadata about the tile’s renderable content. content.uri is a uri that points to the tile’s binary content (see Tile format specifications), or another tileset JSON to create a tileset of tileset (see External tilesets).

A file extension is not required for content.uri. A content’s tile format (see Tile format specifications) can be identified by the magic field in its header, or else as an external tileset if the content is JSON.

The content.boundingVolume property defines an optional bounding volume similar to the top-level boundingVolume property. But unlike the top-level boundingVolume property, content.boundingVolume is a tightly fit bounding volume enclosing just the tile’s content. boundingVolume provides spatial coherence and content.boundingVolume enables tight view frustum culling, excluding from rendering any content not in the volume of what is potentially in view. When it is not defined, the tile’s bounding volume is still used for culling (see Grids).

The screenshot below shows the bounding volumes for the root tile for Canary Wharf. boundingVolume, shown in red, encloses the entire area of the tileset; content.boundingVolume shown in blue, encloses just the four features (models) in the root tile.

Figure 14 — A tile bounding volume in red, and a content bounding volume in blue

The optional transform property (not shown above) defines a 4×4 affine transformation matrix that transforms the tile’s content, boundingVolume, and viewerRequestVolume as described in the T section.

The children property is an array of objects that define child tiles. Each child tile’s content is fully enclosed by its parent tile’s boundingVolume and, generally, a geometricError less than its parent tile’s geometricError. For leaf tiles, the length of this array is zero, and children may not be defined.

6.8.1.  External tilesets

To create a tree of trees, a tile’s content.uri can point to an external tileset (the uri of another tileset JSON file). This enables, for example, storing each city in a tileset and then having a global tileset of tilesets.

Figure 15 — A tileset JSON file with external tileset JSON files

When a tile points to an external tileset, the tile:

• Cannot have any children; tile.children must be undefined or an empty array.

• Cannot be used to create cycles, for example, by pointing to the same tileset file containing the tile or by pointing to another tileset file that then points back to the initial file containing the tile.

• Will be transformed by both the tile’s transform and root tile’s transform. For example, in the following tileset referencing an external tileset, the computed transform for T3 is [T0][T1][T2][T3].

Figure 16 — A tileset with transforms referencing an external tileset with transforms

6.8.2.  Bounding volume spatial coherence

As described above, the tree has spatial coherence; each tile has a bounding volume completely enclosing its content, and the content for child tiles are completely inside the parent’s bounding volume. This does not imply that a child’s bounding volume is completely inside its parent’s bounding volume. For example:

6.8.3.  Spatial data structures

3D Tiles incorporates the concept of Hierarchical Level of Detail (HLOD) for optimal rendering of spatial data. A tileset is composed of a tree, defined by root and, recursively, its children tiles, which can be organized by different types of spatial data structures.

A runtime engine is generic and will render any tree defined by a tileset. Any combination of tile formats and refinement approaches can be used, enabling flexibility in supporting heterogeneous datasets, see Refinement.

A tileset may use a 2D spatial tiling scheme similar to raster and vector tiling schemes (like a Web Map Tile Service (WMTS) or XYZ scheme) that serve predefined tiles at several levels of detail (or zoom levels). However since the content of a tileset is often non-uniform or may not easily be organized in only two dimensions, other spatial data structures may be more optimal.

Included below is a brief description of how 3D Tiles can represent various spatial data structures.

6.8.3.1.  Quadtrees

A quadtree is created when each tile has four uniformly subdivided children (e.g., using the center latitude and longitude), similar to typical 2D geospatial tiling schemes. Empty child tiles can be omitted.

3D Tiles enable quadtree variations such as non-uniform subdivision and tight bounding volumes (as opposed to bounding, for example, the full 25% of the parent tile, which is wasteful for sparse datasets).

For example, here is the root tile and its children for Canary Wharf. Note the bottom left, where the bounding volume does not include the water on the left where no buildings will appear:

Figure 17 — A root tile and its four children tiles

3D Tiles also enable other quadtree variations such as loose quadtrees, where child tiles overlap but spatial coherence is still preserved, i.e., a parent tile completely encloses all of its children. This approach can be useful to avoid splitting features, such as 3D models, across tiles.

Below, the green buildings are in the left child and the purple buildings are in the right child. Note that the tiles overlap so the two green and one purple building in the center are not split.

Figure 18 — Two sibling tiles with overlapping bounding volumes

6.8.3.4.  Grids

3D Tiles enables uniform, non-uniform, and overlapping grids by supporting an arbitrary number of child tiles. For example, here is a top-down view of a non-uniform overlapping grid of Cambridge:

Figure 19 — A tileset with an overlapping grid spatial data structure

3D Tiles takes advantage of empty tiles: those tiles that have a bounding volume, but no content. Since a tile’s content property does not need to be defined, empty non-leaf tiles can be used to accelerate non-uniform grids with hierarchical culling. This essentially creates a quadtree or octree without hierarchical levels of detail (HLOD).

6.9.1.  Extensions

Extensions allow the base specification to be extended with new features. The optional extensions dictionary property may be added to any 3D Tiles JSON object, which contains the name of the extensions and the extension specific objects. The following example shows a tile object with a hypothetical vendor extension which specifies a separate collision volume.

{
  “transform”:[
    4.843178171884396,1.2424271388626869,0,0,
    -0.7993325488216595,3.1159251367235608,3.8278032889280675,0,
    0.9511533376784163,-3.7077466670407433,3.2168186118075526,0,
    1215001.7612985559,-4736269.697480114,4081650.708604793,1
  ],
  “boundingVolume”:{
    “box”:[
      0,0,6.701,
      3.738,0,0,
      0,3.72,0,
      0,0,13.402
    ]
  },
  “geometricError”:32,
  “content”:{
    “uri”:”building.b3dm”
  },
  “extensions”:{
    “VENDOR_collision_volume”:{
      “box”:[
        0,0,6.8,
        3.8,0,0,
        0,3.8,0,
        0,0,13.5
      ]
    }
  }
}

All extensions used in a tileset or any descendant external tilesets must be listed in the entry tileset JSON in the top-level extensionsUsed array property, e.g.,

{
  “extensionsUsed”:[
    “VENDOR_collision_volume”
  ]
}

All extensions required to load and render a tileset or any descendant external tilesets must also be listed in the entry tileset JSON in the top-level extensionsRequired array property, such that extensionsRequired is a subset of extensionsUsed. All values in extensionsRequired must also exist in extensionsUsed.

6.9.2.  Extras

The extras property allows application specific metadata to be added to any 3D Tiles JSON object. The following example shows a tile object with an additional application specific name property.

{
  "transform":[
    4.843178171884396,1.2424271388626869,0,0,
    -0.7993325488216595,3.1159251367235608,3.8278032889280675,0,
    0.9511533376784163,-3.7077466670407433,3.2168186118075526,0,
    1215001.7612985559,-4736269.697480114,4081650.708604793,1
  ],
  "boundingVolume":{
    "box":[
      0,0,6.701,
      3.738,0,0,
      0,3.72,0,
      0,0,13.402
    ]
  },
  "geometricError":32,
  "content":{
    "uri":"building.b3dm"
  },
  "extras":{
    "name":"Empire State Building"
  }
}

7.1.1.  Tileset.asset

Metadata about the entire tileset.

• Type: object

• Required: Yes

7.1.2.  Tileset.properties

A dictionary object of metadata about per-feature properties.

• Type: any

• Required: No

• Type of each property: object

7.1.3.  Tileset.geometricError

The error, in meters, introduced if this tileset is not rendered. At runtime, the geometric error is used to compute screen space error (SSE), i.e., the error measured in pixels.

• Type: number

• Required: Yes

• Minimum: >= 0

7.1.4.  Tileset.root

A tile in a 3D Tiles tileset.

• Type: object

• Required: Yes

7.1.5.  Tileset.extensionsUsed

Names of 3D Tiles extensions used somewhere in this tileset.

• Type: string[1-*]

• Each element in the array must be unique.

• Required: No

7.1.6.  Tileset.extensionsRequired

Names of 3D Tiles extensions required to properly load this tileset.

• Type: string[1-*]

• Each element in the array must be unique.

• Required: No

7.1.7.  Tileset.extensions

Dictionary object with extension-specific objects.

• Type: object

• Required: No

• Type of each property: Extension

7.1.8.  Tileset.extras

Application-specific data.

• Type: any

• Required: No

7.2.1.  Asset.version

The 3D Tiles version. The version defines the JSON schema for the tileset JSON and the base set of tile formats.

• Type: string

• Required: Yes

7.2.2.  Asset.tilesetVersion

Application-specific version of this tileset, e.g., for when an existing tileset is updated.

• Type: string

• Required: No

7.2.3.  Asset.extensions

Dictionary object with extension-specific objects.

• Type: object

• Required: No

• Type of each property: Extension

7.2.4.  Asset.extras

Application-specific data.

• Type: any

• Required: No

7.3.1.  BoundingVolume.box

An array of 12 numbers that define an oriented bounding box. The first three elements define the x, y, and z values for the center of the box. The next three elements (with indices 3, 4, and 5) define the x axis direction and half-length. The next three elements (indices 6, 7, and 8) define the y axis direction and half-length. The last three elements (indices 9, 10, and 11) define the z axis direction and half-length.

• Type: number[12]

• Required: No

7.3.2.  BoundingVolume.region

An array of six numbers that define a bounding geographic region in EPSG:4979 coordinates with the order [west, south, east, north, minimum height, maximum height]. Longitudes and latitudes are in radians, and heights are in meters above (or below) the WGS84 ellipsoid.

• Type: number[6]

• Required: No

7.3.3.  BoundingVolume.sphere

An array of four numbers that define a bounding sphere. The first three elements define the x, y, and z values for the center of the sphere. The last element (with index 3) defines the radius in meters.

• Type: number[4]

• Required: No

7.3.4.  BoundingVolume.extensions

Dictionary object with extension-specific objects.

• Type: object

• Required: No

• Type of each property: Extension

7.3.5.  BoundingVolume.extras

Application-specific data.

• Type: any

• Required: No

7.6.1.  Properties.maximum

The maximum value of this property of all the features in the tileset.

• Type: number

• Required: Yes

7.6.2.  Properties.minimum

The minimum value of this property of all the features in the tileset.

• Type: number

• Required: Yes

7.6.3.  Properties.extensions

Dictionary object with extension-specific objects.

• Type: object

• Required: No

• Type of each property: Extension

7.6.4.  Properties.extras

Application-specific data.

• Type: any

• Required: No

7.7.1.  Tile.boundingVolume

A bounding volume that encloses a tile or its content. Exactly one box, region, or sphere property is required.

• Type: object

• Required: Yes

7.7.2.  Tile.viewerRequestVolume

A bounding volume that encloses a tile or its content. Exactly one box, region, or sphere property is required.

• Type: object

• Required: No

7.7.3.  Tile.geometricError

The error, in meters, introduced if this tile is rendered and its children are not. At runtime, the geometric error is used to compute screen space error (SSE), i.e., the error measured in pixels.

• Type: number

• Required: Yes

• Minimum: >= 0

7.7.4.  Tile.refine

Specifies if additive or replacement refinement is used when traversing the tileset for rendering. This property is required for the root tile of a tileset; it is optional for all other tiles. The default is to inherit from the parent tile.

• Type: string

• Required: No

• Allowed values:

  • "ADD"

  • "REPLACE"

7.7.5.  Tile.transform

A floating-point 4×4 affine transformation matrix, stored in column-major order, that transforms the tile’s content—​i.e., its features as well as content.boundingVolume, boundingVolume, and viewerRequestVolume—​from the tile’s local coordinate system to the parent tile’s coordinate system, or, in the case of a root tile, from the tile’s local coordinate system to the tileset’s coordinate system. transform does not apply to geometricError, nor does it apply any volume property when the volume is a region, defined in EPSG:4979 coordinates.

• Type: number[16]

• Required: No, default: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]

7.7.6.  Tile.content

Metadata about the tile’s content and a link to the content.

• Type: object

• Required: No

7.7.7.  Tile.children

An array of objects that define child tiles. Each child tile content is fully enclosed by its parent tile’s bounding volume and, generally, has a geometricError less than its parent tile’s geometricError. For leaf tiles, the length of this array is zero, and children may not be defined.

• Type: array[]

  • Each element in the array must be unique.

• Required: No

7.7.8.  Tile.extensions

Dictionary object with extension-specific objects.

• Type: object

• Required: No

• Type of each property: Extension

7.7.9.  Tile.extras

Application-specific data.

• Type: any

• Required: No

7.8.1.  TileContent.boundingVolume

A bounding volume that encloses a tile or its content. Exactly one box, region, or sphere property is required.

• Type: object

• Required: No

7.8.2.  TileContent.uri

A uri that points to the tile’s content. When the uri is relative, it is relative to the referring tileset JSON file.

• Type: string

• Required: Yes

7.8.3.  TileContent.extensions

Dictionary object with extension-specific objects.

• Type: object

• Required: No

• Type of each property: Extension

7.8.4.  TileContent.extras

Application-specific data.

• Type: any

• Required: No

8.2.1.  Padding

The JSON header must end on an 8-byte boundary within the containing tile binary. The JSON header must be padded with trailing Space characters (0×20) to satisfy this requirement.

The binary body must start and end on an 8-byte boundary within the containing tile binary. The binary body must be padded with additional bytes, of any value, to satisfy this requirement.

Binary properties must start at a byte offset that is a multiple of the size in bytes of the property’s implicit component type. For example, a property with the implicit component type FLOAT has 4 bytes per element, and therefore must start at an offset that is a multiple of 4. Preceding binary properties must be padded with additional bytes, of any value, to satisfy this requirement.

8.2.2.  JSON header

Feature Table values can be represented in the JSON header in three different ways:

1. A single value or object, e.g., "INSTANCES_LENGTH" : 4.

   • This is used for global semantics like "INSTANCES_LENGTH", which defines the number of model instances in an Instanced 3D Model tile.

2. An array of values, e.g., "POSITION" : [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0].

   • This is used for per-feature semantics like “POSITION” in Instanced 3D Model. Above, each POSITION refers to a float32[3] data type so there are three features: Feature 0’s position=(1.0, 0.0, 0.0), Feature 1’s position=(0.0, 1.0, 0.0), Feature 2’s position=(0.0, 0.0, 1.0).

3. A reference to data in the binary body, denoted by an object with a byteOffset property, e.g., “SCALE” : { “byteOffset” : 24}.

   • byteOffset specifies a zero-based offset relative to the start of the binary body. The value of byteOffset must be a multiple of the size in bytes of the property’s implicit component type, e.g., the “POSITION” property has the component type FLOAT (4 bytes), so the value of byteOffset must be of a multiple of 4.

   • The semantic defines the allowed data type, e.g., when “POSITION” in Instanced 3D Model refers to the binary body, the component type is FLOAT and the number of components is 3.

   • Some semantics allow for overriding the implicit component type. These cases are specified in each tile format, e.g., "BATCH_ID" : { "byteOffset" : 24, "componentType" : "UNSIGNED_BYTE"}.
     The only valid properties in the JSON header are the defined semantics by the tile format and optional extras and extensions properties. Application-specific data should be stored in the Batch Table.

8.2.3.  Binary body

When the JSON header includes a reference to the binary, the provided byteOffset is used to index into the data. The following figure shows indexing into the Feature Table binary body:

Figure 21 — Feature Table binary body layout

Values can be retrieved using the number of features, featuresLength; the desired feature id, featureId; and the data type (component type and number of components) for the feature semantic.

8.4.1.  Feature Table

A set of semantics containing per-tile and per-feature values defining the position and appearance properties for features in a tile.

Properties

Additional properties are allowed.

• Type of each property: Property

8.4.2.  BinaryBodyReference

An object defining the reference to a section of the binary body of the features table where the property values are stored if not defined directly in the JSON.

Properties

Additional properties are allowed.

8.4.3.  Property

A user-defined property which specifies per-feature application-specific metadata in a tile. Values either can be defined directly in the JSON as an array, or can refer to sections in the binary body with a BinaryBodyReference object.

9.2.1.  Padding

The JSON header must end on an 8-byte boundary within the containing tile binary. The JSON header must be padded with trailing Space characters (0×20) to satisfy this requirement.

The binary body must start and end on an 8-byte boundary within the containing tile binary. The binary body must be padded with additional bytes, of any value, to satisfy this requirement.

Binary properties must start at a byte offset that is a multiple of the size in bytes of the property’s componentType. For example, a property with the component type FLOAT has 4 bytes per element, and therefore must start at an offset that is a multiple of 4. Preceding binary properties must be padded with additional bytes, of any value, to satisfy this requirement.

9.2.2.  JSON header

Batch Table values can be represented in the JSON header in two different ways:

1. An array of values, e.g., “name”: [‘name1’, ‘name2’, ‘name3’] or “height” : [10.0, 20.0, 15.0].

   • Array elements can be any valid JSON data type, including objects and arrays. Elements may be null.

   • The length of each array is equal to batchLength, which is specified in each tile format. This is the number of features in the tile. For example, batchLength may be the number of models in a b3dm tile, the number of instances in a i3dm tile, or the number of points (or number of objects) in a pnts tile.

2. A reference to data in the binary body, denoted by an object with byteOffset, componentType, and type properties, e.g., “height” : { “byteOffset” : 24, “componentType” : “FLOAT”, “type” : “SCALAR”}.

   • byteOffset specifies a zero-based offset relative to the start of the binary body. The value of byteOffset must be a multiple of the size in bytes of the property’s componentType, e.g., a property with the component type FLOAT must have a byteOffset value that is a multiple of 4.

   • componentType is the datatype of components in the attribute. Allowed values are “BYTE”, “UNSIGNED_BYTE”, “SHORT”, “UNSIGNED_SHORT”, “INT”, “UNSIGNED_INT”, “FLOAT”, and “DOUBLE”.

   • type specifies if the property is a scalar or vector. Allowed values are “SCALAR”, “VEC2”, “VEC3”, and “VEC4”.

The Batch Table JSON is a UTF-8 string containing JSON.

Implementation Note: In JavaScript, the Batch Table JSON can be extracted from an ArrayBuffer using the TextDecoder JavaScript API and transformed to a JavaScript object with JSON.parse.

A batchId is used to access elements in each array and extract the corresponding properties. For example, the following Batch Table has properties for a batch of two features:

{
  “id” : [“unique id”, “another unique id”],
  “displayName” : [“Building name”, “Another building name”],
  “yearBuilt” : [1999, 2015],
  “address” : [{”street” : “Main Street”, “houseNumber” : “1”},{”street” : “Main Street”, “houseNumber” : “2”}]
}

The properties for the feature with batchId = 0 are

id[0] = ‘unique id’;
displayName[0] = ‘Building name’;
yearBuilt[0] = 1999;
address[0] = {street : ‘Main Street’, houseNumber : ‘1’};

The properties for batchId = 1 are

id[1] = ‘another unique id’;
displayName[1] = ‘Another building name’;
yearBuilt[1] = 2015;
address[1] = {street : ‘Main Street’, houseNumber : ‘2’};

9.2.3.  Binary body

When the JSON header includes a reference to the binary section, the provided byteOffset is used to index into the data, as shown in the following figure:

Figure 23 — Batch Table binary body layout

Values can be retrieved using the number of features, batchLength; the desired batch id, batchId; and the componentType and type defined in the JSON header.

The following tables can be used to compute the byte size of a property.

9.4.1.  Batch Table

A set of properties defining application-specific metadata for features in a tile.

Properties

Additional properties are allowed.

• Type of each property: Property

9.4.2.  BinaryBodyReference

An object defining the reference to a section of the binary body of the batch table where the property values are stored if not defined directly in the JSON.

Properties

Additional properties are allowed.

9.4.3.  Property

A user-defined property which specifies per-feature application-specific metadata in a tile. Values either can be defined directly in the JSON as an array, or can refer to sections in the binary body with a BinaryBodyReference object.

10.1.1.  Overview

Batched 3D Model allows offline batching of heterogeneous 3D models, such as different buildings in a city, for efficient streaming to a web client for rendering and interaction. Efficiency comes from transferring multiple models in a single request and rendering them in the least number of WebGL draw calls necessary. Using the core 3D Tiles spec language, each model is a feature.

Per-model properties, such as IDs, enable individual models to be identified and updated at runtime, e.g., show/hide, highlight color, etc. Properties may be used, for example, to query a web service to access metadata, such as passing a building’s ID to get its address. Or a property might be referenced on the fly for changing a model’s appearance, e.g., changing highlight color based on a property value.

A Batched 3D Model tile is a binary blob in little endian.

10.1.2.  Layout

A tile is composed of two sections: a header immediately followed by a body. The following figure shows the Batched 3D Model layout (dashes indicate optional fields):

Figure 24 — Batched 3D Model layout

10.1.3.  Header

The 28-byte header contains the following fields:

The body section immediately follows the header section, and is composed of three fields: Feature Table, Batch Table, and Binary glTF.

10.1.4.  Feature Table

Contains values for b3dm semantics.

More information is available in the Feature Table specification.

10.1.5.  Batch Table

The Batch Table contains per-model application-specific metadata, indexable by batchId, that can be used for declarative styling and application-specific use cases such as populating a UI or issuing a REST API request. In the binary glTF section, each vertex has an numeric batchId attribute in the integer range [0, number of models in the batch — 1]. The batchId indicates the model to which the vertex belongs. This allows models to be batched together and still be identifiable.

See the Batch Table reference for more information.

10.1.6.  Binary glTF

Batched 3D Model embeds glTF 2.0 containing model geometry and texture information.

The binary glTF immediately follows the Feature Table and Batch Table. It may embed all of its geometry, texture, and animations, or it may refer to external sources for some or all of these data.

As described above, each vertex has a batchId attribute indicating the model to which it belongs. For example, vertices for a batch with three models may look like this:

batchId: [0, 0, 0, …​, 1, 1, 1, …​, 2, 2, 2, …​]
position: [xyz, xyz, xyz, …​, xyz, xyz, xyz, …​, xyz, xyz, xyz, …​]
normal: [xyz, xyz, xyz, …​, xyz, xyz, xyz, …​, xyz, xyz, xyz, …​]

Vertices do not need to be ordered by batchId, so the following is also OK:

batchId: [0, 1, 2, …​, 2, 1, 0, …​, 1, 2, 0, …​]
position: [xyz, xyz, xyz, …​, xyz, xyz, xyz, …​, xyz, xyz, xyz, …​]
normal: [xyz, xyz, xyz, …​, xyz, xyz, xyz, …​, xyz, xyz, xyz, …​]

Note that a vertex can’t belong to more than one model; in that case, the vertex needs to be duplicated so the batchIds can be assigned.

The batchId parameter is specified in a glTF mesh primitive by providing the _BATCHID attribute semantic, along with the index of the batchId accessor.For example,

"primitives": [
  {
    "attributes":{
      "_BATCHID":0
    }
  }
]

{
  "accessors":[
    {
      "bufferView":1,
      "byteOffset":0,
      "componentType":5125,
      "count":4860,
      "max":[2],
      "min":[0],
      "type":"SCALAR"
    }
  ]
}

The accessor.type must be a value of “SCALAR”. All other properties must conform to the glTF schema, but have no additional requirements.

When a Batch Table is present or the BATCH_LENGTH property is greater than 0, the _BATCHID attribute is required; otherwise, it is not.

10.1.7.  File extension and MIME type

Batched 3D Model tiles use the .b3dm extension and application/octet-stream MIME type.

An explicit file extension is optional. Valid implementations may ignore it and identify a content’s format by the magic field in its header.

10.1.8.  Implementation example

This section is non-normative

Code for reading the header can be found in Batched3DModelTileContent.js in the Cesium implementation of 3D Tiles.

10.2.1.  Overview

Instanced 3D Model is a tile format for efficient streaming and rendering of a large number of models, called instances, with slight variations. In the simplest case, the same tree model, for example, may be located—or instanced—in several places. Each instance references the same model and has per-instance properties, such as position. Using the core 3D Tiles spec language, each instance is a feature.

In addition to trees, Instanced 3D Model is useful for exterior features such as fire hydrants, sewer caps, lamps, and traffic lights, and for interior CAD features such as bolts, valves, and electrical outlets.

An Instanced 3D Model tile is a binary blob in little endian.

Implementation Note: A Composite tile can be used to create tiles with different types of instanced models, e.g., trees and traffic lights by combing two Instanced 3D Model tiles.

Implementation Note: Instanced 3D Model maps well to the ANGLE_instanced_arrays extension for efficient rendering with WebGL.

10.2.2.  Layout

A tile is composed of a header section immediately followed by a binary body. The following figure shows the Instanced 3D Model layout (dashes indicate optional fields):

Figure 25 — Instanced 3D Model layout

10.2.3.  Header

The 32-byte header contains the following fields:

The body section immediately follows the header section and is composed of three fields: Feature Table, Batch Table, and glTF.

10.2.4.  Feature Table

The Feature Table contains values for i3dm semantics used to create instanced models. More information is available in the Feature Table specification.

10.2.4.2.  Instance orientation

An instance’s orientation is defined by an orthonormal basis created by an up and right vector. The orientation will be transformed by the Tile transform.

The x vector in the standard basis maps to the right vector in the transformed basis, and the y vector maps to the up vector.
The z vector would map to a forward vector, but it is omitted because it will always be the cross product of right and up.

Figure 26 — A box in the standard basis

Figure 27 — A box transformed into a rotated basis

10.2.4.2.1.  Oct-encoded normal vectors

If NORMAL_UP and NORMAL_RIGHT are not defined for an instance, its orientation may be stored as oct-encoded normals in NORMAL_UP_OCT32P and NORMAL_RIGHT_OCT32P.
These define up and right using the oct-encoding described in A Survey of Efficient Representations of Independent Unit Vectors. Oct-encoded values are stored in unsigned, unnormalized range ([0, 65535]) and then mapped to a signed normalized range ([-1.0, 1.0]) at runtime.

An implementation for encoding and decoding these unit vectors can be found in Cesium’s AttributeCompression module.

10.2.4.2.2.  Default orientation

If NORMAL_UP and NORMAL_RIGHT or NORMAL_UP_OCT32P and NORMAL_RIGHT_OCT32P are not present, the instance will not have a custom orientation. If EAST_NORTH_UP is true, the instance is assumed to be on the WGS84 ellipsoid and its orientation will default to the east/north/up reference frame at its cartographic position.
This is suitable for instanced models such as trees whose orientation is always facing up from their position on the ellipsoid’s surface.

10.2.4.3.  Instance position

POSITION defines the location for an instance before any tile transforms are applied.

10.2.4.3.1.  RTC_CENTER

Positions may be defined relative-to-center for high-precision rendering, see Precisions, Precisions. If defined, RTC_CENTER specifies the center position and all instance positions are treated as relative to this value.

10.2.4.3.2.  Quantized positions

If POSITION is not defined for an instance, its position may be stored in POSITION_QUANTIZED, which defines the instance position relative to the quantized volume.
If neither POSITION or POSITION_QUANTIZED are defined, the instance will not be created.

A quantized volume is defined by offset and scale to map quantized positions into local space, as shown in the following figure:

Figure 28 — A quantized volume

offset is stored in the global semantic QUANTIZED_VOLUME_OFFSET, and scale is stored in the global semantic QUANTIZED_VOLUME_SCALE.
If those global semantics are not defined, POSITION_QUANTIZED cannot be used.

Quantized positions can be mapped to local space using the following formula:

POSITION = POSITION_QUANTIZED * QUANTIZED_VOLUME_SCALE / 65535.0 + QUANTIZED_VOLUME_OFFSET

var featureTableJSON = {
  INSTANCES_LENGTH :4,
  POSITION :{
    byteOffset :0
  }
};

var featureTableBinary = new Buffer(new Float32Array([
  0.0,0.0,0.0,
  1.0,0.0,0.0,
  0.0,0.0,1.0,
  1.0,0.0,1.0
]).buffer);

var featureTableJSON = {
  INSTANCES_LENGTH : 4,
  QUANTIZED_VOLUME_OFFSET : [-250.0,0.0,-250.0],
  QUANTIZED_VOLUME_SCALE : [500.0,0.0,500.0],
  POSITION_QUANTIZED : {
    byteOffset : 0
  },
  NORMAL_UP_OCT32P : {
    byteOffset : 24
  },
  NORMAL_RIGHT_OCT32P : {
    byteOffset : 40
  }
};

var positionQuantizedBinary = new Buffer(new Uint16Array([
  0,0,0,
  65535,0,0,
  0,0,65535,
  65535,0,65535
]).buffer);

var normalUpOct32PBinary = new Buffer(new Uint16Array([
  32768,65535,
  32768,65535,
  32768,65535,
  32768,65535
]).buffer);

var normalRightOct32PBinary = new Buffer(new Uint16Array([
  65535,32768,
  65535,32768,
  65535,32768,
  65535,32768
]).buffer);

var featureTableBinary = Buffer.concat([positionQuantizedBinary, normalUpOct32PBinary, normalRightOct32PBinary]);

10.2.5.  Batch Table

Contains metadata organized by batchId that can be used for declarative styling. See the Batch Table reference for more information.

10.2.6.  glTF

Instanced 3D Model embeds glTF 2.0 containing model geometry and texture information.

The glTF asset to be instanced is stored after the Feature Table and Batch Table. It may embed all of its geometry, texture, and animations, or it may refer to external sources for some or all of these data.

header.gltfFormat determines the format of the glTF field

• When the value of header.gltfFormat is 0, the glTF field is a UTF-8 string, which contains a uri of the glTF or binary glTF model content.

• When the value of header.gltfFormat is 1, the glTF field is a binary blob containing binary glTF.

In either case, header.gltfByteLength contains the length of the glTF field in bytes.

10.2.7.  File extension and MIME type

Instanced 3D models tiles use the .i3dm extension and application/octet-stream MIME type.

An explicit file extension is optional. Valid implementations may ignore it and identify a content’s format by the magic field in its header.

10.2.8.  Property reference

10.3.1.  Overview

The Point Cloud tile format enables efficient streaming of massive point clouds for 3D visualization. Each point is defined by a position and by optional properties used to define its appearance, such as color and normal, as well as optional properties that define application-specific metadata.

Using 3D Tiles terminology, each point is a feature.

A Point Cloud tile is a binary blob in little endian.

10.3.2.  Layout

A tile is composed of a header section immediately followed by a body section. The following figure shows the Point Cloud layout (dashes indicate optional fields):

Figure 29 — Point Cloud layout

10.3.3.  Header

The 28-byte header contains the following fields:

The body section immediately follows the header section, and is composed of a Feature Table and Batch Table.

10.3.4.  Feature Table

Contains per-tile and per-point values that define where and how to render points.
More information is available in the Feature Table specification.

10.3.4.2.  Point positions

POSITION defines the position for a point before any tileset transforms are applied.

10.3.4.2.1.  Coordinate reference system (CRS)

3D Tiles local coordinate systems use a right-handed 3-axis $\left(x,y,z\right)$ Cartesian coordinate system; that is, the cross product of $x$ and $y$ yields $z$. 3D Tiles defines the $z$ axis as up for local Cartesian coordinate systems (also see coordinate reference system).

10.3.4.2.2.  RTC_CENTER

Positions may be defined relative-to-center for high-precision rendering, see Precisions, Precisions. If defined, RTC_CENTER specifies the center position and all point positions are treated as relative to this value.

10.3.4.2.3.  Quantized positions

If POSITION is not defined, positions may be stored in POSITION_QUANTIZED, which defines point positions relative to the quantized volume.
If neither POSITION nor POSITION_QUANTIZED is defined, the tile does not need to be rendered.

A quantized volume is defined by offset and scale to map quantized positions to a position in local space. The following figure shows a quantized volume based on offset and scale:

Figure 30 — A quantized volume

offset is stored in the global semantic QUANTIZED_VOLUME_OFFSET, and scale is stored in the global semantic QUANTIZED_VOLUME_SCALE.
If those global semantics are not defined, POSITION_QUANTIZED cannot be used.

Quantized positions can be mapped to local space using the following formula:

POSITION = POSITION_QUANTIZED * QUANTIZED_VOLUME_SCALE / 65535.0 + QUANTIZED_VOLUME_OFFSET

var featureTableJSON = {
  POINTS_LENGTH : 4,
  POSITION : {
    byteOffset : 0
  }
};

var featureTableBinary = new Buffer(new Float32Array([
  0.0,0.0,0.0,
  1.0,0.0,0.0,
  0.0,0.0,1.0,
  1.0,0.0,1.0
]).buffer);

var featureTableJSON = {
  POINTS_LENGTH : 4,
  RTC_CENTER : [1215013.8,-4736316.7,4081608.4],
  POSITION : {
    byteOffset : 0
  },
  RGB : {
    byteOffset : 48
  }
};

var positionBinary = new Buffer(new Float32Array([
  0.0,0.0,0.0,
  1.0,0.0,0.0,
  0.0,0.0,1.0,
  1.0,0.0,1.0
]).buffer);

var colorBinary = new Buffer(new Uint8Array([
  255,0,0,
  0,255,0,
  0,0,255,
  255,255,0,
]).buffer);

var featureTableBinary =Buffer.concat([positionBinary, colorBinary]);

var featureTableJSON = {
  POINTS_LENGTH : 4,
  QUANTIZED_VOLUME_OFFSET : [-250.0,0.0,-250.0],
  QUANTIZED_VOLUME_SCALE : [500.0,0.0,500.0],
  POSITION_QUANTIZED : {
    byteOffset : 0
  },
  NORMAL_OCT16P : {
    byteOffset : 24
  }
};

var positionQuantizedBinary = new Buffer(new Uint16Array([
  0,0,0,
  65535,0,0,
  0,0,65535,
  65535,0,65535
]).buffer);

var normalOct16PBinary = new Buffer(new Uint8Array([
  128,255,
  128,255,
  128,255,
  128,255
]).buffer);

var featureTableBinary = Buffer.concat([positionQuantizedBinary, normalOct16PBinary]);

var featureTableJSON = {
  POINTS_LENGTH : 4,
  BATCH_LENGTH : 2,
  POSITION : {
    byteOffset : 0
  },
  BATCH_ID : {
    byteOffset : 48,
    componentType : "UNSIGNED_BYTE"
  }
};

var positionBinary = new Buffer(new Float32Array([
  0.0,0.0,0.0,
  1.0,0.0,0.0,
  0.0,0.0,1.0,
  1.0,0.0,1.0
]).buffer);

var batchIdBinary = new Buffer(new Uint8Array([
  0,
  0,
  1,
  1
]).buffer);

var featureTableBinary = Buffer.concat([positionBinary, batchIdBinary]);

var batchTableJSON = {
  names : ['object1', 'object2']
};

var featureTableJSON = {
  POINTS_LENGTH : 4,
  POSITION : {
    byteOffset : 0
  }
};

var featureTableBinary = new Buffer(new Float32Array([
  0.0,0.0,0.0,
  1.0,0.0,0.0,
  0.0,0.0,1.0,
  1.0,0.0,1.0
]).buffer);

var batchTableJSON = {
  names : ['point1','point2','point3','point4']
};

10.3.5.  Batch Table

The Batch Table contains application-specific metadata, indexable by batchId, that can be used for declarative styling and application-specific use cases such as populating a UI or issuing a REST API request.

• If the BATCH_ID semantic is defined, the Batch Table stores metadata for each batchId, and the length of the Batch Table arrays will equal BATCH_LENGTH.

• If the BATCH_ID semantic is not defined, then the Batch Table stores per-point metadata, and the length of the Batch Table arrays will equal POINTS_LENGTH.

See the link: ../../../../../ggetz/Documents/_Batch_Table[Batch Table] reference for more information.

10.3.6.  File extension and MIME type

Point cloud tiles use the .pnts extension and application/octet-stream MIME type.

An explicit file extension is optional. Valid implementations may ignore it and identify a content’s format by the magic field in its header.

10.3.7.  Implementation example

This section is non-normative

Code for reading the header can be found in PointCloud3DModelTileContent.js in the Cesium implementation of 3D Tiles.

10.3.8.  Property reference

10.4.1.  Overview

The Composite tile format enables concatenating tiles of different formats into one tile.

3D Tiles and the Composite tile allow flexibility for streaming heterogeneous datasets. For example, buildings and trees could be stored either in two separate Batched 3D Model and Instanced 3D Model tiles or, using a Composite tile, the tiles can be combined.

Supporting heterogeneous datasets with both inter-tile (separate tiles of different formats that are in the same tileset) and intra-tile (different tile formats that are in the same Composite tile) options allows conversion tools to make trade-offs between number of requests, optimal type-specific subdivision, and how visible/hidden layers are streamed.

A Composite tile is a binary blob in little endian.

10.4.2.  Layout

Composite layout (dashes indicate optional fields):

Figure 31 — Composite layout

10.4.3.  Header

The 16-byte header section contains the following fields:

10.4.4.  Inner tiles

Inner tile fields are stored tightly packed immediately following the header section. The following information describes general characteristics of all tile formats that a Composite tile reader might exploit to find the boundaries of the inner tiles:

• Each tile starts with a 4-byte ANSI string, magic, that can be used to determine the tile format for further parsing. See tile format specifications for a list of possible formats. Composite tiles can contain Composite tiles.

• Each tile’s header contains a uint32 byteLength, which defines the length of the inner tile, including its header, in bytes. This can be used to traverse the inner tiles.

• For any tile format’s version 1, the first 12 bytes of all tiles is the following fields:

Refer to the spec for each tile format for more details.

10.4.5.  File extension and MIME type

Composite tiles use the .cmpt extension and application/octet-stream MIME type.

An explicit file extension is optional. Valid implementations may ignore it and identify a content’s format by the magic field in its header.

10.4.6.  Implementation examples

This section is non-normative

• Python packcmpt tool in gltf2glb toolset contains code for combining one or more Batched 3D Model or Instanced 3D Model tiles into a single Composite tile file.

• Code for reading the header can be found in Composite3DTileContent.js in the Cesium implementation of 3D Tiles.

11.2.1.  Styling features

Visual properties available for styling features are the show property, the assigned expression of which will evaluate to a boolean that determines if the feature is visible, and the color property, the assigned expression of which will evaluate to a Color object (RGB and translucency) which determines the displayed color of a feature.

The following style assigns the default show and color properties to each feature:

{
  “show” : “true”,
  “color” : “color(‘#ffffff’)”
}

Instead of showing all features, show can be an expression dependent on a feature’s properties, for example, the following expression will show only features in the 19341 zip code:

{
  “show” : “${ZipCode} === ‘19341’”
}

show can also be used for more complex queries; for example, here a compound condition and regular expression are used to show only features whose county starts with 'Chest' and whose year built is greater than or equal to 1970:

{
  “show” : “(regExp(‘^Chest’).test(${County})) && (${YearBuilt} >= 1970)”
}

Colors can also be defined by expressions dependent on a feature’s properties. For example, the following expression colors features with a temperature above 90 as red and the others as white:

{
  “color” : “(${Temperature} > 90) ? color(‘red’) : color(‘white’)”
}

The color’s alpha component defines the feature’s opacity. For example, the following sets the feature’s RGB color components from the feature’s properties and makes features with volume greater than 100 transparent:

{
  “color” : “rgba(${red}, ${green}, ${blue}, (${volume} > 100 ? 0.5 : 1.0))”
}

11.2.2.  Conditions

In addition to a string containing an expression, color and show can be an array defining a series of conditions (similar to if…​else statements). Conditions can, for example, be used to make color maps and color ramps with any type of inclusive/exclusive intervals.

For example, the following expression maps an ID property to colors. Conditions are evaluated in order, so if ${id} is not ‘1’ or ‘2’, the “true” condition returns white. If no conditions are met, the color of the feature will be undefined:

{
  “color” : {
    “conditions” : [
      [“${id} === ‘1’”,”color(‘#FF0000’)”],
      [“${id} === ‘2’”,”color(‘#00FF00’)”],
      [“true”,”color(‘#FFFFFF’)”]
    ]
  }
}

The next example shows how to use conditions to create a color ramp using intervals with an inclusive lower bound and exclusive upper bound:

“color” : {
  “conditions” : [
    [“(${Height} >= 1.0) && (${Height} < 10.0)”,”color(‘#FF00FF’)”],
    [“(${Height} >= 10.0) && (${Height} < 30.0)”,”color(‘#FF0000’)”],
    [“(${Height} >= 30.0) && (${Height} < 50.0)”,”color(‘#FFFF00’)”],
    [“(${Height} >= 50.0) && (${Height} < 70.0)”,”color(‘#00FF00’)”],
    [“(${Height} >= 70.0) && (${Height} < 100.0)”,”color(‘#00FFFF’)”],
    [“(${Height} >= 100.0)”,”color(‘#0000FF’)”]
  ]
}

Since conditions are evaluated in order, the above can be written more concisely as the following:

“color”: {
  “conditions”: [
    [“(${Height} >= 100.0)”,”color(‘#0000FF’)”],
    [“(${Height} >= 70.0)”,”color(‘#00FFFF’)”],
    [“(${Height} >= 50.0)”,”color(‘#00FF00’)”],
    [“(${Height} >= 30.0)”,”color(‘#FFFF00’)”],
    [“(${Height} >= 10.0)”,”color(‘#FF0000’)”],
    [“(${Height} >= 1.0)”,”color(‘#FF00FF’)”]
  ]
}

11.2.3.  Defining variables

Commonly used expressions may be stored in a defines object with a variable name as a key. If a variable references the name of a defined expression, it is replaced with the result of the referenced evaluated expression:

{
  “defines” : {
    “NewHeight” : “clamp((${Height} — 0.5) / 2.0, 1.0, 255.0)”,
    “HeightColor” : “rgb(${Height}, ${Height}, ${Height})”
  },
  “color” : {
    “conditions” : [
      [“(${NewHeight} >= 100.0)”,”color(‘#0000FF’) * ${HeightColor}”],
      [“(${NewHeight} >= 50.0)”,”color(‘#00FF00’) * ${HeightColor}”],
      [“(${NewHeight} >= 1.0)”,”color(‘#FF0000’) * ${HeightColor}”]
    ]
  },
  “show” : “${NewHeight} < 200.0”
}

A define expression may not reference other defines; however, it may reference feature properties with the same name. In the style below a feature of height 150 gets the color red:

{
  “defines” : {
    “Height” : “${Height}/2.0}”,
  },
  “color” : {
    “conditions” : [
      [“(${Height} >= 100.0)”,”color(‘#0000FF’)”],
      [“(${Height} >= 1.0)”,”color(‘#FF0000’)”]
    ]
  }
}

11.2.4.  Meta property

Non-visual properties of a feature can be defined using the meta property. For example, the following sets a description meta property to a string containing the feature name:

{
  “meta” : {
    “description” : “‘Hello, ${featureName}.’”
  }
}

A meta property expression can evaluate to any type. For example:

{
  “meta” : {
    “featureColor” : “rgb(${red}, ${green}, ${blue})”,
    “featureVolume” : “${height} * ${width} * ${depth}”
  }
}

11.3.1.  Semantics

Dot notation is used to access properties by name, e.g., building.name.

Bracket notation ( [ ] ) is also used to access properties, e.g., building[‘name’], or arrays, e.g., temperatures[1].

Functions are called with parenthesis ( ( ) ) and comma-separated arguments, e.g., (isNaN(0.0), color('cyan', 0.5)).

11.3.2.  Operators

The following operators are supported with the same semantics and precedence as JavaScript.

• Unary: +, -, !

• Not supported: ~

• Binary: ||, &&, ===, !==, <, >, ⇐, >=, +, -, *, /, %, =~, !~

• Not supported: |, ^, &, <<, >>, and >>>

• Ternary: ? :

( and ) are also supported for grouping expressions for clarity and precedence.

Logical || and && implement short-circuiting; true || expression does not evaluate the right expression, and false && expression does not evaluate the right expression.

Similarly, true ? leftExpression : rightExpression only executes the left expression, and false ? leftExpression : rightExpression only executes the right expression.

11.3.3.  Types

The following types are supported:

• Boolean

• Null

• Undefined

• Number

• String

• Array

• vec2

• vec3

• vec4

• RegExp

All of the types except vec2, vec3, vec4, and RegExp have the same syntax and runtime behavior as JavaScript. vec2, vec3, and vec4 are derived from GLSL vectors and behave similarly to JavaScript Object (see the Vector section). Colors derive from CSS3 Colors and are implemented as vec4. RegExp is derived from JavaScript and described in the RegExp section.

Example expressions for different types include the following:

• true, false

• null

• undefined

• 1.0, NaN, Infinity

• 'Cesium', "Cesium"

• [0, 1, 2]

• vec2(1.0, 2.0)

• vec3(1.0, 2.0, 3.0)

• vec4(1.0, 2.0, 3.0, 4.0)

• color('#00FFFF')

• regExp('^Chest'))

{
  “Name” : “Building 1”
}

regExp(‘a’).test(‘abc’) === true
regExp(‘a(.)’, ‘i’).exec(‘Abc’) === ‘b’
regExp(‘Building\s(\d)’).exec(${Name}) === ‘1’

regExp(‘a’) =~ ‘abc’
‘abc’ =~ regExp(‘a’)

regExp(‘a’) !~ ‘bcd’
‘bcd’ !~ regExp(‘a’)

11.3.4.  Operator rules

• Unary operators + and - operate only on number and vector expressions.

• Unary operator ! operates only on boolean expressions.

• Binary operators <, ⇐, >, and >= operate only on number expressions.

• Binary operators || and && operate only on boolean expressions.

• Binary operator + operates on the following expressions:

  • Number expressions

  • Vector expressions of the same type

  • If at least one expressions is a string, the other expression is converted to a string following String Conversions, and the operation returns a concatenated string, e.g. “name” + 10 evaluates to “name10”

• Binary operator - operates on the following expressions:

  • Number expressions

  • Vector expressions of the same type

• Binary operator * operates on the following expressions:

  • Number expressions

  • Vector expressions of the same type

  • Mix of number expression and vector expression, e.g. 3 * vec3(1.0) and vec2(1.0) * 3

• Binary operator / operates on the following expressions:

  • Number expressions

  • Vector expressions of the same type

  • Vector expression followed by number expression, e.g. vec3(1.0) / 3

• Binary operator % operates on the following expressions:

  • Number expressions

  • Vector expressions of the same type

• Binary equality operators === and !== operate on any expressions. The operation returns false if the expression types do not match.

• Binary regExp operators =~ and !~ require one argument to be a string expression and the other to be a RegExp expression.

• Ternary operator ? : conditional argument must be a boolean expression.

11.3.5.  Type conversions

Explicit conversions between primitive types are handled with Boolean, Number, and String functions.

• Boolean(value : Any) : Boolean

• Number(value : Any) : Number

• String(value : Any) : String

For example:

Boolean(1) === true
Number('1') === 1
String(1) === '1'

Boolean and Number follow JavaScript conventions. String follows String Conversions.

These are essentially casts, not constructor functions.

The styling language does not allow for implicit type conversions, unless stated above. Expressions like vec3(1.0) === vec4(1.0) and “5” < 6 are not valid.

11.3.6.  String conversions

vec2, vec3, vec4, and RegExp expressions are converted to strings using their toString methods. All other types follow JavaScript conventions.

• true - "true"

• false - "false"

• null - "null"

• undefined - "undefined"

• 5.0 - "5"

• NaN - "NaN"

• Infinity - "Infinity"

• "name" - "name"

• [0, 1, 2] - "[0, 1, 2]"

• vec2(1, 2) - "(1, 2)"

• vec3(1, 2, 3) - "(1, 2, 3)"

• vec4(1, 2, 3, 4) - "(1, 2, 3, 4)"

• RegExp('a') - "/a/"

11.3.7.  Constants

The following constants are supported by the styling language:

{
  "show" : "cos(${Angle} + Math.PI) < 0"
}

{
  "color" : "color() * pow(Math.E / 2.0, ${Temperature})"
}

11.3.8.  Variables

Variables are used to retrieve the property values of individual features in a tileset. Variables are identified using the ES 6 ( ECMAScript 2015) template literal syntax, i.e., ${feature.identifier} or ${feature[‘identifier’]}, where the identifier is the case-sensitive property name. feature is implicit and can be omitted in most cases.

Variables can be used anywhere a valid expression is accepted, except inside other variable identifiers. For example, the following is not allowed:

${foo[${bar}]}

If a feature does not have a property with the specified name, the variable evaluates to undefined. Note that the property may also be null if null was explicitly stored for a property.

Variables may be any of the supported native JavaScript types:

• Boolean

• Null

• Undefined

• Number

• String

• Array

For example:

{
  “enabled” : true,
  “description” : null,
  “order” : 1,
  “name” : “Feature name”
}

${enabled} === true
${description} === null
${order} === 1
${name} === ‘Feature name’

Additionally, variables originating from vector properties stored in the Batch Table binary are treated as vector types:

Variables can be used to construct colors or vectors. For example:

rgba(${red}, ${green}, ${blue}, ${alpha})
vec4(${temperature})

Dot or bracket notation is used to access feature subproperties. For example:

{
  “address” : {
  “street” : “Example street”,
  “city” : “Example city”
  }
}

${address.street} === `Example street`
${address[‘street’]} === `Example street`

${address.city} === `Example city`
${address[‘city’]} === `Example city`

Bracket notation supports only string literals.

Top-level properties can be accessed with bracket notation by explicitly using the feature keyword. For example:

{
  “address.street” : “Maple Street”,
  “address” : {
  “street” : “Oak Street”
}
}

${address.street} === `Oak Street`
${feature.address.street} === `Oak Street`
${feature[‘address’].street} === `Oak Street`
${feature[‘address.street’]} === `Maple Street`

To access a feature named feature, use the variable ${feature}. This is equivalent to accessing ${feature.feature}

{
  “feature” : “building”
}

${feature} === `building`
${feature.feature} === `building`

Variables can also be substituted inside strings defined with backticks, for example:

{
  “order” : 1,
  “name” : “Feature name”
}

Name is ${name}, order is ${order}

Bracket notation is used to access feature subproperties or arrays. For example:

{
  “temperatures” : {
  “scale” : “fahrenheit”,
  “values” : [70,80,90]
}
}

${temperatures[‘scale’]} === ‘fahrenheit’
${temperatures.values[0]} === 70
${temperatures[‘values’][0]} === 70 // Same as (temperatures[values])[0] and temperatures.values[0]

11.3.9.  Built-in functions

The following built-in functions are supported by the styling language. Many of the built-in functions take either scalars or vectors as arguments. For vector arguments the function is applied component-wise and the resulting vector is returned.

{
  "show" : "abs(${temperature}) > 20.0"
}

{
  "color" : {
    "conditions" : [
      ["${temperature} >= 0.5", "color('#00FFFF')"],
      ["${temperature} >= 0.0", "color('#FF00FF')"]
    ]
  }
}

{
  "show" : "cos(${Angle}) > 0.0"
}

{
  "show" : "sin(${Angle}) > 0.0"
}

{
  "show" : "tan(${Angle}) > 0.0"
}

{
  "show" : "acos(${Angle}) > 0.0"
}

{
  "show" : "asin(${Angle}) > 0.0"
}

{
  "show" : "atan(${Angle}) > 0.0"
}

{
  "show" : "atan2(${GridY}, ${GridX}) > 0.0"
}

{
  "show" : "radians(${Angle}) > 0.5"
}

{
  "show" : "degrees(${Angle}) > 45.0"
}

{
  "show" : "sign(${Temperature}) * sign(${Velocity}) === 1.0"
}

{
  "show" : "floor(${Position}) === 0"
}

{
  "show" : "ceil(${Position}) === 1"
}

{
  "show" : "round(${Position}) === 1"
}

{
  "show" : "exp(${Density}) > 1.0"
}

{
  "show" : "log(${Density}) > 1.0"
}

{
  "show" : "exp2(${Density}) > 1.0"
}

{
  "show" : "log2(${Density}) > 1.0"
}

{
  "color" : "color() * fract(${Density})"
}

{
  "show" : "pow(${Density}, ${Temperature}) > 1.0"
}

{
  "show" : "min(${Width}, ${Height}) > 10.0"
}

{
  "show" : "max(${Width}, ${Height}) > 10.0"
}

{
  "color" : "color() * clamp(${temperature}, 0.1, 0.2)"
}

{
  "show" : "mix(20.0, ${Angle}, 0.5) > 25.0"
}

{
  "show" : "length(${Dimensions}) > 10.0"
}

{
  "show" : "distance(${BottomRight}, ${UpperLeft}) > 50.0"
}

{
  "show" : "normalize(${RightVector}, ${UpVector}) > 0.5"
}

{
  "show" : "dot(${RightVector}, ${UpVector}) > 0.5"
}

{
  "color" : "vec4(cross(${RightVector}, ${UpVector}), 1.0)"
}

11.3.10.  Notes

Comments are not supported.

11.6.1.  style

A 3D Tiles style.

Properties

Additional properties are not allowed.

11.6.2.  boolean expression

A boolean or string with a 3D Tiles style expression that evaluates to a boolean. See Expressions.

11.6.3.  color expression

3D Tiles style expression that evaluates to a Color. See Expressions.

11.6.4.  conditions

A series of conditions evaluated in order, like a series of if…​else statements that result in an expression being evaluated.

Properties

Additional properties are not allowed.

11.6.5.  condition

An expression evaluated as the result of a condition being true. An array of two expressions. If the first expression is evaluated and the result is true, then the second expression is evaluated and returned as the result of the condition.

11.6.6.  expression

A valid 3D Tiles style expression. See Expressions

11.6.7.  meta

A series of property names and the expression to evaluate for the value of that property.

Additional properties are allowed.

• Type of each property: expression

11.6.8.  number expression

3D Tiles style expression that evaluates to a number. See Expressions.

11.6.9.  Point Cloud Style

A 3D Tiles style with additional properties for Point Clouds.

Properties

Additional properties are not allowed.