embodichain.lab.sim.motion.workspace.configs

Configuration objects for workspace analysis.

Covers sampling (SamplingConfig), caching (CacheConfig), metrics (MetricConfig and per-metric reachability / manipulability / density configs), visualization (VisualizationConfig), and dimension constraints (DimensionConstraint).

Classes:

CacheConfig	Configuration for caching workspace analysis results.
DensityConfig	Configuration for density metric.
DimensionConstraint	Configuration for dimensional constraints in workspace analysis.
ManipulabilityConfig	Configuration for manipulability metric.
MetricConfig	Configuration for workspace analysis metrics.
MetricType	Types of workspace metrics.
ReachabilityConfig	Configuration for reachability metric.
SamplingConfig	Configuration for sampling strategies in workspace analysis.
SamplingStrategy	Sampling strategy for joint space.
VisualizationConfig	Visualization configuration
VisualizationType

class embodichain.lab.sim.motion.workspace.configs.CacheConfig

Bases: object

Configuration for caching workspace analysis results.

Methods:

__init__([enabled, cache_dir, use_hash, ...])

Attributes:

cache_dir	Directory to store cache files.
cache_format	'npz' (numpy), 'pkl' (pickle), 'h5' (hdf5).
compression	Whether to compress cache files to save disk space.
enabled	Whether to enable caching of analysis results.
max_cache_size_mb	Maximum total size of cache directory in megabytes.
use_hash	Whether to use hash-based cache keys (based on robot config and parameters).

__init__(enabled=True, cache_dir=None, use_hash=True, compression=True, max_cache_size_mb=1000, cache_format='npz')

cache_dir: Path | None = None

Directory to store cache files. If None, uses default system cache directory.

cache_format: str = 'npz'

‘npz’ (numpy), ‘pkl’ (pickle), ‘h5’ (hdf5).

Type:

Format for cache files. Options

compression: bool = True

Whether to compress cache files to save disk space.

enabled: bool = True

Whether to enable caching of analysis results.

max_cache_size_mb: int = 1000

Maximum total size of cache directory in megabytes. Old files will be removed if exceeded.

use_hash: bool = True

Whether to use hash-based cache keys (based on robot config and parameters).

class embodichain.lab.sim.motion.workspace.configs.DensityConfig

Bases: object

Configuration for density metric.

Methods:

__init__([radius, k_neighbors, ...])

Attributes:

compute_distribution	Whether to compute density distribution statistics.
k_neighbors	Number of nearest neighbors for density estimation.
radius	Radius for local density estimation in meters.

__init__(radius=0.05, k_neighbors=30, compute_distribution=True)

compute_distribution: bool = True

Whether to compute density distribution statistics.

k_neighbors: int = 30

Number of nearest neighbors for density estimation.

radius: float = 0.05

Radius for local density estimation in meters.

class embodichain.lab.sim.motion.workspace.configs.DimensionConstraint

Bases: object

Configuration for dimensional constraints in workspace analysis.

Methods:

__init__([min_bounds, max_bounds, ...])

Attributes:

enforce_collision_free	Whether to enforce collision-free constraints during analysis.
exclude_zones	List of excluded zones as [(min_bounds, max_bounds), ...].
ground_height	Ground plane height in meters.
joint_limits_scale	Scale factor for joint limits (1.0 = use full range, 0.8 = use 80% of range).
max_bounds	Maximum bounds for workspace [x_max, y_max, z_max] in meters.
min_bounds	Minimum bounds for workspace [x_min, y_min, z_min] in meters.
self_collision_check	Whether to check for self-collision when analyzing workspace.

__init__(min_bounds=None, max_bounds=None, joint_limits_scale=1.0, exclude_zones=<factory>, ground_height=0.0, enforce_collision_free=False, self_collision_check=False)

enforce_collision_free: bool = False

Whether to enforce collision-free constraints during analysis.

exclude_zones: List[Tuple[ndarray, ndarray]]

List of excluded zones as [(min_bounds, max_bounds), …]. Robot end-effector should avoid these regions.

ground_height: float = 0.0

Ground plane height in meters. Points below this will be filtered out.

joint_limits_scale: float = 1.0

Scale factor for joint limits (1.0 = use full range, 0.8 = use 80% of range).

max_bounds: ndarray | None = None

Maximum bounds for workspace [x_max, y_max, z_max] in meters.

min_bounds: ndarray | None = None

Minimum bounds for workspace [x_min, y_min, z_min] in meters.

self_collision_check: bool = False

Whether to check for self-collision when analyzing workspace.

class embodichain.lab.sim.motion.workspace.configs.ManipulabilityConfig

Bases: object

Configuration for manipulability metric.

Methods:

__init__([jacobian_threshold, ...])

Attributes:

compute_heatmap	Whether to generate manipulability heatmap.
compute_isotropy	Whether to compute isotropy index (condition number).
jacobian_threshold	Minimum manipulability value to consider valid.

