org.geotools.renderer.geom
Class Geometry

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

All Implemented Interfaces:

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

Direct Known Subclasses:

GeometryCollection, GeometryProxy, Point, Polyline

public abstract class Geometry

extends java.lang.Object

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

Base class for geometric shape to be rendered in a given coordinate system. Those classes are not designed for spatial analysis or topology: they are not a replacement for JTS, neither an implementation of ISO-19107. They are rather a wrapper around arbitrary source of (x,y) coordinates to be rendered. With the rendering goal in mind, this class implements the Shape interface for interoperability with Java2D. But it provides also some more capabilities. For example, contains and intersects methods accepts arbitrary shapes instead of rectangle only. Geometry objects can have arbitrary two-dimensional coordinate system, which can be changed at any time (i.e. the geometry can be reprojected). Decimation can be applied at rendering time. Futhermore, Geometrys can compress and share their internal data in order to reduce memory footprint.

Version:

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

Author:

Martin Desruisseaux

See Also:

Serialized Form

Field Summary

static CoordinateSystem

DEFAULT_COORDINATE_SYSTEM The default coordinate system for all geometries.

Constructor Summary

	Geometry() Construct an empty geographic shape.
protected	Geometry(Geometry geometry) Construct a geographic shape with the same data than the specified geometry.

Method Summary

Geometry	clip(Clipper clipper) Returns an geometry approximately equal to this geometry clipped to the specified bounds.
java.lang.Object	clone() Return a clone of this geometry.
abstract float	compress(CompressionLevel level) Compress this geometry.
boolean	contains(double x, double y) Tests if the specified coordinates are inside the boundary of this geometry.
boolean	contains(double x, double y, double width, double height) Test if the interior of this geometry entirely contains the given rectangle.
abstract boolean	contains(java.awt.geom.Point2D point) Tests if a specified Point2D is inside the boundary of this geometry.
boolean	contains(java.awt.geom.Rectangle2D rectangle) Tests if the interior of this geometry entirely contains the given rectangle.
abstract boolean	contains(java.awt.Shape shape) Test if the interior of this geometry entirely contains the given shape.
boolean	equals(java.lang.Object object) Compares the specified object with this geometry for equality.
java.awt.Rectangle	getBounds() Deprecated. This method is required by the Shape interface, but it doesn't provide enough precision for most cases. Use getBounds2D() instead.
abstract java.awt.geom.Rectangle2D	getBounds2D() Returns the bounding box of this geometry.
abstract CoordinateSystem	getCoordinateSystem() Returns the geometry's coordinate system, or null if unknow.
java.lang.String	getID() Returns the geometry ID.
java.lang.String	getName(java.util.Locale locale) Returns the localized name for this geometry, or null if none.
abstract java.awt.geom.PathIterator	getPathIterator(java.awt.geom.AffineTransform transform) Returns an iterator object that iterates along the shape boundary and provides access to the geometry of the shape outline.
java.awt.geom.PathIterator	getPathIterator(java.awt.geom.AffineTransform transform, double flatness) Returns a flattened path iterator for this geometry.
abstract int	getPointCount() Return the number of points in this geometry.
float	getRenderingResolution() Returns the rendering resolution.
abstract Statistics	getResolution() Returns the geometry's resolution.
Style	getStyle() Returns the style attached to this geometry, or null if none.
java.lang.Object	getUserObject() Returns the user object attached to this geometry.
int	hashCode() Returns a hash value for this geometry.
boolean	intersects(double x, double y, double width, double height) Tests if the interior of the geometry intersects the interior of a specified rectangle.
boolean	intersects(java.awt.geom.Rectangle2D rectangle) Tests if the interior of the geometry intersects the interior of a specified rectangle.
abstract boolean	intersects(java.awt.Shape shape) Tests if the interior of the geometry intersects the interior of a specified shape.
boolean	isEmpty() Determines whetever this geometry is empty.
abstract void	setCoordinateSystem(CoordinateSystem coordinateSystem) Set the geometry's coordinate system.
void	setID(java.lang.String ID) Sets the geometry ID.
void	setRenderingResolution(float resolution) Hints this geometry that the specified resolution is sufficient for rendering.
abstract void	setResolution(double resolution) Set the geometry's resolution.
void	setStyle(Style style) Set the style attached to this geometry.
void	setUserObject(java.lang.Object userObject) Set the user object for this geometry.
java.lang.String	toString() Return a string representation of this geometry for debugging purpose.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_COORDINATE_SYSTEM

