File Formats

This page describes the proprietary binary file formats that are used by the Tinman 3D SDK.

Basic Data Types

In the following descriptions, the type names int8, int16, int32, int64 refer to signed integer types and the types uint8, uint16, uint32 refer to unsigned integer types.

Floating-point types are indicated by float32 and float64 (IEEE 754).

Unless stated otherwise in the description, multi-byte values use little-endian encoding. In specific cases, big-endian may be indicated by the type suffix _be and _little-endian_ may be indicated by _le.

The type bool is an 8-bit integer which represents either true (0) or false (~0).

Fixed-length array types have a [] suffix. Array elements are stored sequentially, without padding.

The type varint refers to the variable-length integer type, see SystemUtil.VarIntRead and SystemUtil.VarIntWrite.

The special type suffix maps to different basic data types, depending on the name suffix of the enclosing type:

Table 1. Mapping of special type suffix
Name Suffix Maps to…​ Example

…​D

float64

Vec2D

…​F

float32

Vec2F

…​I

int32

Vec2I

…​L

int64

Vec2L

enum

The ordinal values of the items of an enumeration type that is annotated with SemanticEnumAttribute may be used in binary file formats. In such a case, the documented type will be int32, int16 or int8 and the description will point to the enumeration type.

For other enumerations, the persistent values of the enumeration items are documented in-place.

string

A nullable sequence of ISO-8859-1 or UTF-16 characters.

Table 2. The basic type string
Field Type Count Description

length

int32

1

The string length, in characters

if length == -1

The null string

else-if length < 0

Use length = -2 - length

chars

uint16

length

The string characters in UTF-16 encoding

else

chars

uint8

length

The string characters in ISO-8859-1 encoding

end-if

Binary Config Documentation (BCD)

hourglass This section is not yet available, see roadmap for details.

Block Storage (BST)

hourglass This section is not yet available, see roadmap for details.

Compiled Model Hierarchy (CMH)

This is a self-contained file format for 3D models, which aggregates all model data in a single file, while allowing lazy-loading of specific data at runtime; for example vertex buffers, index buffers and textures.

This file format is backward compatible, i.e. files in an older format can always be loaded with the current SDK version.

When writing a file, the smallest file version is chosen that is capable of carrying all information, which makes it possible to generate files that may be consumed by an older SDK version.

History

Table 3. CMH file format history
Changed Released [1] Preview [2] Version Description

2023/03/07

2023/03/07

2023/03/07

v5

Added new material properties to IMaterial, to support the glTF 2.0 specification.

The IMaterial.BaseColor, IMaterial.Emissive, IMaterial.Reflectivity and IMaterial.Translucency properties may now carry HDR color values.

Added base vertex for indexed geometry to PrimitiveBatch.

Added the ModelFlags.Terrain, ModelPartFlags.Opaque and ModelVertexFormat.TextureCoordsExtra flags.

Added support for re-using IModel and IModelPart objects at multiple places in the model hierarchy.

Replaced ModelFlags.Lighting with ModelPartFlags.NoLighting.

2023/02/10

2023/02/10

2023/02/10

v4

Added level-of-detail control, see IModel.FadeIn / IModel.FadeOut.

2023/02/06

-

-

v3

Added surface layers, see IModelPart.Layer.

2021/05/24

2021/09/10

2021/09/10

v3

Added embedded spatial acceleration structures, see ModelFlags.ComplexGeometry.

2020/07/28

2021/01/10

2021/01/10

v2

Added model parts, see IModelPart.

Added 64-bit precision for child-to-parent transforms, see IModel.ChildTransformAt.

2020/07/06

-

-

v2

Added ModelVertexFormat.PositionExtra.

2019/12/21

-

-

v1

Removed model animation frames.

2017/03/23

2017/04/28

2017/04/28

v1

Added unit of measure, see IModel.Unit.

2017/03/21

-

-

-

Initial version (unreleased).

Specification

This is the binary file format specification of the CMH file format.

Byte offsets are always interpreted relative to the beginning of the file.

Header

Table 4. Header block
Field Type Count Description

magic

int64

1

The magic value 0x0A1A0A0D686D6389, which identifies the CMH file format

version

varint

1

The file version number; file format features that depend on specific version numbers are annotated with @ version <> N.

root

int64

1

Byte offset of root Model block

Model

This block encodes the data of IModel objects.

Table 5. Model block
Field Type Count Description

name_length

varint

