Crate terrio

Expand description

Pure-Rust geospatial raster, vector and point cloud data I/O.

terrio opens rasters, vector datasets and point clouds in many formats through one API, converts between them, reprojects, and runs GDAL-style operations, without C dependencies: it builds anywhere Rust does, WebAssembly included. Format codecs come from the wbraster, wbvector, wbprojection and laz crates; terrio adds format detection, remote and archived inputs, its own drivers where those libraries are wrong or missing, and the operations. Results are compared with GDAL’s on real-world files.

§A tour

§Opening, summarizing and writing

open detects the format and returns a Dataset, a raster or a vector dataset read into memory; open_raster and open_vector return one kind. Paths can be local files, URLs, s3://, gs:// and az:// objects or zip archive members (vfs). info summarizes a dataset as gdalinfo and ogrinfo do.

let ds = terrio::open("countries.gpkg")?;
println!("{}", terrio::info::info(&ds, &Default::default()).to_text());

let dem = terrio::open_raster("dem.tif")?;
let options = terrio::RasterWriteOptions {
    driver: Some(terrio::formats::RasterDriver::Cog),
    compression: Some("DEFLATE".into()),
    ..Default::default()
};
terrio::write_raster_dataset(&dem, "dem_cog.tif", &options)?;

let countries = terrio::open_vector("countries.gpkg", &Default::default())?;
terrio::write_vector(&countries.layers, "countries.fgb", &Default::default())?;

§Reading windows lazily

open_raster_lazy opens a GeoTIFF or COG, local or remote, by its headers; a LazyRaster::read_window decodes only the tiles it needs, fetched with HTTP range requests.

let mut cog = terrio::open_raster_lazy("https://example.com/cog.tif")?;
let options = terrio::WindowOptions { bands: vec![1], overview: Some(0) };
let tile = cog.read_window(terrio::Window::new(0, 0, 512, 512), &options)?;

§Operations

ops holds the operations behind the command-line tool, each with an options struct named after the GDAL utility’s options: ops::warp, ops::translate, ops::mosaic, ops::rasterize, ops::polygonize, ops::dem, ops::calc, ops::proximity, ops::sieve and the vector filters of ogr2ogr (ops::vector_filter).

use terrio::crs::SpatialRef;
use terrio::ops::{Resampling, dem, warp};

let dem = terrio::open_raster("dem.tif")?;
let options = warp::WarpOptions {
    dst_srs: Some(SpatialRef::parse("EPSG:32613")?),
    resolution: Some((30.0, 30.0)),
    resampling: Resampling::Bilinear,
    ..Default::default()
};
let utm = warp::warp(&[&dem], &options)?;
let shade = dem::hillshade(&utm, &Default::default())?;
terrio::write_raster_dataset(&shade, "hillshade.tif", &Default::default())?;

§Coordinate reference systems

crs::SpatialRef parses EPSG codes, WKT and PROJ strings; crs::Transformer transforms coordinates as GDAL does, picking the datum transformation GDAL picks.

use terrio::crs::{SpatialRef, Transformer};

let wgs84 = SpatialRef::parse("EPSG:4326")?;
let utm = SpatialRef::parse("EPSG:32613")?;
let (x, y) = Transformer::new(&wgs84, &utm)?.transform(-105.5, 39.5)?;

§Bytes in memory

memory opens datasets from bytes and writes them to bytes, for data already in memory and for WebAssembly, which has no file system.

let bytes = std::fs::read("dem.tif")?;
let dem = terrio::memory::open_raster_bytes(bytes, "dem.tif")?;
let asc = terrio::memory::write_raster_bytes(&dem, "dem.asc", &Default::default())?;

§Point clouds

pointcloud reads LAS, LAZ and COPC into columns (COPC in place, by bounds and octree level), writes them, and grids them into rasters.

use terrio::pointcloud::{self, PointFilter, PointReadOptions, grid};

let filter = PointFilter { classes: vec![2], ..Default::default() };
let ground = pointcloud::read_points("tile.laz", &PointReadOptions { filter, ..Default::default() })?;
let dtm = grid::grid(&ground, &grid::GridOptions { resolution: 1.0, ..Default::default() })?;
terrio::write_raster_dataset(&dtm, "dtm.tif", &Default::default())?;

§The data model

Rasters are wbraster::Rasters (re-exported as Raster): band-major typed pixels with georeferencing and a CRS, wrapped in a RasterDataset that records the driver and whether the nodata value is declared. Vector layers are wbvector::Layers (re-exported as Layer), with Features, a field schema and Geometrys. These types belong to terrio’s public API: use them through terrio’s re-exports (here, raster and vector) rather than depending on wbraster or wbvector directly, so that the versions always match. A breaking release of either crate that terrio adopts is a breaking release of terrio.

§Features

