Skip to content

Latest commit

 

History

History
98 lines (69 loc) · 6.73 KB

README.adoc

File metadata and controls

98 lines (69 loc) · 6.73 KB
Raw

Feature Table

Warning
 Feature Table was deprecated in 3D Tiles 1.1. See glTF migration guide.

Overview

A Feature Table is a component of a tile’s binary body and describes position and appearance properties required to render each feature in a tile. The Batch Table, on the other hand, contains per-feature application-specific properties not necessarily used for rendering.

A Feature Table is used by tile formats like Batched 3D Model (b3dm) where each model is a feature, and Point Cloud (pnts) where each point is a feature.

Per-feature properties are defined using tile format-specific semantics defined in each tile format’s specification. For example, for Instanced 3D Model, SCALE_NON_UNIFORM defines the non-uniform scale applied to each 3D model instance.

Layout

A Feature Table is composed of two parts: a JSON header and an optional binary body in little endian. The JSON property names are tile format-specific semantics, and their values can either be defined directly in the JSON, or refer to sections in the binary body. It is more efficient to store long numeric arrays in the binary body. The following figure shows the Feature Table layout:

feature table layout
Figure 1. Data layout of a Feature Table

When a tile format includes a Feature Table, the Feature Table immediately follows the tile’s header. The header will also contain featureTableJSONByteLength and featureTableBinaryByteLength uint32 fields, which can be used to extract each respective part of the Feature Table.

Padding

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

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

Binary properties shall 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 shall start at an offset that is a multiple of 4. Preceding binary properties shall be padded with additional bytes, of any value, to satisfy this requirement.

JSON header

Feature Table values can be represented in the JSON header in two 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. 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 shall 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 shall 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.

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:

feature table binary index
Figure 2. An example showing how to access the binary body, based on the information from the JSON header

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.

Implementation example

This section is informative

The following example accesses the position property using the POSITION semantic, which has a float32[3] data type:

var byteOffset = featureTableJSON.POSITION.byteOffset;

var positionArray = new Float32Array(featureTableBinary.buffer, byteOffset, featuresLength * 3); // There are three components for each POSITION feature.
var position = positionArray.subarray(featureId * 3, featureId * 3 + 3); // Using subarray creates a view into the array, and not a new array.

Code for reading the Feature Table can be found in Cesium3DTileFeatureTable.js in the CesiumJS implementation of 3D Tiles.