org.geotools.renderer.geom
Class Polyline

java.lang.Object
  org.geotools.renderer.geom.Geometry
      org.geotools.renderer.geom.Polyline

All Implemented Interfaces:

java.lang.Cloneable, org.opengis.util.Cloneable, java.io.Serializable, java.awt.Shape

Direct Known Subclasses:

Polygon

public class Polyline

extends Geometry

A succession of lines linked by their extremities. A polyline is closed if it is part of a Polygon (either the external ring of one of the holes). Each Polyline object can have its own CoordinateSystem object, usually specified at construction time. A set of Polylines can be built from an array of (x,y) coordinates or from a geometric shape using one of GeometryCollection.add(...) methods. Points given to those methods should not contain map border. Border points (orange points in the figure below) are treated specially and must be specified using appendBorder(...) or prependBorder(...) methods.

Version:

$Id: Polyline.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

Polygon, GeometryCollection, Serialized Form

Field Summary

Fields inherited from class org.geotools.renderer.geom.Geometry

DEFAULT_COORDINATE_SYSTEM

Constructor Summary

Polyline(CoordinateSystem coordinateSystem)
Construct an empty Polyline.

Polyline(Polyline polyline)
Construct a new Polyline with the same data as the specified one.

Method Summary

void	append(float[] points, int lower, int upper) Adds the specified coordinate points to the end of this polyline.
void	append(Polyline toAppend) Adds to the end of this polyline the data of the specified polyline.
void	appendBorder(float[] border, int lower, int upper) Adds points to the end of this polyline.
Geometry	clip(Clipper clipper) Returns a polyline approximately equal to this polyline clipped to the specified bounds.
java.lang.Object	clone() Return a clone of this polyline.
void	close() Close this polyline.
float	compress(CompressionLevel level) Compress this polyline.
boolean	contains(double x, double y) Indicates whether the specified (x,y) coordinate is inside this polyline.
boolean	contains(java.awt.geom.Point2D pt) Checks whether a point pt is inside this polyline.
boolean	contains(java.awt.geom.Rectangle2D rect) Test if the interior of this polyline entirely contains the given rectangle.
boolean	contains(java.awt.Shape shape) Test if the interior of this polyline entirely contains the given shape.
boolean	equals(java.lang.Object object) Compare the specified object with this polyline for equality.
java.awt.geom.Rectangle2D	getBounds2D() Return the bounding box of this polyline, including its possible borders.
int	getCachedPointCount() Returns the number of points in the cache.
CoordinateSystem	getCoordinateSystem() Returns the polyline's coordinate system, or null if unknown.
java.awt.geom.Point2D	getFirstPoint(java.awt.geom.Point2D point) Stores the value of the first point into the specified point object.
void	getFirstPoints(java.awt.geom.Point2D[] points) Stores the values of points.length first points into the specified array.
java.awt.geom.Point2D	getLastPoint(java.awt.geom.Point2D point) Stores the value of the last point into the specified point object.
void	getLastPoints(java.awt.geom.Point2D[] points) Stores the values of points.length last points into the specified array.
java.awt.geom.PathIterator	getPathIterator(java.awt.geom.AffineTransform transform) Returns a path iterator for this polyline.
int	getPointCount() Return the number of points in this polyline.
java.util.Collection	getPoints() Returns all polyline's points.
float	getRenderingResolution() Returns the rendering resolution.
Statistics	getResolution() Returns the polyline's resolution.
int	hashCode() Returns a hash value for this polyline.
boolean	intersects(java.awt.geom.Rectangle2D rect) Tests if the interior of the polyline intersects the interior of a specified rectangle.
boolean	intersects(java.awt.Shape shape) Tests if the interior of the polyline intersects the interior of a specified shape.
boolean	isClosed() Returns whether this polyline is closed or not.
boolean	isEmpty() Test if this polyline is empty.
void	prependBorder(float[] border, int lower, int upper) Adds points to the start of this polyline.
static void	print(Polyline[] polylines, java.io.Writer out, java.util.Locale locale) Write all point coordinates of many polylines side by side.
static void	print(java.lang.String[] titles, java.util.Collection[] points, java.io.Writer out, java.util.Locale locale) Write all points from arbitrary collections side by side.
void	print(java.io.Writer out, java.util.Locale locale) Write all point coordinates to the specified stream.
protected void	readObject(java.io.ObjectInputStream in) Invoked during deserialization.
void	reverse() Reverse point order in this polyline.
void	setCoordinateSystem(CoordinateSystem coordinateSystem) Sets the polyline's coordinate system.
void	setRenderingResolution(float resolution) Hints this polyline that the specified resolution is sufficient for rendering.
void	setResolution(double resolution) Sets the polyline's resolution.
Polyline	subpoly(int lower, int upper) Returns a polyline with the point of this polyline from lower inclusive to upper exclusive.
float[]	toArray(float resolution) Returns a copy of all coordinates of this polyline.

