embodichain.lab.sim.motion.workspace

embodichain.lab.sim.motion.workspace#

Robot workspace analysis and runtime sampling.

Runtime types are imported eagerly because Robot depends on them. Analyzer types and their heavier visualization dependencies are loaded lazily to keep the Robot import path free of circular dependencies.

Classes:

`AnalysisMode`	Workspace analysis mode.
`RobotWorkspace`	Reachable Cartesian samples backed by aligned joint configurations.
`RobotWorkspaceCfg`	Runtime configuration for a control-part workspace cache.
`WorkspaceAnalyzer`	Main workspace analyzer class for robotic manipulation.
`WorkspaceAnalyzerConfig`	Complete configuration for workspace analyzer.
`WorkspaceSample`	A batch of cached, reachable robot configurations and FK poses.

class embodichain.lab.sim.motion.workspace.AnalysisMode[source]#

Bases: Enum

Workspace analysis mode.

Attributes:

`CARTESIAN_SPACE`	Sample in Cartesian space, compute IK to verify reachability.
`JOINT_SPACE`	Sample in joint space, compute FK to get workspace points.
`PLANE_SAMPLING`	Sample on a specific plane within Cartesian space.

CARTESIAN_SPACE = 'cartesian_space'#: Sample in Cartesian space, compute IK to verify reachability.

JOINT_SPACE = 'joint_space'#: Sample in joint space, compute FK to get workspace points.

PLANE_SAMPLING = 'plane_sampling'#: Sample on a specific plane within Cartesian space.

class embodichain.lab.sim.motion.workspace.RobotWorkspace[source]#

Bases: object

Reachable Cartesian samples backed by aligned joint configurations.

The cached Cartesian points are used to define the sampling distribution. Runtime callers should recompute end-effector poses from qpos so the result uses the robot base pose of the target environment.

Attributes:

`SUPPORTED_STRATEGIES`
`device`	Return the device holding workspace tensors.
`num_samples`	Return the number of cached reachable samples.

Methods:

`__init__`(positions, qpos, *[, scores, ...])	Initialize a runtime workspace.
`from_cache`(cache_path, *[, device, voxel_size])	Load an analyzer results cache for runtime sampling.
`sample_indices`(count, *[, strategy, ...])	Sample cache indices.
`to`(device)	Move workspace tensors to a device in-place.

SUPPORTED_STRATEGIES = ('point_uniform', 'voxel_uniform')#

__init__(positions, qpos, *, scores=None, voxel_size=0.03, metadata=None, source_path=None)[source]#

Initialize a runtime workspace.

Parameters:

positions (Tensor) – Cached Cartesian positions, shape (N, 3).
qpos (Tensor) – Joint configurations aligned with positions, shape (N, D).
scores (Tensor | None) – Optional score aligned with positions, shape (N,).
voxel_size (float) – Cartesian voxel edge length in meters.
metadata (dict | None) – Optional cache metadata.
source_path (str | Path | None) – Optional source cache path.

Raises:

ValueError – If tensors are empty, have incompatible shapes, or voxel_size is not positive.

property device: device#: Return the device holding workspace tensors.

classmethod from_cache(cache_path, *, device='cpu', voxel_size=0.03)[source]#

Load an analyzer results cache for runtime sampling.

Parameters:

cache_path (str | Path) – Cache entry directory or direct results.npz path.
device (device | str) – Device on which runtime tensors are stored.
voxel_size (float) – Cartesian voxel edge length in meters.

Return type:

RobotWorkspace

Returns:

Loaded runtime workspace.

Raises:

FileNotFoundError – If the cache archive does not exist.
ValueError – If no point set aligns with joint_configurations.

property num_samples: int#: Return the number of cached reachable samples.

sample_indices(count, *, strategy='voxel_uniform', min_score=None, generator=None)[source]#

Sample cache indices.

Parameters:

count (int) – Number of indices to return.
strategy (Literal['point_uniform', 'voxel_uniform']) – Point-uniform or Cartesian-voxel-uniform sampling.
min_score (float | None) – Optional minimum cached score.
generator (Generator | None) – Optional random number generator.

Return type:

Tensor

Returns:

Index tensor with shape (count,).

Raises:

ValueError – If arguments are invalid or filters reject every point.

to(device)[source]#

Move workspace tensors to a device in-place.

Parameters:: device (device | str) – Target torch device.
Return type:: RobotWorkspace
Returns:: This workspace instance.

