ke.asset¶

Loaders, model assets, and result types for MJCF, BVH, FBX, USD, AMASS, SMPL, SMPL-H, and SMPL-X.

API overview¶

`MJCFLoader`	Load MJCF/XML articulation descriptions.
`BVHLoader`	Load a BVH hierarchy or sampled skeleton motion.
`FBXLoader`	Load FBX skeletons, animation clips, and character data.
`USDLoader`	Load meshes from USD scenes.
`AMASSLoader`	Load AMASS body and hand poses as a native `SkeletonMotion`.
`AMASSInfo`	Metadata read from an AMASS NPZ archive.
`ArticulationDesc`	Imported articulation description with skeleton, visual, collision, joint, and site payloads.
`JointDesc`	Joint description imported from robot/character assets.
`SiteDesc`	Imported MJCF site description attached to a character body.
`InertialDesc`	Imported body-local inertial properties.
`VisualGeomDesc`	Visual mesh description imported from a character asset.
`CollisionGeomDesc`	Imported body-local collision geometry description.
`SMPLModel`
`SMPLBody`
`SMPLHModel`	Standard 52-joint SMPL-H NPZ model adapter.
`SMPLHBody`	A 52-joint SMPL-H body and renderable surface asset.
`SMPLXModel`	Standard 55-joint SMPL-X NPZ model adapter.
`SMPLXBody`	A 55-joint SMPL-X body and renderable surface asset.
`ImportDiagnostics`	Warnings collected while importing an asset.

Loader return contracts¶

API	Return
`MJCFLoader.parse()` / `BVHLoader.parse()`	An import-result value containing the parsed payload and diagnostics.
`MJCFLoader.load()` / `BVHLoader.load()`	The commonly used character or motion payload without the result wrapper.
`FBXLoader.load()`	`FBXImportResult` containing meshes, animation clips, materials, and diagnostics. Mesh payloads retain shared native storage.
`USDLoader.parse()`	`USDImportResult` containing imported mesh records and diagnostics.
`AMASSLoader.inspect()`	`AMASSInfo` containing gender, shape coefficients, frame rate, and frame count without constructing a motion.
`AMASSLoader.load_motion()`	A native `SkeletonMotion` mapped onto a supplied SMPL, SMPL-H, or SMPL-X `SkeletonTree`. AMASS Z-up data can be returned as Z-up or converted to KangEngine’s usual Y-up coordinates.

Missing or unreadable files and malformed source data raise RuntimeError; invalid argument values raise ValueError where validation is available. Inspect ImportDiagnostics for supported non-fatal import warnings.

class kangengine.asset.ImportDiagnostics[native]¶

Warnings collected while importing an asset.

property warnings¶: Human-readable importer warnings.

class kangengine.asset.ArticulationDesc[native]¶

Imported articulation description with skeleton, visual, collision, joint, and site payloads.

property asset_dir¶: Directory used to resolve mesh files.

property collision_geoms¶: Collision geometry descriptions keyed by body index.

property inertials¶: Inertial descriptions keyed by body index.

property joints¶: JointDesc metadata keyed by body index.

property sites¶: Imported site markers.

property skeleton_tree¶: Imported skeleton hierarchy.

property visual_geoms¶: Visual mesh descriptions.

class kangengine.asset.JointDesc[native]¶

Joint description imported from robot/character assets.

property armature¶: Joint-space armature.

property axis¶: Joint axis.

property hi_limit¶: Upper joint limit.

property lo_limit¶: Lower joint limit.

property name¶: Joint name.

class kangengine.asset.SiteDesc[native]¶

Imported MJCF site description attached to a character body.

property body_index¶: Index of the body this site belongs to.

property has_zaxis¶: Whether this site has an explicit z-axis.

property name¶: Site name.

property pos¶: Local site position.

property quat¶: Local site orientation.

property rgba¶: Site display color.

property size¶: Site size parameters.

property type¶: Site geometry type.

property zaxis¶: Explicit site z-axis if present.

class kangengine.asset.InertialDesc[native]¶

Imported body-local inertial properties.

property com¶: Body-local center of mass.

