Spatial Data Model

The Spatial Data Model in GeoTools provides the fundamental geometric constructs used to represent geographic features and their extents. This page explains the core data structures that define spatial objects, their reference systems, and how they interact in the GeoTools library. For information about how these structures are used within the Data Access Framework, see Data Access Framework.

Core Components

The GeoTools spatial data model consists of several key components that work together to represent geometry in a consistent way:

1. Positions - Points in coordinate space
2. Bounds/Envelopes - Rectangular extents in coordinate space
3. Coordinate Reference Systems - Define the frame of reference for coordinates

100%

• modules/library/referencing/src/main/java/org/geotools/geometry/package-info.java
• modules/library/main/src/main/java/org/geotools/geometry/jts/ReferencedEnvelope.java
• modules/library/referencing/src/main/java/org/geotools/geometry/GeneralBounds.java

Position

Position represents a point in coordinate space. It serves as a fundamental building block for geometry in GeoTools and can represent coordinates in any number of dimensions.

100%

Position implementations are typically immutable once created, allowing them to be safely shared between threads. The main implementations are:

• GeneralPosition: A general-purpose implementation that can represent a position in n-dimensional space

• Position2D: A specialized 2D position that provides convenience methods for working with x and y coordinates

• modules/library/referencing/src/test/java/org/geotools/geometry/PositionTest.java

• docs/user/welcome/upgrade.rst

Bounds and Envelopes

Bounds represents a rectangular region in coordinate space, defined by minimum and maximum ordinate values along each dimension. Bounds are fundamental to many GeoTools operations, including spatial queries, rendering, and transformation.

The main implementations of Bounds are:

• GeneralBounds: A general-purpose n-dimensional bounds implementation

• ReferencedEnvelope: A JTS-compatible envelope that also implements the Bounds interface, allowing seamless integration with both GeoTools and JTS

• modules/library/main/src/main/java/org/geotools/geometry/jts/ReferencedEnvelope.java

• modules/library/referencing/src/main/java/org/geotools/geometry/GeneralBounds.java

• modules/library/referencing/src/test/java/org/geotools/geometry/GeneralBoundsTest.java

ReferencedEnvelope: A Bridge to JTS

ReferencedEnvelope is a particularly important class in GeoTools as it bridges the gap between the GeoTools spatial data model and the JTS Topology Suite. It extends JTS's Envelope while implementing GeoTools' Bounds interface.

Key features of ReferencedEnvelope:

• Stores a coordinate reference system alongside the JTS envelope

• Provides methods for coordinate transformation between different CRS

• Offers utility methods for creating envelopes from various sources

• Implements both GeoTools' Bounds interface and JTS's Envelope, making it a versatile bridge between the two systems

• modules/library/main/src/main/java/org/geotools/geometry/jts/ReferencedEnvelope.java

• modules/library/main/src/test/java/org/geotools/geometry/jts/ReferencedEnvelopeTest.java

Coordinate Reference Systems

Coordinate Reference Systems (CRS) are fundamental to the spatial data model, defining how coordinates relate to real-world locations. In GeoTools, CRS objects are associated with positions and bounds to give spatial context to the coordinates.

100%

Key points about CRS in the spatial data model:

• Both Position and Bounds objects reference a CRS

• CRS information is essential for coordinate transformations

• The CRS determines how coordinates are interpreted (e.g., latitude/longitude vs. projected coordinates)

• When creating a position or bounds with different CRS, transformations may be required to ensure compatibility

• modules/library/main/src/main/java/org/geotools/geometry/jts/ReferencedEnvelope.java

• modules/plugin/epsg-hsql/src/test/java/org/geotools/referencing/factory/epsg/hsql/ThreadedTransformTest.java

Use in Grid Coverages

The spatial data model is extensively used in GeoTools' grid coverage subsystem. Grid coverages represent continuous phenomena like elevation or temperature using a regular grid of values, and the spatial data model provides the necessary constructs to relate these grids to real-world coordinates.

100%

In grid coverages:

• GridGeometry2D combines a grid range (pixel dimensions) with a transformation that maps pixel coordinates to world coordinates
• The Bounds/ReferencedEnvelope defines the geographic extent of the coverage
• Coordinate transformations are used when reprojecting grid coverages

The spatial data model allows grid coverages to be properly georeferenced, enabling operations like overlaying, subsampling, and reprojection.

• modules/library/coverage/src/main/java/org/geotools/coverage/grid/GridCoverage2D.java
• modules/plugin/coverage-multidim/coverage-api/src/main/java/org/geotools/coverage/io/util/Utilities.java

Recent API Changes

The GeoTools spatial data model underwent significant changes in GeoTools 30.x, including:

1. Package rename from org.opengis.geometry to org.geotools.api.geometry
2. Class rename from DirectPosition to Position
3. Class rename from Envelope to Bounds
4. Additional method changes and refinements

These changes were made to improve the API and remove dependencies on the external OpenGIS packages.

100%

Compatibility considerations:

• Code using the old API must be updated to use the new class and package names

• Some method signatures have changed (e.g., ReferencedEnvelope.create() to ReferencedEnvelope.envelope())

• Direct field access to Envelope2D's x, y, width, height has been replaced with proper getter methods

• docs/user/welcome/upgrade.rst

• docs/user/welcome/files/remove-opengis.xml

Integration with Image Mosaic

The spatial data model is used in the ImageMosaic plugin to define the geographic extents of image tiles. ImageMosaic uses ReferencedEnvelope to track the bounds of each image in a mosaic.

100%

In ImageMosaic:

• The shapefile index contains features with associated filenames

• Each feature has a geometry that defines the bounds of the corresponding image

• ReferencedEnvelope is used to represent these bounds with proper CRS information

• The spatial data model allows efficient querying of which images intersect a requested area

• docs/user/library/coverage/mosaic.rst

• modules/plugin/imagemosaic/src/test/java/org/geotools/gce/imagemosaic/UtilsTest.java

Summary

The spatial data model in GeoTools provides a solid foundation for representing geographic data through:

1. Position classes for representing points in coordinate space
2. Bounds/Envelope classes for representing rectangular regions
3. Integration with coordinate reference systems
4. Compatibility with JTS geometries
5. Support for grid coverages

This model underpins many higher-level GeoTools features, from data access to rendering, and ensures consistent handling of spatial data throughout the library.