Models

Contents

Models#

Data structures for 3D model content.

class AnimationClip(name='clip', frames=0, rate=0.33, translations=<factory>, rotations=<factory>)[source]#

Keyframed bone animation clip.

frames: int = 0#
name: str = 'clip'#
rate: float = 0.33#
property times: Annotated[ndarray[tuple[Any, ...], dtype[float32]], Ellipsis]#
translations: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
rotations: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
class MeshBounds(min=<factory>, max=<factory>, radius=0.0)[source]#

Mesh bounding box.

radius: float = 0.0#
min: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
max: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
class ModelAnimation(clips=<factory>, translation=AnimationTranslation.DELTA, rotation=AnimationRotation.QUATERNION)[source]#

Animation clips container.

rotation: AnimationRotation = 'quaternion'#
translation: AnimationTranslation = 'delta'#
clips: list[AnimationClip]#
class ModelMesh(name='name', material='material', bounds=<factory>, quads=False, bones=<factory>, vertices=<factory>, uv1=<factory>, uv2=<factory>, normals=<factory>, tangents=<factory>, colors=<factory>, links_ids=<factory>, links_weights=<factory>, polygons=<factory>, link_space=LinkSpace.GLOBAL, uv_origin=UVOrigin.TOP_LEFT, uv_sign=UVSign.POSITIVE)[source]#

Mesh geometry container.

material: str = 'material'#
property max_influences: int#
name: str = 'name'#
quads: bool = False#
uv_origin: UVOrigin = 'top_left'#
uv_sign: UVSign = 'positive'#
bounds: MeshBounds#
bones: dict[NewType(LocalBoneId, int), NewType(SkeletonBoneId, int)]#
vertices: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
uv1: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
uv2: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
normals: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
tangents: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
colors: Annotated[ndarray[tuple[Any, ...], dtype[uint8]]]#
polygons: Annotated[ndarray[tuple[Any, ...], dtype[uint32]]]#
class ModelScene(scale=<factory>, meshes=<factory>, skeleton=<factory>, animation=<factory>)[source]#

Container for meshes, skeleton, and animation.

property total_polygons#
property total_vertices#
scale: SceneScales#
meshes: list[ModelMesh]#
skeleton: ModelSkeleton#
animation: ModelAnimation#
class SceneScales(position=1.0, uv=1.0, uv2=1.0, filtering=0.1)[source]#

Scale multipliers for scene data.

filtering: float = 0.1#
position: float = 1.0#
uv: float = 1.0#
uv2: float = 1.0#
class SkeletonBone(id=0, name='bone', parent_id=-1, position=<factory>, rotation=<factory>, children=<factory>)[source]#

Bone with transform data.

id: int = 0#
property is_root: bool#
name: str = 'bone'#
parent_id: int = -1#
property quaternion: Annotated[ndarray[tuple[Any, ...], dtype[float32]], Ellipsis, 4]#
property slug: str#
position: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
rotation: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
children: List[Self]#
class ModelSkeleton(bones=<factory>, space=SkeletonSpace.GLOBAL, hierarchy=SkeletonHierarchy.FLAT)[source]#

Skeleton bones container.

calculate_global_transforms()[source]#

Compute global transformation matrix for each bone.

Return type:

list[ndarray[tuple[Any, ...], dtype[float32]]]

hierarchy: SkeletonHierarchy = 'flat'#
inverse_bind_matrices(transpose)[source]#

Compute inverse bind matrices for all bones.

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

property roots: List[SkeletonBone]#
space: SkeletonSpace = 'global'#
bones: List[SkeletonBone]#
class Flag(value)[source]#

Bases: StrEnum

Model feature flag.

SKELETON = 'skeleton'#
UV = 'uv'#
UV2 = 'uv2'#
NORMALS = 'normals'#
TANGENTS = 'tangents'#
COLORS = 'colors'#
class AnimationRotation(value)[source]#

Bases: StrEnum

Animation rotation format.

QUATERNION = 'quaternion'#
EULER = 'euler'#
class AnimationTranslation(value)[source]#

Bases: StrEnum

Animation translation mode.

DELTA = 'delta'#
ABSOLUTE = 'absolute'#
class LinkSpace(value)[source]#

Bases: StrEnum

Vertex link coordinate space.

GLOBAL = 'global'#
LOCAL = 'local'#
class SkeletonHierarchy(value)[source]#

Bases: StrEnum

Skeleton bones hierarchy state.

FLAT = 'flat'#
BUILT = 'built'#
class SkeletonSpace(value)[source]#

Bases: StrEnum

Skeleton bones coordinate space.

