com.partnersoft.geometry.xy
Class XyPolygon

java.lang.Object
  com.partnersoft.geometry.xy.XyPolygon

All Implemented Interfaces:

Immutable, XyArea<XyPolygon>, XyShape<XyPolygon>, java.lang.Iterable<XyPoint>

public class XyPolygon
extends java.lang.Object
implements XyArea<XyPolygon>

A generalized polygon defined as an ordered list of vertices.

The last vertex is automatically reconnected to the first.

Copyright 2007 Partner Software, Inc.

Version:

$Id: XyPolygon.java 2474 2010-03-13 14:28:43Z paul $

Author:

Paul Reavis, Rich Stepanski, Richard Fay

Constructor Summary

XyPolygon(double... coords)
Defines a polygon via a varargs list of x,y coordinates.

XyPolygon(double[] coordsX, double[] coordsY)
Defines a polygon using a pair of coordinate arrays.

XyPolygon(double[] coords, int start, int length)

XyPolygon(DynamicDoubleArray coords)

XyPolygon(java.lang.Iterable<XyPoint> points)
Creates a polygon using the iterable set of XyPoint vertices.

XyPolygon(java.util.List<XyPoint> points)
Creates a polygon from an ordered list of XyPoints.

XyPolygon(XyPoint... points)
Creates a polygon using the varargs list of XyPoint vertices.

Method Summary

java.util.List<XyPolygon>	choppedIntoPiecesWithMaximumVertexCount(int maximumVertexCount) Breaks this polygon into smaller polygons until none of them have more than the given number of vertices.
java.util.List<XyPolygon>	clippedTo(XyBounds bounds) Clips this polygon and returns the results.
boolean	contains(XyPoint point) Tests if a point is inside this area.
boolean	equals(java.lang.Object nother)
double	getArea() Returns the 2-dimensional area covered by this...
XyBounds	getBounds() Returns an XyBounds object representing the rectangular extents of this shape.
XyPoint	getCentroid()
int	getEdgeCount()
double	getPerimeter() Returns the total length of the lines and/or curves bounding the area.
XyPoint	getStartPoint()
int	getVertexCount()
java.util.Iterator<XyPoint>	iterator()
XyPolygon	scaledBy(double factor) Return a scaled version of the shape by multiplying all coordinates by the given factor in both dimensions.
XyPolygon	scaledBy(double factorX, double factorY)
XyPolygon	simplifiedWithMinimumDistance(double granularity) Simplify the polygon by eliminating segments shorter than a given length.
java.awt.Polygon	toAwtPolygon()
double[]	toDoubleArray() Converts vertex list to an array of doubles [x0, y0, x1, y1...].
XyPoint[]	toPointArray()
XyPolygon	toPolygon() Same as XyArea.toPolygon(XyAngle) with a default angle granularity of 1/60 circle (1 degree, pi/30 radians).
XyPolygon	toPolygon(XyAngle granularity) Converts this area to a polygon which approximates it in some fashion.
XyPolyline	toPolyline()
java.lang.String	toString()
XyPolygon	transformedBy(XyTransform transform) Transform the shape using the given transform.
XyPolygon	translatedBy(double offsetX, double offsetY) Translate the shape by adding all coordinates to the given x and y offsets.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XyPolygon

public XyPolygon(DynamicDoubleArray coords)

XyPolygon

public XyPolygon(double[] coords,
                 int start,
                 int length)

XyPolygon

public XyPolygon(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.

XyPolygon

public XyPolygon(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 -

XyPolygon

public XyPolygon(XyPoint... points)

Creates a polygon using the varargs list of XyPoint vertices.

Parameters:

points -

XyPolygon

public XyPolygon(java.lang.Iterable<XyPoint> points)

Creates a polygon using the iterable set of XyPoint vertices.

Parameters:

points -

XyPolygon

public XyPolygon(java.util.List<XyPoint> points)

Creates a polygon from an ordered list of XyPoints.

Parameters:

points -

Method Detail

toPolyline

public XyPolyline toPolyline()

toPointArray

public XyPoint[] toPointArray()

scaledBy

public XyPolygon 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<XyPolygon>

Parameters:

factor - scaling factor

Returns:

scaled result

scaledBy

public XyPolygon scaledBy(double factorX,
                          double factorY)

translatedBy

public XyPolygon 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<XyPolygon>

Parameters:

offsetX - offset for the x dimension

offsetY - offset for the y dimension

Returns:

offset result

transformedBy

public XyPolygon 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<XyPolygon>

Parameters:

transform - affine transform to apply.

Returns:

transformed result

toDoubleArray

public double[] toDoubleArray()

Converts vertex list to an array of doubles [x0, y0, x1, y1...].

choppedIntoPiecesWithMaximumVertexCount

public java.util.List<XyPolygon> choppedIntoPiecesWithMaximumVertexCount(int maximumVertexCount)

Breaks this polygon into smaller polygons until none of them have more than the given number of vertices. It does this using a clipping grid. If it already meets the vertex count maximum it returns only this current polygon, unmodified in the list.

clippedTo

public java.util.List<XyPolygon> clippedTo(XyBounds bounds)

Clips this polygon and returns the results. The list may be empty, or it may contain one or more fragment polygons depending on the way the clip region affects it.

simplifiedWithMinimumDistance

public XyPolygon simplifiedWithMinimumDistance(double granularity)

Simplify the polygon by eliminating segments shorter than a given length. Returns null if the polygon degenerates into less than three vertices.

Parameters:

granularity - size of the discreteness grid applied to eliminate points that are too close

contains

public boolean contains(XyPoint point)

Tests if a point is inside this area.

This implementation is derived from an example provided by Wm. Randolph Franklin and found on this page.

Here is the license:

License to Use

Copyright (c) 1970-2003, Wm. Randolph Franklin

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers.
2. Redistributions in binary form must reproduce the above copyright notice in the documentation and/or other materials provided with the distribution.
3. The name of W. Randolph Franklin may not be used to endorse or promote products derived from this Software without specific prior written permission.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Specified by:

contains in interface XyArea<XyPolygon>

Parameters:

point - point to test for containment

toPolygon

public XyPolygon toPolygon()

Description copied from interface: XyArea

Same as XyArea.toPolygon(XyAngle) with a default angle granularity of 1/60 circle (1 degree, pi/30 radians).

Specified by:

toPolygon in interface XyArea<XyPolygon>

toPolygon

public XyPolygon toPolygon(XyAngle granularity)

Description copied from interface: XyArea

Converts this area to a polygon which approximates it in some fashion. For example, a circle can be converted to a polygon with enough sides to roughly approximate its shape. Areas 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, a circle would be turned into a polygon by placing points around the circle, separated by the given angle.

Specified by:

toPolygon in interface XyArea<XyPolygon>

getArea

public double getArea()

Description copied from interface: XyArea

Returns the 2-dimensional area covered by this... area.

Specified by:

getArea in interface XyArea<XyPolygon>

Returns:

geometric area of this shape

getPerimeter

public double getPerimeter()

Description copied from interface: XyArea

Returns the total length of the lines and/or curves bounding the area.

Specified by:

getPerimeter in interface XyArea<XyPolygon>

Returns:

geometric perimeter of this shape

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<XyPolygon>

getCentroid

public XyPoint getCentroid()

getStartPoint

public XyPoint getStartPoint()

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

equals

public boolean equals(java.lang.Object nother)

Overrides:

equals in class java.lang.Object

toAwtPolygon

public java.awt.Polygon toAwtPolygon()

getVertexCount

public int getVertexCount()

getEdgeCount

public int getEdgeCount()