Instanced 3D Model

Warning

Instanced 3D Model was deprecated in 3D Tiles 1.1. See i3dm migration guide.

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.

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

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

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 1. Data layout for Instanced 3D Models

Padding

A tile’s byteLength shall be aligned to an 8-byte boundary. The contained Feature Table and Batch Table shall conform to their respective padding requirement.

The binary glTF (if present) shall start on an 8-byte boundary so that glTF’s byte-alignment guarantees are met. The proper alignment for the start of the binary glTF data can be achieved by padding the Feature Table, or by padding the Batch Table if it is present. The alignment for the byteLength of the tile can be achieved by padding the tile data with 0-bytes. The actual binary glTF data does not include possible trailing padding bytes. Clients must take into account the length from the binary glTF header, and use this length to determine the part of the tile data that actually represents the binary glTF.

Otherwise, if the glTF field is a UTF-8 string, it shall be padded with trailing Space characters (0x20) to satisfy alignment requirements of the tile, which shall be removed at runtime before requesting the glTF asset.

Header

The 32-byte header contains the following fields:

Table 1. Header fields for Instanced 3D Models

Field name	Data type	Description
`magic`	4-byte ANSI string	`"i3dm"`. This can be used to identify the content as an Instanced 3D Model tile.
`version`	`uint32`	The version of the Instanced 3D Model format. It is currently `1`.
`byteLength`	`uint32`	The length of the entire tile, including the header, in bytes.
`featureTableJSONByteLength`	`uint32`	The length of the Feature Table JSON section in bytes.
`featureTableBinaryByteLength`	`uint32`	The length of the Feature Table binary section in bytes.
`batchTableJSONByteLength`	`uint32`	The length of the Batch Table JSON section in bytes. Zero indicates that there is no Batch Table.
`batchTableBinaryByteLength`	`uint32`	The length of the Batch Table binary section in bytes. If `batchTableJSONByteLength` is zero, this will also be zero.
`gltfFormat`	`uint32`	Indicates the format of the glTF field of the body. `0` indicates it is a URI, `1` indicates it is embedded binary glTF. See the glTF section below.

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

Feature Table

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

The full JSON schema can be found in i3dm.featureTable.schema.json.

Semantics

Instance semantics

These semantics map to an array of feature values that are used to create instances. The length of these arrays shall be the same for all semantics and is equal to the number of instances. The value for each instance semantic shall be a reference to the Feature Table binary body; they cannot be embedded in the Feature Table JSON header.

If a semantic has a dependency on another semantic, that semantic shall be defined. If both SCALE and SCALE_NON_UNIFORM are defined for an instance, both scaling operations will be applied. If both POSITION and POSITION_QUANTIZED are defined for an instance, the higher precision POSITION will be used. If NORMAL_UP, NORMAL_RIGHT, NORMAL_UP_OCT32P, and NORMAL_RIGHT_OCT32P are defined for an instance, the higher precision NORMAL_UP and NORMAL_RIGHT will be used.

Table 2. Semantics for instances of an Instanced 3D Model

Semantic	Data Type	Description	Required
`POSITION`	`float32[3]`	A 3-component array of numbers containing `x`, `y`, and `z` Cartesian coordinates for the position of the instance.	Yes, unless `POSITION_QUANTIZED` is defined.
`POSITION_QUANTIZED`	`uint16[3]`	A 3-component array of numbers containing `x`, `y`, and `z` in quantized Cartesian coordinates for the position of the instance.	Yes, unless `POSITION` is defined.
`NORMAL_UP`	`float32[3]`	A unit vector defining the `up` direction for the orientation of the instance.	No, unless `NORMAL_RIGHT` is defined.
`NORMAL_RIGHT`	`float32[3]`	A unit vector defining the `right` direction for the orientation of the instance. Shall be orthogonal to `up`.	No, unless `NORMAL_UP` is defined.
`NORMAL_UP_OCT32P`	`uint16[2]`	An oct-encoded unit vector with 32-bits of precision defining the `up` direction for the orientation of the instance.	No, unless `NORMAL_RIGHT_OCT32P` is defined.
`NORMAL_RIGHT_OCT32P`	`uint16[2]`	An oct-encoded unit vector with 32-bits of precision defining the `right` direction for the orientation of the instance. Shall be orthogonal to `up`.	No, unless `NORMAL_UP_OCT32P` is defined.
`SCALE`	`float32`	A number defining a scale to apply to all axes of the instance.	No.
`SCALE_NON_UNIFORM`	`float32[3]`	A 3-component array of numbers defining the scale to apply to the `x`, `y`, and `z` axes of the instance.	No.
`BATCH_ID`	`uint8`, `uint16` (default), or `uint32`	The `batchId` of the instance that can be used to retrieve metadata from the `Batch Table`.	No.

