embodichain.lab.sim.motion.workspace.visualizers

embodichain.lab.sim.motion.workspace.visualizers#

Workspace result visualizers deriving from BaseVisualizer.

Built-in visualizers: point-cloud, voxel, sphere, and axis, plus a VisualizerFactory and create_visualizer helper.

Classes:

`AxisVisualizer`	Visualizer for coordinate axes/frames at specified poses.
`BaseVisualizer`	Abstract base class for all visualizers.
`IVisualizer`	Interface for all visualizers.
`PointCloudVisualizer`	Point cloud visualizer using SimulationManager, Viser, or local tools.
`SphereVisualizer`	Sphere-based visualizer using Open3D or matplotlib.
`VisualizationType`
`VisualizerFactory`	Factory class for creating visualizers (Singleton pattern).
`VoxelVisualizer`	Voxel grid visualizer using Open3D or matplotlib.

Functions:

create_visualizer([viz_type])

Convenience function to create a visualizer.

class embodichain.lab.sim.motion.workspace.visualizers.AxisVisualizer[source]#

Bases: BaseVisualizer

Visualizer for coordinate axes/frames at specified poses.

This visualizer creates coordinate axes (X, Y, Z) at given transformation matrices, useful for visualizing robot end-effector poses, workspace reference frames, etc.

Supports multiple backends: - ‘sim_manager’: Uses SimulationManager.draw_marker() with MarkerCfg - ‘open3d’: Creates coordinate frames using Open3D - ‘matplotlib’: Draws axis lines in 3D matplotlib plot - ‘data’: Returns axis data without visualization

Methods:

`__init__`([backend, axis_length, axis_size, ...])	Initialize the axis visualizer.
`get_type_name`()	Return the type name for this visualizer.
`visualize`(poses[, colors])	Visualize coordinate axes at specified poses or points.

__init__(backend='sim_manager', axis_length=0.15, axis_size=0.005, config=None, sim_manager=None, control_part_name=None, reference_pose=None, arena_index=0)[source]#

Initialize the axis visualizer.

Parameters:

backend (str) – Visualization backend (‘sim_manager’, ‘open3d’, ‘matplotlib’, or ‘data’). Defaults to ‘sim_manager’.
axis_length (float) – Length of each axis. Defaults to 0.15.
axis_size (float) – Thickness/size of axes. Defaults to 0.005.
config (Optional[Dict[str, Any]]) – Optional configuration dictionary. Defaults to None.
sim_manager (Any | None) – SimulationManager instance for ‘sim_manager’ backend. Defaults to None.
control_part_name (str | None) – Control part name for naming (compatibility). Defaults to None.
reference_pose (Union[ndarray, Tensor, None]) – Reference pose (4x4 matrix) for orientation. Defaults to None.
arena_index (int) – Arena index for sim_manager markers. Defaults to 0.

get_type_name()[source]#

Return the type name for this visualizer.

Return type:: str

visualize(poses, colors=None, **kwargs)[source]#

Visualize coordinate axes at specified poses or points.

Parameters:

poses (Tensor | ndarray) – Either transformation matrices of shape (4, 4) or (N, 4, 4), or point coordinates of shape (N, 3) which will be converted to poses.
colors (Tensor | ndarray | None) – Optional colors (not used for axes but kept for interface compatibility).
**kwargs (Any) – Additional visualization parameters: - axis_length: Override default axis length - axis_size: Override default axis size - name_prefix: Prefix for axis names (default: “axis”) - arena_index: Arena index for sim_manager (default: 0)

Return type:

Any

Returns:

Backend-specific axis representation.

Examples

>>> import numpy as np
>>> visualizer = AxisVisualizer(backend='sim_manager', sim_manager=sim)
>>> # Using transformation matrix
>>> pose = np.eye(4)
>>> pose[:3, 3] = [1.0, 0.5, 1.2]  # Set position
>>> result = visualizer.visualize(pose)
>>>
>>> # Using point coordinates
>>> points = np.array([[1.0, 0.5, 1.2], [2.0, 1.0, 0.8]])
>>> result = visualizer.visualize(points)
>>> visualizer.show()

class embodichain.lab.sim.motion.workspace.visualizers.BaseVisualizer[source]#

Bases: ABC

Abstract base class for all visualizers.

This class provides common functionality and enforces the implementation of the visualization method in all derived classes.

backend#: Visualization backend (‘open3d’, ‘matplotlib’, etc.).

config#: Configuration dictionary for visualization parameters.

Methods:

