Workspace Analyzer Configurations

The Workspace Analyzer Configs module provides a comprehensive configuration system for robotic workspace analysis. This module offers type-safe, well-documented configuration classes that control every aspect of workspace analysis, from sampling strategies to visualization options.

Based on the WorkspaceAnalyzerConfig dataclass and its sub-configurations, this system provides modular, extensible configuration management for all aspects of workspace analysis.

Table of Contents

• Overview

• Configuration Types

• Usage Examples

• Best Practices

• API Reference

Overview

The configs module enables fine-grained control over:

• Sampling Strategies: Control how joint space is sampled

• Caching Behavior: Configure result caching and storage

• Metric Calculation: Define which metrics to compute and how

• Visualization Options: Customize visualization appearance and behavior

• Dimensional Constraints: Set workspace bounds and exclusion zones

Key Features

• Type Safety: All configurations use dataclasses with type hints

• Validation: Built-in validation and sensible defaults

• Extensibility: Easy to extend with custom configuration options

• Documentation: Comprehensive docstrings for all parameters

• Modularity: Separate configs for different analysis aspects

Configuration Types

1. Sampling Configuration

Controls how the robot’s joint space is sampled for workspace analysis.

from embodichain.lab.sim.utility.workspace_analyzer.configs import (
    SamplingConfig, SamplingStrategy
)

# Basic uniform sampling
config = SamplingConfig(
    strategy=SamplingStrategy.UNIFORM,
    num_samples=10000,
    grid_resolution=20,
    seed=42
)

# Random sampling with larger batch size
random_config = SamplingConfig(
    strategy=SamplingStrategy.RANDOM,
    num_samples=50000,
    batch_size=5000,
    seed=123
)

Available Sampling Strategies

• UNIFORM: Uniform grid sampling across joint space

• RANDOM: Pseudo-random sampling with specified seed

• HALTON: Quasi-random Halton sequence (better coverage)

• SOBOL: Quasi-random Sobol sequence (low-discrepancy)

• LATIN_HYPERCUBE: Latin Hypercube Sampling (space-filling)

• IMPORTANCE: Importance sampling with custom weight function

• GAUSSIAN: Gaussian distribution around specified mean

Advanced Sampling Examples

# Quasi-random sampling for better coverage
halton_config = SamplingConfig(
    strategy=SamplingStrategy.HALTON,
    num_samples=25000,
    batch_size=2500
)

# Gaussian sampling around robot's nominal pose
gaussian_config = SamplingConfig(
    strategy=SamplingStrategy.GAUSSIAN,
    num_samples=15000,
    gaussian_mean=0.0,  # Center of joint range
    gaussian_std=0.3    # 30% of range as std dev
)

# Importance sampling with custom weight function
def weight_function(joint_values):
    # Higher weight for configurations closer to zero
    return np.exp(-np.sum(joint_values**2))

importance_config = SamplingConfig(
    strategy=SamplingStrategy.IMPORTANCE,
    num_samples=20000,
    importance_weight_func=weight_function
)

2. Cache Configuration

Manages caching of analysis results for improved performance.

from embodichain.lab.sim.utility.workspace_analyzer.configs import CacheConfig
from pathlib import Path

# Basic caching configuration
cache_config = CacheConfig(
    enabled=True,
    cache_dir=Path("./workspace_cache"),
    use_hash=True,
    compression=True
)

# High-performance caching setup
performance_cache = CacheConfig(
    enabled=True,
    cache_dir=Path("/fast_storage/workspace_cache"),
    use_hash=True,
    compression=False,  # Faster access, more storage
    max_cache_size_mb=5000,
    cache_format="npz"
)

Cache Configuration Options

• enabled: Enable/disable caching entirely

• cache_dir: Custom cache directory (default: system cache)

• use_hash: Hash-based cache keys for consistency

• compression: Compress cache files to save space

• max_cache_size_mb: Automatic cleanup of old cache files

• cache_format: Storage format (‘npz’, ‘pkl’, ‘h5’)

3. Metric Configuration

Defines which workspace metrics to compute and their parameters.

from embodichain.lab.sim.utility.workspace_analyzer.configs import (
    MetricConfig, MetricType, ReachabilityConfig, 
    ManipulabilityConfig, DensityConfig
)

# Comprehensive metric analysis
metric_config = MetricConfig(
    enabled_metrics=[MetricType.ALL],
    reachability=ReachabilityConfig(
        voxel_size=0.005,  # High resolution
        min_points_per_voxel=2,
        compute_coverage=True
    ),
    manipulability=ManipulabilityConfig(
        jacobian_threshold=0.001,
        compute_isotropy=True,
        compute_heatmap=True
    ),
    density=DensityConfig(
        radius=0.03,
        k_neighbors=50,
        compute_distribution=True
    ),
    save_results=True,
    output_format="json"
)

