Potential Field API Reference — ManipulaPy 1.1.0 Documentation
Description: This page documents ManipulaPy.potential_field, the module for potential field path planning with attractive and repulsive potential computations, gradient calculations, and collision checking for ...

# Potential Field API Reference

This page documents ManipulaPy.potential_field, the module for potential field path planning with attractive and repulsive potential computations, gradient calculations, and collision checking for robotic manipulator motion planning.

Tip

For conceptual explanations, see Potential Field Module User Guide.

—

## Quick Navigation

—

## PotentialField Class

—

## Potential Field Computations

### Attractive Potential

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

Title underline too short.

    Attractive Potential
    -------------------

### Repulsive Potential

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

Title underline too short.

    Repulsive Potential
    ------------------

### Gradient Computation

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

Title underline too short.

    Gradient Computation
    -------------------

—

## CollisionChecker Class

—

## Collision Detection Methods

### Hull Generation

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

Title underline too short.

    Hull Generation
    --------------

### Geometric Transformation

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

Title underline too short.

    Geometric Transformation
    -----------------------

### Collision Detection

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

Title underline too short.

    Collision Detection
    ------------------

—

## Data Structures and Internal Representation

### Convex Hull Storage

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

Title underline too short.

    Convex Hull Storage
    ------------------

Internal convex_hulls dictionary structure:

    convex_hulls = {
        "link_name_1": ConvexHull(vertices_1),
        "link_name_2": ConvexHull(vertices_2),
        # ... additional links
    }

### ConvexHull Properties

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

Title underline too short.

    ConvexHull Properties
    --------------------

Each ConvexHull object contains:

- points: Original vertex coordinates

- vertices: Indices of vertices forming the hull

- simplices: Triangular faces of the hull

- equations: Hyperplane equations for faces

### Forward Kinematics Integration

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

Title underline too short.

    Forward Kinematics Integration
    -----------------------------

Integration with urchin URDF processing:

- Input: Joint configuration (thetalist)

- Method: robot.link_fk(cfg=thetalist)

- Output: Dictionary {link_name: 4×4_transform_matrix}

—

## Computational Complexity Analysis

### Potential Field Methods

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

Title underline too short.

    Potential Field Methods
    ----------------------

Method | Complexity | Dominant Operations
--- | --- | ---
`compute_attractive_potential` | O(n) | Vector subtraction + norm
`compute_repulsive_potential` | O(k×n) | k obstacles × distance computation
`compute_gradient` | O(k×n) | k obstacles × gradient calculation

### Collision Detection Methods

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

Title underline too short.

    Collision Detection Methods
    --------------------------

Method | Complexity | Dominant Operations
--- | --- | ---
`_create_convex_hulls` | O(m×v³) | m links × ConvexHull(v vertices)
`_transform_convex_hull` | O(v) | v vertices × matrix multiplication
`check_collision` | O(L²×v) | L² link pairs × hull intersection

Where: - n: Configuration space dimensions - k: Number of obstacles - m: Number of robot links - v: Average vertices per mesh - L: Number of links with visual geometry

—

## Numerical Implementation Details

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

Title underline too short.

    Numerical Implementation Details
    ===============================

### Potential Field Scaling

Applied scaling factors in implementation:

- Repulsive potential: 10× multiplier on final result

- Repulsive gradient: 5× multiplier on gradient magnitude

- Distance threshold: influence_distance parameter cutoff

### Distance Computations

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

Title underline too short.

    Distance Computations
    --------------------

All distance calculations use numpy.linalg.norm():

- Method: Euclidean L2 norm

- Input: Configuration space vectors

- Precision: Double precision floating point

### Matrix Operations

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

Title underline too short.

    Matrix Operations
    ----------------

Convex hull transformations use optimized NumPy operations:

- Rotation: 3×3 matrix multiplication with broadcasted points

- Translation: Vector addition with reshaped translation vector

- Memory layout: Contiguous arrays for efficient computation

### Intersection Detection

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

Title underline too short.

    Intersection Detection
    ---------------------

Hull intersection testing relies on scipy.spatial.ConvexHull:

- Algorithm: Built-in intersection testing methods

- Precision: Computational geometry tolerance handling

- Robustness: Handles degenerate cases automatically

—

## Error Handling and Edge Cases

### URDF Processing Errors

- Missing files: URDF.load() exception handling

- Invalid geometry: hasattr() validation for mesh.vertices

- Empty meshes: Automatic skipping of links without valid geometry

### Convex Hull Failures

- Coplanar points: scipy.spatial.ConvexHull internal handling

- Insufficient vertices: Minimum 4 points required for 3D hulls

- Numerical precision: Tolerance-based geometric computations

### Potential Field Singularities

- Zero distance: Protected by influence_distance > 0 requirement

- Infinite gradients: Prevented by distance threshold checking

- Numerical overflow: Managed through finite gain parameters

—

## Memory Management

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

Title underline too short.

    Memory Management
    ================

### Convex Hull Storage

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

Title underline too short.

    Convex Hull Storage
    ------------------

Memory allocation for collision checking:

- Hull objects: Persistent storage throughout object lifetime

- Transformed hulls: Temporary allocation during collision checks

- Point arrays: Copy operations for transformation safety

### Potential Field Computations

Memory usage characteristics:

- Gradient arrays: Allocated once, reused for multiple obstacles

- Distance scalars: Temporary variables with automatic cleanup

- Configuration vectors: Input parameter references (no copying)

—

## See Also

- Path Planning API Reference – Trajectory planning integration with potential fields

- Kinematics API Reference – Forward kinematics for collision checking

- Utils Module – Mathematical utilities for vector operations

- URDF Processor API Reference – URDF loading and processing capabilities

## External Dependencies

- urchin – URDF processing library

- scipy.spatial – Convex hull computations

- NumPy – Numerical array operations