`__init__`([backend, config])	Initialize the base visualizer.
`clear`()	Clear the current visualization.
`from_config`(config[, backend])	Create a visualizer instance from a VisualizationConfig.
`get_type_name`()	Get the name of the visualization type.
`save`(filepath, **kwargs)	Save the last visualization to file.
`show`(**kwargs)	Display the visualization interactively.
`visualize`(points[, colors])	Visualize the workspace data.

__init__(backend='open3d', config=None)[source]#

Initialize the base visualizer.

Parameters:

backend (str) – Visualization backend to use. Defaults to “open3d”.
config (Optional[Dict[str, Any]]) – Optional configuration dictionary. Defaults to None.

clear()[source]#

Clear the current visualization.

Return type:: None

classmethod from_config(config, backend='open3d')[source]#

Create a visualizer instance from a VisualizationConfig.

Parameters:

config (VisualizationConfig) – VisualizationConfig instance with visualization settings.
backend (str) – Visualization backend to use.

Returns:

Configured visualizer instance.

abstract get_type_name()[source]#

Get the name of the visualization type.

Return type:: str
Returns:: String identifier for the visualization type.

save(filepath, **kwargs)[source]#

Save the last visualization to file.

Parameters:

filepath (Union[str, Path]) – Path to save the visualization.
**kwargs (Any) – Additional save parameters.

Raises:

RuntimeError – If no visualization has been created yet.

Return type:

None

show(**kwargs)[source]#

Display the visualization interactively.

Parameters:: **kwargs (Any) – Backend-specific display parameters.
Raises:: RuntimeError – If no visualization has been created yet.
Return type:: None

abstract visualize(points, colors=None, **kwargs)[source]#

Visualize the workspace data.

This method must be implemented by all derived classes.

Parameters:

points (Tensor | ndarray) – Array of shape (N, 3) containing point positions.
colors (Tensor | ndarray | None) – Optional array of shape (N, 3) or (N, 4) containing colors.
**kwargs (Any) – Additional visualization parameters.

Return type:

Any

Returns:

Visualization object.

Raises:

NotImplementedError – If the method is not implemented in the derived class.

class embodichain.lab.sim.motion.workspace.visualizers.IVisualizer[source]#

Bases: Protocol

Interface for all visualizers.

This protocol defines the contract that all visualizers must follow.

Methods:

`__init__`(args, *kwargs)
`get_type_name`()	Get the name of the visualization type.
`save`(filepath, **kwargs)	Save visualization to file.
`visualize`(points[, colors])	Visualize the workspace data.

__init__(*args, **kwargs)#

get_type_name()[source]#

Get the name of the visualization type.

Return type:: str
Returns:: String identifier for the visualization type.

save(filepath, **kwargs)[source]#

Save visualization to file.

Parameters:

filepath (Union[str, Path]) – Path to save the visualization.
**kwargs (Any) – Additional save parameters.

Return type:

None

visualize(points, colors=None, **kwargs)[source]#

Visualize the workspace data.

Parameters:

points (Tensor | ndarray) – Array of shape (N, 3) containing point positions.
colors (Tensor | ndarray | None) – Optional array of shape (N, 3) or (N, 4) containing colors.
**kwargs (Any) – Additional visualization parameters.

Return type:

Any

Returns:

Visualization object (e.g., Open3D geometry, matplotlib figure).

class embodichain.lab.sim.motion.workspace.visualizers.PointCloudVisualizer[source]#

Bases: BaseVisualizer

Point cloud visualizer using SimulationManager, Viser, or local tools.

point_size#: Size of points in visualization.

Methods:

`__init__`([backend, point_size, config, ...])	Initialize the point cloud visualizer.
`get_type_name`()	Get the name of the visualization type.
`visualize`(points[, colors])	Visualize points as a point cloud.

__init__(backend='sim_manager', point_size=2.0, config=None, sim_manager=None, control_part_name=None)[source]#

Initialize the point cloud visualizer.

Parameters:

backend (str) – Visualization backend (‘sim_manager’, ‘viser’, ‘open3d’, ‘matplotlib’, or ‘data’). Defaults to ‘sim_manager’. The ‘data’ backend returns raw data without visualization.
point_size (float) – Size of points in visualization. Defaults to 2.0.
config (Optional[Dict[str, Any]]) – Optional configuration dictionary. Defaults to None.
sim_manager (Any | None) – SimulationManager instance for the ‘sim_manager’ or ‘viser’ backend. Defaults to None.
control_part_name (str | None) – Control part name used to name the point cloud. Defaults to None.

get_type_name()[source]#

Get the name of the visualization type.

Return type:: str
Returns:: String identifier for the visualization type.

visualize(points, colors=None, **kwargs)[source]#

Visualize points as a point cloud.

Parameters:

points (Tensor | ndarray) – Array of shape (N, 3) containing point positions.
colors (Tensor | ndarray | None) – Optional array of shape (N, 3) or (N, 4) containing colors.
**kwargs (Any) – Additional visualization parameters: - point_size: Override default point size

