Package de.xima.fc.common.geometry

Class AxisAlignedRouter2D

  • public final class AxisAlignedRouter2D
extends Object
    Router for creating paths with axis-aligned lines. An axis-aligned line is a line that parallel to a coordinate axis, i.e. either a horizontal or vertical line.
    Since:
    8.4.0

    • Method Detail

      • approximateWithAxisAlignedPath

        public static <Point> List<Point> approximateWithAxisAlignedPath​(Iterable<Point> points,
                                                                 Point2DDoubleAdapter<Point> adapter,
                                                                 ECartesianAxis2D firstAxis,
                                                                 double precision)
        Approximates a path of line segments using only axis-aligned lines.

        For example, given the points p1, p2, p3 that form a diagonal line like this: 

                                   p3
                           ⟋⟍------- q8
                         ⟋ |  ⟍    |
                       ⟋   |    ⟍  |
                     ⟋_____| q7   ⟍|______ q10
                   ⟋ | q6        q9 ⟍    |
                 ⟋   |                ⟍  |
               ⟋_____| q5               ⟍|
             ⟋ | q4                      p3
           ⟋   |
         ⟋_____| q3
       ⟋ | q2
     ⟋   |
   ⟋_____| q1
 p1
        Will create additional points q* to approximate the path with axis-aligned lines. The returned points then are p1, q1, q2, q3, q4, q5, q6, q7, q8, q9, q0, p2.

        The precision parameter controls how many additional points are added to the path. In the example above, the precision is equal to the distance between p1 / q2, q2 / q4, and q4 / q6. The distance q6 / p2 might be shorter.

        Type Parameters:
        Point - The type of the points in the input iterable.
        Parameters:
        points - Points to create the path from. Must contain at least two points. If not, just returns a list with the given points.
        adapter - Adapter to treat objects as points in 2D space.
        firstAxis - Whether axis-aligned segment should go horizontally first (X) or vertically first (Y).
        precision - The length of the diagonal of an axis-aligned segment. Can be used to control how precise the approximation should be. The smaller the value, the more points will be added to the path, and the more precise the path will be.
        Returns:
        The axis-aligned path.

      • approximateWithAxisAlignedPath

        public static <Point> List<Point> approximateWithAxisAlignedPath​(Iterator<Point> points,
                                                                 Point2DDoubleAdapter<Point> adapter,
                                                                 ECartesianAxis2D firstAxis,
                                                                 double precision)
        Approximates a path of line segments using only axis-aligned lines.

        For example, given the points p1, p2, p3 that form a diagonal line like this: 

                                   p3
                           ⟋⟍------- q8
                         ⟋ |  ⟍    |
                       ⟋   |    ⟍  |
                     ⟋_____| q7   ⟍|______ q10
                   ⟋ | q6        q9 ⟍    |
                 ⟋   |                ⟍  |
               ⟋_____| q5               ⟍|
             ⟋ | q4                      p3
           ⟋   |
         ⟋_____| q3
       ⟋ | q2
     ⟋   |
   ⟋_____| q1
 p1
        Will create additional points q* to approximate the path with axis-aligned lines. The returned points then are p1, q1, q2, q3, q4, q5, q6, q7, q8, q9, q0, p2.

        The precision parameter controls how many additional points are added to the path. In the example above, the precision is equal to the distance between p1 / q2, q2 / q4, and q4 / q6. The distance q6 / p2 might be shorter.

        Type Parameters:
        Point - The type of the points in the input iterable.
        Parameters:
        points - Points to create the path from. Must contain at least two points. If not, just returns a list with the given points.
        adapter - Adapter to treat objects as points in 2D space.
        firstAxis - Whether axis-aligned segment should go horizontally first (X) or vertically first (Y).
        precision - The length of the diagonal of an axis-aligned segment. Can be used to control how precise the approximation should be. The smaller the value, the more points will be added to the path, and the more precise the path will be.
        Returns:
        The axis-aligned path.

      • axisAlignedPath

        public static List<Point2DDouble> axisAlignedPath​(Iterable<Point2DDouble> points,
                                                  ECartesianAxis2D firstAxis)
        Given a set of points, returns a list of points that represent the path from the first point to the last point, using only straight (axis-aligned) lines. The path is created by first going straight on the given axis, then making a sharp turn to the other axis for the second point. Then proceeds along the same axis, if possible, to the next point, and so on.

        To illustrate, here's an example of a path with 4 points, 1 source point (s), 3 waypoints (w1, w2, w3), and 1 target point (t). The input points are: (s, w1, w2, t). If the first axis is the y-axis (vertical): 

                             w2
                      o────────────┐ c3
                      │            │
  c1 ┌───────o────────┘ c2         │
     │       w1                    o w3
     │                             │
     │                             │
     │ first axis                  └────────────o
     │                            c4            t
     o  s
        The resulting list contains 7 points, in this order: (s, c1, c2, w2, c3, c4, t). The waypoints w1 and w3 are not included in this list as they lie on the same axis as the neighbouring points. On the other hand, if the first axis is the x-axis (horizontal): 
                    c2       w2
             ┌────────o────────────┐ c3
             │                     │
          w1 o                     │
             │                     o w3
             │                     │
             │                     │
             │                     └────────────o
             │                    c4            t
   s o───────┘ c1
       first
       axis
        Parameters:
        points - Points to create the path from. Must contain at least two points. If not, just returns a list with the given points.
        firstAxis - The first axis to go straight on.
        Returns:
        The path through the points, using only straight (axis-aligned) lines.

      • axisAlignedPath

        public static List<Point2DDouble> axisAlignedPath​(Iterator<Point2DDouble> points,
                                                  ECartesianAxis2D firstAxis)
        Given a set of points, returns a list of points that represent the path from the first point to the last point, using only straight (axis-aligned) lines. The path is created by first going straight on the given axis, then making a sharp turn to the other axis for the second point. Then proceeds along the same axis, if possible, to the next point, and so on.

        To illustrate, here's an example of a path with 4 points, 1 source point (s), 3 waypoints (w1, w2, w3), and 1 target point (t). The input points are: (s, w1, w2, t). If the first axis is the y-axis (vertical): 

                             w2
                      o────────────┐ c3
                      │            │
  c1 ┌───────o────────┘ c2         │
     │       w1                    o w3
     │                             │
     │                             │
     │ first axis                  └────────────o
     │                            c4            t
     o  s
        The resulting list contains 7 points, in this order: (s, c1, c2, w2, c3, c4, t). The waypoints w1 and w3 are not included in this list as they lie on the same axis as the neighbouring points. On the other hand, if the first axis is the x-axis (horizontal): 
                    c2       w2
             ┌────────o────────────┐ c3
             │                     │
          w1 o                     │
             │                     o w3
             │                     │
             │                     │
             │                     └────────────o
             │                    c4            t
   s o───────┘ c1
       first
       axis
        Parameters:
        points - Points to create the path from. Must contain at least two points. If not, just returns a list with the given points.
        firstAxis - The first axis to go straight on.
        Returns:
        The path through the points, using only straight (axis-aligned) lines.

      • cornerPoint

        public static Point2DDouble cornerPoint​(Point2DDouble start,
                                        Point2DDouble end,
                                        ECartesianAxis2D firstAxis)
        Walks from the given start point to the given end point, by first going straight on the given axis, then making a sharp turn to the other axis. Returns the corner point representing the sharp turn. If both points are axis aligned, returns the midway point between the two points.

        To illustrate, here are a source and target point, together with a corner point. The first axis is the y-axis (vertical): 

          corner
     ┌────────────> target
     │
     │
     │ first axis
     │
     │
   source
        Parameters:
        start - The start point.
        end - The end point.
        firstAxis - The first axis to go straight on.
        Returns:
        The corner point representing the sharp turn.

      • isAxisAligned

        public static <Point> boolean isAxisAligned​(Point p1,
                                            Point p2,
                                            Point2DDoubleAdapter<Point> adapter)