GLOBAL = 'global'#
LOCAL = 'local'#
class UVOrigin(value)[source]#

Bases: StrEnum

UV coordinate origin.

TOP_LEFT = 'top_left'#
BOTTOM_LEFT = 'bottom_left'#
class UVSign(value)[source]#

Bases: StrEnum

UV coordinate sign.

POSITIVE = 'positive'#
NEGATIVE = 'negative'#
create_rotation_matrix(rotation)[source]#

Convert euler angles (XYZ) to 3×3 rotation matrix.

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

create_transform_matrix(translation, rotation)[source]#

Convert translation and rotation (R * T) to 4×4 transform matrix.

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

euler_to_quat(rotation)[source]#

Convert euler angles (XYZ) to quaternion (XYZW).

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

Scene#

Data structures for scenes.

class SceneScales(position=1.0, uv=1.0, uv2=1.0, filtering=0.1)[source]#

Scale multipliers for scene data.

position: float = 1.0#
uv: float = 1.0#
uv2: float = 1.0#
filtering: float = 0.1#
class ModelScene(scale=<factory>, meshes=<factory>, skeleton=<factory>, animation=<factory>)[source]#

Container for meshes, skeleton, and animation.

scale: SceneScales#
meshes: list[ModelMesh]#
skeleton: ModelSkeleton#
animation: ModelAnimation#
property total_vertices#
property total_polygons#

Mesh#

Data structures for meshes.

class MeshBounds(min=<factory>, max=<factory>, radius=0.0)[source]#

Mesh bounding box.

min: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
max: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
radius: float = 0.0#
class ModelMesh(name='name', material='material', bounds=<factory>, quads=False, bones=<factory>, vertices=<factory>, uv1=<factory>, uv2=<factory>, normals=<factory>, tangents=<factory>, colors=<factory>, links_ids=<factory>, links_weights=<factory>, polygons=<factory>, link_space=LinkSpace.GLOBAL, uv_origin=UVOrigin.TOP_LEFT, uv_sign=UVSign.POSITIVE)[source]#

Mesh geometry container.

name: str = 'name'#
material: str = 'material'#
bounds: MeshBounds#
quads: bool = False#
bones: dict[NewType(LocalBoneId, int), NewType(SkeletonBoneId, int)]#
vertices: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
uv1: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
uv2: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
normals: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
tangents: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
colors: Annotated[ndarray[tuple[Any, ...], dtype[uint8]]]#
polygons: Annotated[ndarray[tuple[Any, ...], dtype[uint32]]]#
uv_origin: UVOrigin = 'top_left'#
uv_sign: UVSign = 'positive'#
property max_influences: int#

Skeleton#

Data structures for skeletons.

class SkeletonBone(id=0, name='bone', parent_id=-1, position=<factory>, rotation=<factory>, children=<factory>)[source]#

Bone with transform data.

id: int = 0#
name: str = 'bone'#
parent_id: int = -1#
position: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
rotation: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
children: List[Self]#
property is_root: bool#
property quaternion: Annotated[ndarray[tuple[Any, ...], dtype[float32]], Ellipsis, 4]#
property slug: str#
class ModelSkeleton(bones=<factory>, space=SkeletonSpace.GLOBAL, hierarchy=SkeletonHierarchy.FLAT)[source]#

Skeleton bones container.

bones: List[SkeletonBone]#
space: SkeletonSpace = 'global'#
hierarchy: SkeletonHierarchy = 'flat'#
property roots: List[SkeletonBone]#
calculate_global_transforms()[source]#

Compute global transformation matrix for each bone.

Return type:

list[ndarray[tuple[Any, ...], dtype[float32]]]

inverse_bind_matrices(transpose)[source]#

Compute inverse bind matrices for all bones.

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

Animation#

class AnimationClip(name='clip', frames=0, rate=0.33, translations=<factory>, rotations=<factory>)[source]#

Keyframed bone animation clip.

name: str = 'clip'#
frames: int = 0#
rate: float = 0.33#
translations: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
rotations: Annotated[ndarray[tuple[Any, ...], dtype[float32]]]#
property times: Annotated[ndarray[tuple[Any, ...], dtype[float32]], Ellipsis]#
class ModelAnimation(clips=<factory>, translation=AnimationTranslation.DELTA, rotation=AnimationRotation.QUATERNION)[source]#

Animation clips container.

clips: list[AnimationClip]#
translation: AnimationTranslation = 'delta'#
rotation: AnimationRotation = 'quaternion'#

Matrices#

Matrix transformations utilities.

create_rotation_matrix(rotation)[source]#

Convert euler angles (XYZ) to 3×3 rotation matrix.

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