class embodichain.lab.sim.motion.workspace.RobotWorkspaceCfg[source]#

Bases: object

Runtime configuration for a control-part workspace cache.

Methods:

`__init__`([cache_path, strategy, voxel_size, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`cache_path`	Path to a workspace cache entry directory or `results.npz` file.
`min_score`	Optional minimum cached reachability score accepted for sampling.
`strategy`	Default runtime sampling strategy.
`voxel_size`	Cartesian voxel edge length in meters for voxel-uniform sampling.

__init__(cache_path=<factory>, strategy=<factory>, voxel_size=<factory>, min_score=<factory>)#

cache_path: str#: Path to a workspace cache entry directory or results.npz file.

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

min_score: float | None#: Optional minimum cached reachability score accepted for sampling.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

strategy: Literal['point_uniform', 'voxel_uniform']#: Default runtime sampling strategy.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

voxel_size: float#: Cartesian voxel edge length in meters for voxel-uniform sampling.

class embodichain.lab.sim.motion.workspace.WorkspaceAnalyzer[source]#

Bases: object

Main workspace analyzer class for robotic manipulation.

Analyzes the reachable workspace of a robot by sampling joint configurations, computing forward kinematics, and generating metrics and visualizations.

Note

Currently designed for single environment operation (num_envs=1). When multiple environments are present, the analyzer will use the first environment (index 0) and log appropriate warnings. Multi-environment support will be added in future versions.

Attributes:

DEFAULT_CONTROL_PART_PRIORITY

Methods:

`__init__`(robot[, config, sim_manager])	Initialize the workspace analyzer.
`analyze`([num_samples, force_recompute, ...])	Perform complete workspace analysis.
`compute_reachability`(cartesian_points[, ...])	Compute reachability for Cartesian points using batched IK.
`compute_workspace_points`(joint_configs[, ...])	Compute end-effector positions for given joint configurations.
`export_results`(output_path[, format])	Export analysis results to file.
`get_results_cache_path`()	Get the path to the most recently used results cache entry.
`get_workspace_bounds`()	Get the bounding box of the analyzed workspace.
`profiling`()	Enhanced context manager for profiling workspace analysis with detailed metrics.
`sample_cartesian_space`([num_samples])	Sample Cartesian positions within workspace bounds.
`sample_joint_space`([num_samples])	Sample joint configurations within joint limits.
`sample_plane`([num_samples, plane_normal, ...])	Sample points on a specified plane using existing samplers (ultra-simplified version).
`visualize`([vis_type, show, save_path, backend])	Visualize the workspace.

DEFAULT_CONTROL_PART_PRIORITY = ['left_arm', 'right_arm']#

__init__(robot, config=None, sim_manager=None)[source]#

Initialize the workspace analyzer.

Parameters:

robot (Robot) – Robot instance to analyze.
config (WorkspaceAnalyzerConfig | None) – Configuration object. If None, uses defaults.
sim_manager (SimulationManager | None) – SimulationManager instance. Defaults None.

analyze(num_samples=None, force_recompute=False, visualize=False)[source]#

Perform complete workspace analysis.

Parameters:

num_samples (int | None) – Number of samples to generate. If None, uses config value.
force_recompute (bool) – If True, recomputes even if cached results exist.
visualize (bool) – If True, visualizes the workspace points. Prefers sim_manager visualization if available, otherwise falls back to visualizers module.

Return type:

Dict[str, Any]

Returns:

Dictionary containing analysis results.

compute_reachability(cartesian_points, batch_size=None)[source]#

Compute reachability for Cartesian points using batched IK.

All ik_samples_per_point random seeds for a batch of points are merged into the batch dimension and resolved with a single robot.compute_batch_ik call (shape (1, n_valid * K, 4, 4)). This avoids the Python loop overhead and lets the solver process all seeds in one vectorised pass.

Parameters:

cartesian_points (Tensor) – Cartesian positions, shape (num_samples, 3).
batch_size (int | None) – Batch size for IK computation. If None, uses config value.

Returns:

all_points: All Cartesian positions, shape (num_samples, 3)
reachable_points: Reachable positions, shape (num_reachable, 3)
success_rates: IK success rate for each point, shape (num_samples,)
reachability_mask: Boolean mask indicating reachable points, shape (num_samples,)
best_configs: Best joint configurations, shape (num_reachable, num_joints)

Return type:

Tuple of

compute_workspace_points(joint_configs, batch_size=None)[source]#

Compute end-effector positions for given joint configurations.

Uses batched FK computation via robot.compute_batch_fk for significant speedup on large sample counts.

Parameters:

joint_configs (Tensor) – Joint configurations, shape (num_samples, num_joints).
batch_size (int | None) – Batch size for FK computation. If None, uses config value.

Returns:

workspace_points: End-effector positions, shape (num_valid, 3)
valid_configs: Valid joint configurations, shape (num_valid, num_joints)

Return type:

Tuple of

current_mode: AnalysisMode | None#

export_results(output_path, format='npz')[source]#

Export analysis results to file.

Parameters:

output_path (str) – Path to save the results.
format (str) – Output format (‘npz’, ‘pkl’, ‘json’).

Return type:

None

get_results_cache_path()[source]#

Get the path to the most recently used results cache entry.

Return type:: Path | None
Returns:: Path to the cache entry directory, or None if no disk results cache has been read or written yet.

get_workspace_bounds()[source]#

Get the bounding box of the analyzed workspace.

Return type:: Dict[str, ndarray]
Returns:: Dictionary with ‘min’ and ‘max’ bounds.

joint_configurations: Tensor | None#

metrics_results: Dict[str, Any]#

profiling()[source]#: Enhanced context manager for profiling workspace analysis with detailed metrics.

sample_cartesian_space(num_samples=None)[source]#

Sample Cartesian positions within workspace bounds.

Parameters:: num_samples (int | None) – Number of samples to generate. If None, uses config value.
Return type:: Tensor
Returns:: Tensor of shape (num_samples, 3) containing Cartesian positions.

sample_joint_space(num_samples=None)[source]#

Sample joint configurations within joint limits.

Parameters:: num_samples (int | None) – Number of samples to generate. If None, uses config value.
Return type:: Tensor
Returns:: Tensor of shape (num_samples, num_joints) containing joint configurations.

sample_plane(num_samples=None, plane_normal=None, plane_point=None, plane_bounds=None)[source]#

Sample points on a specified plane using existing samplers (ultra-simplified version).

Parameters:

num_samples (int | None) – Number of samples to generate. If None, uses config value.
plane_normal (Tensor | None) – Plane normal vector [nx, ny, nz]. Defaults to [0,0,1] (XY plane).
plane_point (Tensor | None) – A point on the plane [x, y, z]. Defaults to [0,0,0].
plane_bounds (Tensor | None) – 2D bounds [[u_min, u_max], [v_min, v_max]]. Defaults to [[-1,1], [-1,1]].

Return type:

Tensor

Returns:

Tensor of shape (num_samples, 3) containing 3D points on the plane.

success_rates: Tensor | None#

visualize(vis_type=None, show=True, save_path=None, backend=None)[source]#

Visualize the workspace.

Parameters:

vis_type (VisualizationType | str | None) – Type of visualization to create. Can be VisualizationType enum or string. If None, uses the vis_type from configuration (default: POINT_CLOUD). Supported types: ‘point_cloud’, ‘voxel’, ‘sphere’.
show (bool) – Whether to display the visualization.
save_path (str | None) – Optional path to save the visualization.
backend (str | None) – Backend to use (‘sim_manager’, ‘viser’, ‘open3d’, ‘matplotlib’, ‘data’). If None, automatically selects based on the SimulationManager configuration and availability.

Return type:

Any

Returns:

Visualization object.

workspace_points: Tensor | None#

class embodichain.lab.sim.motion.workspace.WorkspaceAnalyzerConfig[source]#

Bases: object

Complete configuration for workspace analyzer.

Methods:

__init__([mode, sampling, cache, ...])

Attributes:

`cache`	Cache configuration.
`constraint`	Dimension constraint configuration.
`constraint_bounds`	[[x_min, x_max], [y_min, y_max], ...].
`constraint_type`	'box', 'sphere', None.
`control_part_name`	Name of the control part (e.g., 'left_arm', 'right_arm').
`enable_plane_sampling`	Whether to enable plane sampling functionality (uses existing samplers directly)
`ik_samples_per_point`	number of random joint seeds to try for each Cartesian point.
`metric`	Metric configuration.
`mode`	joint space or Cartesian space sampling.
`plane_bounds`	Bounds for 2D plane coordinates [[u_min, u_max], [v_min, v_max]]
`plane_normal`	Normal vector of the plane for plane sampling [nx, ny, nz]
`plane_point`	A point on the plane for plane sampling [x, y, z]
`reference_pose`	Optional reference pose (4x4 matrix) for IK target orientation.
`sampling`	Sampling configuration.
`sphere_center`	Center point for sphere constraint [x, y, z, ...].
`sphere_radius`	Radius for sphere constraint.
`sphere_radius_mode`	'inscribed' or 'circumscribed'.
`visualization`	Visualization configuration.

__init__(mode=AnalysisMode.JOINT_SPACE, sampling=None, cache=None, constraint=None, visualization=None, metric=None, ik_samples_per_point=1, reference_pose=None, control_part_name=None, enable_plane_sampling=False, plane_normal=None, plane_point=None, plane_bounds=None, constraint_type=None, constraint_bounds=None, sphere_center=None, sphere_radius=None, sphere_radius_mode='inscribed')#

cache: CacheConfig = None#: Cache configuration.

constraint: DimensionConstraint = None#: Dimension constraint configuration.

constraint_bounds: Tensor | None = None#

[[x_min, x_max], [y_min, y_max], …]. For sphere: used to auto-calculate radius if sphere_radius is None.

Type:: Bounds for constraint
Type:: For box

constraint_type: str | None = None#

‘box’, ‘sphere’, None. If None, no constraint applied.

Type:: Type of geometric constraint

control_part_name: str | None = None#: Name of the control part (e.g., ‘left_arm’, ‘right_arm’). If None, uses the default solver or first available control part.

enable_plane_sampling: bool = False#: Whether to enable plane sampling functionality (uses existing samplers directly)

ik_samples_per_point: int = 1#

number of random joint seeds to try for each Cartesian point.

Type:: For Cartesian mode

metric: MetricConfig = None#: Metric configuration.

mode: AnalysisMode = 'joint_space'#

joint space or Cartesian space sampling.

Type:: Analysis mode

plane_bounds: Tensor | None = None#: Bounds for 2D plane coordinates [[u_min, u_max], [v_min, v_max]]

plane_normal: Tensor | None = None#: Normal vector of the plane for plane sampling [nx, ny, nz]

plane_point: Tensor | None = None#: A point on the plane for plane sampling [x, y, z]

reference_pose: Any | None = None#: Optional reference pose (4x4 matrix) for IK target orientation. If None, uses current robot pose.

sampling: SamplingConfig = None#: Sampling configuration.

sphere_center: Tensor | None = None#: Center point for sphere constraint [x, y, z, …]. If None and constraint_type=’sphere’, calculated from constraint_bounds.

sphere_radius: float | None = None#: Radius for sphere constraint. If None and constraint_type=’sphere’, auto-calculated from constraint_bounds.

sphere_radius_mode: str = 'inscribed'#

‘inscribed’ or ‘circumscribed’. Only used if sphere_radius is None.

Type:: Mode for auto-calculating sphere radius from bounds

visualization: VisualizationConfig = None#: Visualization configuration.

class embodichain.lab.sim.motion.workspace.WorkspaceSample[source]#

Bases: object

A batch of cached, reachable robot configurations and FK poses.

Methods:

__init__(eef_pose, qpos, indices, valid[, score])

Attributes:

`eef_pose`	End-effector poses in the local arena frame, shape `(B, K, 4, 4)`.
`indices`	Workspace cache indices, shape `(B, K)`; invalid entries are `-1`.
`qpos`	Control-part joint configurations, shape `(B, K, D)`.
`score`	Optional cached reachability score, shape `(B, K)`.
`valid`	Whether each returned sample satisfies the runtime filters, shape `(B, K)`.

__init__(eef_pose, qpos, indices, valid, score=None)#

eef_pose: Tensor#: End-effector poses in the local arena frame, shape (B, K, 4, 4).

indices: Tensor#: Workspace cache indices, shape (B, K); invalid entries are -1.

qpos: Tensor#: Control-part joint configurations, shape (B, K, D).

score: Tensor | None = None#: Optional cached reachability score, shape (B, K).

valid: Tensor#: Whether each returned sample satisfies the runtime filters, shape (B, K).

Runtime Sampling#

Runtime loading and sampling of cached robot workspaces.

Classes:

`RobotWorkspace`	Reachable Cartesian samples backed by aligned joint configurations.
`WorkspaceSample`	A batch of cached, reachable robot configurations and FK poses.

class embodichain.lab.sim.motion.workspace.runtime.RobotWorkspace[source]#

Bases: object

Reachable Cartesian samples backed by aligned joint configurations.

The cached Cartesian points are used to define the sampling distribution. Runtime callers should recompute end-effector poses from qpos so the result uses the robot base pose of the target environment.

Attributes:

`SUPPORTED_STRATEGIES`
`device`	Return the device holding workspace tensors.
`num_samples`	Return the number of cached reachable samples.

Methods:

`__init__`(positions, qpos, *[, scores, ...])	Initialize a runtime workspace.
`from_cache`(cache_path, *[, device, voxel_size])	Load an analyzer results cache for runtime sampling.
`sample_indices`(count, *[, strategy, ...])	Sample cache indices.
`to`(device)	Move workspace tensors to a device in-place.

SUPPORTED_STRATEGIES = ('point_uniform', 'voxel_uniform')#

__init__(positions, qpos, *, scores=None, voxel_size=0.03, metadata=None, source_path=None)[source]#

Initialize a runtime workspace.

Parameters:

positions (Tensor) – Cached Cartesian positions, shape (N, 3).
qpos (Tensor) – Joint configurations aligned with positions, shape (N, D).
scores (Tensor | None) – Optional score aligned with positions, shape (N,).
voxel_size (float) – Cartesian voxel edge length in meters.
metadata (dict | None) – Optional cache metadata.
source_path (str | Path | None) – Optional source cache path.

Raises:

ValueError – If tensors are empty, have incompatible shapes, or voxel_size is not positive.

property device: device#: Return the device holding workspace tensors.

classmethod from_cache(cache_path, *, device='cpu', voxel_size=0.03)[source]#

Load an analyzer results cache for runtime sampling.

Parameters:

cache_path (str | Path) – Cache entry directory or direct results.npz path.
device (device | str) – Device on which runtime tensors are stored.
voxel_size (float) – Cartesian voxel edge length in meters.

Return type:

RobotWorkspace

Returns:

Loaded runtime workspace.

Raises:

FileNotFoundError – If the cache archive does not exist.
ValueError – If no point set aligns with joint_configurations.

property num_samples: int#: Return the number of cached reachable samples.

sample_indices(count, *, strategy='voxel_uniform', min_score=None, generator=None)[source]#

Sample cache indices.

Parameters:

count (int) – Number of indices to return.
strategy (Literal['point_uniform', 'voxel_uniform']) – Point-uniform or Cartesian-voxel-uniform sampling.
min_score (float | None) – Optional minimum cached score.
generator (Generator | None) – Optional random number generator.

Return type:

Tensor

Returns:

Index tensor with shape (count,).

Raises:

ValueError – If arguments are invalid or filters reject every point.

to(device)[source]#

Move workspace tensors to a device in-place.

Parameters:: device (device | str) – Target torch device.
Return type:: RobotWorkspace
Returns:: This workspace instance.

class embodichain.lab.sim.motion.workspace.runtime.WorkspaceSample[source]#

Bases: object

A batch of cached, reachable robot configurations and FK poses.

Methods:

__init__(eef_pose, qpos, indices, valid[, score])

Attributes:

`eef_pose`	End-effector poses in the local arena frame, shape `(B, K, 4, 4)`.
`indices`	Workspace cache indices, shape `(B, K)`; invalid entries are `-1`.
`qpos`	Control-part joint configurations, shape `(B, K, D)`.
`score`	Optional cached reachability score, shape `(B, K)`.
`valid`	Whether each returned sample satisfies the runtime filters, shape `(B, K)`.

__init__(eef_pose, qpos, indices, valid, score=None)#

eef_pose: Tensor#: End-effector poses in the local arena frame, shape (B, K, 4, 4).

indices: Tensor#: Workspace cache indices, shape (B, K); invalid entries are -1.

qpos: Tensor#: Control-part joint configurations, shape (B, K, D).

score: Tensor | None = None#: Optional cached reachability score, shape (B, K).

valid: Tensor#: Whether each returned sample satisfies the runtime filters, shape (B, K).

Runtime Configuration#

Runtime workspace configuration.

Classes:

RobotWorkspaceCfg

Runtime configuration for a control-part workspace cache.

class embodichain.lab.sim.motion.workspace.cfg.RobotWorkspaceCfg[source]#

Bases: object

Runtime configuration for a control-part workspace cache.

Attributes:

`cache_path`	Path to a workspace cache entry directory or `results.npz` file.
`min_score`	Optional minimum cached reachability score accepted for sampling.
`strategy`	Default runtime sampling strategy.
`voxel_size`	Cartesian voxel edge length in meters for voxel-uniform sampling.

cache_path: str#: Path to a workspace cache entry directory or results.npz file.

min_score: float | None#: Optional minimum cached reachability score accepted for sampling.

strategy: Literal['point_uniform', 'voxel_uniform']#: Default runtime sampling strategy.

voxel_size: float#: Cartesian voxel edge length in meters for voxel-uniform sampling.

Offline Analysis#

Classes:

`AnalysisMode`	Workspace analysis mode.
`WorkspaceAnalyzer`	Main workspace analyzer class for robotic manipulation.
`WorkspaceAnalyzerConfig`	Complete configuration for workspace analyzer.

class embodichain.lab.sim.motion.workspace.analyzer.AnalysisMode[source]#

Bases: Enum

Workspace analysis mode.

Attributes:

`CARTESIAN_SPACE`	Sample in Cartesian space, compute IK to verify reachability.
`JOINT_SPACE`	Sample in joint space, compute FK to get workspace points.
`PLANE_SAMPLING`	Sample on a specific plane within Cartesian space.

CARTESIAN_SPACE = 'cartesian_space'#: Sample in Cartesian space, compute IK to verify reachability.

JOINT_SPACE = 'joint_space'#: Sample in joint space, compute FK to get workspace points.

PLANE_SAMPLING = 'plane_sampling'#: Sample on a specific plane within Cartesian space.

class embodichain.lab.sim.motion.workspace.analyzer.WorkspaceAnalyzer[source]#

Bases: object

Main workspace analyzer class for robotic manipulation.

Analyzes the reachable workspace of a robot by sampling joint configurations, computing forward kinematics, and generating metrics and visualizations.

Note

Currently designed for single environment operation (num_envs=1). When multiple environments are present, the analyzer will use the first environment (index 0) and log appropriate warnings. Multi-environment support will be added in future versions.

Attributes:

`DEFAULT_CONTROL_PART_PRIORITY`
`current_mode`
`joint_configurations`
`metrics_results`
`success_rates`
`workspace_points`

Methods:

`__init__`(robot[, config, sim_manager])	Initialize the workspace analyzer.
`analyze`([num_samples, force_recompute, ...])	Perform complete workspace analysis.
`compute_reachability`(cartesian_points[, ...])	Compute reachability for Cartesian points using batched IK.
`compute_workspace_points`(joint_configs[, ...])	Compute end-effector positions for given joint configurations.
`export_results`(output_path[, format])	Export analysis results to file.
`get_results_cache_path`()	Get the path to the most recently used results cache entry.
`get_workspace_bounds`()	Get the bounding box of the analyzed workspace.
`profiling`()	Enhanced context manager for profiling workspace analysis with detailed metrics.
`sample_cartesian_space`([num_samples])	Sample Cartesian positions within workspace bounds.
`sample_joint_space`([num_samples])	Sample joint configurations within joint limits.
`sample_plane`([num_samples, plane_normal, ...])	Sample points on a specified plane using existing samplers (ultra-simplified version).
`visualize`([vis_type, show, save_path, backend])	Visualize the workspace.

DEFAULT_CONTROL_PART_PRIORITY = ['left_arm', 'right_arm']#

__init__(robot, config=None, sim_manager=None)[source]#

Initialize the workspace analyzer.

Parameters:

robot (Robot) – Robot instance to analyze.
config (WorkspaceAnalyzerConfig | None) – Configuration object. If None, uses defaults.
sim_manager (SimulationManager | None) – SimulationManager instance. Defaults None.

analyze(num_samples=None, force_recompute=False, visualize=False)[source]#

Perform complete workspace analysis.

Parameters:

num_samples (int | None) – Number of samples to generate. If None, uses config value.
force_recompute (bool) – If True, recomputes even if cached results exist.
visualize (bool) – If True, visualizes the workspace points. Prefers sim_manager visualization if available, otherwise falls back to visualizers module.

Return type:

Dict[str, Any]

Returns:

Dictionary containing analysis results.

compute_reachability(cartesian_points, batch_size=None)[source]#

Compute reachability for Cartesian points using batched IK.

All ik_samples_per_point random seeds for a batch of points are merged into the batch dimension and resolved with a single robot.compute_batch_ik call (shape (1, n_valid * K, 4, 4)). This avoids the Python loop overhead and lets the solver process all seeds in one vectorised pass.

Parameters:

cartesian_points (Tensor) – Cartesian positions, shape (num_samples, 3).
batch_size (int | None) – Batch size for IK computation. If None, uses config value.

Returns:

all_points: All Cartesian positions, shape (num_samples, 3)
reachable_points: Reachable positions, shape (num_reachable, 3)
success_rates: IK success rate for each point, shape (num_samples,)
reachability_mask: Boolean mask indicating reachable points, shape (num_samples,)
best_configs: Best joint configurations, shape (num_reachable, num_joints)

Return type:

Tuple of

compute_workspace_points(joint_configs, batch_size=None)[source]#

Compute end-effector positions for given joint configurations.

Uses batched FK computation via robot.compute_batch_fk for significant speedup on large sample counts.

Parameters:

joint_configs (Tensor) – Joint configurations, shape (num_samples, num_joints).
batch_size (int | None) – Batch size for FK computation. If None, uses config value.

Returns:

workspace_points: End-effector positions, shape (num_valid, 3)
valid_configs: Valid joint configurations, shape (num_valid, num_joints)

Return type:

Tuple of

current_mode: AnalysisMode | None#

export_results(output_path, format='npz')[source]#

Export analysis results to file.

Parameters:

output_path (str) – Path to save the results.
format (str) – Output format (‘npz’, ‘pkl’, ‘json’).

Return type:

None

get_results_cache_path()[source]#

Get the path to the most recently used results cache entry.

Return type:: Path | None
Returns:: Path to the cache entry directory, or None if no disk results cache has been read or written yet.

get_workspace_bounds()[source]#

Get the bounding box of the analyzed workspace.

Return type:: Dict[str, ndarray]
Returns:: Dictionary with ‘min’ and ‘max’ bounds.

joint_configurations: Tensor | None#

metrics_results: Dict[str, Any]#

profiling()[source]#: Enhanced context manager for profiling workspace analysis with detailed metrics.

sample_cartesian_space(num_samples=None)[source]#

Sample Cartesian positions within workspace bounds.

Parameters:: num_samples (int | None) – Number of samples to generate. If None, uses config value.
Return type:: Tensor
Returns:: Tensor of shape (num_samples, 3) containing Cartesian positions.

sample_joint_space(num_samples=None)[source]#

Sample joint configurations within joint limits.

Parameters:: num_samples (int | None) – Number of samples to generate. If None, uses config value.
Return type:: Tensor
Returns:: Tensor of shape (num_samples, num_joints) containing joint configurations.

sample_plane(num_samples=None, plane_normal=None, plane_point=None, plane_bounds=None)[source]#

Sample points on a specified plane using existing samplers (ultra-simplified version).

Parameters:

num_samples (int | None) – Number of samples to generate. If None, uses config value.
plane_normal (Tensor | None) – Plane normal vector [nx, ny, nz]. Defaults to [0,0,1] (XY plane).
plane_point (Tensor | None) – A point on the plane [x, y, z]. Defaults to [0,0,0].
plane_bounds (Tensor | None) – 2D bounds [[u_min, u_max], [v_min, v_max]]. Defaults to [[-1,1], [-1,1]].

Return type:

Tensor

Returns:

Tensor of shape (num_samples, 3) containing 3D points on the plane.

success_rates: Tensor | None#

visualize(vis_type=None, show=True, save_path=None, backend=None)[source]#

Visualize the workspace.

Parameters:

vis_type (VisualizationType | str | None) – Type of visualization to create. Can be VisualizationType enum or string. If None, uses the vis_type from configuration (default: POINT_CLOUD). Supported types: ‘point_cloud’, ‘voxel’, ‘sphere’.
show (bool) – Whether to display the visualization.
save_path (str | None) – Optional path to save the visualization.
backend (str | None) – Backend to use (‘sim_manager’, ‘viser’, ‘open3d’, ‘matplotlib’, ‘data’). If None, automatically selects based on the SimulationManager configuration and availability.

Return type:

Any

Returns:

Visualization object.

workspace_points: Tensor | None#

class embodichain.lab.sim.motion.workspace.analyzer.WorkspaceAnalyzerConfig[source]#

Bases: object

Complete configuration for workspace analyzer.

Methods:

__init__([mode, sampling, cache, ...])

Attributes:

`cache`	Cache configuration.
`constraint`	Dimension constraint configuration.
`constraint_bounds`	[[x_min, x_max], [y_min, y_max], ...].
`constraint_type`	'box', 'sphere', None.
`control_part_name`	Name of the control part (e.g., 'left_arm', 'right_arm').
`enable_plane_sampling`	Whether to enable plane sampling functionality (uses existing samplers directly)
`ik_samples_per_point`	number of random joint seeds to try for each Cartesian point.
`metric`	Metric configuration.
`mode`	joint space or Cartesian space sampling.
`plane_bounds`	Bounds for 2D plane coordinates [[u_min, u_max], [v_min, v_max]]
`plane_normal`	Normal vector of the plane for plane sampling [nx, ny, nz]
`plane_point`	A point on the plane for plane sampling [x, y, z]
`reference_pose`	Optional reference pose (4x4 matrix) for IK target orientation.
`sampling`	Sampling configuration.
`sphere_center`	Center point for sphere constraint [x, y, z, ...].
`sphere_radius`	Radius for sphere constraint.
`sphere_radius_mode`	'inscribed' or 'circumscribed'.
`visualization`	Visualization configuration.

__init__(mode=AnalysisMode.JOINT_SPACE, sampling=None, cache=None, constraint=None, visualization=None, metric=None, ik_samples_per_point=1, reference_pose=None, control_part_name=None, enable_plane_sampling=False, plane_normal=None, plane_point=None, plane_bounds=None, constraint_type=None, constraint_bounds=None, sphere_center=None, sphere_radius=None, sphere_radius_mode='inscribed')#

cache: CacheConfig = None#: Cache configuration.

constraint: DimensionConstraint = None#: Dimension constraint configuration.

constraint_bounds: Tensor | None = None#

[[x_min, x_max], [y_min, y_max], …]. For sphere: used to auto-calculate radius if sphere_radius is None.

Type:: Bounds for constraint
Type:: For box

constraint_type: str | None = None#

‘box’, ‘sphere’, None. If None, no constraint applied.

Type:: Type of geometric constraint

control_part_name: str | None = None#: Name of the control part (e.g., ‘left_arm’, ‘right_arm’). If None, uses the default solver or first available control part.

enable_plane_sampling: bool = False#: Whether to enable plane sampling functionality (uses existing samplers directly)

ik_samples_per_point: int = 1#

number of random joint seeds to try for each Cartesian point.

Type:: For Cartesian mode

metric: MetricConfig = None#: Metric configuration.

mode: AnalysisMode = 'joint_space'#

joint space or Cartesian space sampling.

Type:: Analysis mode

plane_bounds: Tensor | None = None#: Bounds for 2D plane coordinates [[u_min, u_max], [v_min, v_max]]

plane_normal: Tensor | None = None#: Normal vector of the plane for plane sampling [nx, ny, nz]

plane_point: Tensor | None = None#: A point on the plane for plane sampling [x, y, z]

reference_pose: Any | None = None#: Optional reference pose (4x4 matrix) for IK target orientation. If None, uses current robot pose.

sampling: SamplingConfig = None#: Sampling configuration.

sphere_center: Tensor | None = None#: Center point for sphere constraint [x, y, z, …]. If None and constraint_type=’sphere’, calculated from constraint_bounds.

sphere_radius: float | None = None#: Radius for sphere constraint. If None and constraint_type=’sphere’, auto-calculated from constraint_bounds.

sphere_radius_mode: str = 'inscribed'#

‘inscribed’ or ‘circumscribed’. Only used if sphere_radius is None.

Type:: Mode for auto-calculating sphere radius from bounds

visualization: VisualizationConfig = None#: Visualization configuration.

Workspace Components#

`caches`	Cache backends and a cache manager for persisting workspace-analysis results.
`configs`	Configuration objects for workspace analysis.
`constraints`	Workspace constraint checkers that validate sampled configurations against the robot's limits.
`metrics`	Workspace evaluation metrics deriving from `BaseMetric`.
`samplers`	Workspace sampling strategies deriving from `BaseSampler`.
`visualizers`	Workspace result visualizers deriving from `BaseVisualizer`.

embodichain.lab.sim.motion.workspace

Contents

embodichain.lab.sim.motion.workspace#

Runtime Sampling#

Runtime Configuration#

Offline Analysis#

Workspace Components#