Metric Types

Reachability Metrics:

• Workspace volume calculation

• Coverage percentage

• Reachable point density

reachability_config = ReachabilityConfig(
    voxel_size=0.01,           # Voxel resolution for volume
    min_points_per_voxel=1,    # Occupancy threshold
    compute_coverage=True      # Coverage vs bounding box
)

Manipulability Metrics:

• Manipulability index throughout workspace

• Isotropy analysis

• Dexterity heatmaps

manipulability_config = ManipulabilityConfig(
    jacobian_threshold=0.01,   # Minimum valid manipulability
    compute_isotropy=True,     # Condition number analysis
    compute_heatmap=False      # Generate spatial heatmap
)

Density Metrics:

• Local point density

• Distribution statistics

• Clustering analysis

density_config = DensityConfig(
    radius=0.05,              # Local neighborhood radius
    k_neighbors=30,           # Number of neighbors to consider
    compute_distribution=True  # Statistical distribution
)

4. Visualization Configuration

Controls the appearance and behavior of workspace visualizations.

from embodichain.lab.sim.utility.workspace_analyzer.configs import (
    VisualizationConfig, VisualizationType
)

# High-quality point cloud visualization
viz_config = VisualizationConfig(
    enabled=True,
    vis_type=VisualizationType.POINT_CLOUD,
    point_size=3.0,
    alpha=0.8,
    color_by_distance=True,
    voxel_size=0.02,
    is_voxel_down=True,
    show_unreachable_points=True
)

# Sphere visualization for presentations
sphere_viz_config = VisualizationConfig(
    vis_type=VisualizationType.SPHERE,
    sphere_radius=0.008,
    sphere_resolution=15,
    alpha=0.6,
    show_unreachable_points=False
)

Visualization Options

• vis_type: Visualization method (POINT_CLOUD, VOXEL, SPHERE, MESH, HEATMAP)

• point_size: Size of rendered points

• alpha: Transparency level (0.0-1.0)

• color_by_distance: Color-code by distance from base

• voxel_size: Downsampling resolution

• show_unreachable_points: Display unreachable regions

5. Dimension Constraints

Defines workspace bounds, exclusion zones, and physical constraints.

from embodichain.lab.sim.utility.workspace_analyzer.configs import DimensionConstraint
import numpy as np

# Basic workspace bounds
dimension_config = DimensionConstraint(
    min_bounds=np.array([-1.0, -1.0, 0.0]),  # [x_min, y_min, z_min]
    max_bounds=np.array([1.0, 1.0, 2.0]),    # [x_max, y_max, z_max]
    joint_limits_scale=0.95,  # Use 95% of joint range
    ground_height=0.0
)

# Complex workspace with exclusion zones
complex_constraints = DimensionConstraint(
    min_bounds=np.array([-2.0, -1.5, -0.5]),
    max_bounds=np.array([2.0, 1.5, 2.5]),
    joint_limits_scale=0.9,
    exclude_zones=[
        # Obstacle 1: table
        (np.array([0.3, -0.5, 0.0]), np.array([1.2, 0.5, 0.8])),
        # Obstacle 2: wall
        (np.array([1.8, -1.5, 0.0]), np.array([2.0, 1.5, 2.5]))
    ],
    ground_height=-0.1,
    enforce_collision_free=True,
    self_collision_check=True
)

Constraint Options

• min_bounds/max_bounds: Cartesian workspace limits

• joint_limits_scale: Scale factor for joint range usage

• exclude_zones: List of forbidden regions

• ground_height: Floor level for filtering

• enforce_collision_free: Enable collision checking

• self_collision_check: Check robot self-collisions

Usage Examples

Basic Workspace Analysis Setup

from embodichain.lab.sim.utility.workspace_analyzer.configs import *

# Complete configuration for basic analysis
sampling_config = SamplingConfig(
    strategy=SamplingStrategy.UNIFORM,
    num_samples=15000,
    grid_resolution=25,
    batch_size=1500
)

cache_config = CacheConfig(
    enabled=True,
    compression=True,
    max_cache_size_mb=2000
)

metric_config = MetricConfig(
    enabled_metrics=[MetricType.REACHABILITY, MetricType.DENSITY],
    save_results=True
)

viz_config = VisualizationConfig(
    vis_type=VisualizationType.POINT_CLOUD,
    point_size=2.5,
    color_by_distance=True
)

constraints = DimensionConstraint(
    min_bounds=np.array([-1.2, -1.2, 0.0]),
    max_bounds=np.array([1.2, 1.2, 1.8]),
    joint_limits_scale=0.9
)

High-Performance Configuration