Global semantics

These semantics define global properties for all instances.

Table 3. Global semantics for Instanced 3D Models

Semantic	Data Type	Description	Required
`INSTANCES_LENGTH`	`uint32`	The number of instances to generate. The length of each array value for an instance semantic should be equal to this.	Yes.
`RTC_CENTER`	`float32[3]`	A 3-component array of numbers defining the center position when instance positions are defined relative-to-center.	No.
`QUANTIZED_VOLUME_OFFSET`	`float32[3]`	A 3-component array of numbers defining the offset for the quantized volume.	No, unless `POSITION_QUANTIZED` is defined.
`QUANTIZED_VOLUME_SCALE`	`float32[3]`	A 3-component array of numbers defining the scale for the quantized volume.	No, unless `POSITION_QUANTIZED` is defined.
`EAST_NORTH_UP`	`boolean`	When `true` and per-instance orientation is not defined, each instance will default to the `east/north/up` reference frame’s orientation on the `WGS84` ellipsoid.	No.

Examples using these semantics can be found in the examples section.

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 2. A box in the standard basis

Figure 3. A box transformed into a rotated basis

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.

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

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.

Instance position

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

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. See Coordinate System for the effect that this property has on the transform.

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 4. Illustration of the quantization that is used for the POSITION_QUANTIZED semantic

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

Compressed attributes should be decompressed before any other transforms are applied.

Instance scaling

Scaling can be applied to instances using the SCALE and SCALE_NON_UNIFORM semantics. SCALE applies a uniform scale along all axes, and SCALE_NON_UNIFORM applies scaling to the x, y, and z axes independently.

Examples

These examples show how to generate JSON and binary buffers for the Feature Table.

Positions only

In this minimal example, we place four instances on the corners of a unit length square with the default orientation:

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);

Quantized positions and oct-encoded normals

In this example, the four instances will be placed with an orientation up of [0.0, 1.0, 0.0] and right of [1.0, 0.0, 0.0] in oct-encoded format and they will be placed on the corners of a quantized volume that spans from -250.0 to 250.0 units in the x and z directions:

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]);

Batch Table

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

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.

When the glTF field contains a URI, then this URI may point to a relative external reference (RFC3986). When the URI is relative, its base is always relative to the referring .i3dm file. Client implementations are required to support relative external references. Optionally, client implementations may support other schemes (such as http://). All URIs shall be valid and resolvable.

Coordinate system

By default glTFs use a right handed coordinate system where the y-axis is up. For consistency with the z-up coordinate system of 3D Tiles, glTFs shall be transformed at runtime. See glTF transforms for more details.

When the RTC_CENTER is defined in the feature table of an Instanced 3D Model, the computation of the tile transform is done as follows:

glTF node hierarchy transformations
glTF y-up to z-up transform
The per-instance positions and scales, as defined in the feature table of the Instanced 3D Model.
The transform for the RTC_CENTER, which is used to translate model vertices
Tile transform

File extension and media type

Instanced 3D models tiles use the .i3dm extension and application/octet-stream media 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.adoc

README.adoc

Instanced 3D Model

Overview

Layout

Padding

Header

Feature Table

Semantics

Instance semantics

Global semantics

Instance orientation

Oct-encoded normal vectors

Default orientation

Instance position

RTC_CENTER

Quantized positions

Instance scaling

Examples

Positions only

Quantized positions and oct-encoded normals

Batch Table

glTF

Coordinate system

File extension and media type

Files

README.adoc

Latest commit

History

README.adoc

File metadata and controls

Instanced 3D Model

Overview

Layout

Padding

Header

Feature Table

Semantics

Instance semantics

Global semantics

Instance orientation

Oct-encoded normal vectors

Default orientation

Instance position

RTC_CENTER

Quantized positions

Instance scaling

Examples

Positions only

Quantized positions and oct-encoded normals

Batch Table

glTF

Coordinate system

File extension and media type