1

Length of name field, in array elements

name

uint8[]

1

The UTF-8 byte sequence of the model name

parts

varint

1

Number of subsequent ModelPart blocks
- or -
Flags of model and part

if parts >= 0

A bitmask that carries the following information:

0x000001 (bit 0)

ModelPartFlags.NoLighting
iff bit is set @ version > 4
iff bit is not set @ version < 5

0x000002 (bit 1)

ModelPartFlags.FrontFaces

0x000004 (bit 2)

ModelPartFlags.BackFaces

0x000008 (bit 3)

ModelPartFlags.Transparent

0x000010 (bit 4)

ModelPartFlags.VertexColorIsBaseColor

0x000020 (bit 5)

ModelPartFlags.VertexAlphaIsOcclusion

0x000040 (bit 6)

ModelFlags.ComplexGeometry @ version > 2

0x000080 (bit 7)

ModelFlags.Group

0x000100 (bit 8)

ModelFlags.NoSpatialQuery

0x07FE00 (bits 9..18)

IModelPart.Layer, encoded as a 10-bit signed integer

0x080000 (bit 19)

ModelFlags.Terrain @ version > 4

0x100000 (bit 20)

ModelPartFlags.Opaque @ version > 4

geometry

int64

1

Byte offset to the Geometry block for IModelPart.Geometry

material

int64

1

Byte offset to the Material block for IModelPart.Material

unit

object

1

Serialized UnitOfMeasure object for IModel.Unit

batch

Batch

1

Embedded Batch block for IModelPart.Batch

-

int8

1

Not used, should be 0 and must be ignored.

else-if parts < 0

Number of subsequent embedded ModelPart blocks, encoded as: count = -1-parts @ version > 1

flags

varint

1

A bitmask that carries the following information:

0x000001 (bit 0)

ModelPartFlags.NoLighting
if bit is not set @ version < 5

0x000040 (bit 6)

ModelFlags.ComplexGeometry @ version > 2

0x000080 (bit 7)

ModelFlags.Group

0x000100 (bit 8)

ModelFlags.NoSpatialQuery

0x080000 (bit 19)

ModelFlags.Terrain @ version > 4

unit

object

1

Serialized UnitOfMeasure object for IModel.Unit

part

ModelPart

count

Embedded ModelPart blocks for IModel.PartAt.

end-if

collider

Collider

1

The pre-computed spatial acceleration structure @ version > 2

fade

object

2

Serialized Fade values for IModel.FadeIn and IModel.FadeOut, in that order @ version > 3

children

varint

1

Number of subsequent Model blocks.

if children >= 0

Number of child models with 32-bit floating-point transformations, encoded as count = children

repeat count times

child

int64

1

Byte offset of index-th child Model block

matrix

Mat4F

1

The affine matrix that transforms from child to parent

end-repeat

else-if children < 0

Number of child models with 64-bit floating-point transformations, encoded as count = -1-children @ version > 1

repeat count times

child

int64

1

Byte offset of index-th child Model block

translation

Vec3D

1

Translation from child to parent

rotation

Mat3D

1

Rotation from child to parent (may include axis flip)

scaling

float64

1

The uniform scale factor from child to parent

end-repeat

end-if

ModelPart

This block encodes the data of IModelPart objects.

Table 6. ModelPart block
Field Type Count Description

part

varint

1

The part flags or byte offset.

if part < 0

Byte offset of known ModelPart block to reference, encoded as offset = -1-part @ version > 4

else

A bitmask that carries the following information:

0x000001 (bit 0)

ModelPartFlags.NoLighting
iff bit is set @ version > 4
iff bit is not set @ version < 5

0x000002 (bit 1)

ModelPartFlags.FrontFaces

0x000004 (bit 2)

ModelPartFlags.BackFaces

0x000008 (bit 3)

ModelPartFlags.Transparent

0x000010 (bit 4)

ModelPartFlags.VertexColorIsBaseColor

0x000020 (bit 5)

ModelPartFlags.VertexAlphaIsOcclusion

0x07FE00 (bits 9..18)

IModelPart.Layer, encoded as a 10-bit signed integer

0x100000 (bit 20)

ModelPartFlags.Opaque @ version > 4

geometry

int64

1

Byte offset of Geometry block.

material

int64

1

Byte offset of Material block.

batch

Batch

1

Embedded Batch block.

end-if

Batch

hourglass This section is not yet available, see roadmap for details.

