XyPolyline

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.partnersoft.geometry.xy
Class 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>
extends java.lang.Object
implements XyPath<XyPolyline>

A generalized polyline consisting of at least two vertices and one line segment.

Version:: $Id: XyPolyline.java 2474 2010-03-13 14:28:43Z paul $
Author:: Paul Reavis, Rich Stepanski, Richard Fay

Constructor Summary
`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
`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.