Perception API Reference — ManipulaPy 1.1.0 Documentation
Description: This page documents ManipulaPy.perception, the module for higher-level perception capabilities including obstacle detection, 3D point cloud generation, clustering, and environmental understanding f...

# Perception API Reference

This page documents ManipulaPy.perception, the module for higher-level perception capabilities including obstacle detection, 3D point cloud generation, clustering, and environmental understanding for robotic systems.

Tip

For conceptual explanations, see Perception User Guide.

—

## Quick Navigation

—

## Perception Class

—

## Primary Perception Methods

### Obstacle Detection Pipeline

—

## Stereo Vision Integration

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 86)

Title underline too short.

    Stereo Vision Integration
    ========================

### Disparity Computation

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 89)

Title underline too short.

    Disparity Computation
    --------------------

### Point Cloud Generation

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 111)

Title underline too short.

    Point Cloud Generation
    ---------------------

—

## Machine Learning Components

### Clustering Analysis

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 138)

Title underline too short.

    Clustering Analysis
    ------------------

—

## Resource Management

### Cleanup Methods

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 176)

Title underline too short.

    Cleanup Methods
    --------------

—

## Logging Infrastructure

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 201)

Title underline too short.

    Logging Infrastructure
    =====================

### Logger Configuration

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 204)

Title underline too short.

    Logger Configuration
    -------------------

—

### Error Handling Hierarchy

1. Vision Instance Validation: Constructor-level checking

2. Image Availability: Depth image validation with fallbacks

3. Detection Results: None-checking with empty array returns

4. Clustering Input: Empty point array handling

5. Resource Cleanup: Exception-safe cleanup operations

—

## Dependencies and Integration

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 239)

Title underline too short.

    Dependencies and Integration
    ===========================

### Required Dependencies

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 242)

Title underline too short.

    Required Dependencies
    --------------------

Module | Purpose | Integration Point
--- | --- | ---
`sklearn.cluster.DBSCAN` | Point clustering | cluster_obstacles() method
`numpy` | Array operations | All coordinate manipulations
`logging` | Debug/status output | Logger configuration and usage
`ManipulaPy.vision` | Low-level vision | vision_instance dependency

### Vision Module Interface

System Message: WARNING/2 (/home/abo/Desktop/ManipulaPy/docs/source/api/perception.rst, line 265)

Title underline too short.

    Vision Module Interface
    ----------------------

Perception requires Vision instance with specific methods:

- capture_image(): RGB/depth image acquisition

- detect_obstacles(): YOLO-based object detection

- stereo_enabled: Boolean stereo capability flag

- rectify_stereo_images(): Stereo rectification

- compute_disparity(): Disparity map computation

- get_stereo_point_cloud(): 3D reconstruction

- release(): Resource cleanup

—

## Error Recovery and Robustness

### Vision Failure Handling

- Missing Depth: Empty array return with warning logs

- Detection Failures: None-result handling with error logs

- Stereo Unavailability: Runtime exception with clear messaging

### Clustering Robustness

- Empty Input: Graceful handling with early return

- Insufficient Points: DBSCAN handles minimum sample requirements

- Parameter Validation: Implicit through sklearn parameter checking

### Resource Management Safety

- Constructor Validation: Immediate failure for invalid Vision instances

- Cleanup Exceptions: Silent handling in destructor context

- Multiple Cleanup Calls: Safe repeated release() invocation

—

## See Also

- Vision API Reference – Low-level computer vision and camera management

- Path Planning API Reference – Trajectory planning with obstacle avoidance

- Potential Field API Reference – Obstacle-aware potential field methods

- Control API Reference – Control systems with environmental feedback

## External Dependencies

- scikit-learn – DBSCAN clustering algorithm

- NumPy – Numerical array operations

- Python logging – Structured logging framework