org.geotools.renderer.geom
Class GeometryCollection

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

All Implemented Interfaces:

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

Direct Known Subclasses:

JTSGeometries

public class GeometryCollection

extends Geometry

implements java.lang.Comparable

A collection of geometry shapes. Included geometries may be Polylines, Polygons or others GeometryCollection. Regrouping related polygons in a single collection help to speed up the rendering. Polygons can be regrouped on a spatial basis (European polygons, African polygons, etc.) or on a value basis (50 meters isobath, 100 meters isobath, etc.).

A GeometryCollection is initially built with a coordinate system. An arbitrary amount of geometries can be added after construction using add(Geometry) or add(float[],int,int). Geometries will be rendered in the order they were added. If polygons are broken in many pieces, then the assemble(...) method may help to assemble them before rendering.

Note: this class has a natural ordering that is inconsistent with equals. The compareTo(java.lang.Object) method compares only the collection's value, while equals(java.lang.Object) compares also all coordinate points. The natural ordering for GeometryCollection is convenient for sorting collections in alphabetical order or isobaths in increasing order of altitude.

Version:

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

Author:

Martin Desruisseaux

See Also:

Polyline, Polygon, Serialized Form

Task:

TODO: Add a 'getTree(boolean)' method returning a TreeNode. Would be usefull for debugging. Node contains GeometryCollection only if boolean argument is false, GeometryCollection and Polygons if true (not Polylines). Node.toString returns Geometry.getName().

Field Summary

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

DEFAULT_COORDINATE_SYSTEM

Constructor Summary

GeometryCollection()
Construct an initially empty collection using the default coordinate system.

GeometryCollection(CoordinateSystem coordinateSystem)
Construct an initially empty collection.

GeometryCollection(GeometryCollection geometry)
Construct a collection with the same data as the specified collection.

Method Summary

void	add(float[] array, int lower, int upper) Adds points to this collection.
Geometry	add(Geometry toAdd) Add a geometry to this collection.
void	add(java.awt.Shape shape) Add geometries from the specified shape.
void	assemble(ProgressListener progress) Assemble all polylines with default setting.
void	assemble(java.awt.Shape mapBounds, float[] toComplete, ProgressListener progress) Assemble all polylines in order to create closed polygons for proper rendering.
Geometry	clip(Clipper clipper) Returns an geometry approximately equal to this geometry clipped to the specified bounds.
java.lang.Object	clone() Return a copy of this geometry.
int	compareTo(java.lang.Object object) Compare this geometry with the specified object for order.
float	compress(CompressionLevel level) Compress all geometries in this collection.
boolean	contains(double x, double y) Indicates whether the specified (x,y) point is inside this geometry.
boolean	contains(java.awt.geom.Point2D point) Indicates whether the specified point is inside this geometry.
boolean	contains(java.awt.geom.Rectangle2D rect) Checks whether the specified rectangle is entirely contained within this geometry.
boolean	contains(java.awt.Shape shape) Checks whether the specified shape is entirely contained within this geometry.
boolean	equals(java.lang.Object object) Compares the specified object with this geometry for equality.
java.awt.geom.Rectangle2D	getBounds2D() Return the bounding box of this geometry, including its possible borders.
CoordinateSystem	getCoordinateSystem() Returns the geometry's coordinate system, or null if unknown.
java.util.Collection	getGeometries() Returns the collection of Geometry objects.
java.util.Collection	getGeometries(java.awt.geom.Point2D point) Returns the collection of geometries containing the specified point.
java.util.Collection	getGeometriesContaining(java.awt.Shape shape) Returns the collection of geometries containing the specified shape.
java.util.Collection	getGeometriesIntersecting(java.awt.Shape shape) Returns the collection of geometries intersecting the specified shape.
java.lang.String	getName(java.util.Locale locale) Returns the localized name for this geometry, or null if none.
java.awt.geom.PathIterator	getPathIterator(java.awt.geom.AffineTransform transform) Returns a path iterator for this geometry.
int	getPointCount() Returns the number of points in this geometry.
java.lang.String	getPolygonName(java.awt.geom.Point2D point, java.util.Locale locale) Returns the name of the smallest polygon at the given location.
float	getRenderingResolution() Returns the rendering resolution.
Statistics	getResolution() Returns the geometry's resolution.
float	getValue() Returns the value for this collection, or NaN if none.
int	hashCode() Returns a hash value for this geometry.
boolean	intersects(java.awt.geom.Rectangle2D rect) Tests whether the specified rectangle intersects the interior of this geometry.
boolean	intersects(java.awt.Shape shape) Tests whether the specified shape intersects the interior of this geometry.
boolean	isEmpty() Determines whetever the collection is empty.
protected void	readObject(java.io.ObjectInputStream in) Invoked during deserialization.
boolean	remove(Geometry toRemove) Removes a geometry from this collection.
void	removeAll() Remove all geometries from this geometry.
void	setCoordinateSystem(CoordinateSystem coordinateSystem) Set the geometry's coordinate system.
void	setRenderingResolution(float resolution) Hints this geometry that the specified resolution is sufficient for rendering.
void	setResolution(double resolution) Set the geometry's resolution.
void	setValue(java.lang.Comparable value) Set the value for this geometry.
void	setValue(float value) Set the value for this geometry.
protected void	writeObject(java.io.ObjectOutputStream out) Invoked during serialization.

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

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

