File Formats | 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)

See: ConfigDoc.Load

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

Block Storage (BST)

See: BlockStorage

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.

See: ModelFormat.CMH

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)

See: ShapeFormat.CSH

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

Digitally Licensed Content (LIC)

See: LicenceDomain.UnlockContent

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

Heightmap Cache (HGC)

See: DatasetFileCache

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

Heightmap Dataset (HGT)

See: Heightmap.Datasets

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

Pixel Buffer (PXB)

See: ImageFormat.PXB

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

Pixel Pyramid Cache (PYC)

See: PyramidFileCache

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

Pixel Pyramid Dataset (PYR)

See: PixelPyramid.Datasets

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

Program Structure Information (PSI/API)

See: Code-X Processor

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.

See: SceneDataFormat.TDB

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

Texel Buffer (TXB)

See: ImageFormat.TXB
TexelBuffer

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