property diag_inertia¶: Diagonal inertia in the inertial frame.

property mass¶: Body mass.

property quat¶: Body-local inertial frame orientation.

class kangengine.asset.VisualGeomDesc[native]¶

Visual mesh description imported from a character asset.

property body_index¶: Owning body index.

property body_name¶: Owning body name.

property mesh_file¶: Mesh file path.

property pos¶: Local mesh position.

property quat¶: Local mesh orientation.

property rgba¶: Mesh display color.

class kangengine.asset.CollisionGeomDesc[native]¶

Imported body-local collision geometry description.

property condim¶: Imported contact dimensionality.

property friction¶: Imported MuJoCo sliding friction value.

property from_pos¶: Collision endpoint start position.

property has_from_to¶: Whether capsule-style from/to endpoints are present.

property is_fallback¶: Whether KangEngine synthesized this fallback shape.

property margin¶: Imported collision margin.

property mesh_data¶: Imported mesh payload used for convex cooking.

property mesh_file¶: Source mesh file for convex mesh collision geoms.

property name¶: Imported MJCF geom name, if present.

property physics_material¶: PhysX-style material factors derived from this geom.

property pos¶: Local collision position.

property quat¶: Local collision orientation.

property size¶: Collision size parameters.

property to_pos¶: Collision endpoint end position.

property type¶: Collision geometry type.

class kangengine.asset.MJCFLoader[native]¶

Load MJCF/XML articulation descriptions.

static load( mjcf_path: str, scale: float = 1.0, order: str = 'DFS', ) → KE::Asset::ArticulationDesc¶: Load MJCF and return an articulation description.

static parse( mjcf_path: str, scale: float = 1.0, order: str = 'DFS', ) → MJCFImportResult¶: Parse MJCF and return an articulation description with diagnostics.

class kangengine.asset.MJCFImportResult[native]¶

Parsed MJCF articulation plus diagnostics.

property articulation¶: Imported articulation description.

property diagnostics¶: Importer diagnostics.

class kangengine.asset.BVHLoader[native]¶

Load a BVH hierarchy or sampled skeleton motion.

static load_motion( bvh_path: str, scale: float = 1.0, ) → SkeletonMotion¶: Load the hierarchy and animation frames as a SkeletonMotion.

static load_skeleton( bvh_path: str, scale: float = 1.0, ) → SkeletonTree¶: Load only the skeleton hierarchy from bvh_path.

static parse(bvh_path: str, scale: float = 1.0) → BVHImportResult¶: Load BVH motion together with diagnostics and source timing metadata.

class kangengine.asset.BVHImportResult[native]¶

BVH motion and source-file metadata returned by BVHLoader.parse().

property diagnostics¶: Importer diagnostics.

property frame_count¶: Number of motion frames.

property frame_rate¶: Source frame rate in Hz.

property frame_time¶: Seconds per source frame.

property motion¶: Imported skeleton motion.

class kangengine.asset.FBXLoader[native]¶

Load FBX skeletons, animation clips, and character data.

static load_animation_clip_infos( fbx_path: str, ) → list[FBXAnimationClipInfo]¶: Return metadata for the animation clips in an FBX file.

static load_character( fbx_path: str, clip_index: int = -1, fps: float = -1.0, scale: float = 0.009999999776482582, ) → FBXCharacterData¶: Load one animation clip and all associated skinned meshes.

static load_character_with_bind( motion_fbx_path: str, bind_fbx_path: str, clip_index: int = -1, fps: float = -1.0, scale: float = 0.009999999776482582, ) → FBXCharacterData¶: Load character data using a separate FBX file for the bind pose.

static load_meshes(fbx_path: str, scale: float = 0.009999999776482582) → list¶: Load static meshes without animation data.

static load_motion( fbx_path: str, clip_index: int = -1, fps: float = -1.0, scale: float = 0.009999999776482582, ) → SkeletonMotion¶: Load one FBX animation clip as a SkeletonMotion.

static load_skeleton( fbx_path: str, scale: float = 0.009999999776482582, ) → SkeletonTree¶: Load only the FBX skeleton hierarchy.

