GeoTrellis Documentation

GeoTrellis is a Scala library and framework designed for high-performance raster data processing at scale. It leverages Apache Spark to handle arbitrarily large datasets (terabyte-level and beyond).

Key Capabilities:

• Raster Operations: Implements Map Algebra operations and vector-to-raster/raster-to-vector conversions.
• I/O: Fast reading and writing of raster data.
• Rendering: Tools to render rasters into PNGs.
• Metadata: Ability to store raster metadata as JSON.
• Scalability: Designed for both sub-second RESTful endpoint responses and large-scale batch processing.

The geotrellis-vector module provides types and algorithms for processing vector data via the geotrellis.vector.* package. Key capabilities include:

• JTS Helpers: Idiomatic helpers for JTS types like Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection.
• Geometric Operations: Type-safe geometric operations, Convex Hull, Densification, Simplification, and affine transformations.
• Feature Type: A Feature type that composes an id, a geometry, and a generic data type.
• I/O Formats: Read and write geometries and features using GeoJSON, WKT, and WKB.
• Reprojection: Reproject geometries between two Coordinate Reference Systems (CRS).
• Interpolation: Perform Kriging interpolation on point values.

The geotrellis-vectortile module is an experimental implementation of the Mapbox VectorTile codec. It provides the geotrellis.vectortile.* package, which enables:

• Lazy decoding of vector tiles.
• Reading and writing VectorTile tile layers from any supported tile backend.

The geotrellis.raster.io package provides various methods for serializing and deserializing raster data for persistence and networking. Depending on your requirements, you can use different sub-packages:

• GeoTIFF: Use geotrellis.raster.io.geotiff (specifically the reader and writer packages) to read and write .tif files. This is the most common use case for raster I/O.
• JSON: Use geotrellis.raster.io.json to encode or decode raster data (typically metadata or small subsets rather than entire rasters) as JSON.
• ARG: Use geotrellis.raster.io.arg to move data in and out of the Azavea Raster Grid format.
• ASCII: Use geotrellis.raster.io.ascii to interact with ASCII-art representations of rasters.

The geotrellis-util module provides essential low-level utilities and data structures used across the GeoTrellis ecosystem. It provides the geotrellis.util.* package, which includes:

• Constants and common data structures (e.g., BTree).
• Haversine implementation for distance calculations.
• Lenses for data manipulation.
• RangeReaderProvider for reading contiguous subsets of data.
• Implementations for FileRangeReader and HttpRangeReader.

The Pipeline Tool is an ETL (Extract, Transform, Load) abstraction inspired by PDAL. It allows you to define a sequence of instructions for reading, transforming, and writing geospatial data using JSON objects. Each instruction is represented as a Stage Object.

Stages are categorized into three types:

1. Readers: Load data into Spark memory.
2. Transformations: Process the data (e.g., reprojecting, resampling, building pyramids).
3. Writers: Save the processed data to storage.

Pipelines can be defined using JSON or via the internal Scala DSL.

In GeoTrellis, an 'ingest' is the process of collecting raw data, transforming it into rasters of a desirable format, and storing it for efficient querying.

Modern GeoTrellis workflows have moved away from monolithic ETL (Extract/Transform/Load) packages and generic pipeline approaches. Instead, the recommended pattern is to write programs using lower-level constructs, specifically the RasterSource abstraction. This allows for better handling of edge cases and more expressive interaction with imagery sources.

A LayoutScheme defines how zoom levels are structured within a pyramid. It provides the levelFor() method to determine an integer zoom level and layout definition based on an extent and cell size, and allows navigation via zoomIn() and zoomOut().

There are two primary modes:

1. Local Layout Schemes (LocalLayoutScheme): Starts with a specific LayoutDefinition and assigns it an arbitrary zoom number. Subsequent lower-resolution levels are generated via power-of-two reductions. The user must specify the initial numerical zoom level.
2. Global Layout Schemes (ZoomedLayoutScheme): Has a predefined structure starting from a global extent defined by a CRS. It defines the cell size at zoom level 0 (where one tile covers the entire world extent), and resolution doubles at each successive zoom level. This is compatible with web map standards like TMS.

For large-scale datasets, GeoTrellis uses a tiling strategy to divide a large spatial Extent into a grid of smaller Tile objects. This allows for distributed processing (e.g., via Apache Spark).

Key components for tiling:

• TileLayout: Defines the grid structure. It specifies the number of columns/rows and the dimensions (width/height in cells) of each tile.
• LayoutDefinition: Combines an Extent with a TileLayout to define the complete spatial grid.
• mapTransform: A property of LayoutDefinition used to translate spatial extents into grid indices (e.g., finding which tiles overlap a specific area).

import geotrellis.spark.tiling._

// Create a 7x4 grid where each tile is 100x100 cells
val tl = TileLayout(7, 4, 100, 100)

// Combine with spatial extent
val ld = LayoutDefinition(extent, tl)