Return type:

Any

Returns:

Backend-specific point-cloud handle, Viser overlay, geometry, or matplotlib figure.

Examples

>>> visualizer = PointCloudVisualizer()
>>> points = np.random.rand(1000, 3)
>>> colors = np.random.rand(1000, 3)
>>> pcd = visualizer.visualize(points, colors)
>>> visualizer.show()

class embodichain.lab.sim.motion.workspace.visualizers.SphereVisualizer[source]#

Bases: BaseVisualizer

Sphere-based visualizer using Open3D or matplotlib.

sphere_radius#: Radius of each sphere.

sphere_resolution#: Resolution of sphere mesh (higher = smoother).

Methods:

`__init__`([backend, sphere_radius, ...])	Initialize the sphere visualizer.
`get_type_name`()	Get the name of the visualization type.
`visualize`(points[, colors])	Visualize points as spheres.

__init__(backend='sim_manager', sphere_radius=0.005, sphere_resolution=10, config=None, sim_manager=None, control_part_name=None)[source]#

Initialize the sphere visualizer.

Parameters:

backend (str) – Visualization backend (‘sim_manager’, ‘open3d’, ‘matplotlib’, or ‘data’). Defaults to ‘sim_manager’. ‘data’ backend returns sphere data without visualization.
sphere_radius (float) – Radius of each sphere. Defaults to 0.005.
sphere_resolution (int) – Sphere mesh resolution. Defaults to 10.
config (Optional[Dict[str, Any]]) – Optional configuration dictionary. Defaults to None.
sim_manager (Any | None) – SimulationManager instance for ‘sim_manager’ backend. Defaults to None.
control_part_name (str | None) – Control part name for naming. Defaults to None.

get_type_name()[source]#

Get the name of the visualization type.

Return type:: str
Returns:: String identifier for the visualization type.

visualize(points, colors=None, **kwargs)[source]#

Visualize points as spheres.

Parameters:

points (Tensor | ndarray) – Array of shape (N, 3) containing point positions.
colors (Tensor | ndarray | None) – Optional array of shape (N, 3) or (N, 4) containing colors.
**kwargs (Any) – Additional visualization parameters: - sphere_radius: Override default sphere radius - sphere_resolution: Override sphere resolution - max_spheres: Maximum number of spheres to render (for performance)

Return type:

Any

Returns:

Open3D TriangleMesh or matplotlib figure.

Examples

>>> visualizer = SphereVisualizer(sphere_radius=0.01)
>>> points = np.random.rand(100, 3)
>>> colors = np.random.rand(100, 3)
>>> mesh = visualizer.visualize(points, colors)
>>> visualizer.show()

class embodichain.lab.sim.motion.workspace.visualizers.VisualizationType[source]#

Bases: Enum

Attributes:

`AXIS`
`POINT_CLOUD`
`SPHERE`
`VOXEL`

AXIS = 'axis'#

POINT_CLOUD = 'point_cloud'#

SPHERE = 'sphere'#

VOXEL = 'voxel'#

class embodichain.lab.sim.motion.workspace.visualizers.VisualizerFactory[source]#

Bases: object

Factory class for creating visualizers (Singleton pattern).

This factory allows registration and creation of visualizers based on the visualization type. It uses the singleton pattern to ensure only one instance exists throughout the application.

The factory comes pre-registered with built-in visualizers:

POINT_CLOUD: PointCloudVisualizer
VOXEL: VoxelVisualizer
SPHERE: SphereVisualizer

Additional visualizers can be registered using register_visualizer().

Examples

>>> factory = VisualizerFactory()
>>> visualizer = factory.create_visualizer(
...     VisualizationType.POINT_CLOUD,
...     backend='open3d'
... )
>>> isinstance(visualizer, PointCloudVisualizer)
True

>>> # Register custom visualizer
>>> factory.register_visualizer("custom", CustomVisualizer)
>>> custom_viz = factory.create_visualizer("custom")

Methods:

`__init__`()	Initialize the factory with built-in visualizers.
`__new__`(cls)	Create or return the singleton instance.
`create_visualizer`([viz_type])	Create a visualizer instance based on the type.
`is_registered`(viz_type)	Check if a visualization type is registered.
`list_available_types`()	List all registered visualization types.
`register_visualizer`(name, visualizer_class)	Register a new visualizer class.
`reset_instance`()	Reset the singleton instance (mainly for testing).

__init__()[source]#

Initialize the factory with built-in visualizers.

This method only runs once due to the singleton pattern.

static __new__(cls)[source]#

Create or return the singleton instance.

