ke.visual¶

Python viewer-side bridges for scene objects, animated characters, and simulation state visualization.

Scene and asset visuals¶

`ArticulationVisual`	Viewer-side articulated rigid-link visual object.
`ArticulationVisualAsset`	Reusable articulated rigid-link visual asset that can instantiate scene prims.
`ArticulatedSurface`	Application-owned FK surface composed of rigid link meshes.
`ArticulatedSurfaceAsset`	Reusable MJCF skeleton and rigid-link mesh asset.
`DeformableSurface`	TODO scaffold for directly streamed deformable geometry.
`SkinVisual`	Skinned-character visual bridge created from an FBX asset.
`SkinnedSurface`	One or more skinned render parts driven by a shared skeleton.
`SkinnedSurfaceAsset`	Static topology and four-weight LBS data uploaded once.
`SkeletalVisual`	Instanced line/point renderer for skeleton poses and motion clips.
`SkeletalVisualConfig`	Style settings for SkeletalVisual line/joint rendering.

class kangengine.visual.ArticulationVisual[native]¶

Viewer-side articulated rigid-link visual object.

apply_pose(self: kangengine.animation.ArticulationVisual) → None¶: Apply the current skeleton/body state to scene prims.

body_prim( self: kangengine.animation.ArticulationVisual, index: int, ) → Prim¶: Return the scene prim for a body index.

body_prims( self: kangengine.animation.ArticulationVisual, ) → list[Prim]¶: Return all body scene prims.

static from_mjcf( mjcf_path: str, scene: SceneBackend, path: str = '/robot', scale: float = 1.0, order: str = 'DFS', mesh_asset_base_path: str = '', ) → kangengine.animation.ArticulationVisual¶: Create an articulation visual and scene prims from an MJCF file.

num_bodies(self: kangengine.animation.ArticulationVisual) → int¶: Return the number of bridged bodies.

render_prim_body_indices( self: kangengine.animation.ArticulationVisual, ) → list[int]¶: Return body index for each render prim.

render_prims( self: kangengine.animation.ArticulationVisual, ) → list[Prim]¶: Return actual renderable mesh prims.

reset_to_zero_pose( self: kangengine.animation.ArticulationVisual, ) → None¶: Reset all joint rotations and root translation to zero pose.

set_joint_rotation(*args, **kwargs)¶

Overloaded function.

set_joint_rotation(self: kangengine.animation.ArticulationVisual, index: int, rotation: npt.ArrayLike | torch.Tensor) -> None

Set a joint rotation from an XYZW array.

set_joint_rotation(self: kangengine.animation.ArticulationVisual, index: int, rotation: glm::qua<float, (glm::qualifier)0>) -> None

Set a joint rotation from a quaternion.

set_root_translation(*args, **kwargs)¶

Overloaded function.

set_root_translation(self: kangengine.animation.ArticulationVisual, translation: npt.ArrayLike | torch.Tensor) -> None

Set the root translation from an array.

set_root_translation(self: kangengine.animation.ArticulationVisual, translation: glm::vec<3, float, (glm::qualifier)0>) -> None

Set the root translation from a vec3.

skeleton( self: kangengine.animation.ArticulationVisual, ) → SkeletonTree¶: Return the bridged skeleton tree.

state( self: kangengine.animation.ArticulationVisual, ) → SkeletonState¶: Return the mutable current skeleton state.

class kangengine.visual.ArticulationVisualAsset[native]¶

Reusable articulated rigid-link visual asset that can instantiate scene prims.

define_mesh_assets( self: kangengine.animation.ArticulationVisualAsset, scene: SceneBackend, mesh_asset_base_path: str, split_visual_geoms: bool = False, ) → None¶: Define shared mesh asset prims in a scene.

static from_mjcf( mjcf_path: str, scale: float = 1.0, order: str = 'DFS', ) → kangengine.animation.ArticulationVisualAsset¶: Load reusable bridge asset data from an MJCF file.