public static final CoordinateSystem DEFAULT_COORDINATE_SYSTEM

The default coordinate system for all geometries. This is the coordinate system used if no CS were explicitly specified at construction time. The default implementation uses a two-dimensional cartesian coordinate system with x,y axis in metres. This coordinate system is treated specially by the default coordinate transformation factory with loose transformation rules: if no transformation path were found, then the transformation from this CS to any CS with a compatible number of dimensions is assumed to be the identity transform.

See Also:

LocalCoordinateSystem.PROMISCUOUS, LocalCoordinateSystem.CARTESIAN, GeographicCoordinateSystem.WGS84

Constructor Detail

Geometry

public Geometry()

Construct an empty geographic shape.

Geometry

protected Geometry(Geometry geometry)

Construct a geographic shape with the same data than the specified geometry.

Parameters:

geometry - The geometry to copy data from.

Method Detail

getName

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

Returns the localized name for this geometry, or null if none. The default implementation returns always null.

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.

getID

public java.lang.String getID()

Returns the geometry ID. The ID is string that identifies the current geometry and its application specific, that is, the renderer won't use it in any special way.

Returns:

The geometry ID, or null if none.

setID

public void setID(java.lang.String ID)

Sets the geometry ID.

getUserObject

public java.lang.Object getUserObject()

Returns the user object attached to this geometry. This is often the feature where this geometry come from, or an ID for this feature as a character string.

setUserObject

public void setUserObject(java.lang.Object userObject)

Set the user object for this geometry. This is often the feature where this geometry come from, or an ID for this geometry as a character string. The renderer will not use this information in any way. It is stored here mostly for faster retrieval of the feature under the mouse cursor.

getStyle

public Style getStyle()

Returns the style attached to this geometry, or null if none.

setStyle

public void setStyle(Style style)

Set the style attached to this geometry.

Parameters:

style - The new style for this geometry, or null if none.

getCoordinateSystem

public abstract CoordinateSystem getCoordinateSystem()

Returns the geometry's coordinate system, or null if unknow.

setCoordinateSystem

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

Set the geometry's coordinate system. Calling this method is equivalents to reproject all geometry's points from the old coordinate system to the new one.

Parameters:

coordinateSystem - The new coordinate system. A null value reset the default coordinate system (usually the one that best fits internal data).

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.

isEmpty

public boolean isEmpty()

Determines whetever this geometry is empty.

getPointCount

public abstract int getPointCount()

Return the number of points in this geometry.

getBounds

public java.awt.Rectangle getBounds()

Deprecated. This method is required by the Shape interface, but it doesn't provide enough precision for most cases. Use getBounds2D() instead.

Returns the smallest bounding box containing getBounds2D().

Specified by:

getBounds in interface java.awt.Shape

getBounds2D

public abstract java.awt.geom.Rectangle2D getBounds2D()

Returns the bounding box of this geometry. The rectangle's coordinates will be expressed in this geometry's coordinate system (as returned by getCoordinateSystem()).

Specified by:

getBounds2D in interface java.awt.Shape

Returns:

The bounding box of this geometry.

contains

public boolean contains(double x,
                        double y)

Tests if the specified coordinates are inside the boundary of this geometry.

Specified by:

contains in interface java.awt.Shape

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 abstract boolean contains(java.awt.geom.Point2D point)

Tests if a specified Point2D is inside the boundary of this geometry.

