glTF Format - jgoffeney/Cesium4Unreal GitHub Wiki

Back

Example From JSON File

Order is MinX, MinY, MaxX, MaxY, MinZ, MaxZ where:

  • MinX & MaxX: the minimum and maximum longitude in radians
  • MinY & MaxY: the minimum and maximum latitude in radians
  • MinZ & MaxZ: the minimum and maximum altitude in meters
"region":[-0.7853981633974483,-0.5406359802559503,0.7853981633974483,0.785398163381105,-10170.587093897164,4549.5897529535]

References

Introduction

Description

The glTF format was created to deliver assets for runtime applications with regards to loading and transmission. It was designed with the following goals:

  • Compact file sizes with the file description being in compact JSON with source such as geometry, textures and animation stored in binary files.
  • Runtime-independence to not be tied to any specific rendering technology.
  • Complete scene representation to represent entire scenes including nodes, transformations, transform hierarchy, meshes, cameras and animations.
  • Extensibility to enable general and vendor specific extensions for things like geometry and texture compression.

The glTF format does not address the following:

  • The binary data is streamable and the buffers allows for incrementation fetching but that is the limit of its streamable constructs.
  • The files do not maintain authoring information to reduce the file size.
  • It is not intentionally human-readable.

Basics

A glTF asset can be composed of multiple files with the JSON .gltf (or binary .glb) file containing the scene information while binary (.bin) files contain buffer based data such as geometry and animation. Image files (.jpg or .png) contain texture images.

The binary and image data can be embedded in the .gltk file or in a separate .glb file.

URIs

Files external to the .gltk are refernced by URI or IRIs.

Concepts

General

hierarchy

Asset

Each glTF asset is required to have an asset property with at least a version tag. The asset can also be used store additional metadata such as a copyright.

Indices and Names

Data / references are stored within their arrays and then referenced by an index when contained in another JSON structure. For example buffer objects are stored in an array and then a bufferView refers to a buffer as the key value pair buffer : indexValue.

Coordinate Systems and Units

The glTF format uses a right-handed coordinate system with +Y as up, +Z as forward and -X as right. The linear distances are in meters, all angles are in radians and positive rotation is counterclockwise.

Scenes

Overview

A scene is the representation of a scene graph. The scenes array contains the scene objects which all reference a singles nodes array. A single scene can reference multiple parent nodes.

Nodes and Hierarchy

Nodes are used to define a scene graph. The nodes array contains all the node object for the scenes. The section below shows how a hierarchy is defined through the use of the children array. The parent nodes are each the root of a graph (which may only consist of the root)

{
    "nodes": [
        {
            "name": "Car",
            "children": [1, 2, 3, 4]
        },
        {
            "name": "wheel_1"
        },
        {
            "name": "wheel_2"
        },
        {
            "name": "wheel_3"
        },
        {
            "name": "wheel_4"
        }
    ]
}
  • camera : the index for the node's camera
  • children : the array of the node indices of the node's children
  • skin : the index of the skin
  • matrix : the 4x4 transformation matrix for the node
  • mesh : the index to the node's mesh
  • rotation : the quaternion rotation for the node as 4 eleemnt array
  • scale : the node's scale vector as a 3 element array
  • translation : the node's translation vector as a 3 element array
  • weights : the array of weights for the morph targets
  • name : the user defined name
  • extensions : a JSON map of extensions
  • extras : application specific data

Transformations

Each node can also define a local space transform which is propagated to its children. A transform in a root node defines a global transform since is applied to all nodes within the graph.

Transforms are stored within node as a 4 element rotation array, and 3 element scale and translation arrays or as a single 16 element matrix array.

Binary Data Storage

Buffers and Buffer Views

Overview

A buffer is data stored as a binary blob. It can contain any combination of geometry, animation, skins, and images. Binary blobs can be loaded directly to a GPU.

An asset may have any number of buffer resources and are defined in the buffers array. GLB binary chunks can not exceed 32 bits in size.

This example defines a buffer with an external reference to the binary data. The byteLength has to be smaller or equal to the size of duck.bin.

{
   "buffers": [
       {
           "byteLength": 102040,
           "uri": "duck.bin"
       }
   ]
}

A bufferView represents blocks of binary data which contain concatenated binary assets. Within its array it contains references to individual buffers within the block.

  • buffer: the index to the buffer object in the buffers array.
  • byteLength: the size of the buffer region to read.
  • byteOffset: the byte location in the buffer to start reading.
  • byteStride: an optional property used with vertex attribute data to define the stride between vertices
  • target: a integer value defining the type of data within the buffer
    • ARRAY_BUFFER (34962): contains general data
    • ELEMENT_ARRAY_BUFFER (34963): contains indices to elements within an ARRAY_BUFFER. Mainly indices to vertices for triangles/quads.
{
    "bufferViews": [
        {
            "buffer": 0,
            "byteLength": 25272,
            "byteOffset": 0,
            "target": 34963
        },
        {
            "buffer": 0,
            "byteLength": 76768,
            "byteOffset": 25272,
            "byteStride": 32,
            "target": 34962
        }
    ]
}

GLB-stored Buffer

A GLB file will contain glTF JSON and a single internal buffer. To reference it a buffer object without a uri component must be the first element in the buffers array.

Accessors

Overview

An accessor is the method used to retrieve binary data from the buffers.

  • bufferView: the index to the buffer view to access the binary data
  • byteOffset: the offset within the buffer view to begin reading
  • componentType: an enum defining the component type (if the data stores 3D vectors then this is the type of the vector element)
  • count: the number of elements within the data
  • min & max: the array of range of values (for scalar values each would have one element while a 3D vector would have 3 each).
  • type: a string for the type of data stored, such as, SCALAR or VEC3.

Accessor Data Types

The reading size is computed by size of(componentType) * number of elements by type * count.

Sparse Accessors

The accessor sparse tag defines an object to define how a sparse data array is stored.

Data Alignment

Buffer data has to be aligned based on its component type.

Geometry

Meshes

A set of geometry primitives to be rendered.

  • primitive : the array of geometry mesh primitives
  • weights : the array of weights to apply to morph targets
  • name : the user defined name for this
  • extensions : the JSON object map of extensions
  • extras : a JSON value of application specific data

Mesh Primitives

The mesh primitive defines the properties of the geometry.

  • attributes : the map of name of geometry attributes to the indices of their accessors
    • POSITION : the vertex position data
    • NORMAL : the vertex normal data
    • TEXCOORD_0 : the texture UV coordinates
  • material : the index of the material
  • indices : the accessor index containing the vertex indices
  • mode : an enum defining the geometry type
    • POINTS
    • LINES
    • LINE_LOOP
    • LINE_STRIP
    • TRIANGLES
    • TRIANGLE_STRIP
    • TRIANGLE_FAN
  • targets : an array of morph targets
  • extensions : a JSON map of extensions
  • extras : application specific data

GLB File Format Specification