Methods inherited from class java.lang.Object

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

Constructor Detail

GeometryCollection

public GeometryCollection()

Construct an initially empty collection using the default coordinate system. Polygons can be added using one of the add(...) methods.

See Also:

add(float[],int,int), add(Shape), add(Geometry)

GeometryCollection

public GeometryCollection(CoordinateSystem coordinateSystem)

Construct an initially empty collection. Polygons can be added using one of the add(...) methods.

Parameters:

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

See Also:

Geometry.DEFAULT_COORDINATE_SYSTEM, LocalCoordinateSystem.PROMISCUOUS, LocalCoordinateSystem.CARTESIAN, GeographicCoordinateSystem.WGS84, add(float[],int,int), add(Shape), add(Geometry)

GeometryCollection

public GeometryCollection(GeometryCollection geometry)

Construct a collection with the same data as the specified collection. The new collection will have a copy semantic, but the underlying arrays of (x,y) points will be shared.

Method Detail

getName

public java.lang.String getName(java.util.Locale locale)

Returns the localized name for this geometry, or null if none.

Overrides:

getName in class Geometry

Parameters:

locale - The desired locale. If no name is available for this locale, a default locale will be used.

Returns:

The geometry's name, localized if possible.

Task:

TODO: We should find a way to avoid the creation of Format object at each invocation.

getValue

public float getValue()

Returns the value for this collection, or NaN if none. If this collection is an isobath, then the value is typically the isobath altitude.

setValue

public void setValue(float value)

Set the value for this geometry. If this geometry is an isobath, then the value is typically the isobath altitude.

setValue

public void setValue(java.lang.Comparable value)

Set the value for this geometry. It may be a String (for example "Africa"), or a value as a Number object (for example Float(-50) for the -50 meters isobath). There is two advantages in using Number instead of String for values:

• Better ordering with compareTo(java.lang.Object).
• Locale-dependent formatting with getName(java.util.Locale).

Parameters:

value - The value of value for this geometry.

getCoordinateSystem

public CoordinateSystem getCoordinateSystem()

Returns the geometry'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

Set the geometry's coordinate system. Calling this method is equivalent to reprojecting all geometries 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 remain 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.

add

public void add(float[] array,
                int lower,
                int upper)
         throws UnmodifiableGeometryException

Adds points to this collection. The points must be stored as (x,y) pairs in this geometry's coordinate system. NaN values will be considered as disjoint lines.

Parameters:

array - Coordinate array (may contain NaNs). These data will be copied. Consequently, any modification on data will have no impact on the geometries created by this method.

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

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

Throws:

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

add

public void add(java.awt.Shape shape)
         throws java.lang.IllegalArgumentException,
                UnmodifiableGeometryException

Add geometries from the specified shape. Shape's coordinates must be express in this geometry's coordinate system.

Parameters:

shape - The shape to add.

Throws:

java.lang.IllegalArgumentException - if the specified shape can't be added. This error may occur if shape is an instance of Geometry and uses an incompatible coordinate system.

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

add

public Geometry add(Geometry toAdd)
             throws org.opengis.referencing.operation.TransformException,
                    UnmodifiableGeometryException

Add a geometry to this collection.

Parameters:

toAdd - Geometry to add.

Throws:

org.opengis.referencing.operation.TransformException - if the specified geometry can't be transformed in this collection coordinate system.

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

remove

public boolean remove(Geometry toRemove)
               throws UnmodifiableGeometryException

Removes a geometry from this collection.

Parameters:

toRemove - The geometry to remove.

Returns:

true if the geometry has been removed.

Throws:

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

removeAll

public void removeAll()
               throws UnmodifiableGeometryException

Remove all geometries from this geometry.

Throws:

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

assemble

public void assemble(java.awt.Shape mapBounds,
                     float[] toComplete,
                     ProgressListener progress)
              throws org.opengis.referencing.operation.TransformException,
                     UnmodifiableGeometryException

Assemble all polylines in order to create closed polygons for proper rendering. This method analyses all available polylines and merges together the polylines that look like parts of the same polygons. It can also complete the polygons that were cut by the map border. This method is useful in the context of geometries digitalized from many consecutive maps (for example the GEBCO digital atlas). It is not possible to fill polygons with Java2D if the polygons are broken in many pieces, as in the figure below.

Running this method once for a given collection of geometries before renderering helps to repair them. The algorithm is:

1. A list of all possible pairs of polylines is built.
2. For any pair of polylines, the shortest distance between their extremities is computed. All combinations between the beginning and the end of a polyline with the beginning or end of the other polyline are taken into account.
3. The pair with the shortest distance are identified. When the shortest distance from one polyline's extremity is the other extremity of the same polyline, then the polyline is identified as a closed polygon (e.g. an island or a lake). Otherwise, the closest polylines are merged together.
4. The loop is reexecuted from step 1 until no more polylines have been merged.

This method will produces better results if this collection contains other GeometryCollection objects (one for each isobath) with value set to the bathymetric value (for example -50 for the -50 meters isobath). The toComplete argument tells which isobaths to complete with the map border provided by the mapBounds argument.

Parameters:

mapBounds - The bounded shape of the map, or null for assuming a rectangular map inferred from this geometry. This is the bounding shape of the software that created the polylines, not an arbitrary clip that the application would like.

toComplete - value of collections to complete with map border, or null if none.

progress - An optional progress listener (null in none). This is an optional but recommanded argument, since the computation may be very long.

Throws:

org.opengis.referencing.operation.TransformException - if a transformation was required and failed.

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

assemble

public void assemble(ProgressListener progress)
              throws org.opengis.referencing.operation.TransformException,
                     UnmodifiableGeometryException

Assemble all polylines with default setting. This convenience method will complete the map border only for the 0 meters isobath.

Parameters:

progress - An optional progress listener (null in none). This is an optional but recommanded argument, since the computation may be very long.

Throws:

org.opengis.referencing.operation.TransformException - if a transformation was required and failed.

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

clip

public Geometry clip(Clipper clipper)

Returns an geometry approximately equal to this geometry clipped to the specified bounds. The clip is only approximate in that the resulting geometry may extend outside the clip area. However, it is guaranteed that the resulting geometry 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 geometry doesn't intersect the clip area, then this method returns null. Otherwise, a new geometry is created and returned. The new geometry 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 clipping area.

Returns:

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

getGeometries

public java.util.Collection getGeometries()

Returns the collection of Geometry objects. The collection will contains geometries in the order they were added.

Returns:

A collection of Geometry objects.

getGeometries

public java.util.Collection getGeometries(java.awt.geom.Point2D point)

Returns the collection of geometries containing the specified point. The collection will contains geometries in the reverse order, i.e. geometries added last will be returned first. This convention make it easier to find the smallest geometry contained in bigger geometry.

Parameters:

point - The coordinates to look at in this geometry's coordinate system.

Returns:

The collection of geometries under the specified point.

getGeometriesContaining

public java.util.Collection getGeometriesContaining(java.awt.Shape shape)

Returns the collection of geometries containing the specified shape. The collection will contains geometries in the reverse order, i.e. geometries added last will be returned first. This convention make it easier to find the smallest geometry contained in bigger geometry.

Parameters:

shape - A shape with coordinates expressed according to getCoordinateSystem().

Returns:

The collection of geometries containing the specified shape.

getGeometriesIntersecting

public java.util.Collection getGeometriesIntersecting(java.awt.Shape shape)

Returns the collection of geometries intersecting the specified shape. The collection will contains geometries in the reverse order, i.e. geometries added last will be returned first. This convention make it easier to find the smallest geometry contained in bigger geometry.