instantiate( self: kangengine.animation.ArticulationVisualAsset, scene: SceneBackend, path: str = '/robot', mesh_asset_base_path: str = '', split_visual_geoms: bool = False, ) → kangengine.animation.ArticulationVisual¶: Instantiate this asset into a scene.

num_bodies( self: kangengine.animation.ArticulationVisualAsset, ) → int¶: Return the number of bodies in this asset.

class kangengine.visual.ArticulatedSurfaceAsset(native: Any, mesh_asset_path: str)[python]¶

Reusable MJCF skeleton and rigid-link mesh asset.

classmethod from_mjcf( mjcf_path: str | Path, *, scale: float = 1.0, order: str = 'DFS', ) → ArticulatedSurfaceAsset¶

Load a reusable kinematic surface asset from MJCF.

Return type:: ArticulatedSurfaceAsset

property num_bodies¶

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

Create an independently posed surface instance.

Return type:: ArticulatedSurface

class kangengine.visual.ArticulatedSurface( app: App, path: str, asset: ArticulatedSurfaceAsset, native: Any, views: list[RenderablePrimView], material: Material, )[python]¶

Application-owned FK surface composed of rigid link meshes.

classmethod create_from_mjcf( app: App, path: str, mjcf_path: str | Path, *, material: Material, color: ArrayLike | None = None, scale: float = 1.0, order: str = 'DFS', ) → ArticulatedSurface¶

Load an MJCF asset and create its first kinematic instance.

Return type:: ArticulatedSurface

property asset¶

property skeleton_tree¶

property prims¶

property views¶

create_instance( path: str, *, material: Material | None = None, color: ArrayLike | None = None, ) → ArticulatedSurface¶

Create a visual-only instance initialized from the current pose.

Return type:: ArticulatedSurface

apply_state( state: SkeletonState, ) → ArticulatedSurface¶

Apply a SkeletonState to the rigid links.

Return type:: ArticulatedSurface

apply_pose( root_translation: ArrayLike, local_rotations_wxyz: ArrayLike, ) → ArticulatedSurface¶

Apply a raw root translation and WXYZ local joint rotations.

Return type:: ArticulatedSurface

set_color( color: ArrayLike, ) → ArticulatedSurface¶

Return type:: ArticulatedSurface

set_alpha_mode( mode: Any, cutoff: float = 0.5, ) → ArticulatedSurface¶

Return type:: ArticulatedSurface

set_alpha( alpha: float, ) → ArticulatedSurface¶

Return type:: ArticulatedSurface

set_visible( visible: bool, ) → ArticulatedSurface¶

Return type:: ArticulatedSurface

set_casts_shadow( enabled: bool = True, ) → ArticulatedSurface¶

Return type:: ArticulatedSurface

remove() → bool¶

Remove the instance while preserving its shared asset resources.

Return type:: bool

class kangengine.visual.SkinnedSurfaceAsset( skeleton_tree: SkeletonTree, positions: ndarray[tuple[Any, ...], dtype[float32]], normals: ndarray[tuple[Any, ...], dtype[float32]], indices: ndarray[tuple[Any, ...], dtype[int32]], bone_indices: ndarray[tuple[Any, ...], dtype[int32]], bone_weights: ndarray[tuple[Any, ...], dtype[float32]], bone_node_indices: ndarray[tuple[Any, ...], dtype[int32]], inverse_bind_matrices: ndarray[tuple[Any, ...], dtype[float32]], uvs: ndarray[tuple[Any, ...], dtype[float32]] | None = None, ) → None[python]¶

Static topology and four-weight LBS data uploaded once.

skeleton_tree¶

positions¶

normals¶

indices¶

bone_indices¶

bone_weights¶

bone_node_indices¶

inverse_bind_matrices¶

uvs = None¶

classmethod from_fbx( skeleton_tree: SkeletonTree, mesh_info: FBXSkinnedMeshInfo, ) → SkinnedSurfaceAsset¶

Convert one imported FBX skinned mesh without reading the file again.