# Configuration optimized for speed and large datasets
fast_sampling = SamplingConfig(
    strategy=SamplingStrategy.HALTON,  # Better than random
    num_samples=100000,                # Large dataset
    batch_size=10000,                  # Large batches
    seed=42
)

fast_cache = CacheConfig(
    enabled=True,
    compression=False,                 # Faster access
    cache_format="npz",               # Efficient format
    max_cache_size_mb=10000           # Large cache
)

minimal_metrics = MetricConfig(
    enabled_metrics=[MetricType.REACHABILITY],  # Only essential
    reachability=ReachabilityConfig(
        voxel_size=0.02,              # Lower resolution
        compute_coverage=False         # Skip expensive computation
    ),
    save_results=False                # Don't save to disk
)

efficient_viz = VisualizationConfig(
    vis_type=VisualizationType.VOXEL, # Faster than spheres
    voxel_size=0.03,                  # Aggressive downsampling
    is_voxel_down=True,
    show_unreachable_points=False     # Reduce complexity
)

Research Configuration

# Configuration for detailed research analysis
research_sampling = SamplingConfig(
    strategy=SamplingStrategy.SOBOL,  # Low-discrepancy sequence
    num_samples=50000,
    batch_size=2500
)

persistent_cache = CacheConfig(
    enabled=True,
    cache_dir=Path("./research_cache"),
    use_hash=True,
    compression=True,
    cache_format="h5"                 # Good for large datasets
)

comprehensive_metrics = MetricConfig(
    enabled_metrics=[MetricType.ALL],
    reachability=ReachabilityConfig(
        voxel_size=0.005,             # High resolution
        compute_coverage=True
    ),
    manipulability=ManipulabilityConfig(
        jacobian_threshold=0.001,
        compute_isotropy=True,
        compute_heatmap=True          # Generate heatmaps
    ),
    density=DensityConfig(
        radius=0.02,                  # Fine-grained density
        k_neighbors=50,
        compute_distribution=True
    ),
    save_results=True,
    output_format="json"
)

publication_viz = VisualizationConfig(
    vis_type=VisualizationType.SPHERE,
    sphere_radius=0.006,
    sphere_resolution=20,             # High quality spheres
    alpha=0.7,
    color_by_distance=True,
    show_unreachable_points=True
)

detailed_constraints = DimensionConstraint(
    min_bounds=np.array([-1.5, -1.5, -0.2]),
    max_bounds=np.array([1.5, 1.5, 2.0]),
    joint_limits_scale=1.0,           # Full joint range
    exclude_zones=[],                 # No exclusions for research
    enforce_collision_free=True,
    self_collision_check=True
)

Configuration Composition

# Create configurations programmatically
def create_analysis_config(
    resolution: str = "medium",
    enable_cache: bool = True,
    visualization_type: str = "point_cloud"
) -> tuple:
    """Create configuration set based on analysis requirements."""
    
    # Resolution-dependent settings
    resolution_params = {
        "low": {"samples": 5000, "voxel": 0.05, "batch": 1000},
        "medium": {"samples": 20000, "voxel": 0.02, "batch": 2000},
        "high": {"samples": 80000, "voxel": 0.01, "batch": 5000}
    }
    params = resolution_params[resolution]
    
    sampling_config = SamplingConfig(
        strategy=SamplingStrategy.HALTON,
        num_samples=params["samples"],
        batch_size=params["batch"]
    )
    
    cache_config = CacheConfig(enabled=enable_cache)
    
    viz_config = VisualizationConfig(
        vis_type=getattr(VisualizationType, visualization_type.upper()),
        voxel_size=params["voxel"]
    )
    
    return sampling_config, cache_config, viz_config

# Usage
low_res_configs = create_analysis_config("low", True, "voxel")
high_res_configs = create_analysis_config("high", False, "sphere")

Best Practices

Configuration Management

1. Use Type Hints: Leverage the type safety provided by dataclasses

2. Validate Parameters: Check parameter ranges before analysis

3. Document Choices: Comment configuration choices for reproducibility

4. Version Configs: Save configuration alongside results

5. Test Different Settings: Experiment with sampling strategies

Performance Optimization

# Performance tips based on use case
def optimize_for_speed():
    return SamplingConfig(
        strategy=SamplingStrategy.RANDOM,  # Fastest generation
        batch_size=10000,                  # Large batches
        num_samples=20000                  # Moderate resolution
    )

def optimize_for_accuracy():
    return SamplingConfig(
        strategy=SamplingStrategy.SOBOL,   # Better coverage
        batch_size=2000,                   # Moderate batches
        num_samples=100000                 # High resolution
    )

def optimize_for_memory():
    return SamplingConfig(
        batch_size=500,                    # Small batches
        num_samples=15000                  # Moderate total
    )