Methods inherited from class org.geotools.renderer.geom.Geometry

contains, getBounds, getID, getName, getPathIterator, getStyle, getUserObject, intersects, setID, setStyle, setUserObject, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Polyline

public Polyline(CoordinateSystem coordinateSystem)

Construct an empty Polyline. Points can be added after the construction with the append(float[], int, int) method.

Parameters:

coordinateSystem - The coordinate system to use for all points in this Polyline, or null if unknown.

Polyline

public Polyline(Polyline polyline)

Construct a new Polyline with the same data as the specified one. The new Polyline will have a copy semantic. However, implementation shares as much internal data as possible in order to reduce memory footprint.

Method Detail

getCoordinateSystem

public CoordinateSystem getCoordinateSystem()

Returns the polyline's coordinate system, or null if unknown.

Specified by:

getCoordinateSystem in class Geometry

setCoordinateSystem

public void setCoordinateSystem(CoordinateSystem coordinateSystem)
                         throws org.opengis.referencing.operation.TransformException,
                                UnmodifiableGeometryException

Sets the polyline's coordinate system. Calling this method is equivalent to reprojecting all polyline's points from the old coordinate system to the new one.

Specified by:

setCoordinateSystem in class Geometry

Parameters:

coordinateSystem - The new coordinate system. A null value resets the coordinate system given at construction time.

Throws:

org.opengis.referencing.operation.TransformException - If a transformation failed. In case of failure, the state of this object will stay unchanged (as if this method has never been invoked).

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

prependBorder

public void prependBorder(float[] border,
                          int lower,
                          int upper)
                   throws org.opengis.referencing.operation.TransformException,
                          java.lang.IllegalStateException

Adds points to the start of this polyline. These points will be considered to form part of the map border, and not considered as points representing a geographic structure.

Parameters:

border - Coordinates to add as (x,y) number pairs.

lower - Index of the first x ordinate to add to the border.

upper - Index after the last y ordinate to add to the border.

Throws:

org.opengis.referencing.operation.TransformException - if border contains points that are invalid for this polyline's native coordinate system.

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

java.lang.IllegalStateException - if this polyline has already been closed.

appendBorder

public void appendBorder(float[] border,
                         int lower,
                         int upper)
                  throws org.opengis.referencing.operation.TransformException,
                         java.lang.IllegalStateException

Adds points to the end of this polyline. These points will be considered to form part of the map border, and not considered as points representing a geographic structure.

Parameters:

border - Coordinates to add as (x,y) number pairs.

lower - Index of the first x ordinate to add to the border.

upper - Index after the last y ordinate to add to the border.

Throws:

org.opengis.referencing.operation.TransformException - if border contains points that are invalid for this polyline's native coordinate system.

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

java.lang.IllegalStateException - if this polyline has already been closed.

append

public void append(float[] points,
                   int lower,
                   int upper)
            throws org.opengis.referencing.operation.TransformException,
                   java.lang.IllegalStateException

Adds the specified coordinate points to the end of this polyline.

Parameters:

points - Array of (x,y) coordinates points. These data will be copied, in such a way that any future modifications of data will have no impact on the Polylines created.

lower - Index of the first x ordinate to add to the polyline.

upper - Index after the last y ordinate to add to the polyline.

Throws:

org.opengis.referencing.operation.TransformException - if points contains points that are invalid for this polyline's native coordinate system.

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

java.lang.IllegalStateException - if this polyline has already been closed.

append

public void append(Polyline toAppend)
            throws org.opengis.referencing.operation.TransformException,
                   java.lang.IllegalStateException

Adds to the end of this polyline the data of the specified polyline. This method does nothing if toAppend is null.

Parameters:

toAppend - Polyline to add to the end of this. The polyline toAppend will not be modified.

Throws:

java.lang.IllegalStateException - if this polyline has already been closed.

org.opengis.referencing.operation.TransformException - if toAppend contains points that are invalid for this polyline's native coordinate system.

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

java.lang.IllegalArgumentException - if the polyline toAppend has already been closed.

reverse

public void reverse()

Reverse point order in this polyline.

