XyPolyline

java.lang.Object
- com.partnersoft.geometry.xy.XyPolyline

All Implemented Interfaces:

Immutable, XyPath<XyPolyline>, XyShape<XyPolyline>, java.lang.Iterable<XyPoint>
```
public class XyPolyline
extends java.lang.Object
implements XyPath<XyPolyline>
```
A generalized polyline consisting of at least two vertices and one line segment.
Copyright 2007 Partner Software, Inc.

Author:

Paul Reavis, Rich Stepanski, Richard Fay

Constructor Summary

Constructors
Constructor and Description
`XyPolyline(double... coords)` Defines a polygon via a varargs list of x,y coordinates.
`XyPolyline(double[] coordsX, double[] coordsY)` Defines a polygon using a pair of coordinate arrays.
`XyPolyline(double[] coords, int start, int end)` Builds a polygon from an existing coordinate array, including start and ends.
`XyPolyline(DynamicXyPointArray points)` Creates a polygon from an ordered list of XyPoints.
`XyPolyline(java.util.List<XyPoint> points)` Private no-arg constructor, leaves properties unset.
`XyPolyline(XyPoint... points)` Creates a polygon using the varargs list of XyPoint vertices.

Method Summary

Methods
Modifier and Type	Method and Description
`XyPolyline`	`appendedWith(XyPolyline nother)` Appends the given polyline to the end of this one and returns the combined result.
`void`	`appendPointsTo(DynamicXyPointArray array)` Appends the points of this polyline to the given DynamicXyPointArray.
`java.util.List<XyPolyline>`	`clippedTo(XyBounds bounds)` Returns a list of polylines that result from clipping this polyline to the given bounds.
`XyPointOnPolyline`	`closestPointOnPolylineTo(XyPoint nother)` Returns XyPointOnPolyline containing closest point, line segment, and segment's start point's vertex number as well as the original line.
`XyPoint`	`closestPointTo(XyPoint test)`
`boolean`	`contains(XyPoint point)`
`XyBounds`	`getBounds()` Returns an XyBounds object representing the rectangular extents of this shape.
`XyPoint`	`getCenterPoint()` Returns the center point of the polyline.
`XyPointOnPolyline`	`getCenterPointOnPolyline()` Returns XyPointOnPolyline containing center point of the polyline.
`XyPoint`	`getCentroid()` Returns Centroid of this Polyline.
`XyPoint`	`getEndPoint()` Returns the last point in the shape.
`double`	`getLength()` Returns the length of the path.
`int`	`getLineSegmentCount()`
`int`	`getPointCount()`
`XyPoint`	`getStartPoint()` Returns the first point in the shape.
`java.util.Iterator<XyPoint>`	`iterator()`
`XyLineSegment`	`lineSegmentAt(int index)` Returns the index-th XyLineSegment for this XyPolyline.
`java.util.List<XyLineSegment>`	`listLineSegments()` Returns a newly-allocated list of XyLineSegments for this polyline, in the same order as the XyPoints.
`XyPolyline`	`parallelAt(XyPoint point)` Returns a polyline created by offsetting this polyline's shape to a parallel polyline running through the given point.
`XyPolyline`	`parallelAt(XyRotation rotation, double distance)` Returns a polyline created by offsetting this polyline's shape by the given distance in the given relative direction (indicated by a rotation angle).
`XyPoint`	`pointAt(int index)` Returns the index-th XyPoint for this XyPolyline.
`XyPointOnPolyline`	`pointOnPolylineForFraction(double fraction)` Returns XyPointOnPolyline located at the given fraction of the total length from the beginning of the XyPolyline.
`XyPointOnPolyline`	`pointOnPolylineForLength(double length)` Returns XyPointOnPolyline located at the given length (following the polyline, not straight-line) from the beginning of the XyPolyline.
`XyPolyline`	`reversed()` Reverses the order of points in this polyline from start to end.
`XyPolyline`	`scaledBy(double factor)` Return a scaled version of the shape by multiplying all coordinates by the given factor in both dimensions.
`XyPolyline`	`scaledBy(double factorX, double factorY)`
`XyPolyline`	`simplifiedWithGrid(double granularity)` Simplify the polyline by eliminating points who share the same cell on a discreteness grid.
`XyPolyline`	`simplifiedWithMinimumDistance(double granularity)` Simplify the polyline by eliminating segments shorter than a given length.
`java.util.List<XyPolyline>`	`splitAtIntervals(double... intervals)` Returns a list of parts, determined by splitting this polyline up using the sequence of intervals given.
`java.util.List<XyPolyline>`	`splitAtIntervalsOld(double... intervals)` Returns a list of parts, determined by splitting this polyline up using the sequence of intervals given.
`java.util.List<XyPolyline>`	`splitInHalf()`
`double[]`	`toDoubleArray()` Converts to an array of doubles [x0, y0, x1, y1...].
`XyPoint[]`	`toPointArray()` Converts this polyline to an array of XyPoints.
`XyPolyline`	`toPolyline()` Same as `XyPath.toPolyline(XyAngle)` with a default angle granularity of 1/60 circle (6 degrees, pi/30 radians).
`XyPolyline`	`toPolyline(XyAngle granularity)` Converts this area to a polyline which approximates it in some fashion.
`java.lang.String`	`toString()`
`XyPolyline`	`transformedBy(XyTransform transform)` Transform the shape using the given transform.
`XyPolyline`	`translatedBy(double offsetX, double offsetY)` Translate the shape by adding all coordinates to the given x and y offsets.
`XyPolyline`	`withVertexChanged(int vertexIndex, XyPoint newVertex)` Returns a new XyPolyline that is identical to this one except for the given vertex.
`XyPolyline`	`withVertexInserted(int vertexIndex, XyPoint vertex)` Returns a new XyPolyline that is identical to this one except for inserting the given vertex.
`XyPolyline`	`withVertexRemoved(int vertexIndex)` Returns a new XyPolyline that is identical to this one except for removing the given vertex.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - XyPolyline
```
public XyPolyline(double[] coords,
          int start,
          int end)
```
    Builds a polygon from an existing coordinate array, including start and ends.
  - XyPolyline
