Class PathBuilder

java.lang.Object
org.apache.sis.internal.feature.j2d.PathBuilder
Direct Known Subclasses:
Joiner

public class PathBuilder extends Object
Builds a Polyline, Polygon or MultiPolylines from given coordinates.
Since:
1.1
Version:
1.1
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private double[]
    The coordinates as (x,y) tuples.
    private static final int
    Number of coordinates in a tuple.
    private final List<Polyline>
    The polylines built from the coordinates.
    private int
    Number of valid coordinates.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new builder.
  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    append(double[] source, int limit, boolean reverse)
    Appends the given coordinates to current polyline, omitting repetitive points.
    final void
    Adds all polylines defined in the other builder.
    final Shape
    Returns a shape containing all polylines or polygons added to this builder.
    final void
    createPolyline(boolean close)
    Creates a new polyline or polygon with the coordinates added by append(double[], int, boolean).
    protected int
    filterChunk(double[] coordinates, int lower, int upper)
    Applies a custom filtering on the coordinates added by a call to append(double[], int, boolean).
    protected int
    filterFull(double[] coordinates, int upper)
    Applies a custom filtering on the coordinates of a polyline or polygon.
    private boolean
    isValidSize(int limit)
    Verifies that size is even, positive and smaller than the given limit.
    final Shape
    Returns a snapshot of currently added polylines or polygons without modifying the state of this builder.
    Returns a string representation of the polyline under construction for debugging purposes.
    static String
    toString(double[] coordinates, int size)
    Returns a string representation of the given coordinates for debugging purposes.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • DIMENSION

      private static final int DIMENSION
      Number of coordinates in a tuple.
      See Also:
    • coordinates

      private double[] coordinates
      The coordinates as (x,y) tuples. The number of valid coordinates is given by size and this array is expanded as needed. Shall not contains Double.NaN values.
    • size

      private int size
      Number of valid coordinates. This is twice the amount of points.
    • polylines

      private final List<Polyline> polylines
      The polylines built from the coordinates.
  • Constructor Details

    • PathBuilder

      public PathBuilder()
      Creates a new builder.
  • Method Details

    • isValidSize

      private boolean isValidSize(int limit)
      Verifies that size is even, positive and smaller than the given limit. This method is used for assertions.
    • append

      public final void append(PathBuilder other)
      Adds all polylines defined in the other builder. The other builder shall have no polylines under construction, i.e. append(double[], int, boolean) shall not have been invoked since last createPolyline(boolean) invocation.
      Parameters:
      other - the other builder for which to add polylines, or null if none.
    • append

      public final void append(double[] source, int limit, boolean reverse) throws org.opengis.referencing.operation.TransformException
      Appends the given coordinates to current polyline, omitting repetitive points. Coordinates are added to the same polyline than the one updated by previous calls to this method, unless createPolyline(boolean) has been invoked before. The filterChunk(double[], int, int) method is invoked after the points have been added for allowing subclasses to apply customized filtering in addition to the above-cited removal of repetitive points.

      NaN coordinate values

      If the given array contains Double.NaN values, then the coordinates before and after NaNs are stored in two distinct polylines. This is an exception to above paragraph saying that this method does not create new polyline. The filterChunk(double[], int, int) method will be invoked for each of those polylines.
      Parameters:
      source - coordinates to copy.
      limit - index after the last coordinate to copy. Must be an even number.
      reverse - whether to copy (x,y) tuples in reverse order.
      Throws:
      org.opengis.referencing.operation.TransformException - if filterFull(double[], int) wanted to apply a coordinate operation and that transform failed.
    • filterChunk

      protected int filterChunk(double[] coordinates, int lower, int upper)
      Applies a custom filtering on the coordinates added by a call to append(double[], int, boolean). The default implementation does nothing. Subclasses can override this method for changing or removing some coordinate values.

      This method is invoked at least once per append(double[], int, boolean) call. Consequently, it is not necessarily invoked with the coordinates of a complete polyline or polygon, because caller can build a polyline with multiple calls to append(…). If those append(…) calls correspond to some logical chunks (at users choice), this filterChunk(…) method allows users to exploit this subdivision in their processing.

      Parameters:
      coordinates - the coordinates to filter. Values can be modified in-place.
      lower - index of first coordinate to filter. Always even.
      upper - index after the last coordinate to filter. Always even.
      Returns:
      number of valid coordinates after filtering. Should be upper, unless some coordinates have been removed. Must be an even number ≥ 0 and ≤ upper.
    • filterFull

      protected int filterFull(double[] coordinates, int upper) throws org.opengis.referencing.operation.TransformException
      Applies a custom filtering on the coordinates of a polyline or polygon. The default implementation does nothing. Subclasses can override this method for changing or removing some coordinate values. For example, a subclass could decimate points using Ramer–Douglas–Peucker algorithm. Contrarily to filterChunk(double[], int, int), this method is invoked when the coordinates of the full polyline or polygon are available. If polyline points need to be transformed before to build the final geometry, this is the right place to do so.
      Parameters:
      coordinates - the coordinates to filter. Values can be modified in-place.
      upper - index after the last coordinate to filter. Always even.
      Returns:
      number of valid coordinates after filtering. Should be upper, unless some coordinates have been removed. Must be an even number ≥ 0 and ≤ upper.
      Throws:
      org.opengis.referencing.operation.TransformException - if this method wanted to apply a coordinate operation and that transform failed.
    • createPolyline

      public final void createPolyline(boolean close) throws org.opengis.referencing.operation.TransformException
      Creates a new polyline or polygon with the coordinates added by append(double[], int, boolean). If the first point and last point have the same coordinates, then the polyline is automatically closed as a polygon. After this method call, next calls to append(…) will add coordinates in a new polyline.
      Parameters:
      close - whether to force a polygon even if source and last points are different.
      Throws:
      org.opengis.referencing.operation.TransformException - if filterFull(double[], int) wanted to apply a coordinate operation and that transform failed.
    • build

      public final Shape build()
      Returns a shape containing all polylines or polygons added to this builder. The createPolyline(boolean) method should be invoked before this method for making sure that there are no pending polylines.
      Returns:
      the polyline, polygon or collection of polylines. May be null if no polyline or polygon has been created.
    • snapshot

      public final Shape snapshot()
      Returns a snapshot of currently added polylines or polygons without modifying the state of this builder. It is safe to continue building the shape and invoke this method again later for progressive rendering.
      Returns:
      the polyline, polygon or collection of polylines added so far. May be null if no polyline or polygon has been created.
    • toString

      public String toString()
      Returns a string representation of the polyline under construction for debugging purposes. Current implementation formats only the first and last points, and tells how many points are between.
      Overrides:
      toString in class Object
    • toString

      public static String toString(double[] coordinates, int size)
      Returns a string representation of the given coordinates for debugging purposes. Current implementation formats only the first and last points, and tells how many points are between.
      Parameters:
      coordinates - the coordinates for which to return a string representation.
      size - index after the last valid coordinate in coordinates.
      Returns:
      a string representation for debugging purposes.