subpoly

public Polyline subpoly(int lower,
                        int upper)

Returns a polyline with the point of this polyline from lower inclusive to upper exclusive. The returned polyline may not be closed. If no data are available in the specified range, this method returns null.

close

public void close()

Close this polyline. After closing it, no more points can be added to this polyline.

isClosed

public boolean isClosed()

Returns whether this polyline is closed or not. A closed polyline is usually a Polygon instance.

isEmpty

public boolean isEmpty()

Test if this polyline is empty. An empty polyline contains no points.

Overrides:

isEmpty in class Geometry

See Also:

getPointCount()

getCachedPointCount

public int getCachedPointCount()

Returns the number of points in the cache. This method is invoked only for statistics purpose after a rendering. The number of points is the absolute value of the returned value. A positive value means that the cache has been reused. A negative value means that the cache has been flushed and recomputed.

getPointCount

public int getPointCount()

Return the number of points in this polyline.

Specified by:

getPointCount in class Geometry

See Also:

isEmpty(), getPoints(), getFirstPoint(java.awt.geom.Point2D), getFirstPoints(java.awt.geom.Point2D[]), getLastPoint(java.awt.geom.Point2D), getLastPoints(java.awt.geom.Point2D[]), toArray(float)

getPoints

public java.util.Collection getPoints()

Returns all polyline's points. Point coordinates are stored in Point2D objects using this polyline's coordinate system (getCoordinateSystem()). This method returns an immutable collection: changes done to Polyline after calling this method will not affect the collection. Despite the fact that this method has a copy semantic, the collection will share many internal structures in such a way that memory consumption should stay low.

Returns:

The polyline's points as a collection of Point2D objects.

See Also:

getFirstPoint(java.awt.geom.Point2D), getFirstPoints(java.awt.geom.Point2D[]), getLastPoint(java.awt.geom.Point2D), getLastPoints(java.awt.geom.Point2D[])

getFirstPoint

public java.awt.geom.Point2D getFirstPoint(java.awt.geom.Point2D point)
                                    throws java.util.NoSuchElementException

Stores the value of the first point into the specified point object.

Parameters:

point - Object in which to store the unprojected coordinate.

Returns:

point, or a new Point2D if point was null.

Throws:

java.util.NoSuchElementException - If this polyline contains no point.

See Also:

getFirstPoints(Point2D[]), getLastPoint(Point2D)

getLastPoint

public java.awt.geom.Point2D getLastPoint(java.awt.geom.Point2D point)
                                   throws java.util.NoSuchElementException

Stores the value of the last point into the specified point object.

Parameters:

point - Object in which to store the unprojected coordinate.

Returns:

point, or a new Point2D if point was null.

Throws:

java.util.NoSuchElementException - If this polyline contains no point.

See Also:

getLastPoints(Point2D[]), getFirstPoint(Point2D)

getFirstPoints

public void getFirstPoints(java.awt.geom.Point2D[] points)
                    throws java.util.NoSuchElementException

Stores the values of points.length first points into the specified array.

Parameters:

points - An array to fill with first polyline's points. points[0] will contains the first point, points[1] the second point, etc.

Throws:

java.util.NoSuchElementException - If this polyline doesn't contain enough points.

getLastPoints

public void getLastPoints(java.awt.geom.Point2D[] points)
                   throws java.util.NoSuchElementException

Stores the values of points.length last points into the specified array.

Parameters:

points - An array to fill with last polyline's points. points[points.length-1] will contains the last point, points[points.length-2] the point before the last one, etc.

Throws:

java.util.NoSuchElementException - If this polyline doesn't contain enough points.

getBounds2D

public java.awt.geom.Rectangle2D getBounds2D()

Return the bounding box of this polyline, including its possible borders. This method uses a cache, such that after a first calling, the following calls should be fairly quick.

Specified by:

getBounds2D in interface java.awt.Shape

Specified by:

getBounds2D in class Geometry

Returns:

A bounding box of this polyline. Changes to the fields of this rectangle will not affect the cache.

contains

public boolean contains(double x,
                        double y)

Indicates whether the specified (x,y) coordinate is inside this polyline. The point's coordinates must be expressed according to the polyline's coordinate system, that is getCoordinateSystem(). The polyline must also have been closed before the call to this method (see close()), if it wasn't this method will always return false.

Specified by:

contains in interface java.awt.Shape

Overrides:

contains in class Geometry

Parameters:

x - the specified x coordinates in this geometry coordinate system.

