Module org.apache.sis.referencing

# Package org.apache.sis.geometry

package org.apache.sis.geometry
Basic geometric objects (envelopes and direct positions). Every geometry objects are associated with a Coordinate Reference System, which may have an arbitrary number of dimensions. However, a few specialized classes restrict the CRS to a fixed number of dimensions only. The table below summarizes the most common objects, and list the Java2D classes that are conceptually equivalent.

Java2D and geometry equivalences
Purpose | Any dimension | One dimension | Two dimensions | Java2D equivalence
--- | --- | --- | --- | ---
A point in a multi-dimensional space | `GeneralDirectPosition` | `DirectPosition1D` | `DirectPosition2D` | `Point2D`
A box in a multi-dimensional space | `GeneralEnvelope` |  | `Envelope2D` | `Rectangle2D`

## Java2D dependency

All classes having a name that ends with "2D" are designed for inter-operability with Java2D. All other classes have no dependency to Java2D. This clear separation aims to make easier to use Apache SIS on platforms that do not support Java2D (for example Android) or to avoid loading Java2D classes when only JavaFX is desired.

## Envelopes crossing the anti-meridian of a Geographic CRS

The Web Coverage Service (WCS) 1.1 specification uses an extended interpretation of the bounding box definition. In a WCS 1.1 data structure, the lower corner defines the edges region in the directions of decreasing coordinate values in the envelope CRS, while the upper corner defines the edges region in the directions of increasing coordinate values. Those lower and upper corners are usually the algebraic minimum and maximum coordinates respectively, but not always. For example, an envelope crossing the anti-meridian could have a lower corner longitude greater than the upper corner longitude, like the red box below (the green box is the usual case):
In SIS, every envelopes defined in this package support the extended bounding box interpretation: for any dimension, coordinate values such that upper < lower are handled in a special way. This handling is slightly different for two groups of methods:

- In calculation of envelopes spans and median positions (centers) — handled specially only on axes having the `WRAPAROUND` range meaning.
- When checking for containment, intersections or unions — can be handled specially for any axis, in which case the envelope represents an exclusion area instead than an inclusion area.

Since:
  0.3
See Also:
  - `GeometryLibrary`

- Class
  Description
  AbstractDirectPosition
  Default implementations of some `DirectPosition` methods, leaving the data storage to subclasses.
  AbstractEnvelope
  Default implementations of most `Envelope` methods, leaving the data storage to subclasses.
  CoordinateFormat
  Formats spatiotemporal coordinates using number, angle and date formats inferred from the coordinate system.
  DirectPosition1D
  A one-dimensional position within some coordinate reference system.
  DirectPosition2D
  A two-dimensional position on top of Java2D point.
  Envelope2D
  A two-dimensional envelope on top of Java2D rectangle.
  Envelopes
  Transforms envelopes to new Coordinate Reference Systems, and miscellaneous utilities.
  GeneralDirectPosition
  A mutable `DirectPosition` (the coordinates of a position) of arbitrary dimension.
  GeneralEnvelope
  A mutable `Envelope` (a minimum bounding box or rectangle) of arbitrary dimension.
  ImmutableEnvelope
  An immutable `Envelope` (a minimum bounding box or rectangle) of arbitrary dimension.
  MismatchedReferenceSystemException
  Indicates that an object cannot be constructed because of a mismatch in the reference systems of geometric components.
  Shapes2D
  Utility methods working on Java2D shapes.
  UnmodifiableGeometryException
  Indicates that an operation is not allowed on a geometry object because it is unmodifiable.
  WraparoundAdjustment
  An envelope or position converter making them more compatible with a given domain of validity.
  WraparoundMethod
  The strategy to use for representing a region crossing the anti-meridian or other wraparound limit.