Collider

hourglass This section is not yet available, see roadmap for details.

Geometry

hourglass This section is not yet available, see roadmap for details.

Material

hourglass This section is not yet available, see roadmap for details.

Texture

hourglass This section is not yet available, see roadmap for details.

Compiled Shape (CSH)

hourglass This section is not yet available, see roadmap for details.

Digitally Licensed Content (LIC)

hourglass This section is not yet available, see roadmap for details.

Heightmap Cache (HGC)

hourglass This section is not yet available, see roadmap for details.

Heightmap Dataset (HGT)

hourglass This section is not yet available, see roadmap for details.

Pixel Buffer (PXB)

hourglass This section is not yet available, see roadmap for details.

Pixel Pyramid Cache (PYC)

hourglass This section is not yet available, see roadmap for details.

Pixel Pyramid Dataset (PYR)

hourglass This section is not yet available, see roadmap for details.

Program Structure Information (PSI/API)

hourglass This section is not yet available, see roadmap for details.

Serialized Object (SER)

The ISerializable interface is implemented by classes that support compact binary serialization, for example JsonValue. The implementations of the ITypeSerializer interface may be used to serialize non-object values, for example Vec3D.Serializer.

The binary format of every ISerializable object begins with a common preamble block, which defines the serial type ID and version.

Table 7. Preamble block
Field Type Count Description

length

int32

1

The type identifier length / format version

if length == -1

The deserialized object is null.

else-if length == 36

guid

GUID

1

The serial type ID, see GUID.From

version

int32

1

The serial version number

payload

…​

1

The serialized data of the object

else-if length > 36

Use version = length - 36 as the serial version number.

guid

int64

2

The parts of the serial type ID, see GUID.GUID

payload

…​

1

The serialized data of the object

else

Use the value id = -2-length to lookup an already known object that has been deserialized earlier.

Each deserialized non-null object is assigned a positive identifier, which begins at zero and is incremented for each object.

end-if

The serial type ID is used to lookup the serial type via SerialTypeInfos.Get, a new object instance is created with ISerialTypeInfo.CreateInstance and the object state is deserialized by calling ISerializable.Deserialize, passing the serial version number.

The common type name prefix "Tinman." is omitted in the following sections.

Core.Math

Cuboid

Table 8. Value format Cuboid.Serializer
Field Type Count Description

origin

Vec3D

1

Cuboid.Origin

orientation

Mat3D

1

Cuboid.Orientation

Fraction

Table 9. Value format Fraction.Serializer
Field Type Count Description

numerator

int32

1

Fraction.Numerator

denominator

int32

1

Fraction.Denominator

Gauss

Table 10. Value format Gauss.Serializer
Field Type Count Description

expected

float64

1

The expected value of the distribution

deviation

float64

1

The deviation value of the distribution

scale

float64

1

The scale value of the distribution

Plane

Table 11. Value format Plane.Serializer
Field Type Count Description

normal

Vec3D

1

Plane.Normal

distance

float64

1

Plane.Distance

QuatD

Table 12. Value format QuatD.Serializer
Field Type Count Description

x

float64

1

Quat4.X

y

float64

1

Quat4.Y

z

float64

1

Quat4.Z

w

float64

1

Quat4.W

Range(DF)

Table 13. Value format Range(DF).Serializer
Field Type Count Description

start

suffix

1

Range(DF).Start

end

suffix

1

Range(DF).End

Range(IL)

Table 14. Value format Range(IL).Serializer
Field Type Count Description

start

suffix

1

Range(IL).Start

last

suffix

1

Range(IL).Last

Ray

Table 15. Value format Ray.Serializer
Field Type Count Description

origin

Vec3D

1

Ray.Origin

direction

Vec3D

1

Ray.Direction

Sphere

Table 16. Value format Sphere.Serializer
Field Type Count Description

center

Vec3D

1

Sphere.Center

radius

float64

1

Sphere.Radius

Core.Math.Vectors

Mat2(DF)

Table 17. Value format Mat2(DF).Serializer
Field Type Count Description

element

suffix

4

The matrix elements, in row-major order

Mat3(DF)

Table 18. Value format Mat3(DF).Serializer
Field Type Count Description

element

suffix

9

The matrix elements, in row-major order

Mat4(DF)

Table 19. Value format Mat4(DF).Serializer
Field Type Count Description

element

suffix

16

The matrix elements, in row-major order

Vec2(DFIL)

