Crate gdal

GDAL

GDAL is a translator and processing library for various raster and vector geospatial data formats.

This crate provides safe, idiomatic Rust bindings for GDAL.

Capabilities

GDAL is an incredibly powerful library. For a general understanding of its capabilities, a good place to get started is the GDAL User-oriented documentation. These features include:

• Opening raster and vector file formats for reading/writing
• Translating between file formats
• Reading and writing metadata in raster and vector datasets
• Accessing raster bands and their metadata
• Reading and writing geospatial coordinate system and projection values
• Warping (resampling and re-projecting) between coordinate systems

Usage

This crate provides high-level, idiomatic Rust bindings for GDAL. To do that, it uses gdal-sys internally, a low-level interface to the GDAL C library, which is generated using bindgen. Using the gdal-sys crate directly is normally not needed, but it can be useful in order to call APIs that have not yet been exposed in gdal.

Version support

As a general rule, only GDAL versions in Ubuntu LTS-1 (previous LTS version, that is, GDAL 3.0 in 20.04 at this moment) are supported. gdal-sys might support earlier versions using the bindgen feature flag, but gdal does not.

Building this crate assumes a compatible version of GDAL is installed with the corresponding header files and shared libraries. This repository includes pre-generated bindings for GDAL 3.0 through 3.9 (see thegdal-sys/prebuilt-bindings directory). If you’re compiling against another version of GDAL, you can enable the bindgen feature flag to have the bindings generated on the fly.

Show Me Code!

To get you started with GDAL (without having to read the whole manual!), take a look at the examples in the raster and vector modules, but for the maximally impatient, here you go:

use gdal::Dataset;
let ds = Dataset::open("fixtures/m_3607824_se_17_1_20160620_sub.tif")?;
println!("This {} is in '{}' and has {} bands.", ds.driver().long_name(), ds.spatial_ref()?.name()?, ds.raster_count());

This GeoTIFF is in 'NAD83 / UTM zone 17N' and has 4 bands.

Data Model

At the top level, GDAL uses the same data model to access both vector and raster data sets. There are several shared data model constructs at this level, but the first ones to become familiar with are Driver, Dataset, and Metadata. These provide the general access points to raster- and vector-specific constructs.

Driver

One of GDAL’s major strengths is the vast number of data formats it’s able to work with. The GDAL Manual has a full list of available raster and vector drivers.

The Driver API provides the requisite access points for working GDAL’s drivers.

Dataset

Dataset is the top-level container for accessing all data within a data set, whether raster or vector. Some methods and traits on Dataset are shared between raster and vector datasets, and (due to historical reasons) some associated functions are only applicable to one context or the other. The raster and vector modules cover these specifics.

Metadata

Metadata in GDAL takes a number of forms, some of which are specific to purpose (e.g. pixel interpretation, spatial reference system), and other more general-purpose (e.g. acquisition date-time). The former will be covered in relevant sections of the raster and vector modules, and the general-purpose data model in the Metadata API.

Raster Data

A raster Dataset has a size (cols,rows), an ordered sequence of RasterBands, geospatial metadata, and general-purpose Metadata, common to all the bands.

Each RasterBand contains a buffer of pixels (a.k.a. cells), a no-data value, and other metadata.

The raster module covers these concepts in more detail.

Vector Data

A vector Dataset contains a sequence of one or more Layers, geospatial metadata, and general-purpose Metadata, common to all the layers. Each Layer in turn contains zero or more Features, each of which contains a geometry and set of fields.

The vector module covers these concepts in more detail.

Re-exports

• pub use version::version_info;

Modules

• config
  GDAL Configuration Functions
• cpl
  GDAL Common Portability Library Functions
• errors
  GDAL Error Types
• programs
  Rust wrappers for the GDAL Programs
• raster
  GDAL Raster Data API
• spatial_ref
  GDAL Spatial Reference System
• vector
  GDAL Vector Data API
• version
  GDAL Version Inspection Utilities
• vsi
  GDAL Virtual File System Library Functions

Structs

• ArrowArrayStream
  Data type for a Arrow C stream. Include ogr_recordbatch.h to get the definition.
• Dataset
  Wrapper around a GDALDataset object.
• DatasetOptions
  Open options for crate::Dataset
• Driver
  Raster and Vector Driver API
• DriverManager
  A wrapper around GDALDriverManager. This struct helps listing and registering Drivers.
• Gcp
  An owned Ground Control Point.
• GcpRef
  A wrapper over a Ground Control Point, borrowed from an existing dataset.
• GdalOpenFlags
  GDal extended open flags used by [Dataset::open_ex].
• MetadataEntry
  Standalone metadata entry, as returned by iterator from Metadata::metadata.

Enums

• DriverType

Traits

• GeoTransformEx
  Extension methods on GeoTransform
• Metadata
  General-Purpose Metadata API

Type Aliases

• GeoTransform
  A six-element array storing the coefficients of an affine transform used in mapping coordinates between pixel/line (P, L) (raster) space, and (Xp,Yp) (projection/crate::spatial_ref::SpatialRef) space.