y - the specified y coordinates in this geometry coordinate system.

Returns:

true if the specified coordinates are inside the geometry boundary; false otherwise.

contains

public boolean contains(java.awt.geom.Point2D pt)

Checks whether a point pt is inside this polyline. The point's coordinates must be expressed according to the polyline's coordinate system, that is getCoordinateSystem(). The polyline must also have been closed before the call to this method (see close()), if it wasn't this method will always return false.

Specified by:

contains in interface java.awt.Shape

Specified by:

contains in class Geometry

Parameters:

pt - the specified point in this geometry coordinate system.

Returns:

true if the specified point is inside the geometry boundary; false otherwise.

contains

public boolean contains(java.awt.geom.Rectangle2D rect)

Test if the interior of this polyline entirely contains the given rectangle. The rectangle's coordinates must be expressed in this polyline's coordinate system (as returned by getCoordinateSystem()).

Specified by:

contains in interface java.awt.Shape

Overrides:

contains in class Geometry

contains

public boolean contains(java.awt.Shape shape)

Test if the interior of this polyline entirely contains the given shape.

Specified by:

contains in class Geometry

intersects

public boolean intersects(java.awt.geom.Rectangle2D rect)

Tests if the interior of the polyline intersects the interior of a specified rectangle. The rectangle's coordinates must be expressed in this polyline's coordinate system (as returned by getCoordinateSystem()).

Specified by:

intersects in interface java.awt.Shape

Overrides:

intersects in class Geometry

intersects

public boolean intersects(java.awt.Shape shape)

Tests if the interior of the polyline intersects the interior of a specified shape. The shape's coordinates must be expressed in this polyline's coordinate system (as returned by getCoordinateSystem()).

Specified by:

intersects in class Geometry

clip

public Geometry clip(Clipper clipper)

Returns a polyline approximately equal to this polyline clipped to the specified bounds. The clip is only approximative in that the resulting polyline may extend outside the clip area. However, it is guaranteed that the resulting polyline contains at least all the interior of the clip area. If this method can't perform the clip, or if it believes that it isn't worth doing a clip, it returns this. If this polyline doesn't intersect the clip area, then this method returns null. Otherwise, a new polyline is created and returned. The new polyline will try to share as much internal data as possible with this in order to keep memory footprint low.

Overrides:

clip in class Geometry

Parameters:

clipper - The clip area.

Returns:

null if this polyline doesn't intersect the clip, this if no clip has been performed, or a new clipped polyline otherwise.

Task:

TODO: Change the returns type to Polyline when we will be allowed to use the J2SE 1.5 compiler. Then remove the cast in Polygon.clip(Clipper).

compress

public float compress(CompressionLevel level)
               throws org.opengis.referencing.operation.TransformException,
                      UnmodifiableGeometryException

Compress this polyline. The level argument specify the algorithm, which may be desctructive (i.e. data may loose precision). Compressing polyline may help to reduce memory usage, providing that there is no reference to the (x,y) coordinate points outside this polyline (otherwise the garbage collector will not reclaim the old data).

Specified by:

compress in class Geometry

Parameters:

level - The compression level (or algorithm) to use. See the CompressionLevel javadoc for an explanation of available algorithms.

Returns:

A estimation of the compression rate. For example a value of 0.2 means that the new polyline use approximatively 20% less memory. Warning: this value may be inacurate, for example if the old polyline was used to shares its data with an other polyline, compressing one polyline may actually increase memory usage since the two polylines will no longer share their data.

Throws:

org.opengis.referencing.operation.TransformException - If an error has come up during a cartographic projection.

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

getResolution

public Statistics getResolution()

Returns the polyline's resolution. The mean resolution is the mean distance between every pair of consecutive points in this polyline (ignoring "extra" points used for drawing a border, if there is one). This method tries to express the resolution in linear units (usually meters) no matter whether the coordinate system is actually a ProjectedCoordinateSystem or a GeographicCoordinateSystem. More specifically:

• If the coordinate system is a geographic one, then the resolution is expressed in units of the underlying ellipsoid's axis length.
• Otherwise (especially if the coordinate system is a projected one), the resolution is expressed in units of the coordinate system.

Specified by:

getResolution in class Geometry

Returns:

Statistics about the resolution, or null if this geometry doesn't contains any point. If non-null, the statistics object contains minimum, maximum, mean, root mean square and standard deviation always in linear units.

setResolution

public void setResolution(double resolution)
                   throws org.opengis.referencing.operation.TransformException,
                          UnmodifiableGeometryException

