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

Disparity Computation

Point Cloud Generation

—

Machine Learning Components

Clustering Analysis

—

Resource Management

Cleanup Methods

—

Logging Infrastructure

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

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

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

External Dependencies