__init__(jacobian_threshold=0.01, compute_isotropy=True, compute_heatmap=False)

compute_heatmap: bool = False

Whether to generate manipulability heatmap.

compute_isotropy: bool = True

Whether to compute isotropy index (condition number).

jacobian_threshold: float = 0.01

Minimum manipulability value to consider valid.

class embodichain.lab.sim.motion.workspace.configs.MetricConfig

Bases: object

Configuration for workspace analysis metrics.

Methods:

__init__([enabled_metrics, reachability, ...])

Attributes:

density	Configuration for density metric.
enabled_metrics	List of metrics to compute.
manipulability	Configuration for manipulability metric.
output_format	'json', 'yaml', 'pkl'.
reachability	Configuration for reachability metric.
save_results	Whether to save metric results to file.

__init__(enabled_metrics=None, reachability=None, manipulability=None, density=None, save_results=True, output_format='json')

density: DensityConfig = None

Configuration for density metric.

enabled_metrics: List[MetricType] = None

List of metrics to compute. If None, computes all metrics.

manipulability: ManipulabilityConfig = None

Configuration for manipulability metric.

output_format: str = 'json'

‘json’, ‘yaml’, ‘pkl’.

Type:

Output format for metrics. Options

reachability: ReachabilityConfig = None

Configuration for reachability metric.

save_results: bool = True

Whether to save metric results to file.

class embodichain.lab.sim.motion.workspace.configs.MetricType

Bases: Enum

Types of workspace metrics.

Attributes:

ALL	Compute all available metrics.
DENSITY	Measures point density and workspace distribution.
MANIPULABILITY	Measures dexterity/manipulability throughout workspace.
REACHABILITY	Measures reachable workspace volume and coverage.

ALL = 'all'

Compute all available metrics.

DENSITY = 'density'

Measures point density and workspace distribution.

MANIPULABILITY = 'manipulability'

Measures dexterity/manipulability throughout workspace.

REACHABILITY = 'reachability'

Measures reachable workspace volume and coverage.

class embodichain.lab.sim.motion.workspace.configs.ReachabilityConfig

Bases: object

Configuration for reachability metric.

Methods:

__init__([voxel_size, min_points_per_voxel, ...])

Attributes:

compute_coverage	Whether to compute coverage percentage relative to bounding box.
min_points_per_voxel	Minimum number of points in a voxel to consider it reachable.
voxel_size	Size of voxels for volume calculation in meters.

__init__(voxel_size=0.01, min_points_per_voxel=1, compute_coverage=True)

compute_coverage: bool = True

Whether to compute coverage percentage relative to bounding box.

min_points_per_voxel: int = 1

Minimum number of points in a voxel to consider it reachable.

voxel_size: float = 0.01

Size of voxels for volume calculation in meters.

class embodichain.lab.sim.motion.workspace.configs.SamplingConfig

Bases: object

Configuration for sampling strategies in workspace analysis.

Methods:

__init__([strategy, num_samples, ...])

Attributes:

batch_size	Number of samples to process in each batch.
gaussian_mean	Mean for Gaussian sampling (used with GAUSSIAN strategy).
gaussian_std	Standard deviation for Gaussian sampling (used with GAUSSIAN strategy).
grid_resolution	Resolution for grid sampling (used with UNIFORM strategy).
importance_weight_func	Weight function for importance sampling (used with IMPORTANCE strategy).
num_samples	Number of samples to generate.
seed	Random seed for reproducibility.
sphere_boundary_handling	'clip', 'reject', 'extend'.
sphere_center	Custom sphere center for SPHERE strategy (used when sphere_center_mode='custom').
sphere_center_mode	'bounds_center', 'custom', 'auto'.
sphere_radius	Custom sphere radius for SPHERE strategy (used when sphere_radius_mode='custom').
sphere_radius_mode	'inscribed', 'circumscribed', 'custom'.
strategy	Sampling strategy to use.

__init__(strategy=None, num_samples=1000, grid_resolution=10, batch_size=1000, seed=42, importance_weight_func=None, gaussian_mean=None, gaussian_std=None, sphere_center_mode='bounds_center', sphere_radius_mode='inscribed', sphere_boundary_handling='reject', sphere_center=None, sphere_radius=None)

batch_size: int = 1000

Number of samples to process in each batch.

gaussian_mean: float | None = None

Mean for Gaussian sampling (used with GAUSSIAN strategy). If None, uses center of bounds.

gaussian_std: float | None = None

Standard deviation for Gaussian sampling (used with GAUSSIAN strategy). If None, uses 1/6 of range.

grid_resolution: int = 10

Resolution for grid sampling (used with UNIFORM strategy).

importance_weight_func: Optional[Callable] = None

Weight function for importance sampling (used with IMPORTANCE strategy).

num_samples: int = 1000

Number of samples to generate.

seed: int = 42

Random seed for reproducibility.

sphere_boundary_handling: str = 'reject'

‘clip’, ‘reject’, ‘extend’.

