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.

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.utility.workspace_analyzer 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", 
    "arm_kind": "industrial"
}))

# 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.utility.workspace_analyzer.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.utility.workspace_analyzer import (
    WorkspaceAnalyzer, WorkspaceAnalyzerConfig, AnalysisMode
)
from embodichain.lab.sim.utility.workspace_analyzer.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", "arm_kind": "industrial"
}))

# 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