ModelReaderOptions

Description

sealed class Tinman.Engine.Models.ModelReaderOptions

Derived from: Versioned ^abstract

The ModelReaderOptions class provides a set of standard options that can be used to configure the import process for 3D models.

If supported by a IModelReader, the options can be used to control how the read model data is processed:

3D model structure
Many model files contain a hierarchy of nodes, which gets flattened or retained during processing by the model reader. Use ModelNames to control this behaviour. The IsModelNameKept method can be used to check whether a node name will be retained. Simplification via IModel.Simplify can be controlled via Simplify. Additional customization can be performed with ReadModelFlags.ModelGroup and RootUnit.
Texture file lookup
Use TextureNameReplace, TexturePath and TextureFileReplace to configure texture name mapping and file lookup. With TextureName¹, ResolveTexturePath and TextureFile¹, texture lookups may be performed, similarly to the model reader. The TextureUnresolved property maintains a list of texture names for which lookup has failed.
Geometry post-processing
The geometry data of a model file can be post-processed. To configure this, set the FixWinding, Flags and Transform properties accordingly. The Process* methods are helpers that apply post-processing to the given data, similarly to the model reader.
Material tweaking
Use BumpScale, GlossinessScale, ReflectivityScale, RootMaterial and ReadModelFlags.NormalIsBump to customize import of materials, for example if the 3D model file contains badly authored data.

See also: IModelReader.Options

Public / Constructors

ModelReaderOptions

public constructor ModelReaderOptions → (1)

modelDirectory ⁱⁿ : Path: Path to the directory that contains the model file or null if none.

Creates a new instance of ModelReaderOptions.

Public / Methods

IsModelNameKept

[Pure]
public method IsModelNameKept → (1)

name ⁱⁿ : string: The model name.
returns → bool: true if the model shall be kept,
false if it may be merged.

Checks if the given model name shall be kept, including its hierarchical structure.

The names of the models to keep are listed in ModelNames.

See also: ModelReaderOptions.ModelName

ModelName

public method ModelName → (2)

name ⁱⁿ : string: [not-empty]
The model name.
keep ^opt : bool = true: true to keep name ⁱⁿ,
false to not keep name ⁱⁿ.

Specifies whether to keep the given model name or not.

The names of the models to keep are listed in ModelNames.

See also: ModelReaderOptions.IsModelNameKept

PostProcessIndices

public method PostProcessIndices → (3)

vertices ⁱⁿ : VertexArrays: The vertex data.
indices ⁱⁿ : int32 [ ]: The index data to process.
batch ⁱⁿ : PrimitiveBatch: The geometry batch.

Performs in-place post processing on the given index data:

See also: ReadModelFlags.FlipWinding
ModelReaderOptions.FixWinding

PostProcessTextureCoordsNormals

public method PostProcessTextureCoordsNormals → (1)

vertices ⁱⁿ : VertexArrays: The vertex data to process.

Performs in-place post processing on the given vertex data:

PostProcessVertices

_2 overloads

public method PostProcessVertices¹ → ()

returns → Mat4D: The transformation matrix.

Returns a transformation matrix for performing post processing on vertex data:

public method PostProcessVertices² → (1)

vertices ⁱⁿ : VertexArrays: The vertex data to process.

Performs in-place post processing on the given vertex data:

ResolveTexturePath

[Pure]
public method ResolveTexturePath → (1)

texturePath ⁱⁿ : Path: [not-null]
The texture path.
returns → Path: The resolved canonical texture path.

Resolves the given texture path, using the current model reader settings.

See also: ModelReaderOptions.ResolveTexturePathReverse

ResolveTexturePathReverse

[Pure]
public method ResolveTexturePathReverse → (1)

texturePath ⁱⁿ : Path: [not-null]
The resolved texture path.
returns → Path: The texture path (relative if possible).

Reverse-resolves the given texture path.

See also: ModelReaderOptions.ResolveTexturePath

TextureFile

_2 overloads

[Pure]
public method TextureFile¹ → (1)

file ⁱⁿ : Path: [not-null]
The texture file path.
returns → IModelTexture: The model texture or null.

Returns the model texture object that has been specified for the given texture file.

The model texture object for the given texture file ⁱⁿ is obtained by the following steps:

The given texture path is resolved (see ResolveTexturePath).
If a model texture object has been specified earlier for the resolved texture path via TextureFileReplace, that object is used.

public method TextureFile² → (3)

file ⁱⁿ : Path: [not-null]
The texture file path.
srgb ⁱⁿ : bool: The ISrgb.Srgb flag to use for encoding the texture. Will be ignored if a cached texture is used.
format ^opt : TextureFormat = null: The texture format to use or null to choose one automatically. Will be ignored if a cached texture is used.
returns → IModelTexture: The model texture or null.

Returns the model texture object for the given texture file.

The model texture object for the given texture file ⁱⁿ is obtained by the following steps:

The given texture path is resolved (see ResolveTexturePath).
If a model texture object has been specified earlier for the resolved texture path via TextureFileReplace, that object is used (the srgb ⁱⁿ parameter is ignored in this case). Otherwise, a new model texture object is created and cached, using the canonical path value as the key.

IOException: An I/O error has occurred while reading the image metadata in order to determine the texture format.

ValidatingException: The image reader has reported an error while reading the image metadata for determining the texture format, for example because of a missing file format feature.

TextureFileReplace

public method TextureFileReplace → (2)

path ⁱⁿ : Path: [not-null]
The texture file path.
texture ⁱⁿ : IModelTexture: [not-null]
The replacement model texture object.

Replaces a texture file.

The given texture file path will be resolved (see ResolveTexturePath), if necessary.