Specified by:

contains in interface java.awt.Shape

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(double x,
                        double y,
                        double width,
                        double height)

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

Specified by:

contains in interface java.awt.Shape

contains

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

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

Specified by:

contains in interface java.awt.Shape

contains

public abstract boolean contains(java.awt.Shape shape)

Test if the interior of this geometry entirely contains the given shape. The coordinate system for the specified shape argument must be the same than this Geometry object, as returned by getCoordinateSystem().

intersects

public boolean intersects(double x,
                          double y,
                          double width,
                          double height)

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

Specified by:

intersects in interface java.awt.Shape

intersects

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

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

Specified by:

intersects in interface java.awt.Shape

intersects

public abstract boolean intersects(java.awt.Shape shape)

Tests if the interior of the geometry intersects the interior of a specified shape. The coordinate system for the specified shape argument must be the same than this Geometry object, as returned by getCoordinateSystem().

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 returned 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.

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.

compress

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

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

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 geometry use approximatively 20% less memory. Warning: this value may be inacurate, for example if the old geometry was used to shares its data with an other geometry, compressing one geometry may actually increase memory usage since the two geometries 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 abstract Statistics getResolution()

Returns the geometry's resolution. The mean resolution is the mean distance between every pair of consecutive points in this geometry (ignoring "extra" points used for drawing a border, if there is one). This method try to express the resolution in linear units (usually meters) no matter if the coordinate systems is actually a projected or a geographic one. 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.

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 abstract void setResolution(double resolution)
                            throws org.opengis.referencing.operation.TransformException,
                                   UnmodifiableGeometryException

Set the geometry'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. Consequently, the resolution after this call will have a standard deviation close to 0.

Calling this method with a large resolution may help to reduce memory footprint if a fine resolution is not needed (note that compress(org.geotools.renderer.geom.CompressionLevel) provides an alternative way to reduce memory footprint). This method is irreversible. Invoking setResolution with a finner resolution will increase memory consumption with no real resolution improvement.

Parameters:

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

Throws:

org.opengis.referencing.operation.TransformException - If some coordinate transformations were needed and failed. There is no guaranteed on geometry'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. Note that at the difference of getResolution(), the units are not always linear; they may be angular if the underlying coordinate system is geographic. Resolution in angular units is not very meaningful for computation purpose (since the length of longitude degrees vary with latitude), but is what the user see if the map is unprojected. The rendering resolution is about what the user see.

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. Note that this method affect the PathIterator behavior only; it has no impact on the underlying data. This method is non-destructive; it is possible to set a finer resolution after a large one.

Parameters:

resolution - The resolution to use at rendering time, in units of this geometry's coordinate system (linear or angular units, see getRenderingResolution() for a discussion).

getPathIterator

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

Returns an iterator object that iterates along the shape boundary and provides access to the geometry of the shape outline. If an optional AffineTransform is specified, the coordinates returned in the iteration are transformed accordingly. The iterator may not iterate through all internal data. If a rendering resolution has been specified, then some points may be skipped during the iteration.

Specified by:

getPathIterator in interface java.awt.Shape

getPathIterator

public java.awt.geom.PathIterator getPathIterator(java.awt.geom.AffineTransform transform,
                                                  double flatness)

Returns a flattened path iterator for this geometry.

Specified by:

getPathIterator in interface java.awt.Shape

clone

public java.lang.Object clone()

Return a clone of this geometry. The returned geometry will have a deep copy semantic. However, subclasses should overrides this method in such a way that both shapes will share as much internal arrays as possible, even if they use differents coordinate systems.

Specified by:

clone in interface org.opengis.util.Cloneable

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this geometry for equality.

hashCode

public int hashCode()

Returns a hash value for this geometry.

toString

public java.lang.String toString()

Return a string representation of this geometry for debugging purpose. The returned string will look like "Polygon["polygon name", 44?30'N-51?59'N 70?59'W-54?59'W (56 pts)]".