Return type:: SkinnedSurfaceAsset

create_native() → tuple[Any, Any]¶

Return type:: tuple[Any, Any]

class kangengine.visual.SkinnedSurface( view: Any, asset: SkinnedSurfaceAsset, app: Any, material: Any, native_mesh: Any, native_skin: Any, )[python]¶

One or more skinned render parts driven by a shared skeleton.

classmethod create( app: App, path: str, asset: SkinnedSurfaceAsset, *, material: Material, color: ArrayLike | None = None, ) → SkinnedSurface¶

Return type:: SkinnedSurface

classmethod create_from_fbx( app: App, path: str, skeleton_tree: SkeletonTree, mesh_info: FBXSkinnedMeshInfo, *, material: Material, color: ArrayLike | None = None, ) → SkinnedSurface¶

Create one surface from one already imported FBX skinned mesh.

Return type:: SkinnedSurface

classmethod create_from_fbx_result( app: App, path: str, result: FBXImportResult, *, material: Material | None = None, color: ArrayLike | None = None, use_imported_materials: bool = True, ) → SkinnedSurface¶

Create one logical surface from every skinned mesh in an FBX result.

By default, distinct imported FBX materials become retained PBR materials. Passing material applies one caller-owned override to every part instead.

Return type:: SkinnedSurface

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

Create an independently posed instance sharing this surface’s assets.

Bind geometry, skin weights, textures, and materials are shared unless a material override is supplied. The new prims and runtime skinning buffers are independent from the source surface.

Return type:: SkinnedSurface

property prim¶

property prims¶

property view¶

property views¶

property asset¶

property assets¶

property skeleton_tree¶

remove() → bool¶

Remove every render part from the scene.

Shared assets and materials remain alive for other surface instances. Calling remove more than once is safe and returns False after the first call.

Return type:: bool

update_joint_matrices( joint_matrices: ArrayLike, ) → SkinnedSurface¶

Return type:: SkinnedSurface

update_bind_geometry( positions: ArrayLike, normals: ArrayLike | None = None, ) → SkinnedSurface¶

Update pre-skinning vertices on a single-part surface.

Return type:: SkinnedSurface

reset_bind_geometry() → SkinnedSurface¶

Restore original bind vertices on a single-part surface.

Return type:: SkinnedSurface

set_visible( visible: bool, ) → SkinnedSurface¶

Return type:: SkinnedSurface

set_casts_shadow( enabled: bool = True, ) → SkinnedSurface¶

Return type:: SkinnedSurface

set_alpha_mode( mode: AlphaMode, cutoff: float = 0.5, ) → SkinnedSurface¶

Return type:: SkinnedSurface

set_color( color: ArrayLike, ) → SkinnedSurface¶

Return type:: SkinnedSurface

set_alpha(alpha: float) → SkinnedSurface¶

Set per-instance opacity without modifying the shared material.

Return type:: SkinnedSurface

apply_state( state: SkeletonState, ) → SkinnedSurface¶

Apply a SkeletonState to the skinned vertices.

Return type:: SkinnedSurface

apply_pose( root_translation: ArrayLike, local_rotations_wxyz: ArrayLike, ) → SkinnedSurface¶

Apply a raw root translation and WXYZ local joint rotations.

Return type:: SkinnedSurface

class kangengine.visual.DeformableSurface(view: Any)[python]¶

TODO scaffold for directly streamed deformable geometry.

This path does not yet guarantee per-surface geometry isolation or complete dynamic bounds handling. It is not a supported cloth/soft-body visual API.

classmethod create( app: Any, path: str, positions: ArrayLike, normals: ArrayLike, indices: ArrayLike, material: Any, color: Any = None, ) → DeformableSurface¶

Return type:: DeformableSurface

property prim¶

update( positions: ArrayLike, normals: ArrayLike | None = None, ) → DeformableSurface¶

Upload geometry through the current experimental batch path.

Return type:: DeformableSurface