Configuration Validation

def validate_config(config):
    """Validate configuration parameters."""
    if config.num_samples <= 0:
        raise ValueError("num_samples must be positive")
    
    if config.batch_size > config.num_samples:
        raise ValueError("batch_size cannot exceed num_samples")
    
    if hasattr(config, 'voxel_size') and config.voxel_size <= 0:
        raise ValueError("voxel_size must be positive")

# Usage
try:
    validate_config(my_config)
except ValueError as e:
    print(f"Configuration error: {e}")

API Reference

SamplingConfig

Configuration for joint space sampling strategies.

Parameters

• strategy: SamplingStrategy - Sampling method to use

• num_samples: int - Total number of samples to generate (default: 1000)

• grid_resolution: int - Grid resolution for uniform sampling (default: 10)

• batch_size: int - Batch size for processing (default: 1000)

• seed: int - Random seed for reproducibility (default: 42)

• importance_weight_func: Optional[Callable] - Weight function for importance sampling

• gaussian_mean: Optional[float] - Mean for Gaussian sampling

• gaussian_std: Optional[float] - Standard deviation for Gaussian sampling

CacheConfig

Configuration for result caching and storage.

CacheConfig Parameters

• enabled: bool - Enable caching (default: True)

• cache_dir: Optional[Path] - Cache directory path

• use_hash: bool - Use hash-based cache keys (default: True)

• compression: bool - Compress cache files (default: True)

• max_cache_size_mb: int - Maximum cache size in MB (default: 1000)

• cache_format: str - Cache file format: ‘npz’, ‘pkl’, ‘h5’ (default: ‘npz’)

MetricConfig

Configuration for workspace analysis metrics.

MetricConfig Parameters

• enabled_metrics: List[MetricType] - List of metrics to compute

• reachability: ReachabilityConfig - Reachability analysis settings

• manipulability: ManipulabilityConfig - Manipulability analysis settings

• density: DensityConfig - Density analysis settings

• save_results: bool - Save results to file (default: True)

• output_format: str - Output format: ‘json’, ‘yaml’, ‘pkl’ (default: ‘json’)

VisualizationConfig

Configuration for visualization appearance and behavior.

VisualizationConfig Parameters

• enabled: bool - Enable visualization (default: True)

• vis_type: VisualizationType - Visualization type (default: POINT_CLOUD)

• voxel_size: float - Voxel downsampling size (default: 0.05)

• point_size: float - Point size in visualization (default: 4.0)

• alpha: float - Transparency level 0.0-1.0 (default: 0.5)

• color_by_distance: bool - Color by distance from base (default: True)

• sphere_radius: float - Sphere radius for sphere visualization (default: 0.005)

• show_unreachable_points: bool - Show unreachable points (default: False)

DimensionConstraint

Configuration for workspace bounds and constraints.

DimensionConstraint Parameters

• min_bounds: Optional[np.ndarray] - Minimum workspace bounds [x, y, z]

• max_bounds: Optional[np.ndarray] - Maximum workspace bounds [x, y, z]

• joint_limits_scale: float - Joint range scale factor (default: 1.0)

• exclude_zones: List[Tuple[np.ndarray, np.ndarray]] - Exclusion zones

• ground_height: float - Ground plane height (default: 0.0)

• enforce_collision_free: bool - Enable collision checking (default: False)

• self_collision_check: bool - Check self-collisions (default: False)

Configuration Examples

Minimal Configuration

# Simplest possible configuration
from embodichain.lab.sim.utility.workspace_analyzer.configs import *

config = SamplingConfig()  # Uses defaults
# Result: uniform sampling, 1000 samples, grid resolution 10

Production Configuration

# Production-ready configuration
production_sampling = SamplingConfig(
    strategy=SamplingStrategy.HALTON,
    num_samples=25000,
    batch_size=2500,
    seed=42
)

production_cache = CacheConfig(
    enabled=True,
    cache_dir=Path("/app/cache"),
    compression=True,
    max_cache_size_mb=5000
)

production_metrics = MetricConfig(
    enabled_metrics=[MetricType.REACHABILITY, MetricType.MANIPULABILITY],
    save_results=True,
    output_format="json"
)

Debug Configuration

# Configuration for debugging and development
debug_config = SamplingConfig(
    strategy=SamplingStrategy.UNIFORM,
    num_samples=500,        # Small for fast testing
    batch_size=100,         # Small batches
    grid_resolution=8       # Low resolution
)

debug_viz = VisualizationConfig(
    vis_type=VisualizationType.POINT_CLOUD,
    point_size=5.0,         # Large points for visibility
    show_unreachable_points=True,  # Show all data
    alpha=0.9               # High opacity
)