Type:

How to handle boundary violations for SPHERE strategy. Options

sphere_center: list | None = None

Custom sphere center for SPHERE strategy (used when sphere_center_mode=’custom’).

sphere_center_mode: str = 'bounds_center'

‘bounds_center’, ‘custom’, ‘auto’.

Type:

How to determine sphere center for SPHERE strategy. Options

sphere_radius: float | None = None

Custom sphere radius for SPHERE strategy (used when sphere_radius_mode=’custom’).

sphere_radius_mode: str = 'inscribed'

‘inscribed’, ‘circumscribed’, ‘custom’.

Type:

How to determine sphere radius for SPHERE strategy. Options

strategy: SamplingStrategy = None

Sampling strategy to use.

class embodichain.lab.sim.motion.workspace.configs.SamplingStrategy

Bases: Enum

Sampling strategy for joint space.

Attributes:

GAUSSIAN
HALTON
IMPORTANCE
LATIN_HYPERCUBE
RANDOM
SOBOL
SPHERE
UNIFORM

GAUSSIAN = 'gaussian'

HALTON = 'halton'

IMPORTANCE = 'importance'

LATIN_HYPERCUBE = 'lhs'

RANDOM = 'random'

SOBOL = 'sobol'

SPHERE = 'sphere'

UNIFORM = 'uniform'

class embodichain.lab.sim.motion.workspace.configs.VisualizationConfig

Bases: object

Visualization configuration

Methods:

__init__([enabled, vis_type, voxel_size, ...])

Attributes:

alpha	Transparency level of points.
axis_length	Length of coordinate axes for axis visualization.
axis_size	Thickness/size of coordinate axes for axis visualization.
color_by_distance	Color points by distance.
enabled	Enable or disable visualization.
is_voxel_down	Enable voxel downsampling.
nb_neighbors	Number of neighbors for statistical outlier removal.
point_size	Size of points in visualization.
show_unreachable_points	Whether to show unreachable points in Cartesian space and Plane sampling modes.
sphere_radius	Radius of spheres for sphere visualization.
sphere_resolution	Sphere mesh resolution for sphere visualization.
std_ratio	Standard deviation ratio for statistical outlier removal.
vis_type	Type of visualization to use.
viser_point_size	Point size in world units for the Viser browser backend.
voxel_size	Voxel size for downsampling.

__init__(enabled=True, vis_type=VisualizationType.POINT_CLOUD, voxel_size=0.05, nb_neighbors=20, std_ratio=2.0, is_voxel_down=True, color_by_distance=True, point_size=4.0, viser_point_size=0.01, alpha=0.5, sphere_radius=0.005, sphere_resolution=10, axis_length=0.05, axis_size=0.003, show_unreachable_points=True)

alpha: float = 0.5

Transparency level of points.

axis_length: float = 0.05

Length of coordinate axes for axis visualization.

axis_size: float = 0.003

Thickness/size of coordinate axes for axis visualization.

color_by_distance: bool = True

Color points by distance.

enabled: bool = True

Enable or disable visualization.

is_voxel_down: bool = True

Enable voxel downsampling.

nb_neighbors: int = 20

Number of neighbors for statistical outlier removal.

point_size: float = 4.0

Size of points in visualization.

show_unreachable_points: bool = True

Whether to show unreachable points in Cartesian space and Plane sampling modes.

If True, shows both reachable (green, large) and unreachable (red, small) points. If False, only shows reachable points in Cartesian space and Plane sampling modes. Has no effect in Joint space mode (all points are always shown as reachable).

Note: This parameter now supports all IK-based analysis modes including: - AnalysisMode.CARTESIAN_SPACE - AnalysisMode.PLANE_SAMPLING

sphere_radius: float = 0.005

Radius of spheres for sphere visualization.

sphere_resolution: int = 10

Sphere mesh resolution for sphere visualization.

std_ratio: float = 2.0

Standard deviation ratio for statistical outlier removal.

vis_type: Union[VisualizationType, str] = 'point_cloud'

Type of visualization to use. Can be VisualizationType enum or string.

Available visualization types: - POINT_CLOUD: Fast point cloud rendering, good for large datasets - VOXEL: Volumetric voxel grid representation for occupancy mapping - SPHERE: Smooth sphere rendering for publication-quality figures - AXIS: Coordinate frame visualization for poses and transformations

Examples

vis_type = VisualizationType.SPHERE vis_type = “point_cloud” vis_type = “axis” # For coordinate frames

viser_point_size: float = 0.01

Point size in world units for the Viser browser backend.

voxel_size: float = 0.05

Voxel size for downsampling.

class embodichain.lab.sim.motion.workspace.configs.VisualizationType

Bases: Enum

Attributes:

AXIS
POINT_CLOUD
SPHERE
VOXEL

AXIS = 'axis'

POINT_CLOUD = 'point_cloud'

SPHERE = 'sphere'

VOXEL = 'voxel'