Sets the polyline's resolution. This method interpolates new points in such a way that every point is spaced by exactly resolution units (usually meters) from the previous one.

Specified by:

setResolution in class Geometry

Parameters:

resolution - Desired resolution, in the same units as getResolution().

Throws:

org.opengis.referencing.operation.TransformException - If some coordinate transformations were needed and failed. There is no guarantee on polyline's state in case of failure.

UnmodifiableGeometryException - if modifying this geometry would corrupt a container. To avoid this exception, clone this geometry before to modify it.

getRenderingResolution

public float getRenderingResolution()

Returns the rendering resolution. This is the spatial resolution used by PathIterator only; it has no effect on the underyling data.

Overrides:

getRenderingResolution in class Geometry

Returns:

The rendering resolution in units of this polyline's coordinate system (linear or angular units), or 0 if the finest available resolution should be used.

setRenderingResolution

public void setRenderingResolution(float resolution)

Hints this polyline that the specified resolution is sufficient for rendering. Value 0 ask for the best available resolution. If a value greater than 0 is provided, then the PathIterator will skip as many points as it can while preserving a distance equals or smaller than resolution between two consecutive points.

Overrides:

setRenderingResolution in class Geometry

Parameters:

resolution - The resolution to use at rendering time, in units of this polyline's coordinate system (linear or angular units).

getPathIterator

public java.awt.geom.PathIterator getPathIterator(java.awt.geom.AffineTransform transform)

Returns a path iterator for this polyline.

Specified by:

getPathIterator in interface java.awt.Shape

Specified by:

getPathIterator in class Geometry

toArray

public float[] toArray(float resolution)

Returns a copy of all coordinates of this polyline. Coordinates are usually (x,y) or (longitude,latitude) pairs, depending on the coordinate system in use. This method never returns null, but may return an array of length 0 if no data are available.

Parameters:

resolution - The minimum distance desired between points, in the same units as for the getResolution() method (i.e. linear units as much as possible - usually meters - even for geographic coordinate system). If resolution is greater than 0, then points that are closer than resolution from previous points will be skipped. This method is not required to perform precise distance computations.

Returns:

The coordinates expressed in this polyline's coordinate system.

print

public void print(java.io.Writer out,
                  java.util.Locale locale)
           throws java.io.IOException

Write all point coordinates to the specified stream. This method is useful for debugging purposes.

Parameters:

out - The destination stream, or null for the standard output.

locale - Desired locale, or null for a default one.

Throws:

java.io.IOException - If an error occured while writing to the destination stream.

print

public static void print(Polyline[] polylines,
                         java.io.Writer out,
                         java.util.Locale locale)
                  throws java.io.IOException

Write all point coordinates of many polylines side by side. This method is useful for checking the result of a coordinate transformation; one could write the original and transformed polylines side by side. Note that this method may require unicode support for proper output.

Parameters:

polylines - The set of polylines. Polygons may have different lengths.

out - The destination stream, or null for the standard output.

locale - Desired locale, or null for a default one.

Throws:

java.io.IOException - If an error occured while writing to the destination stream.

print

public static void print(java.lang.String[] titles,
                         java.util.Collection[] points,
                         java.io.Writer out,
                         java.util.Locale locale)
                  throws java.io.IOException

Write all points from arbitrary collections side by side. Note that this method may require unicode support for proper output.

Parameters:

titles - The column's titles. Should have the same length as points.

points - Array of points collections. Collections may have different sizes.

out - The destination stream, or null for the standard output.

locale - Desired locale, or null for a default one.

Throws:

java.io.IOException - If an error occured while writing to the destination stream.

clone

public java.lang.Object clone()

Return a clone of this polyline. The clone has a deep copy semantic, i.e. any change to the current polyline (including adding new points) will not affect the clone, and vice-versa (any change to the clone will not affect the current polyline). However, the two polylines will share many internal structures in such a way that memory consumption for polyline's clones should be kept low.

Specified by:

clone in interface org.opengis.util.Cloneable

Overrides:

clone in class Geometry

equals

public boolean equals(java.lang.Object object)

Compare the specified object with this polyline for equality.

Overrides:

equals in class Geometry

hashCode

public int hashCode()

Returns a hash value for this polyline.

Overrides:

hashCode in class Geometry

readObject

protected void readObject(java.io.ObjectInputStream in)
                   throws java.io.IOException,
                          java.lang.ClassNotFoundException

Invoked during deserialization.

Throws:

java.io.IOException

java.lang.ClassNotFoundException