static load_skinned_meshes( fbx_path: str, scale: float = 0.009999999776482582, ) → list¶: Load skinned meshes without animation data.

static parse( fbx_path: str, clip_index: int = -1, fps: float = -1.0, scale: float = 0.009999999776482582, ) → FBXImportResult¶: Load FBX character data together with clip metadata and diagnostics.

static parse_with_bind( motion_fbx_path: str, bind_fbx_path: str, clip_index: int = -1, fps: float = -1.0, scale: float = 0.009999999776482582, ) → FBXImportResult¶: Parse animation using a separate FBX file for the bind pose.

class kangengine.asset.FBXImportResult[native]¶

FBX character data, clips, and import diagnostics.

property character¶: Imported FBX character data.

property clips¶: Animation clips discovered in the FBX.

property diagnostics¶: Importer diagnostics.

property motion¶: Imported skeleton motion.

property skinned_meshes¶: Imported skinned meshes.

class kangengine.asset.FBXAnimationClipInfo[native]¶

Animation clip metadata discovered in an FBX file.

property end_time¶: Clip end time in seconds.

property frame_rate¶: Clip source frame rate in Hz.

property name¶: Clip name.

property start_time¶: Clip start time in seconds.

class kangengine.asset.FBXMaterialInfo[native]¶

Material metadata imported from an FBX file.

property diffuse_color¶: Diffuse color as RGBA.

property diffuse_texture_path¶: Resolved diffuse texture path.

property has_diffuse_texture¶: Whether a diffuse texture is referenced.

property has_embedded_diffuse_texture¶: Whether the diffuse texture was embedded in the FBX.

property has_embedded_normal_texture¶: Whether the normal texture was embedded in the FBX.

property has_normal_texture¶: Whether a normal texture is referenced.

property name¶: Material name.

property normal_texture_path¶: Resolved normal texture path.

class kangengine.asset.FBXMeshMetadata[native]¶

Summary metadata for a mesh imported from FBX.

property has_normals¶: Whether normals are present.

property has_skin¶: Whether skinning data is present.

property has_uvs¶: Whether UV coordinates are present.

property index_count¶: Number of indices.

property material_count¶: Number of assigned materials.

property materials¶: Material metadata assigned to this mesh.

property name¶: Mesh name.

property primary_material_index¶: Primary material index.

property skin_cluster_names¶: Names of skin clusters affecting this mesh.

property vertex_count¶: Number of vertices.

class kangengine.asset.FBXMeshInfo[native]¶

Imported static FBX mesh and material metadata.

property has_normals¶

property has_skin¶

property has_uvs¶

property index_count¶

property material_count¶

property materials¶

property mesh_data¶

property metadata¶

property name¶

property primary_material_index¶

property skin_cluster_names¶

property vertex_count¶

class kangengine.asset.FBXSkinnedMeshInfo[native]¶

Imported skinned-mesh data and skin bindings.

property bind_bone_matrices¶

property bind_mesh_matrices¶

property bone_indices¶

property bone_names¶

property bone_node_indices¶

property bone_weights¶

property has_normals¶

property has_skin¶

property has_uvs¶

property index_count¶

property inverse_bind_matrices¶

property material_count¶

property materials¶

property mesh_data¶

property metadata¶

property mismatched_cluster_count¶

property name¶

property normals¶

property overweight_vertex_count¶

property primary_material_index¶

property skin_cluster_names¶

property skinned_mesh_data¶

property unweighted_vertex_count¶

property vertex_count¶

property vertices¶

class kangengine.asset.FBXCharacterData[native]¶

An FBX motion and its skinned meshes.

property motion¶: Imported skeleton motion.

property skinned_meshes¶: Imported skinned meshes.

class kangengine.asset.USDLoader[native]¶

Load meshes from USD scenes.

static load_meshes(usd_path: str, scale: float = 1.0) → list¶: Load mesh payloads from a USD file.

static parse(usd_path: str, scale: float = 1.0) → USDImportResult¶: Parse USD and return meshes plus diagnostics.

class kangengine.asset.USDImportResult[native]¶

