org.geotools.renderer.geom
Class GeometryCollection

java.lang.Object
  extended byorg.geotools.renderer.geom.Geometry
      extended byorg.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:

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


Copyright © GeoTools. All Rights Reserved.