Parameters:

shape - A shape with coordinates expressed according to getCoordinateSystem().

Returns:

The collection of geometries intersecting the specified shape.

getPolygonName

public java.lang.String getPolygonName(java.awt.geom.Point2D point,
                                       java.util.Locale locale)

Returns the name of the smallest polygon at the given location. This method is usefull for formatting tooltip text when the mouse cursor moves over the map.

Parameters:

point - The coordinates to look at in this geometry's coordinate system.

locale - The desired locale for the geometry name.

Returns:

The geometry name at the given location, or null if there is none.

isEmpty

public boolean isEmpty()

Determines whetever the collection is empty.

Overrides:

isEmpty in class Geometry

getPointCount

public int getPointCount()

Returns the number of points in this geometry.

Specified by:

getPointCount in class Geometry

getBounds2D

public java.awt.geom.Rectangle2D getBounds2D()

Return the bounding box of this geometry, including its possible borders. This method uses a cache, such that after a first call, 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 geometry. Changes to this rectangle will not affect the cache.

contains

public boolean contains(double x,
                        double y)

Indicates whether the specified (x,y) point is inside this geometry. The point coordinates must be expressed in the geometry's coordinate system, that is getCoordinateSystem().

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 point)

Indicates whether the specified point is inside this geometry. The point coordinates must be expressed in the geometry's coordinate system, that is getCoordinateSystem().

Specified by:

contains in interface java.awt.Shape

Specified by:

contains in class Geometry

Parameters:

point - 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)

Checks whether the specified rectangle is entirely contained within this geometry. The rectangle's coordinates should be expressed in the geometry's coordinate system, that is {link #getCoordinateSystem()}.

Specified by:

contains in interface java.awt.Shape

Overrides:

contains in class Geometry

contains

public boolean contains(java.awt.Shape shape)

Checks whether the specified shape is entirely contained within this geometry. The shape's coordinates must be expressed in the geometry's coordinate system, that is getCoordinateSystem().

Specified by:

contains in class Geometry

intersects

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

Tests whether the specified rectangle intersects the interior of this geometry.

Specified by:

intersects in interface java.awt.Shape

Overrides:

intersects in class Geometry

intersects

public boolean intersects(java.awt.Shape shape)

Tests whether the specified shape intersects the interior of this geometry.

Specified by:

intersects in class Geometry

compress

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

Compress all geometries in this collection. The level argument specify the algorithm, which may be desctructive (i.e. data may loose precision). For example, the compression may replaces direct positions by relative positions, as in the figures below:

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 polygon uses approximately 20% less memory.

Throws:

org.opengis.referencing.operation.TransformException - If an error has occurred 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 geometry's resolution. The mean resolution is the mean distance between every pair of consecutive points in this geometry. This method tries to express the resolution in linear units (usually meters) no matter whether the coordinate systems is actually a projected or a geographic one.

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

Set the geometry's resolution. This method tries to interpolate 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 contour'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 geometry'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 geometry 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 geometry'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 geometry.

Specified by:

getPathIterator in interface java.awt.Shape

Specified by:

getPathIterator in class Geometry

clone

public final java.lang.Object clone()

Return a copy of this geometry. The clone has a deep copy semantic, but will share many internal arrays with the original geometry. This method is final for implementation reason.

Specified by:

clone in interface org.opengis.util.Cloneable

Overrides:

clone in class Geometry

compareTo

public int compareTo(java.lang.Object object)

Compare this geometry with the specified object for order. Note that this method is inconsistent with equals. The method compareTo compares only the value, while equals compares all coordinate points. The natural ordering for GeometryCollection is convenient for sorting geometries in alphabetical order or isobaths in increasing order of altitude. Geometries without value are sorted last.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

object - The geometry to compare value with.

Returns:

• +1 if this geometry's value is greater than the value for the specified geometry.
• -1 if this geometry's value is less than the value for the specified geometry.
• 0 if both geometries have the same value or value.

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this geometry for equality. This methods checks and all coordinate points.

Overrides:

equals in class Geometry

hashCode

public int hashCode()

Returns a hash value for this geometry.

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

writeObject

protected void writeObject(java.io.ObjectOutputStream out)
                    throws java.io.IOException

Invoked during serialization.

Throws:

java.io.IOException