org.geotoolkit.geometry
Class Envelopes

Object
  Static
      Envelopes

public final class Envelopes
extends Static

Utility methods for envelopes. This utility class is made up of static functions working with arbitrary implementations of GeoAPI interfaces.

Since:

3.19 (derived from 2.4)

Version:

3.19

Author:

Martin Desruisseaux (IRD, Geomatys), Jody Garnett (Refractions), Andrea Aime (TOPP), Johann Sorel (Geomatys)

See Also:

CRS

Module:

referencing/geotk-referencing (download)

View source code for this class

Method Summary

static Envelope	getDomainOfValidity(CoordinateReferenceSystem crs) Returns the domain of validity for the specified coordinate reference system, or null if unknown.
static Envelope	parseWKT(String wkt) Returns an envelope from the given Well Known Text (WKT).
static String	toPolygonWKT(Envelope envelope) Formats a POLYGON element from an envelope.
static String	toWKT(Envelope envelope) Formats a BOX element from an envelope.
static GeneralEnvelope	transform(CoordinateOperation operation, Envelope envelope) Transforms an envelope using the given coordinate operation.
static Rectangle2D	transform(CoordinateOperation operation, Rectangle2D envelope, Rectangle2D destination) Transforms a rectangular envelope using the given coordinate operation.
static Envelope	transform(Envelope envelope, CoordinateReferenceSystem targetCRS) Transforms the given envelope to the specified CRS.
static Rectangle2D	transform(MathTransform2D transform, Rectangle2D envelope, Rectangle2D destination) Transforms a rectangular envelope using the given math transform.
static GeneralEnvelope	transform(MathTransform transform, Envelope envelope) Transforms an envelope using the given math transform.

Methods inherited from class Object

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

Method Detail

getDomainOfValidity

public static Envelope getDomainOfValidity(CoordinateReferenceSystem crs)

Returns the domain of validity for the specified coordinate reference system, or null if unknown. The returned envelope is expressed in terms of the specified CRS.

This method performs the work documented in the CRS.getEnvelope(CoordinateReferenceSystem) method. It is defined in this class for convenience.

Parameters:

crs - The coordinate reference system, or null.

Returns:

The envelope in terms of the specified CRS, or null if none.

See Also:

CRS.getEnvelope(CoordinateReferenceSystem), GeneralEnvelope.reduceToDomain(boolean)

transform

public static Envelope transform(Envelope envelope,
                                 CoordinateReferenceSystem targetCRS)
                          throws TransformException

Transforms the given envelope to the specified CRS. If the given envelope is null, or the envelope CRS is null, or the given target CRS is null, or the transform is identity, then the envelope is returned unchanged. Otherwise a new transformed envelope is returned.

Performance tip
If there is many envelopes to transform with the same source and target CRS, then it is more efficient to get the coordinate operation or math transform once for ever and invoke one of the methods below.

Parameters:

envelope - The envelope to transform (may be null).

targetCRS - The target CRS (may be null).

Returns:

A new transformed envelope, or directly envelope if no transformation was required.

Throws:

TransformException - If a transformation was required and failed.

transform

public static GeneralEnvelope transform(MathTransform transform,
                                        Envelope envelope)
                                 throws TransformException

Transforms an envelope using the given math transform. The transformation is only approximative: the returned envelope may be bigger than necessary, or smaller than required if the bounding box contains a pole.

This method can not handle the case where the envelope contains the North or South pole, or when it cross the ±180° longitude, because math transforms does not carry sufficient informations. For a more robust envelope transformation, use transform(CoordinateOperation, Envelope) instead.

Parameters:

transform - The transform to use.

envelope - Envelope to transform, or null. This envelope will not be modified.

Returns:

The transformed envelope, or null if envelope was null.

Throws:

TransformException - if a transform failed.

See Also:

transform(CoordinateOperation, Envelope)

transform

public static GeneralEnvelope transform(CoordinateOperation operation,
                                        Envelope envelope)
                                 throws TransformException

Transforms an envelope using the given coordinate operation. The transformation is only approximative: the returned envelope may be bigger than the smallest possible bounding box, but should not be smaller in most cases.

This method can handle the case where the envelope contains the North or South pole, or when it cross the ±180° longitude.

Note: If the envelope CRS is non-null, then the caller should ensure that the operation source CRS is the same than the envelope CRS. In case of mismatch, this method transforms the envelope to the operation source CRS before to apply the operation. This extra step may cause a lost of accuracy. In order to prevent this method from performing such pre-transformation (if not desired), callers can ensure that the envelope CRS is null before to call this method.

