Package de.bsommerfeld.pathetic.engine.result

Class PathUtils

java.lang.Object
de.bsommerfeld.pathetic.engine.result.PathUtils
public final class PathUtils extends Object
Utility class providing post-processing operations on Path objects.

All methods are static, immutable (return new paths), and use ArrayDeque internally for optimal performance when building sequences.

These operations are not part of core pathfinding but are essential for path refinement, visualization, animation, or coordinate transformation.

Since:
5.3.3
See Also:

  • Method Details

    • interpolate

      public static Path interpolate(Path path, double resolution)
      Interpolates a path by inserting intermediate positions between each pair of consecutive points.

      For every segment from start to end, this method calculates the Euclidean distance and inserts points such that no two consecutive points are farther apart than resolution.

      Useful for smooth movement, dense sampling, or visualization.

      Parameters:
      path - the original path to interpolate
      resolution - the maximum allowed distance between any two consecutive points in the result
      Returns:
      a new path with interpolated positions
      Throws:
      IllegalArgumentException - if resolution <= 0
      NullPointerException - if path is null

    • simplify

      public static Path simplify(Path path, double epsilon)
      Simplifies a path by retaining only every nth point based on an epsilon value.

      The stride is calculated as max(1, round(1.0 / epsilon)), meaning:

      • epsilon = 1.0 → keep every point
      • epsilon = 0.5 → keep every 2nd point
      • epsilon = 0.1 → keep every 10th point

      This is a lightweight downsampling method. For geometric simplification (e.g. Ramer-Douglas-Peucker), use a dedicated algorithm.

      Parameters:
      path - the path to simplify
      epsilon - a value in (0.0, 1.0] controlling sampling density
      Returns:
      a new simplified path
      Throws:
      IllegalArgumentException - if epsilon is not in (0.0, 1.0]

    • join

      public static Path join(Path first, Path second)
      Concatenates two paths into a single continuous path.

      The end of the first path is connected to the start of the second. If either path is empty, the other is returned.

      Parameters:
      first - the first path segment
      second - the second path segment
      Returns:
      a new path combining both
      Throws:
      NullPointerException - if either argument is null

    • trim

      public static Path trim(Path path, int maxLength)
      Truncates a path to a maximum number of positions.

      If the path has fewer than maxLength positions, it is returned unchanged. Otherwise, only the first maxLength positions are kept.

      Parameters:
      path - the path to trim
      maxLength - the maximum number of positions to retain
      Returns:
      a new path with at most maxLength positions
      Throws:
      IllegalArgumentException - if maxLength <= 0

    • mutatePositions

      public static Path mutatePositions(Path path, ParameterizedSupplier<PathPosition> mutator)
      Applies a transformation function to every position in the path.

      This is a functional map operation: each PathPosition is passed to the ParameterizedSupplier, and the returned position is included in the new path.

      Use cases:

      • Coordinate system conversion (world → screen)
      • Scaling, rotation, offset
      • Adding metadata (e.g. timestamp, color)
      • Path animation (e.g. oscillation)
      Parameters:
      path - the original path
      mutator - a function that transforms one position into another
      Returns:
      a new path with transformed positions
      Throws:
      NullPointerException - if mutator is null