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.