```
public XyPolyline(double... coords)
```
    Defines a polygon via a varargs list of x,y coordinates. These must be in the order x1, y1, x2, y2...xn, yn.
  - XyPolyline
```
public XyPolyline(double[] coordsX,
          double[] coordsY)
```
    Defines a polygon using a pair of coordinate arrays. One array lists the x coordinates, the other the y. They must have the same length.
    
    Parameters:
    coordsX -
    coordsY -
  - XyPolyline
```
public XyPolyline(XyPoint... points)
```
    Creates a polygon using the varargs list of XyPoint vertices.
    
    Parameters:
    points -
  - XyPolyline
```
public XyPolyline(DynamicXyPointArray points)
```
    Creates a polygon from an ordered list of XyPoints.
    
    Parameters:
    points -
  - XyPolyline
```
public XyPolyline(java.util.List<XyPoint> points)
```
    Private no-arg constructor, leaves properties unset.
- Method Detail
  - withVertexChanged
```
public XyPolyline withVertexChanged(int vertexIndex,
                           XyPoint newVertex)
```
    Returns a new XyPolyline that is identical to this one except for the given vertex.
  - withVertexRemoved
```
public XyPolyline withVertexRemoved(int vertexIndex)
```
    Returns a new XyPolyline that is identical to this one except for removing the given vertex.
  - withVertexInserted
```
public XyPolyline withVertexInserted(int vertexIndex,
                            XyPoint vertex)
```
    Returns a new XyPolyline that is identical to this one except for inserting the given vertex.
  - simplifiedWithGrid
```
public XyPolyline simplifiedWithGrid(double granularity)
```
    Simplify the polyline by eliminating points who share the same cell on a discreteness grid. Returns null if the polyline degenerates into a single point.
    More accurately, what this method does is define a grid with square cells the size of the granularity. It then iterates through the polyline and eliminates points falling into the same cell as the previous point. This provides similar results to the elimination of short segments but much more efficiently. There will be edge effects, however (e.g. where point[i] is just barely to one side of a grid line and point[i + 1] is just barely to the other).
    
    Parameters:
    granularity - size of the discreteness grid applied to eliminate points that are too close
  - simplifiedWithMinimumDistance
```
public XyPolyline simplifiedWithMinimumDistance(double granularity)
```
    Simplify the polyline by eliminating segments shorter than a given length. Returns null if the polyline degenerates into a single point.
    
    Parameters:
    granularity - size of the discreteness grid applied to eliminate points that are too close
  - reversed
```
public XyPolyline reversed()
```
    Reverses the order of points in this polyline from start to end.
  - appendedWith