set_visible( visible: bool, ) → DeformableSurface¶

Return type:: DeformableSurface

set_casts_shadow( enabled: bool = True, ) → DeformableSurface¶

Return type:: DeformableSurface

set_alpha_mode( mode: Any, cutoff: float = 0.5, ) → DeformableSurface¶

Return type:: DeformableSurface

class kangengine.visual.SkinVisual[native]¶

Skinned-character visual bridge created from an FBX asset.

apply_pose( self: kangengine.SkinVisual, root_translation: npt.ArrayLike | torch.Tensor, local_rotations_wxyz: npt.ArrayLike | torch.Tensor, ) → SkeletonState¶

apply_time( self: kangengine.SkinVisual, time: float, loop: bool = True, ) → SkeletonState¶

static from_fbx( app: App, material: kangengine.Material, fbx_path: str, bind_fbx_path: str | None = None, path: str = '/fbx_character', clip_index: int = -1, fps: float = -1.0, scale: float = 0.009999999776482582, use_materials: bool = True, ) → kangengine.SkinVisual¶

motion(self: kangengine.SkinVisual) → SkeletonMotion¶

num_meshes(self: kangengine.SkinVisual) → int¶

set_casts_shadow(self: kangengine.SkinVisual, enabled: bool = True) → None¶

set_color(self: kangengine.SkinVisual, color: kangengine.Vec4) → None¶

set_visible(self: kangengine.SkinVisual, visible: bool) → None¶

class kangengine.visual.SkeletalVisualConfig[native]¶

Style settings for SkeletalVisual line/joint rendering.

__init__( *, bone_color: glm::vec<4, float, (glm: :qualifier)0> | None = None, joint_color: glm::vec<4, float, (glm: :qualifier)0> | None = None, bone_radius: float = 0.006000000052154064, joint_radius: float = 0.02500000037252903, segments: int = 8, visible: bool = True, show_joints: bool = True, )¶: Create skeleton visual settings from keyword fields.

property bone_color¶: RGBA color for bones.

property bone_radius¶: Radius used for bone line geometry.

property joint_color¶: RGBA color for joints.

property joint_radius¶: Radius used for joint point geometry.

property segments¶: Segment count for generated round geometry.

property show_joints¶: Whether joint markers should be visible.

property visible¶: Initial visibility state.

class kangengine.visual.SkeletalVisual[native]¶

Instanced line/point renderer for skeleton poses and motion clips.

apply_motion( self: kangengine.animation.SkeletalVisual, motion: SkeletonMotion, time: float, loop: bool = True, ) → None¶: Update visuals by sampling a SkeletonMotion.

apply_state( self: kangengine.animation.SkeletalVisual, state: SkeletonState, ) → None¶: Update visuals from a SkeletonState.

bone_handle(self: kangengine.animation.SkeletalVisual) → int¶: Return the renderable handle used for bones.

static define(*args, **kwargs)¶

Overloaded function.

define(app: KE::App, material: kangengine.Material, path: str, state: kangengine.animation.SkeletonState, config: kangengine.animation.SkeletalVisualConfig = SkeletalVisualConfig(bone_color=(0.686, 0.867, 1, 1), joint_color=(1, 0.745, 0.675, 1), bone_radius=0.006, joint_radius=0.025, segments=8, visible=True, show_joints=True)) -> kangengine.animation.SkeletalVisual

Create skeleton visuals from a SkeletonState.

define(app: KE::App, material: kangengine.Material, path: str, motion: kangengine.animation.SkeletonMotion, time: float = 0.0, loop: bool = True, config: kangengine.animation.SkeletalVisualConfig = SkeletalVisualConfig(bone_color=(0.686, 0.867, 1, 1), joint_color=(1, 0.745, 0.675, 1), bone_radius=0.006, joint_radius=0.025, segments=8, visible=True, show_joints=True)) -> kangengine.animation.SkeletalVisual

Create skeleton visuals by sampling a SkeletonMotion.