Table 20. Value format Vec2(DFIL).Serializer
Field Type Count Description

x

suffix

1

Vec2(DFIL).X

y

suffix

1

Vec2(DFIL).Y

Vec3(DFIL)

Table 21. Value format Vec3(DFIL).Serializer
Field Type Count Description

x

suffix

1

Vec3(DFIL).X

y

suffix

1

Vec3(DFIL).Y

z

suffix

1

Vec3(DFIL).Z

Vec4(DFIL)

Table 22. Value format Vec4(DFIL).Serializer
Field Type Count Description

x

suffix

1

Vec4(DFIL).X

y

suffix

1

Vec4(DFIL).Y

z

suffix

1

Vec4(DFIL).Z

z

suffix

1

Vec4(DFIL).W

Core.Util

ColorF

Table 23. Value format ColorF.Serializer
Field Type Count Description

r

float32

1

ColorF.R

g

float32

1

ColorF.G

b

float32

1

ColorF.B

a

float32

1

ColorF.A

GUID

Table 24. Value format GUID.Serializer
Field Type Count Description

first

int64

1

GUID.First

second

int64

1

GUID.Second

LUID

Table 25. Value format LUID.Serializer
Field Type Count Description

value

int32

1

LUID.Value

Terrain.Georef

LatLon

Table 26. Value format LatLon.Serializer
Field Type Count Description

longitude

float64

1

LatLon.Longitude

latitude

float64

1

LatLon.Latitude

LatLonHeight

Table 27. Value format LatLonHeight.Serializer
Field Type Count Description

coords

LatLon

1

LatLonHeight.Coords

height

float64

1

LatLonHeight.Height

vertical

int32

1

LatLonHeight.Vertical

LatLonRange

Table 28. Value format LatLonRange.Serializer
Field Type Count Description

start

LatLon

1

LatLonRange.Start

end

LatLon

1

LatLonRange.End

UnitOfMeasure

Table 29. Object format (version 1)
Field Type Count Description

name

string

1

IGeoObject.Name

-

int8

8

Not used, should be 0 and must be ignored.

one

float64

1

UnitOfMeasure.One

type

int32

1

UnitOfMeasure.UnitType

Terrain.Heightmaps

HeightmapSample

Table 30. Value format HeightmapSample.Serializer
Field Type Count Description

values

int8

1

HeightmapSample.LayerMask

if values has Coverage

coverage

int32

1

HeightmapSample.Coverage

end-if

if values has Elevation

elevation

int32

1

HeightmapSample.Elevation

end-if

if values has Texture

texture

int64

1

HeightmapSample.Texture

end-if

if values has Material

material

int64

1

HeightmapSample.Material

end-if

if values has Displacement

displacement

int32

1

HeightmapSample.Displacement

end-if

VerticalRange

Table 31. Value format VerticalRange.Serializer
Field Type Count Description

minimum

float64

1

VerticalRange.Minimum

maximum

float64

1

VerticalRange.Maximum

Terrain.Mapping

CubemapFaceCoordsI

Table 32. Value format CubemapFaceCoordsI.Serializer
Field Type Count Description

x

int32

1

CubemapFaceCoordsI.X

y

int32

1

CubemapFaceCoordsI.Y

face

int32

1

CubemapFaceCoordsI.Face

Terrain.Util

Box2(DIL)

Table 33. Value format Box2(DIL).Serializer
Field Type Count Description

x1

suffix

1

Box2(DIL).X1

y1

suffix

1

Box2(DIL).Y1

x2

suffix

1

Box2(DIL).X2

y2

suffix

1

Box2(DIL).Y2

Box3(DI)

Table 34. Value format Box3(DI).Serializer
Field Type Count Description

x1

suffix

1

Box3(DI).X1

y1

suffix

1

Box3(DI).Y1

x2

suffix

1

Box3(DI).X2

y2

suffix

1

Box3(DI).Y2

Fade

Table 35. Value format Fade.Serializer
Field Type Count Description

scale

float64

1

The scale factor

offset

float64

1

The offset value

The return value of Fade.Compute is defined as result = value * scale + offset, clamped to the range [0..1].

Terrain Database (TDB)

hourglass This section is not yet available, see roadmap for details.

hourglass This section is not yet available, see roadmap for details.

Texel Buffer (TXB)

hourglass This section is not yet available, see roadmap for details.


1. The official release that includes the change
2. The stable preview that includes the change