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.

—

PotentialField Class

—

Potential Field Computations

Attractive Potential

Repulsive Potential

Gradient Computation

—

CollisionChecker Class

—

Collision Detection Methods

Hull Generation

Geometric Transformation

Collision Detection

—

Data Structures and Internal Representation

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

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

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

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

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

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

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

Method: Euclidean L2 norm
Input: Configuration space vectors
Precision: Double precision floating point

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

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

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)

—

External Dependencies

urchin – URDF processing library
scipy.spatial – Convex hull computations
NumPy – Numerical array operations

Potential Field API Reference

Quick Navigation

PotentialField Class

Potential Field Computations

Attractive Potential

Repulsive Potential

Gradient Computation

CollisionChecker Class

Collision Detection Methods

Hull Generation

Geometric Transformation

Collision Detection

Data Structures and Internal Representation

Convex Hull Storage

ConvexHull Properties

Forward Kinematics Integration

Computational Complexity Analysis

Potential Field Methods

Collision Detection Methods

Numerical Implementation Details

Potential Field Scaling

Distance Computations

Matrix Operations

Intersection Detection

Error Handling and Edge Cases

URDF Processing Errors

Convex Hull Failures

Potential Field Singularities

Memory Management

Convex Hull Storage

Potential Field Computations

See Also

External Dependencies