joint_handle(self: kangengine.animation.SkeletalVisual) → int¶: Return the renderable handle used for joints.

set_show_joints( self: kangengine.animation.SkeletalVisual, show_joints: bool, ) → None¶: Show or hide joint markers.

set_visible( self: kangengine.animation.SkeletalVisual, visible: bool, ) → None¶: Set visibility for all skeleton visuals.

Simulation visual sync¶

ke.visual.sim mirrors KangSimWorld objects into scene and render visuals. These objects own visualization state only; simulation state remains owned by the world and its simulation handles.

`SimWorldVisualizer`	Viewer-side visualizer for one KangSimWorld.
`VisualBatch`	Handle returned by `SimWorldVisualizer.add(...)`.
`VisualBodyPick`	High-level body pick result resolved from a renderer selection.
`VisualRigidSceneGraph`	Viewer-side visual wrapper for one rigid object.
`VisualArticulationSceneGraph`	Viewer-side visual wrapper for one articulation.

class kangengine.visual.sim.SimWorldVisualizer(app, world)[python]¶

Viewer-side visualizer for one KangSimWorld.

This class syncs render/scene visuals from simulation objects. It is not the canonical state owner; use world.state / world.refresh() for runtime state consumed by policy or training code.

add(

sim_handle: SimRigid | SimArticulation | SimRigidBatch | SimArticulationBatch,

mjcf_path: str,

*,

path: str | None = None,

**kwargs,

) → VisualBatch¶

Create one CPU or GPU ExternalBuffer VisualBatch.

sim_handle may be a single SimRigid / SimArticulation or a SimRigidBatch / SimArticulationBatch. Single objects are treated as a one-env visual batch. Use add_scene_graph when an inspectable per-environment SceneGraph visual is required.

Return type:: VisualBatch

add_articulation_scene_graph( env_id: int, obj_id: int, mjcf_path: str, *, path: str = '/robot', scale: float = 1.0, order: str = 'DFS', material=None, add_shapes: bool = True, collision_path: str | None = None, collision_material=None, show_collision: bool = False, color=None, _debug_registration: bool = True, ) → VisualArticulationSceneGraph¶

Prefer add(sim_handle, ...) for normal simulation viewers. This path is kept for editor/debug tools, collision visual inspection, and MimicKit-style per-body SceneGraph control.

Return type:: VisualArticulationSceneGraph

add_articulation_skin( env_id: int, obj_id: int, mjcf_path: str, *, path: str = '/robot', scale: float = 1.0, order: str = 'DFS', material=None, add_shapes: bool = True, color=None, ) → VisualArticulationSceneGraph¶

Create an adapter/debug articulation skin without PhysX ownership.

Return type:: VisualArticulationSceneGraph

add_rigid_scene_graph( env_id: int, obj_id: int, mjcf_path: str, *, path: str = '/rigid', scale: float = 1.0, order: str = 'DFS', material=None, add_shapes: bool = True, color=None, _debug_registration: bool = True, ) → VisualRigidSceneGraph¶

Prefer add(sim_handle, ...) for normal simulation viewers. This path remains for editor/debug tools and adapter code that needs direct prim access.

Return type:: VisualRigidSceneGraph

Create one inspectable SceneGraph visual for a simulation object.

Unlike add(), this path creates ordinary SceneGraph-owned prims and is intended for detailed playback and editor inspection. A batch handle requires env_id so accidentally expanding every training environment into prims is impossible.

Return type:: VisualArticulationSceneGraph | VisualRigidSceneGraph

body_id_from_render_handle_scene_graph( env_id: int, obj_id: int, handle, ) → int | None¶

Low-level scene-graph handle lookup; prefer pick_body(selection).

Return type:: int | None

cleanup()¶

get_visual_articulation_scene_graph( env_id: int, obj_id: int, ) → VisualArticulationSceneGraph | None¶

Return type:: VisualArticulationSceneGraph | None

get_visual_batch( obj_id: int, ) → VisualBatch | None¶

