Workspace Analyzer Metrics

Workspace Analyzer Metrics#

The Workspace Analyzer Metrics module provides comprehensive metrics and analysis tools for evaluating robotic workspace characteristics. This module implements various quantitative measures to assess workspace quality, coverage, manipulability, and performance.

Overview#

This module provides three main workspace analysis metrics:

  • ReachabilityMetric: Voxel-based volume and coverage analysis ✅

  • ManipulabilityMetric: Dexterity analysis (heuristic method or with Jacobians) ✅

  • DensityMetric: Point distribution and density analysis ✅

Note: Some advanced features like spatial heatmaps, clustering analysis, and robot-specific helpers are not yet implemented.

Table of Contents#

Metric Types#

1. ReachabilityMetric#

Computes workspace volume and coverage using voxel-based analysis.

import numpy as np
from embodichain.lab.sim.utility.workspace_analyzer.metrics import ReachabilityMetric

# Basic usage
workspace_points = np.random.uniform(-1, 1, size=(1000, 3))
reachability = ReachabilityMetric()
results = reachability.compute(workspace_points)

print(f"Volume: {results['volume']:.4f} m³")
print(f"Coverage: {results['coverage']:.1f}%")

Returns: volume, coverage percentage, voxel count, bounding box, centroid

2. ManipulabilityMetric#

Analyzes dexterity using distance-based heuristic or Yoshikawa index (with Jacobians).

import numpy as np
from embodichain.lab.sim.utility.workspace_analyzer.metrics import ManipulabilityMetric

# Basic usage (heuristic method)
workspace_points = np.random.uniform(-1, 1, size=(1000, 3))
manipulability = ManipulabilityMetric()
results = manipulability.compute(workspace_points)

print(f"Mean manipulability: {results['mean_manipulability']:.3f}")

Returns: mean, std, min, max manipulability; condition numbers (if Jacobians provided)

3. DensityMetric#

Computes local point density using radius-based neighborhood analysis.

import numpy as np
from embodichain.lab.sim.utility.workspace_analyzer.metrics import DensityMetric

# Basic usage
workspace_points = np.random.uniform(-1, 1, size=(1000, 3))
density = DensityMetric()
results = density.compute(workspace_points)

print(f"Mean density: {results['mean_density']:.2f}")

Returns: mean, std, min, max density; distribution histogram (if enabled)

Usage Examples#

Basic Usage#

import numpy as np
from embodichain.lab.sim.utility.workspace_analyzer.metrics import (
    ReachabilityMetric, ManipulabilityMetric, DensityMetric
)

# Generate sample data
workspace_points = np.random.uniform(-1, 1, size=(5000, 3))

# Compute all metrics
reach_results = ReachabilityMetric().compute(workspace_points)
manip_results = ManipulabilityMetric().compute(workspace_points)
density_results = DensityMetric().compute(workspace_points)

print(f"Volume: {reach_results['volume']:.4f} m³")
print(f"Mean manipulability: {manip_results['mean_manipulability']:.3f}")
print(f"Mean density: {density_results['mean_density']:.2f}")

With Custom Configuration#

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

# Custom configuration
reach_config = ReachabilityConfig(voxel_size=0.02, compute_coverage=True)
density_config = DensityConfig(radius=0.1, compute_distribution=True)

reachability = ReachabilityMetric(reach_config)
density = DensityMetric(density_config)

reach_results = reachability.compute(workspace_points)
density_results = density.compute(workspace_points)

Configuration#

All metrics can be customized using configuration classes:

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

# Reachability configuration
reach_config = ReachabilityConfig(
    voxel_size=0.01,          # Voxel size in meters
    min_points_per_voxel=1,   # Minimum points for occupancy
    compute_coverage=True     # Enable coverage calculation
)

# Manipulability configuration  
manip_config = ManipulabilityConfig(
    jacobian_threshold=0.01,  # Minimum valid manipulability
    compute_isotropy=True     # Enable condition number analysis
)

# Density configuration
density_config = DensityConfig(
    radius=0.05,              # Neighborhood radius
    compute_distribution=True # Enable histogram computation
)

API Reference#

ReachabilityMetric: Returns volume, coverage, num_voxels, bounding_box, centroid

ManipulabilityMetric: Returns mean/std/min/max manipulability, num_valid_points, condition numbers (if available)

DensityMetric: Returns mean/std/min/max density, distribution histogram (if enabled)

Quick Reference#

# Default usage
reachability = ReachabilityMetric()
manipulability = ManipulabilityMetric() 
density = DensityMetric()

# Custom configuration
from embodichain.lab.sim.utility.workspace_analyzer.configs import ReachabilityConfig
reach_config = ReachabilityConfig(voxel_size=0.02, compute_coverage=True)
reachability = ReachabilityMetric(reach_config)
Contents