Model3D

Qualified name: algan.mobs.three\_d\_models.model\_mob.Model3D

class Model3D(file_path=None, scene_data=None, load_textures=True, fit_to_size=None, smooth_normals=True, normal_maps=True, pbr_materials=True, **kwargs)

Bases: Mob

Load a 3-D model file and build its geometry/textures as a Mob.

Parameters:

• file_path (str) – Path to the model file. .glb/.gltf (and .obj/.ply/…) load through trimesh (no native dependency); .fbx loads through pyassimp (needs the native assimp library installed).

• scene_data (SceneData, optional) – Pre-parsed IR to build from instead of reading file_path (used by tests and alternative importer backends). When given, file_path may be a label only.

• load_textures (bool) – Load and apply diffuse texture maps referenced by materials (default True). When False (or a texture fails to load) meshes fall back to their material’s flat base color.

• fit_to_size (float, optional) – Recenter the model and uniformly scale it so its bounding-box diagonal is this many world units – handy, since model files use wildly different unit scales. Defaults to None, which leaves the model at the size the file gives it.

• smooth_normals (bool) – Use the mesh’s authored / generated per-vertex normals for smooth shading (default True). When False, flat per-face normals are derived at render time.

• normal_maps (bool) – Apply tangent-space normal maps from materials (default True), adding per-fragment surface detail. Requires per-vertex UVs; batches carrying a normal map render through the general wavefront tracer.

• pbr_materials (bool) – Apply each material’s PBR parameters (metalness / roughness / emissive) as a MeshStandardMaterial (default True), so imported meshes shade with Cook-Torrance GGX. When False the default lit shader is kept.

• *args – Passed to Mob (e.g. location to place the model).

• **kwargs – Passed to Mob (e.g. location to place the model).

Methods

get_default_color	Get the color this Mob uses when none was given.
get_part	The imported mesh mob(s) for a named node, so a sub-part of the model can be manipulated (moved, colored, animated) on its own.
play_animation	Play a baked node-keyframe animation on the timeline.
precompute_animation	Bake an animation clip to per-frame world-space corner positions.

Attributes

animation_manager	This mob's scene-owned animation manager.
animation_names	Names of the model's animation clips.
animations	The animation clips (AnimationData) parsed from the model file, if any.
basis	The Mob's orientation and scale, as a flattened 3x3 matrix of shape (*, 9).
casts_shadows	Whether this Mob's geometry blocks light on its way from a light source to another surface -- whether it casts a shadow.
children	The Mobs attached below this one, in attachment order.
closed_shell	Whether this Mob's triangles form a CLOSED shell -- every camera ray that enters the geometry crosses a second time on its way out.
draws_descendants	Whether get_render_primitives returns geometry belonging to this Mob's DESCENDANTS as well as its own.
forward	Get the direction the Mob is facing.
lifespan	This mob's [spawn, despawn) interval on its Scene timeline (a Lifespan).
location	The Mob's position in world space, shape (*, 3).
node_names	The names of the model's nodes that carry geometry.
normalized_basis	The Mob's orientation with scale divided out, shape (*, 9).
parents	The Mobs this one is attached to, in attachment order.
receives_shadows	Whether this Mob's surfaces are darkened by shadows cast onto them.
right	Get the Mob's own rightward direction.
scale_coefficient	The Mob's scale along its own right, up and forward axes, shape (*, 3).
two_sided	Whether this Mob's geometry should be lit from whichever side the ray arrives on.
up	Get the Mob's own upward direction.
x	The Mob's x coordinate in world units, shape (*, 1).
xy	The Mob's x and y coordinates in world units, shape (*, 2).
y	The Mob's y coordinate in world units, shape (*, 1).
z	The Mob's z coordinate in world units, shape (*, 1).

property animation_names

Names of the model’s animation clips.

property animations

The animation clips (AnimationData) parsed from the model file, if any.

get_default_color()

Get the color this Mob uses when none was given.

Override in a subclass to give a shape its own default; the built-in shapes do exactly that.

Returns:

BLACK for the base class.

Return type:

Color

get_part(name)

The imported mesh mob(s) for a named node, so a sub-part of the model can be manipulated (moved, colored, animated) on its own. Returns a single TriangleMesh when the node has one mesh, else a list. Raises KeyError for an unknown node.

property node_names

The names of the model’s nodes that carry geometry.

play_animation(name=None, runtime=None, fps=30, loop=1, easing=<function identity>)

Play a baked node-keyframe animation on the timeline.

The clip is baked to per-frame world corners (see precompute_animation()) and each mesh instance’s corners are driven through those poses, so rigid node motion (a bone/part translating, rotating or scaling, composed down the hierarchy) plays back. Meshes with authored normals are switched to per-frame smooth-normal recomputation so shading stays correct as the geometry moves.

Parameters:

• name (str, optional) – Clip name; defaults to the first clip.

• runtime (float, optional) – Playback runtime in seconds (per loop). Defaults to the clip’s authored runtime.

• fps (int) – Sampling rate for baking (higher = smoother rotation, since corners are linearly interpolated between baked poses).

• loop (int) – Number of times to repeat the clip.

• easing (callable) – Timeline rate function; defaults to linear playback.

precompute_animation(name=None, times=None, fps=30)

Bake an animation clip to per-frame world-space corner positions.

Evaluates every node’s animated local transform at each sample time, composes them down the hierarchy and transforms each mesh instance’s local vertices, yielding the exact geometry the ray tracer renders per frame. Pure computation (no scene mutation), so it is unit-testable and also drives play_animation().

Parameters:

• name (str, optional) – Clip name; defaults to the first clip.

• times (sequence of float, optional) – Explicit sample times (seconds). Defaults to an fps grid over the clip runtime unioned with the authored keyframe times.

• fps (int) – Sampling rate used when times is not given.

Returns:

(times, corners) – The sample times and, per mesh mob, a [T, 3F, 3] stack of world-space corner positions (one slice per sample time).

Return type:

(list[float], dict[TriangleMesh, torch.Tensor])