Return type:: VisualBatch | None

get_visual_rigid_scene_graph( env_id: int, obj_id: int, ) → VisualRigidSceneGraph | None¶

Return type:: VisualRigidSceneGraph | None

get_visual_scene_graph( env_id: int, obj_id: int, ) → VisualArticulationSceneGraph | VisualRigidSceneGraph | None¶

Return type:: VisualArticulationSceneGraph | VisualRigidSceneGraph | None

property is_valid¶

pick_body(selection) → VisualBodyPick | None¶

Resolve a renderer selection to visual env/object/body metadata.

Return type:: VisualBodyPick | None

release()¶

set_articulation_color_scene_graph(env_id: int, obj_id: int, color)¶

set_body_transforms_scene_graph( env_id: int, obj_id: int, body_pos=None, body_rot=None, )¶

Override rendered body prim transforms with world-space FK poses.

This is used by MimicKit view_motion, where the environment computes the reference pose itself and expects the engine viewer to draw that pose.

set_collision_visible(visible: bool)¶

set_root_transform_scene_graph( env_id: int, obj_id: int, root_pos=None, root_rot=None, )¶

Apply a root-only fallback pose to a visual articulation.

MimicKit visual/reference objects are not backed by PhysX, but some envs still drive them through root setters before or instead of body setters. ArticulationVisual keeps a zero-pose FK model that can at least move the whole rendered character with that root pose.

sync()¶

class kangengine.visual.sim.VisualBatch(obj_id, env_ids, *, backend)[python]¶

Handle returned by SimWorldVisualizer.add(...).

The handle owns no simulation state. It delegates visual operations to a CPU or GPU ExternalBuffer backend. The low-level C++ transform batch remains exposed as kangengine.physics.SimVisualBatch.

property body_handles¶

body_id_from_render_handle(handle)¶

property collision_visuals¶

property is_valid¶

property key¶

property num_bodies¶

property num_envs¶

pick_body(selection) → VisualBodyPick | None¶

Return type:: VisualBodyPick | None

property prims¶

release()¶

set_collision_visible(visible: bool)¶

set_color(color)¶

set_visible(visible: bool)¶

sync()¶

class kangengine.visual.sim.VisualBodyPick(env_id: int | None, obj_id: int, body_id: int, visual: object) → None[python]¶

High-level body pick result resolved from a renderer selection.

env_id¶

obj_id¶

body_id¶

visual¶

class kangengine.visual.sim.VisualRigidSceneGraph( env_id: int, obj_id: int, rigid: object, rigid_visual: object, body_prims: list[object], body_handles: list[int], ) → None[python]¶

Viewer-side visual wrapper for one rigid object.

env_id¶

obj_id¶

rigid¶

rigid_visual¶

body_prims¶

body_handles¶

body_id_from_render_handle(handle) → int | None¶

Return type:: int | None

property key¶

property num_bodies¶

pick_body( selection, ) → VisualBodyPick | None¶

Return type:: VisualBodyPick | None

property prims¶

set_color(color)¶

set_visible(visible: bool)¶

class kangengine.visual.sim.VisualArticulationSceneGraph( env_id: int, obj_id: int, articulation_visual: object, body_prims: list[object], render_prims: list[object], collision_prims: list[object], body_handles: list[int], handle_body_ids: dict[int, int] | None = None, ) → None[python]¶

Viewer-side visual wrapper for one articulation.

env_id¶

obj_id¶

articulation_visual¶

body_prims¶

render_prims¶

collision_prims¶

body_handles¶

handle_body_ids¶

body_id_from_render_handle(handle) → int | None¶

Return type:: int | None

property collision_visuals¶

property key¶

property num_bodies¶

pick_body( selection, ) → VisualBodyPick | None¶

Return type:: VisualBodyPick | None

property prims¶

set_alpha(alpha: float)¶

set_collision_visible(visible: bool)¶

set_color(color)¶

set_visible(visible: bool)¶

property visual_prims¶