create_transform_matrix(translation, rotation)[source]#

Convert translation and rotation (R * T) to 4×4 transform matrix.

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

euler_to_quat(rotation)[source]#

Convert euler angles (XYZ) to quaternion (XYZW).

Return type:

ndarray[tuple[Any, ...], dtype[float32]]

Transforms#

Scene transformation functions.

unique_names(scene)[source]#

Ensure all meshes have unique names.

Return type:

ModelScene

flip_uv(scene)[source]#

Flip V axis (TOP_LEFT → BOTTOM_LEFT).

Return type:

ModelScene

invert_uv(scene)[source]#

Invert V axis sign (POSITIVE → NEGATIVE).

Return type:

ModelScene

skeleton_to_local(scene)[source]#

Convert bone positions (GLOBAL → LOCAL).

Return type:

ModelScene

build_hierarchy(scene)[source]#

Build bone children tree (FLAT → BUILT).

Return type:

ModelScene

animation_to_absolute(scene)[source]#

Add rest pose positions to animation deltas (DELTA → ABSOLUTE).

Return type:

ModelScene

Enums#

Enums for model data structures.

class Flag(value)[source]#

Bases: StrEnum

Model feature flag.

SKELETON = 'skeleton'#
UV = 'uv'#
UV2 = 'uv2'#
NORMALS = 'normals'#
TANGENTS = 'tangents'#
COLORS = 'colors'#
class UVOrigin(value)[source]#

Bases: StrEnum

UV coordinate origin.

TOP_LEFT = 'top_left'#
BOTTOM_LEFT = 'bottom_left'#
class UVSign(value)[source]#

Bases: StrEnum

UV coordinate sign.

POSITIVE = 'positive'#
NEGATIVE = 'negative'#
class LinkSpace(value)[source]#

Bases: StrEnum

Vertex link coordinate space.

GLOBAL = 'global'#
LOCAL = 'local'#
class SkeletonSpace(value)[source]#

Bases: StrEnum

Skeleton bones coordinate space.

GLOBAL = 'global'#
LOCAL = 'local'#
class SkeletonHierarchy(value)[source]#

Bases: StrEnum

Skeleton bones hierarchy state.

FLAT = 'flat'#
BUILT = 'built'#
class AnimationTranslation(value)[source]#

Bases: StrEnum

Animation translation mode.

DELTA = 'delta'#
ABSOLUTE = 'absolute'#
class AnimationRotation(value)[source]#

Bases: StrEnum

Animation rotation format.

QUATERNION = 'quaternion'#
EULER = 'euler'#

Types#

Type aliases for model data structures.

ModelFlags#

Per-feature presence flags.

alias of dict[Flag, bool]

class LocalBoneId#

Bone index within mesh.

alias of int

class SkeletonBoneId#

Bone index within skeleton.

alias of int

BonesMapping#

Mapping from mesh local to skeleton bone indices.

alias of dict[LocalBoneId, SkeletonBoneId]

Vector2D#

2D float32 vector.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 2)]

Vector3D#

3D float32 vector.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 3)]

Vector4D#

4D float32 vector.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 4)]

LinksIds#

Bone indices per vertex.

alias of Annotated[ndarray[tuple[Any, …], dtype[uint8]], (Ellipsis, 4)]

LinksWeights#

Bone weights per vertex.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 4)]

Bone indices and weights pair.

alias of tuple[Annotated[ndarray[tuple[Any, …], dtype[uint8]], (Ellipsis, 4)], Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 4)]]

Polygons#

Triangle indices.

alias of Annotated[ndarray[tuple[Any, …], dtype[uint32]], (Ellipsis, 3)]

Colors#

RGBA vertex colors.

alias of Annotated[ndarray[tuple[Any, …], dtype[uint8]], (Ellipsis, 4)]

EulerAngles#

Euler angles in degrees (XYZ intrinsic).

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 3)]

Quaternion#

Quaternion rotation (XYZW).

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 4)]

RotationMatrix#

3x3 rotation matrix.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (3, 3)]

TransformMatrix#

4×4 transformation matrix.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (4, 4)]

BindPose#

Global transform per bone.

alias of list[Annotated[ndarray[tuple[Any, …], dtype[float32]], (4, 4)]]

InverseBindMatrices#

Inverse bind matrices per bone.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 4, 4)]

AnimationTranslations#

Animation translations per frame.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 3)]

AnimationRotations#

Animation rotations per frame.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], (Ellipsis, 4)]

AnimationTimes#

Animation times per frame.

alias of Annotated[ndarray[tuple[Any, …], dtype[float32]], Ellipsis]

Contents