Model.Read

Description

Name

class Tinman.Model.Read

Derived from

Model

Reads the given 3D model file.

Fields / Required

data

Type

Data

Constraint

# != null

The 3D model file to read.

Fields / Optional

format

Type

string

Default

null

The 3D model file format. If unknown, the format is inferred from the data stream.
The following default model file formats are available:

'Any'

The file format is unknown and will be determined automatically.

'ASSIMP5'
Open Asset Import Library v5.*
https://github.com/assimp/assimp

This model format is available if any of the following native libraries is present in the search path of the process:

  • 'assimp5.x32' : 32-bit dynamic link library

  • 'assimp5.x64' : 64-bit dynamic link library

  • 'assimp5' : dynamic link library

  • 'assimp.x32' : 32-bit dynamic link library

  • 'assimp.x64' : 64-bit dynamic link library

  • 'assimp' : dynamic link library

  • 'libassimp5' : dynamic link library

  • 'libassimp' : dynamic link library

This class assumes that the library interfaces of all minor versions are binary compatible.

To re-build the dynamic libraries that are included in the Tinman 3D SDK, please perform the following steps (you may use other library versions, toolsets or build options, of course):

  • Install CMake 3.28.0 or newer (https://cmake.org).

  • Download Assimp release 5.4.0 (https://github.com/assimp/assimp/tags).

  • Choose generator 'Visual Studio 17 2022', using the 'Win32' and 'x64' platforms.

  • Use default build options of CMake, then apply the following:
    ASSIMP_BUILD_ASSIMP_TOOLS = FALSE
    ASSIMP_BUILD_TESTS = FALSE
    ASSIMP_BUILD_ZLIB = TRUE
    ASSIMP_DOUBLE_PRECISION = FALSE
    CMAKE_C_FLAGS += ' /DWINVER=0x0601 /D_WIN32_WINNT=0x0601'
    CMAKE_CXX_FLAGS += ' /DWINVER=0x0601 /D_WIN32_WINNT=0x0601'

  • Build the Assimp binaries (project assimp with configuration Release), then rename and copy each one into its respective SDK folder:
    bin/win.any/assimp5.x32.dll
    bin/win.any/assimp5.x64.dll
    bin/win.x32/assimp5.x32.dll
    bin/win.x64/assimp5.x64.dll

This model format supports the following options:

'CMH'

The CMH model file format ('Compiled Model Hierarchy', proprietary):
https://manual.tinman3d.com/STABLE-PREVIEW/file-formats.html#_compiled_model_hierarchy_cmh

Write supported: yes
IANA media type: none
File extensions: .cmh

This file format is self-contained, i.e. all resources are embedded in the model file. Lazy loading is applied for all model geometry objects and all model texture resources.

This file format ignores all options ofModel.Read.

'FLT'

OpenFlight API v22.0
https://www.presagis.com/en/glossary/detail/openflight/

This file format is available if any of the following native libraries is present in the search path of the process:

  • 'mgapilib' : dynamic link library

If the OpenFlight API has been installed locally, the libraries can be found there, for example:

c:\Presagis\Suite22\OpenFlight_API_22_0\bin\debug\
c:\Presagis\Suite22\OpenFlight_API_22_0\bin\release\
c:\Presagis\Suite22\OpenFlight_API_22_0\bin_x64\debug\
c:\Presagis\Suite22\OpenFlight_API_22_0\bin_x64\release\

The OpenFlight API binaries are not included in the Tinman 3D SDK. However, an application may choose to bundle and redistribute them, in accordance to the Presagis Software Licence Agreement, which does not require Tinman 3D to be involved in any way.

This model format supports the following options:

'GLB'

The GL Transmission Format Version 2.0 - Binary
https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
glTF Sample Viewer
https://github.khronos.org/glTF-Sample-Viewer-Release/

Write supported: no
IANA media type: model/gltf-binary
File extensions: .glb

The binary JSON .glb file format may be self-contained, i.e. all resources are embedded in the model file. Lazy loading is applied for all model geometry objects and all model texture resources. These glTF extensions are supported:

  • KHR_materials_emissive_strength

  • KHR_materials_ior

  • KHR_materials_pbrSpecularGlossiness

  • KHR_materials_specular

  • KHR_materials_transmission

  • KHR_materials_unlit

The following glTF features are not supported:

  • 3.7.3. Skins

  • 3.10. Cameras

  • 3.11. Animations

This model format supports the following options:

'GLTF'

The GL Transmission Format Version 2.0 - JSON
https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
glTF Sample Viewer
https://github.khronos.org/glTF-Sample-Viewer-Release/

Write supported: no
IANA media type: model/gltf+json
File extensions: .gltf

The JSON .gltf file format is not necessarily self-contained, i.e. some resources may be present as external files, which are referenced by the model file. Lazy loading is applied for all model geometry objects and all model texture resources. These glTF extensions are supported:

  • KHR_materials_emissive_strength

  • KHR_materials_ior

  • KHR_materials_pbrSpecularGlossiness

  • KHR_materials_specular

  • KHR_materials_transmission

  • KHR_materials_unlit

The following glTF features are not supported:

  • 3.7.3. Skins

  • 3.10. Cameras

  • 3.11. Animations

This model format supports the following options:

'LAS'

The LAS model file format.

Write supported: no
IANA media type: application/vnd.las
File extensions: .las

This model format supports the following options:

'OBJ'

The OBJ model file format.

Write supported: yes
IANA media type: model/obj
File extensions: .obj

The following commands are supported in *.obj files:

  • v X Y Z (vertex coordinates)

  • v X Y Z R G B (vertex coordinates with color)

  • vn X Y Z (vertex normal vector)

  • vt X Y (vertex texture coordinates)

  • s N (smoothing group for normal vectors)

  • f A1 B1 C1 …​ (polygon face)

  • f A1/A2 B1/B2 C1/C2 …​ (polygon face)

  • f A1/A2/A3 B1/B2/B3 C1/C2/C3 …​ (polygon face)

  • mtllib NAME (select material library)

  • usemtl NAME (select material)

The following commands are supported in *.mtl files:

  • newmtl NAME (define new material)

  • Ka R G B (ambient reflectivity)

  • Kd R G B (diffuse reflectivity)

  • Ks R G B (specular reflectivity)

  • Tf R G B (transmission filter)

  • d V (material dissolve)

  • sharpness V (glossiness)

  • map_Ka NAME (ambient texture map)

  • map_Kd NAME (diffuse texture map)

  • map_Ks NAME (specular texture map)

  • map_d NAME (dissolve texture map)

This model format supports the following options:

winding

Type

number

Default

0

Fix vertex winding of indexed triangle list primitives:
Given a triangle (a,b,c), vertex winding is fixed using the face normal N and the cross product X=(b-a)x(c-a):
> 0: Fix triangle winding so that dot(N,X) is positive.
< 0: Fix triangle winding so that dot(N,X) is negative.
= 0: Do not fix triangle winding.

If the model does not have normal vectors, vertex winding will never be fixed. This fix is applied after Read.Flags.FlipWinding.

flags

Type

Read.Flags[]

Default

[None]

The flags to use for reading the 3D model.

glossiness

Type

number

Default

1

Scale factor to apply to Model.Material.glossiness of all read materials.

reflectivity

Type

Tinman.Color

Default

{Color.Name: White}

Modulation color to apply to Model.Material.reflectivity of all read materials.

material

Type

Model.Material

Default

null

The material to use for the model root node.

unit

Type

Unit

Default

null

The unit of measure to use for the model root node.

texturePath

Type

path

Constraint

# != null

Default

<.>

The base directory to use for resolving relative texture file paths in the 3D model.

The given base directory can be relative; in this case, it will be resolved using the path of the directory that contains the model file. If there is no path info for the model data, the current filesystem directory is used instead.

transform

Type

Mat4

Default

{Mat4: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]}

Optional transformation matrix to apply to the model geometry.

The transformation matrix is applied as the last transformation step, before the custom post processors are invoked.

textureName

Type

Read.Name[]

Default

null

Specifies substitutions for texture names.

textureFile

Type

Read.File[]

Default

null

Specifies replacements for texture files.

modelNames

Type

string[]

Default

null

Names of the model nodes to keep, including their hierarchical structure.

If Read.Flags.ModelNames is present, this property is ignored.

bump

Type

number

Default

0

Relative height of bump maps.

This value is interpreted relative to the dimensions of the unit square of normalized texture coordinates. A value of 1 will extrude the unit square to the unit cube.

Instead of a normal map, a model may define a bump height map. In this case, a tangent-space normal map can be generated from the bump map, using the given bump height.

simplify

Type

bool

Default

true

Simplify the model structure after loading?