Parameters:

operation - The operation to use.

envelope - Envelope to transform, or null. This envelope will not be modified.

Returns:

The transformed envelope, or null if envelope was null.

Throws:

TransformException - if a transform failed.

See Also:

transform(MathTransform, Envelope)

transform

public static Rectangle2D transform(MathTransform2D transform,
                                    Rectangle2D envelope,
                                    Rectangle2D destination)
                             throws TransformException

Transforms a rectangular envelope using the given math transform. The transformation is only approximative: the returned envelope may be bigger than necessary, or smaller than required if the bounding box contains a pole.

Invoking this method is equivalent to invoking the following:

transform(transform, new GeneralEnvelope(envelope)).toRectangle2D()

Note that this method can not handle the case where the rectangle contains the North or South pole, or when it cross the ±180° longitude, because math transforms do not carry sufficient informations. For a more robust rectangle transformation, use transform(CoordinateOperation, Rectangle2D, Rectangle2D) instead.

Parameters:

transform - The transform to use. Source and target dimension must be 2.

envelope - The rectangle to transform (may be null).

destination - The destination rectangle (may be envelope). If null, a new rectangle will be created and returned.

Returns:

destination, or a new rectangle if destination was non-null and envelope was null.

Throws:

TransformException - if a transform failed.

See Also:

transform(CoordinateOperation, Rectangle2D, Rectangle2D), XAffineTransform.transform(AffineTransform, Rectangle2D, Rectangle2D)

transform

public static Rectangle2D transform(CoordinateOperation operation,
                                    Rectangle2D envelope,
                                    Rectangle2D destination)
                             throws TransformException

Transforms a rectangular envelope using the given coordinate operation. The transformation is only approximative: the returned envelope may be bigger than the smallest possible bounding box, but should not be smaller in most cases.

Invoking this method is equivalent to invoking the following:

transform(operation, new GeneralEnvelope(envelope)).toRectangle2D()

This method can handle the case where the rectangle contains the North or South pole, or when it cross the ±180° longitude.

Parameters:

operation - The operation to use. Source and target dimension must be 2.

envelope - The rectangle to transform (may be null).

destination - The destination rectangle (may be envelope). If null, a new rectangle will be created and returned.

Returns:

destination, or a new rectangle if destination was non-null and envelope was null.

Throws:

TransformException - if a transform failed.

See Also:

transform(MathTransform2D, Rectangle2D, Rectangle2D), XAffineTransform.transform(AffineTransform, Rectangle2D, Rectangle2D)

parseWKT

public static Envelope parseWKT(String wkt)
                         throws FactoryException

Returns an envelope from the given Well Known Text (WKT). This method is quite lenient. For example all the following strings are accepted:

• BOX(-180 -90, 180 90)
• POINT(6 10)
• MULTIPOLYGON(((1 1, 5 1, 1 5, 1 1),(2 2, 3 2, 3 3, 2 2)))
• GEOMETRYCOLLECTION(POINT(4 6),LINESTRING(3 8,7 10))

See GeneralEnvelope.GeneralEnvelope(String) for more information about the parsing rules.

Parameters:

wkt - The BOX, POLYGON or other kind of element to parse.

Returns:

The envelope of the given geometry.

Throws:

FactoryException - If the given WKT can not be parsed.

See Also:

CRS.parseWKT(String), toWKT(Envelope), CoordinateFormat, org.geotoolkit.io.wkt

toWKT

public static String toWKT(Envelope envelope)

Formats a BOX element from an envelope. This method formats the given envelope in the Well Known Text (WKT) format. The output is like below, where n is the number of dimensions:

BOXnD(lower corner, upper corner)

The output of this method can be parsed by the GeneralEnvelope constructor.

Parameters:

envelope - The envelope to format.

Returns:

The envelope as a BOX2D or BOX3D in WKT format.

See Also:

parseWKT(String), CoordinateFormat, org.geotoolkit.io.wkt

toPolygonWKT

public static String toPolygonWKT(Envelope envelope)

Formats a POLYGON element from an envelope. This method formats the given envelope as a geometry in the Well Known Text (WKT) format. This is provided as an alternative to the BOX element formatted by the above toWKT(Envelope) method, because the BOX element is usually not considered a geometry while POLYGON is.

The output of this method can be parsed by the GeneralEnvelope constructor.

Parameters:

envelope - The envelope to format.

Returns:

The envelope as a POLYGON in WKT format.

See Also:

org.geotoolkit.io.wkt