Every driver is on by default. With default-features = false, terrio keeps its core: GeoTIFF and COG, the raw and ASCII rasters, PNG, JPEG, VRT, STAC, GeoJSON, TopoJSON, Shapefile, KML/KMZ, GML, GPX, CSV and MapInfo, the CRS engine, the operations and the streams. The other drivers are features:

geotiff: GeoTIFF and COG, always built (the feature names what a build needs: features = ["geotiff"] is a COG reader and writer);
parquet: GeoParquet, the arrow module and Arrow streams;
remote: URLs, s3://, gs:// and az:// objects, read whole or by range (the http and s3 modules), and datum grids from the PROJ CDN; native builds only;
netcdf-hdf5: NetCDF, HDF5 and HDF-EOS;
sqlite: GeoPackage and SQLite/SpatiaLite;
tiles: MBTiles, PMTiles and MVT (tiles); avif: their AVIF tiles;
zarr, jp2 (JPEG 2000), flatgeobuf, osm (OpenStreetMap);
pointcloud: LAS, LAZ, COPC, EPT, PLY and E57 (pointcloud);
lerc and lzma: GeoTIFFs with those compressions.

The drivers a build leaves out stay in formats::RasterDriver and formats::VectorDriver, listed as neither read nor written: opening or writing their files fails with Error::Unsupported (“built without the zarr feature”).

gdal (off by default): the optional GDAL backend (gdal_backend), which opens the formats terrio has no driver for through GDAL, and writes rasters with GDAL’s drivers. It is the only C dependency, opt-in: GDAL must be installed.

§Minimum supported Rust version

Rust 1.90 (the rust-version in Cargo.toml, checked in CI). The minimum is raised only when a dependency or a language feature needs it, never to a release less than six months old, and only in a minor release (before 1.0, in any release, noted in the changelog).

Modules§

arrowparquet: Vector layers as Apache Arrow record batches, with GeoArrow geometries, and back.
crs: Coordinate reference systems and transformations between them.
formats: The format drivers terrio knows, named as GDAL names them.
gdal_backendgdal: The optional GDAL backend (the gdal cargo feature): opens anything GDAL can when terrio has no driver for it, and writes rasters with GDAL’s drivers.
httpremote: Reading remote files in place, over HTTP(S) range requests.
info: Dataset summaries, like gdalinfo and ogrinfo: info for an open dataset, info_path for a path (reading GeoTIFFs and point clouds by their headers). Summaries print as text (Info::to_text) and serialize to JSON.
memory: Datasets in memory: opening from bytes and writing to bytes, for callers that hold the data already (uploads, HTTP bodies, language bindings) or have no file system (WebAssembly).
ops: GDAL-style processing operations: translate (gdal_translate), warp (gdalwarp), mosaic (gdalbuildvrt and gdal_merge.py), vrt (GDAL’s virtual raster format), rasterize (gdal_rasterize), polygonize (gdal_polygonize), dem (gdaldem), calc (gdal_calc.py), proximity (gdal_proximity.py), sieve (gdal_sieve.py), and the vector filtering of ogr2ogr (vector_filter, sql).
pointcloudpointcloud: Point clouds: LAS 1.0 to 1.4 (point formats 0 to 10, extra bytes, VLRs and EVLRs, waveforms), LAZ (LASzip-compressed LAS), COPC (Cloud Optimized Point Clouds), EPT (Entwine Point Tiles), PLY and E57; read whole or in chunks (for files larger than memory), filtered as PDAL’s filters do (filters) and gridded (grid).
raster: Raster types from wbraster, terrio’s raster data model: pixel storage, CRS records and reprojection options.
s3remote: Amazon S3: object URLs and AWS Signature Version 4 request signing.
sparse: Remote files read by a caller that fetches their bytes itself, for runtimes where reads cannot block on the network (WebAssembly in browsers and Node.js, where fetch is asynchronous).
stac: SpatioTemporal Asset Catalog (STAC) documents as datasets, as GDAL’s STACIT driver and its GeoJSON driver read them.
stream: Vector layers read and written as streams of features, for layers larger than memory.
tiles: Tile archives: PMTiles (v3) and MBTiles, holding raster tiles (PNG, JPEG, WebP, AVIF) or Mapbox Vector Tiles, in the Web Mercator tiling scheme (EPSG:3857, 256-pixel tiles).
vector: Vector layer helpers, and the parts of terrio’s vector data model (from wbvector) that the crate root does not re-export: coordinates, rings, schemas, bounding boxes and layer CRSs.
vfs: Locating datasets: local paths, HTTP(S) URLs, cloud object storage and zip archives.
warnings: Warnings: problems that do not stop an operation but change its result, such as a CRS that terrio reads but cannot represent. They are kept for the thread that raised them until taken with take, so that callers (the command line, the Python bindings) can report them. Warnings are raised where datasets are opened, on the caller’s thread: those raised on other threads (a worker of a parallel operation) are kept for those threads and not reported.

