Module org.dyn4j

Class Epa

  • All Implemented Interfaces:
    MinkowskiPenetrationSolver

    public class Epa
    extends java.lang.Object
    implements MinkowskiPenetrationSolver
    Epa, or Expanding Polytope Algorithm, is used to find the penetration depth and vector given the final simplex of Gjk.

    Epa expands the given simplex in the direction of the origin until it cannot be expanded any further. Gjk guarantees that the simplex points are on the edge of the Minkowski sum which creates a convex polytope from which to start the Epa algorithm.

    Expansion is achieved by breaking edges of the simplex. Find the edge on the simplex closest to the origin, then use that edge's normal to find another support point (using the same support method that Gjk uses). Add the new support point to the simplex between the points that made the closest edge. Repeat this process until the polytope cannot be expanded further.

    This implementation has three termination cases:

    • If the new support point is not past the edge along the edge normal given some epsilon.
    • If the distance between the last support point and the new support point is below a given epsilon.
    • Maximum iteration count.
    Once Epa terminates, the penetration vector is the current closest edge normal and the penetration depth is the distance from the origin to the edge along the normal.

    Epa will terminate in a finite number of iterations if the two shapes are Polygons. If either shape has curved surfaces the algorithm requires an expected accuracy epsilon: distanceEpsilon. In the case that the distanceEpsilon is too small, the maxIterations will prevent the algorithm from running forever.

    Since:
    1.0.0
    Version:
    3.2.0
    Author:
    William Bittle
    See Also:
    Gjk, EPA (Expanding Polytope Algorithm)
    • Field Detail

      • DEFAULT_MAX_ITERATIONS

        public static final int DEFAULT_MAX_ITERATIONS
        The default Epa maximum iterations
        See Also:
        Constant Field Values
      • DEFAULT_DISTANCE_EPSILON

        public static final double DEFAULT_DISTANCE_EPSILON
        The default Epa distance epsilon in meters; near 1E-8
      • maxIterations

        protected int maxIterations
        The maximum number of Epa iterations
      • distanceEpsilon

        protected double distanceEpsilon
        The Epa distance epsilon in meters
    • Constructor Detail

      • Epa

        public Epa()
    • Method Detail

      • getMaxIterations

        public int getMaxIterations()
        Returns the maximum number of iterations the algorithm will perform before exiting.
        Returns:
        int
        See Also:
        setMaxIterations(int)
      • setMaxIterations

        public void setMaxIterations​(int maxIterations)
        Sets the maximum number of iterations the algorithm will perform before exiting.
        Parameters:
        maxIterations - the maximum number of iterations in the range [5, ∞]
        Throws:
        java.lang.IllegalArgumentException - if maxIterations is less than 5
      • getDistanceEpsilon

        public double getDistanceEpsilon()
        Returns the distance epsilon.
        Returns:
        double
        See Also:
        setDistanceEpsilon(double)
      • setDistanceEpsilon

        public void setDistanceEpsilon​(double distanceEpsilon)
        The minimum distance between two iterations of the algorithm.

        The distance epsilon is used to determine when the algorithm is close enough to the edge of the minkowski sum to conclude that it can no longer expand. This is primarily used when one of the Convex Shapes in question has a curved shape.

        Parameters:
        distanceEpsilon - the distance epsilon in the range (0, ∞]
        Throws:
        java.lang.IllegalArgumentException - if distanceEpsilon is less than or equal to zero