Home

Rasterio reads and writes geospatial raster datasets, using GDAL and NumPy.

This wiki contains additional material of interest to rasterio developers (WORK IN PROGRESS).

Please see the README for the main documentation of this project.

Cython and GDAL

Cython is used to build C extensions that provide bindings against GDAL and additional optimizations for performant functions accessible from Python.

GDAL functions

GDAL functions are typically made available in rasterio using the following components:

• Declaration of external function available in one of GDAL's header files (for example: _gdal.pxd).
• Cython bridge function that wraps the GDAL function and associated data structures, and may include additional operations to be compiled to C code using Cython (for example: _features.pyx).
• Python function that calls above bridge function, providing additional utility operations and data validation as necessary (for example: features.py).

GDAL data structures

TODO

Memory management

TODO

Wrapping a GDAL function

Here is an example workflow that covers the highlights:

1. Find the declaration of function you want in the appropriate GDAL header file (for example: gdal_alg.h). Add this declaration to the appropriate declaration file in rasterio (for example: _gdal.pxd) to the existing section that includes other declarations from that header file, or preceded by cdef extern from "<name of header file>": otherwise.
2. Add declarations and wrappings of any required data structures (TODO).
3. Create a Cython bridge function in the appropriate rasterio Cython file (for example: _features.pyx). This function will typically take Python or NumPy objects as input, and transform them into the appropriate data structures to pass into the GDAL function. This function will also need to handle transformation of the outputs into the proper representation to return to the calling Python code. This module will need to cimport the module above with the declarations.
4. Create wrapping python function, if necessary. (TODO: better describe recommended division of labor between python and cython functions).

Naming conventions:

TODO: file names (*.pxd, *.pyx, *.py) and function names (_foo() in *.pyx, foo() in *.py)