Structs§

BandMetadata: The descriptive metadata of a band, as GDAL keeps it.
CsvOptions: Options for reading and writing CSV.
Feature: The vector types: layers of features with geometries and attributes. A single geographic feature: optional geometry + attribute values.
FieldDef: The vector types: layers of features with geometries and attributes. Metadata for a single attribute field.
Gcp: A ground control point: a pixel position and its georeferenced coordinates, as GDAL’s GDAL_GCP.
GeoJsonOptions: Options for writing GeoJSON.
GeoTiffWriter: A GeoTIFF written a few rows at a time, so that rasters larger than memory can be written: the image data first, as rows of blocks are complete, then the image’s directory at the end of the file (a layout GDAL writes too, and reads as any GeoTIFF). The lossless compressions, predictors, tiles or strips, pixel or band interleaving, georeferencing (rotated or by GCPs), metadata, color tables, RPCs and GDAL’s internal mask are written as by crate::write_raster_dataset; overviews and COGs need the whole raster and are not.
Geolocation: Where the longitude and latitude of each pixel of a raster are, as GDAL describes geolocation arrays (its GEOLOCATION metadata domain, RFC 4): two rasters (x_dataset, y_dataset), sampled every pixel_step columns from pixel_offset and every line_step rows from line_offset.
Layer: The vector types: layers of features with geometries and attributes. A named collection of features sharing a geometry type and attribute schema.
LazyRaster: A raster opened for its metadata, whose pixels are read on demand.
NullSafeAllocator: The system allocator, ignoring the release of null pointers.
Raster: The raster type: pixels, georeferencing and CRS, in memory. A raster grid with one or more bands.
RasterConfig: The raster type: pixels, georeferencing and CRS, in memory. Parameters used to construct a new Raster.
RasterDataset: A raster dataset read into memory.
RasterWriteOptions: Options for writing rasters.
VectorDataset: A vector dataset read into memory: one or more layers.
VectorOpenOptions: Options for opening vector datasets.
VectorWriteOptions: Options for writing vector datasets.
Window: A rectangle of pixels: width columns and height rows from column x, row y.
WindowOptions: What LazyRaster::read_window reads.

Enums§

CsvGeometry: How CsvOptions writes geometries.
DataType: The raster type: pixels, georeferencing and CRS, in memory. The underlying numeric data type of raster cells.
Dataset: A dataset of either kind.
Error: A terrio error.
FieldType: The vector types: layers of features with geometries and attributes. Storage type of one attribute field.
FieldValue: The vector types: layers of features with geometries and attributes. A typed attribute value.
Geometry: The vector types: layers of features with geometries and attributes. The canonical geometry type covering all OGC Simple Features.
GeometryType: The vector types: layers of features with geometries and attributes. Enumerates OGC Simple Features geometry classes.

Constants§

VERSION: The version of this crate.

Functions§

geo_transform: The GDAL-style geotransform of a raster (north-up: see RasterDataset::geo_transform for rotated ones).
is_north_up: Whether a geotransform is north-up: no rotation, a positive pixel width and a negative pixel height.
list_layers: The layer names of a vector dataset, without reading the features when the format allows it.
open: Opens a dataset, raster or vector, detecting its format.
open_raster: Opens a raster dataset, reading it into memory.
open_raster_lazy: Opens a raster lazily: see LazyRaster::open.
open_vector: Opens a vector dataset, reading its layers into memory.
read_gcps: The ground control points of a GeoTIFF (local, remote or in an archive), as GDAL reads them: tie points without a pixel scale or transformation matrix, in the file’s CRS. Empty for rasters georeferenced by a geotransform, and for other formats.
write_netcdf_groups: Writes rasters into one netCDF-4 file, each in its group: /science/grid (groups created as needed) or / for the root, with its own dimensions, coordinate variables and grid mapping, as the netCDF library lays out groups. A single raster goes in a group with the GROUP creation option of write_raster_dataset. The creation options are the netCDF driver’s (FORMAT defaults to NC4, which groups need; COMPRESS=DEFLATE, ZLEVEL, CHUNKING).
write_raster: Writes a raster, declaring its nodata value.
write_raster_dataset: Writes a raster dataset, declaring a nodata value only when the dataset has one.
write_vector: Writes vector layers. GeoPackage, GPX, KML, KMZ and TopoJSON hold several layers in one file; for the other formats, write one layer at a time.

Type Aliases§

Result: A result with a terrio Error.

Crate terrio

Crate terrio Copy item path

§A tour

§Opening, summarizing and writing

§Reading windows lazily

§Operations

§Coordinate reference systems

§Bytes in memory

§Point clouds

§The data model

§Features

§Minimum supported Rust version

Modules§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate terrio