Returns:: The singleton VisualizerFactory instance.

create_visualizer(viz_type=None, **kwargs)[source]#

Create a visualizer instance based on the type.

Parameters:

viz_type (VisualizationType | str | None) – The visualization type to use. Can be a VisualizationType enum or a string identifier. If None, defaults to POINT_CLOUD.
**kwargs (Any) – Additional keyword arguments to pass to the visualizer constructor. Common options include backend, voxel_size for VoxelVisualizer, sphere_radius for SphereVisualizer, and point_size for PointCloudVisualizer.

Return type:

BaseVisualizer

Returns:

An instance of the requested visualizer.

Raises:

ValueError – If the visualization type is not registered.

Examples

>>> factory = VisualizerFactory()
>>> viz = factory.create_visualizer(
...     VisualizationType.POINT_CLOUD,
...     backend='open3d'
... )
>>> viz = factory.create_visualizer("voxel", voxel_size=0.02)
>>> viz = factory.create_visualizer()  # Uses default (POINT_CLOUD)

is_registered(viz_type)[source]#

Check if a visualization type is registered.

Parameters:: viz_type (VisualizationType | str) – The visualization type to check.
Return type:: bool
Returns:: True if the type is registered, False otherwise.

list_available_types()[source]#

List all registered visualization types.

Return type:: list[str]
Returns:: List of registered type names.

register_visualizer(name, visualizer_class)[source]#

Register a new visualizer class.

Parameters:

name (str) – String identifier for the visualizer type.
visualizer_class (Type[BaseVisualizer]) – The visualizer class to register. Must inherit from BaseVisualizer.

Raises:

TypeError – If visualizer_class is not a subclass of BaseVisualizer.

Return type:

None

Examples

>>> factory = VisualizerFactory()
>>> factory.register_visualizer("my_viz", MyVisualizerClass)

classmethod reset_instance()[source]#: Reset the singleton instance (mainly for testing). :rtype: None

Warning

This should only be used in testing scenarios.

class embodichain.lab.sim.motion.workspace.visualizers.VoxelVisualizer[source]#

Bases: BaseVisualizer

Voxel grid visualizer using Open3D or matplotlib.

voxel_size#: Size of each voxel cube.

Methods:

`__init__`([backend, voxel_size, config, ...])	Initialize the voxel visualizer.
`get_type_name`()	Get the name of the visualization type.
`visualize`(points[, colors])	Visualize points as a voxel grid.

__init__(backend='sim_manager', voxel_size=0.01, config=None, sim_manager=None, control_part_name=None)[source]#

Initialize the voxel visualizer.

Parameters:

backend (str) – Visualization backend (‘sim_manager’, ‘open3d’, ‘matplotlib’, or ‘data’). Defaults to ‘sim_manager’. ‘data’ backend returns voxelized data without visualization.
voxel_size (float) – Size of each voxel. Defaults to 0.01.
config (Optional[Dict[str, Any]]) – Optional configuration dictionary. Defaults to None.
sim_manager (Any | None) – SimulationManager instance for ‘sim_manager’ backend. Defaults to None.
control_part_name (str | None) – Control part name for naming. Defaults to None.

get_type_name()[source]#

Get the name of the visualization type.

Return type:: str
Returns:: String identifier for the visualization type.

visualize(points, colors=None, **kwargs)[source]#

Visualize points as a voxel grid.

Parameters:

points (Tensor | ndarray) – Array of shape (N, 3) containing point positions.
colors (Tensor | ndarray | None) – Optional array of shape (N, 3) or (N, 4) containing colors.
**kwargs (Any) – Additional visualization parameters: - voxel_size: Override default voxel size

Return type:

Any

Returns:

Open3D VoxelGrid geometry or matplotlib figure.

Examples

>>> visualizer = VoxelVisualizer(voxel_size=0.02)
>>> points = np.random.rand(1000, 3)
>>> voxel_grid = visualizer.visualize(points)
>>> visualizer.show()

embodichain.lab.sim.motion.workspace.visualizers.create_visualizer(viz_type=None, **kwargs)[source]#

Convenience function to create a visualizer.

This is a shorthand for VisualizerFactory().create_visualizer().

Parameters:

viz_type (VisualizationType | str | None) – The visualization type to use.
**kwargs (Any) – Additional keyword arguments to pass to the visualizer constructor.

Return type:

BaseVisualizer

Returns:

An instance of the requested visualizer.

Examples

>>> viz = create_visualizer(VisualizationType.POINT_CLOUD, backend='open3d')
>>> viz = create_visualizer("voxel", voxel_size=0.02)

embodichain.lab.sim.motion.workspace.visualizers

Contents

embodichain.lab.sim.motion.workspace.visualizers#