Parsed USD meshes plus diagnostics.

property diagnostics¶: Importer diagnostics.

property meshes¶: Meshes imported from the USD scene.

class kangengine.asset.USDMeshInfo[native]¶

Mesh payload imported from a USD scene.

property diffuse_texture_path¶: Resolved diffuse texture path.

property index_count¶

property material_path¶: USD material path if found.

property mesh_data¶

property name¶: Mesh name.

property normal_texture_path¶: Resolved normal texture path.

property prim_path¶: USD prim path.

property vertex_count¶

class kangengine.asset.AMASSInfo( path: Path, gender: str, betas: ndarray, fps: float, num_frames: int, ) → None[python]¶

Metadata read from an AMASS NPZ archive.

path¶

gender¶

betas¶

fps¶

num_frames¶

class kangengine.asset.AMASSLoader[python]¶

Load AMASS body and hand poses as a native SkeletonMotion.

static inspect(path: str | Path) → AMASSInfo¶

Return type:: AMASSInfo

static load_motion( path: str | Path, skeleton_tree: SkeletonTree, *, model_type: str = 'smplx', up_axis=<UpAxis.Y: 1>, scale: float = 1.0, motion_name: str | None = None, ) → SkeletonMotion¶

Load an AMASS NPZ directly into animation.SkeletonMotion.

Return type:: SkeletonMotion

class kangengine.asset.SMPLModel(path: str | Path)[python]¶

classmethod load(path: str | Path) → SMPLModel¶

Return type:: SMPLModel

create_body( betas: ArrayLike | None = None, ) → SMPLBody¶

Return type:: SMPLBody

class kangengine.asset.SMPLBody( skeleton_tree: SkeletonTree, surface_asset: SkinnedSurfaceAsset, joints: ndarray, discarded_weight_max: float, pose_directions: ndarray, ) → None[python]¶

skeleton_tree¶

surface_asset¶

joints¶

discarded_weight_max¶

pose_directions¶

create_visual( app: App, path: str, *, material: Material, color: ArrayLike | None = None, ) → SkinnedSurface¶

Return type:: SkinnedSurface

corrected_bind_vertices( rotations_wxyz: ArrayLike, ) → ndarray[tuple[Any, ...], dtype[float32]]¶

Evaluate SMPL pose blend shapes before LBS.

Return type:: ndarray[tuple[Any, ...], dtype[float32]]

update_pose_correctives( surface: SkinnedSurface, state: SkeletonState, *, enabled: bool = True, update_normals: bool = True, ) → SkinnedSurface¶

Update or clear pose-dependent geometry from a SkeletonState.

Return type:: SkinnedSurface

update_pose_correctives_from_rotations( surface: SkinnedSurface, local_rotations_wxyz: ArrayLike, *, enabled: bool = True, update_normals: bool = True, ) → SkinnedSurface¶

Update or clear pose-dependent geometry from raw local rotations.

Return type:: SkinnedSurface

class kangengine.asset.SMPLHModel(path: str | Path)[python]¶

Bases: SMPLModel

Standard 52-joint SMPL-H NPZ model adapter.

create_body( betas: ArrayLike | None = None, ) → SMPLHBody¶

Return type:: SMPLHBody

class kangengine.asset.SMPLHBody( skeleton_tree: SkeletonTree, surface_asset: SkinnedSurfaceAsset, joints: ndarray, discarded_weight_max: float, pose_directions: ndarray, ) → None[python]¶

Bases: SMPLBody

A 52-joint SMPL-H body and renderable surface asset.

class kangengine.asset.SMPLXModel(path: str | Path)[python]¶

Bases: SMPLModel

Standard 55-joint SMPL-X NPZ model adapter.

create_body( betas: ArrayLike | None = None, ) → SMPLXBody¶

Return type:: SMPLXBody

class kangengine.asset.SMPLXBody( skeleton_tree: SkeletonTree, surface_asset: SkinnedSurfaceAsset, joints: ndarray, discarded_weight_max: float, pose_directions: ndarray, ) → None[python]¶

Bases: SMPLBody

A 55-joint SMPL-X body and renderable surface asset.