Feature Table

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:

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 must end on an 8-byte boundary within the containing tile binary. The JSON header must be padded with trailing Space characters (0x20) 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.

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 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.

See Property reference for the full JSON header schema reference. The full JSON schema can be found in featureTable.schema.json.

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:

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 non-normative

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.

Property reference

• Feature Table
  • BinaryBodyReference
  • Property

---

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

	Type	Description	Required
extensions	object	Dictionary object with extension-specific objects.	No
extras	any	Application-specific data.	No

Additional properties are allowed.

• Type of each property: Property

FeatureTable.extensions

Dictionary object with extension-specific objects.

• Type: object
• Required: No
• Type of each property: Extension

FeatureTable.extras

Application-specific data.

• Type: any
• Required: No

---

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

	Type	Description	Required
byteOffset	number	The offset into the buffer in bytes.	✅ Yes

Additional properties are allowed.

BinaryBodyReference.byteOffset ✅

The offset into the buffer in bytes.

• Type: number
• Required: Yes
• Minimum: >= 0

---

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.

• JSON schema: featureTable.schema.json