```
public XyPolyline appendedWith(XyPolyline nother)
```
    Appends the given polyline to the end of this one and returns the combined result. If the end XyPoint of this polyline equals the start XyPoint of the given one, only one of the points is used at the junction.
  - toPointArray
```
public XyPoint[] toPointArray()
```
    Converts this polyline to an array of XyPoints.
  - appendPointsTo
```
public void appendPointsTo(DynamicXyPointArray array)
```
    Appends the points of this polyline to the given DynamicXyPointArray.
  - closestPointOnPolylineTo
```
public XyPointOnPolyline closestPointOnPolylineTo(XyPoint nother)
```
    Returns XyPointOnPolyline containing closest point, line segment, and segment's start point's vertex number as well as the original line.
    *
    
    Parameters:
    nother - - XyPoint to find closest point to on this polyline.
    
    Returns:
    XyPointOnPolyline
  - getCenterPointOnPolyline
```
public XyPointOnPolyline getCenterPointOnPolyline()
```
    Returns XyPointOnPolyline containing center point of the polyline. This is different from the centroid, which is the average of the vertices.
    
    Returns:
    XyPointOnPolyline
  - pointOnPolylineForFraction
```
public XyPointOnPolyline pointOnPolylineForFraction(double fraction)
```
    Returns XyPointOnPolyline located at the given fraction of the total length from the beginning of the XyPolyline. For example, providing 0.25 will give you the point at a quarter the distance from the beginning.
    
    Returns:
    XyPointOnPolyline
  - pointOnPolylineForLength
```
public XyPointOnPolyline pointOnPolylineForLength(double length)
```
    Returns XyPointOnPolyline located at the given length (following the polyline, not straight-line) from the beginning of the XyPolyline.
    
    Returns:
    XyPointOnPolyline
  - getCenterPoint
```
public XyPoint getCenterPoint()
```
    Returns the center point of the polyline. This is different from the centroid, which is the average of the vertices.
  - parallelAt
```
public XyPolyline parallelAt(XyPoint point)
```
    Returns a polyline created by offsetting this polyline's shape to a parallel polyline running through the given point. It uses the perpendicular from the point to the nearest point on this polyline to determine distance and direction.
  - parallelAt
```
public XyPolyline parallelAt(XyRotation rotation,
                    double distance)
```
    Returns a polyline created by offsetting this polyline's shape by the given distance in the given relative direction (indicated by a rotation angle). This is not a simple offset, it is a parallel curve so will be compressed when inside this polyline's curves and expand ed when outside.
  - splitAtIntervalsOld
```
public java.util.List<XyPolyline> splitAtIntervalsOld(double... intervals)
```
    Returns a list of parts, determined by splitting this polyline up using the sequence of intervals given. These intervals will be repeated as needed for the length of the line.
  - splitInHalf
```
public java.util.List<XyPolyline> splitInHalf()
```
  - splitAtIntervals
```
public java.util.List<XyPolyline> splitAtIntervals(double... intervals)
```
    Returns a list of parts, determined by splitting this polyline up using the sequence of intervals given. These intervals will be repeated as needed for the length of the line.
  - listLineSegments
```
public java.util.List<XyLineSegment> listLineSegments()
```
    Returns a newly-allocated list of XyLineSegments for this polyline, in the same order as the XyPoints.
  - lineSegmentAt
```
public XyLineSegment lineSegmentAt(int index)
```
    Returns the index-th XyLineSegment for this XyPolyline. ArrayIndexOutOfBoundsException will result from invalid indices.
  - pointAt
```
public XyPoint pointAt(int index)
```
    Returns the index-th XyPoint for this XyPolyline. ArrayIndexOutOfBoundsException will result from invalid indices.
  - clippedTo
```
public java.util.List<XyPolyline> clippedTo(XyBounds bounds)
```
    Returns a list of polylines that result from clipping this polyline to the given bounds.
  - getLength
```
public double getLength()
```
    Description copied from interface: XyPath
    
    Returns the length of the path.
    
    Specified by:
    
    getLength in interface XyPath<XyPolyline>
    
    Returns:
    geometric length of this shape
  - toPolyline
```
public XyPolyline toPolyline()
```
    Description copied from interface: XyPath
    
    Same as XyPath.toPolyline(XyAngle) with a default angle granularity of 1/60 circle (6 degrees, pi/30 radians).
    
    Specified by:
    
    toPolyline in interface XyPath<XyPolyline>
  - toPolyline