See also: ModelReaderOptions.TextureFile¹
ModelReaderOptions.TextureFile²

TextureName

_2 overloads

[Pure]
public method TextureName¹ → (1)

name ⁱⁿ : string: The texture name, as found in the 3D model.
returns → string: The model texture name or null iff there is no texture name replacement.

Returns the model texture name replacement for the given texture name.

See also: ModelReaderOptions.TextureNameReplace

public method TextureName² → (3)

name ⁱⁿ : string: The texture name, as found in the 3D model.
srgb ⁱⁿ : bool: The ISrgb.Srgb flag to use for encoding the texture.
format ^opt : TextureFormat = null: The texture format to use or null to choose one automatically.
returns → IModelTexture: The model texture or null if name ⁱⁿ is null. Will be ModelTexture.Error if the texture name does not resolve to a valid file path or if the resolved texture file does not exist.

Returns the model texture object for the given texture name.

The model texture object for the given texture name ⁱⁿ is obtained by the following steps:

The texture name ⁱⁿ is replaced, according to the mappings that have been established earlier via TextureNameReplace. If there is no mapping for name ⁱⁿ and it is an absolute path to a non-existent file, it will be replaced with the last path element (i.e. the file name).
The texture name is interpreted as a file path and resolved (see Path.Resolve) using the configured texture path (see TexturePath).
This method delegates to TextureFile², using the resolved texture path.

IOException: An I/O error has occurred while reading the image metadata in order to determine the texture format.

ValidatingException: The image reader has reported an error while reading the image metadata for determining the texture format, for example because of a missing file format feature.

TextureNameReplace

public method TextureNameReplace → (2)

original ⁱⁿ : string: [not-null]
The original texture name.
corrected ⁱⁿ : string: [not-null]
The corrected texture name.

Replaces a texture name.

See also: ModelReaderOptions.TextureName¹
ModelReaderOptions.TextureName²

TextureUnresolvedClear

public method TextureUnresolvedClear → ()

Clears the list of unresolved texture names.

See also: ModelReaderOptions.TextureUnresolved

Public / Attributes

BumpScale

public attribute BumpScale → (get,set)

value : float64: The relative bump height. 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.

Relative height of bump maps.

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.

Defaults to 0.

See also: ReadModelFlags.NormalIsBump

FixWinding

public attribute FixWinding → (get,set)

value : int32: 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.

Fix vertex winding of indexed triangle list primitives?

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

Defaults to 0.

See also: ReadModelFlags.FlipWinding
ModelPartFlags.FrontFaces
ModelPartFlags.BackFaces

Flags

public attribute Flags → (get,set)

value : ReadModelFlags: The flags.

The flags to use for reading the 3D model.

Defaults to ReadModelFlags.None.

GlossinessScale

public attribute GlossinessScale → (get,set)

value : float32: [>=0]
The gloss scale.

Scale factor to apply to IMaterial.Glossiness. MaterialPart.Value of all read materials.

Defaults to 1.0.

ModelNames

public attribute ModelNames → (get)

value : ISortedSetConst<string>: [not-null]
The set of model names to keep.

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

If ReadModelFlags.ModelNames is present, this property is ignored.

See also: ModelReaderOptions.ModelName

ReflectivityScale

public attribute ReflectivityScale → (get,set)

value : ColorF: The reflectivity scale.

Modulation color to apply to IMaterial.Reflectivity. MaterialPart.Value of all read materials.

Defaults to ColorF.White.

RootMaterial

public attribute RootMaterial → (get,set)

value : IMaterial: The root material or null.

The material to use for the model root node.

RootUnit

public attribute RootUnit → (get,set)

value : UnitOfMeasure: The root unit of measure or null.

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

Simplify

public attribute Simplify → (get,set)

value : ModelSimplifyFlags: The model simplification actions.

The model simplification actions that will be performed by IModelReader.ReadModel before returning the final IModel.

Defaults to ModelSimplifyFlags.All.

TexturePath

public attribute TexturePath → (get,set)

value : Path: [not-null]
The texture base directory.

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 (see IFileData.IsPathInfoValid), the current filesystem directory is used instead.

Defaults to Path.Current.

TextureUnresolved

[Constant]
public attribute TextureUnresolved → (get)

value : ISortedSetConst<string>: [not-null]
The unresolved texture names. Will be empty iff all texture names have resolved successfully.

Returns the texture names (see TextureName¹ and TextureName²) that could not have been resolved.

See also: ModelReaderOptions.TextureUnresolvedClear

Transform

public attribute Transform → (get,set)

value : Mat4D: The transformation matrix.

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.

Defaults to Mat4D.Identity.

ModelReaderOptions

Description

Public / Constructors

Model​Reader​Options

Public / Methods

Is​Model​Name​Kept

Model​Name

Post​Process​Indices

Post​Process​Texture​Coords​Normals

Post​Process​Vertices

Resolve​Texture​Path

Resolve​Texture​Path​Reverse

Texture​File

Texture​File​Replace

Texture​Name

Texture​Name​Replace

Texture​Unresolved​Clear

Public / Attributes

Bump​Scale

Fix​Winding

Flags

Glossiness​Scale

Model​Names

Reflectivity​Scale

Root​Material

Root​Unit

Simplify

Texture​Path

Texture​Unresolved

Transform

ModelReaderOptions

IsModelNameKept

ModelName

PostProcessIndices

PostProcessTextureCoordsNormals

PostProcessVertices

ResolveTexturePath

ResolveTexturePathReverse

TextureFile

TextureFileReplace

TextureName

TextureNameReplace

TextureUnresolvedClear

BumpScale

FixWinding

GlossinessScale

ModelNames

ReflectivityScale

RootMaterial

RootUnit

TexturePath

TextureUnresolved