Workspace Analyzer

Workspace Analyzer#

The Workspace Analyzer is a comprehensive tool in EmbodiChain for analyzing robot workspace characteristics, reachability, and performance metrics. It provides multiple analysis modes with advanced sampling strategies, caching mechanisms, and visualization capabilities.

The analyzer and runtime sampling APIs are unified under embodichain.lab.sim.motion.workspace. See Runtime Workspace Sampling for using cached results in task environments.

Table of Contents#

  1. Quick Start

  2. Analysis Modes

  3. Configuration

  4. Usage Examples

  5. Best Practices

Quick Start#

import torch
import numpy as np
from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
from embodichain.lab.sim.robots import DexforceW1Cfg
from embodichain.lab.sim.motion.workspace import (
    WorkspaceAnalyzer,
    WorkspaceAnalyzerConfig,
    AnalysisMode
)

# Setup simulation
sim = SimulationManager(SimulationManagerCfg(headless=False, sim_device="cpu"))

# Add robot
robot = sim.add_robot(DexforceW1Cfg.from_dict({
    "uid": "dexforce_w1", 
    "version": "v021"
}))

# Quick analysis with defaults
analyzer = WorkspaceAnalyzer(robot=robot, sim_manager=sim)
results = analyzer.analyze(num_samples=1000, visualize=True)
print(f"Analysis complete: {results['num_reachable']} reachable points")

Analysis Modes#

Joint Space Analysis#

Analyzes robot workspace based on joint configurations.

wa_joint = WorkspaceAnalyzer(robot=robot, sim_manager=sim)
results = wa_joint.analyze(num_samples=1000, visualize=True)
print(f"Valid points: {results['num_valid']}/{results['num_samples']}")
Joint Workspace
Joint Workspace Analysis

Cartesian Space Analysis#

Analyzes reachable positions in 3D Cartesian space.

cartesian_config = WorkspaceAnalyzerConfig(
    mode=AnalysisMode.CARTESIAN_SPACE,
    visualization=VisualizationConfig(show_unreachable_points=False, point_size=8.0),
    control_part_name="left_arm",
)

wa_cartesian = WorkspaceAnalyzer(robot=robot, config=cartesian_config, sim_manager=sim)
results = wa_cartesian.analyze(num_samples=1000, visualize=True)
print(f"Reachable points: {results['num_reachable']}/{results['num_samples']}")
pose_workspace1
(show_unreachable_points=True)
pose_workspace2
(show_unreachable_points=False)

Plane Sampling Analysis#

Analyzes reachability within a 2D plane (e.g., table height).

plane_config = WorkspaceAnalyzerConfig(
    mode=AnalysisMode.PLANE_SAMPLING,
    plane_normal=torch.tensor([0.0, 0.0, 1.0]),  # Horizontal plane
    plane_point=torch.tensor([0.0, 0.0, 1.2]),   # Height z=1.2m
    visualization=VisualizationConfig(show_unreachable_points=True, point_size=8.0),
    control_part_name="left_arm",
)

wa_plane = WorkspaceAnalyzer(robot=robot, config=plane_config, sim_manager=sim)
results = wa_plane.analyze(num_samples=1500, visualize=True)
print(f"Reachable points: {results['num_reachable']}/{results['num_samples']}")
plane_workspace1
(show_unreachable_points=True)
plane_workspace2
(show_unreachable_points=False)

Configuration#

Basic Configuration#

from embodichain.lab.sim.motion.workspace.configs import VisualizationConfig

# Basic configuration with defaults
config = WorkspaceAnalyzerConfig(
    mode=AnalysisMode.CARTESIAN_SPACE
)

# Custom visualization
vis_config = VisualizationConfig(
    show_unreachable_points=False,  # Only show reachable points
    point_size=8.0                  # Larger points for visibility
)

config = WorkspaceAnalyzerConfig(
    mode=AnalysisMode.CARTESIAN_SPACE,
    visualization=vis_config,
    control_part_name="left_arm",
)

Configuration Parameters#

Main Parameters:

  • mode: Analysis mode (JOINT_SPACE, CARTESIAN_SPACE, PLANE_SAMPLING)

  • plane_normal: Normal vector for plane sampling (3D vector)

  • plane_point: Point on plane for plane sampling (3D point)

Visualization Options:

  • show_unreachable_points: Show failed samples (True) or only reachable (False)

  • point_size: Size of visualization points (typically 6.0-10.0)

Usage Examples#

Complete Example#

import torch
import numpy as np
from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
from embodichain.lab.sim.robots import DexforceW1Cfg
from embodichain.lab.sim.motion.workspace import (
    WorkspaceAnalyzer, WorkspaceAnalyzerConfig, AnalysisMode
)
from embodichain.lab.sim.motion.workspace.configs import VisualizationConfig

# Setup simulation
sim = SimulationManager(SimulationManagerCfg(headless=False, sim_device="cpu"))

# Add robot
robot = sim.add_robot(DexforceW1Cfg.from_dict({
    "uid": "dexforce_w1", "version": "v021"
}))

# 1. Joint Space Analysis
wa_joint = WorkspaceAnalyzer(robot=robot, sim_manager=sim)
results = wa_joint.analyze(num_samples=1000, visualize=True)

# 2. Cartesian Space Analysis
cartesian_config = WorkspaceAnalyzerConfig(
    mode=AnalysisMode.CARTESIAN_SPACE,
    visualization=VisualizationConfig(show_unreachable_points=False),
    control_part_name="left_arm",
)
wa_cartesian = WorkspaceAnalyzer(robot=robot, config=cartesian_config, sim_manager=sim)
results = wa_cartesian.analyze(num_samples=1000, visualize=True)

# 3. Plane Sampling
plane_config = WorkspaceAnalyzerConfig(
    mode=AnalysisMode.PLANE_SAMPLING,
    plane_normal=torch.tensor([0.0, 0.0, 1.0]),  # Horizontal plane
    plane_point=torch.tensor([0.0, 0.0, 1.2]),   # Height 1.2m
    control_part_name="left_arm",                # robot control part name
)
wa_plane = WorkspaceAnalyzer(robot=robot, config=plane_config, sim_manager=sim)
results = wa_plane.analyze(num_samples=1500, visualize=True)

Best Practices#

Sample Size Guidelines:

  • Joint space: 1000-3000 samples

  • Cartesian space: 1000-2000 samples

  • Plane sampling: 1000-1500 samples

Visualization Tips:

  • Use show_unreachable_points=False for clean workspace boundaries

  • Use show_unreachable_points=True for debugging and complete coverage

  • Set point_size=8.0 for better visibility

  • Use headless=False for visualization, headless=True for batch processing

Performance:

  • Start with smaller sample sizes (1000) for testing

  • Use CPU device for consistent results

  • Disable visualization for large batch analyses

Results:

  • num_valid: Valid joint configurations (Joint Space)

  • num_reachable: Reachable Cartesian points (Cartesian/Plane)

  • num_samples: Total samples tested

  • analysis_time: Time taken for analysis

  • metrics: Workspace volume and other metrics

Contents