```
public XyPolyline toPolyline(XyAngle granularity)
```
    Description copied from interface: XyPath
    
    Converts this area to a polyline which approximates it in some fashion. For example, a curve can be converted to a polyline with enough segments to roughly approximate its shape. Paths consisting of linked line segments can be represented exactly.
    The angle parameter allows a certain level of control of the output. Essentially it dictates the minimum angular granularity used to approximate curved paths. For example, an arc would be turned into a polyline by placing points around the arc's slice of a circle, separated by the given angle.
    
    Specified by:
    
    toPolyline in interface XyPath<XyPolyline>
  - getStartPoint
```
public XyPoint getStartPoint()
```
    Description copied from interface: XyPath
    
    Returns the first point in the shape.
    
    Specified by:
    
    getStartPoint in interface XyPath<XyPolyline>
  - getEndPoint
```
public XyPoint getEndPoint()
```
    Description copied from interface: XyPath
    
    Returns the last point in the shape.
    
    Specified by:
    
    getEndPoint in interface XyPath<XyPolyline>
  - getCentroid
```
public XyPoint getCentroid()
```
    Returns Centroid of this Polyline. Centroid being the average of all points.
    
    Returns:
    - XyPoint positioned at this XyPolyline's centroid. If Polyline has zero points, an XyPoint at 0,0 is returned;
  - toDoubleArray
```
public double[] toDoubleArray()
```
    Converts to an array of doubles [x0, y0, x1, y1...].
  - closestPointTo
```
public XyPoint closestPointTo(XyPoint test)
```
  - scaledBy
```
public XyPolyline scaledBy(double factor)
```
    Description copied from interface: XyShape
    
    Return a scaled version of the shape by multiplying all coordinates by the given factor in both dimensions. This resulting shape must be of the same class as the original.
    
    Specified by:
    
    scaledBy in interface XyShape<XyPolyline>
    
    Parameters:
    factor - scaling factor
    
    Returns:
    scaled result
  - scaledBy
```
public XyPolyline scaledBy(double factorX,
                  double factorY)
```
  - translatedBy
```
public XyPolyline translatedBy(double offsetX,
                      double offsetY)
```
    Description copied from interface: XyShape
    
    Translate the shape by adding all coordinates to the given x and y offsets. The resulting shape must be of the same class as the original.
    
    Specified by:
    
    translatedBy in interface XyShape<XyPolyline>
    
    Parameters:
    offsetX - offset for the x dimension
    offsetY - offset for the y dimension
    
    Returns:
    offset result
  - transformedBy
```
public XyPolyline transformedBy(XyTransform transform)
```
    Description copied from interface: XyShape
    
    Transform the shape using the given transform. Due to potential distortion the result may be a different type of shape than this one.
    
    Specified by:
    
    transformedBy in interface XyShape<XyPolyline>
    
    Parameters:
    transform - affine transform to apply.
    
    Returns:
    transformed result
  - getBounds
```
public XyBounds getBounds()
```
    Description copied from interface: XyShape
    
    Returns an XyBounds object representing the rectangular extents of this shape.
    
    Specified by:
    
    getBounds in interface XyShape<XyPolyline>
  - contains
```
public boolean contains(XyPoint point)
```
  - iterator
```
public java.util.Iterator<XyPoint> iterator()
```
    Specified by:
    
    iterator in interface java.lang.Iterable<XyPoint>
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - getPointCount
```
public int getPointCount()
```
  - getLineSegmentCount
```
public int getLineSegmentCount()
```

Class XyPolyline

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XyPolyline

XyPolyline

XyPolyline

XyPolyline

XyPolyline

XyPolyline

Method Detail

withVertexChanged

withVertexRemoved

withVertexInserted

simplifiedWithGrid

simplifiedWithMinimumDistance

reversed

appendedWith

toPointArray

appendPointsTo

closestPointOnPolylineTo

getCenterPointOnPolyline

pointOnPolylineForFraction

pointOnPolylineForLength

getCenterPoint

parallelAt

parallelAt

splitAtIntervalsOld

splitInHalf

splitAtIntervals

listLineSegments

lineSegmentAt

pointAt

clippedTo

getLength

toPolyline

toPolyline

getStartPoint

getEndPoint

getCentroid

toDoubleArray

closestPointTo

scaledBy

scaledBy

translatedBy

transformedBy

getBounds

contains

iterator

toString

getPointCount

getLineSegmentCount