Born from a collaboration between:


               

Overview

GeoRacoon is aimed at supporting work and analyses with large spatial raster data. It heavily relies on RasterIO (rio) extending its functionality and usability. Leveraging gdal's block-based read/write capability, GeoRacoon implements efficient multi-core support (i.e. parallelization) for various high and low-level operations, such as convolution operations (e.g., applying a Gaussian filter) or even area-wide multiple linear regressions. It also facilitates GeoTIFF handling with an object oriented abstraction layer to RasterIO which incorporates the management of metadata with source and band tagging.

GeoRacoon provides 3 packages, riogrande, convster and coonfit, which facilitate (in our opinion) working with TIFF files.

• RioGrande is the great heart of the GeoRacoon and adds functionality for parallel processing using block-based I/O, dataset compatibility checks, data type conversion, mask and selector creation as well as simple file compression.
• Convster allows for (Gaussian) convolution of raster files using parallelized processing, coon-style. While Gaussian and border-preserving Gaussian filters are default parameters, other filters can be used.
• CoonFit allows to fit linear models the coon-way, meaning parallelized and fast, while understandable due to the reliance on matrix operations

Quickstart

Installation

Supported Python versions:

Setting up a virtual environment

We recommend installing GeoRacoon in a virtual environment to avoid dependency conflicts.

On macOS and Linux:

$ python -m venv .venv
$ source .venv/bin/activate

On Windows:

PS> python -m venv .venv
PS> .venv\Scripts\activate

Installing GeoRacoon

GeoRacoon is available on PyPI and can be installed with:

pip install GeoRacoon

To install the latest version directly from GitHub into your virtual environment, run:

pip install git+https://github.com/GeoRacoon/georacoon.git

$ python -m pip install -e .

PS> python -m pip install -e .

Note: This package relies on rasterio which partially depends on libgdal. If you follow the installation instructions below you will attempt to install rasterio from the Python Package Index in which case the libgdal library will be shipped along. However, if you encounter any issues with the installation of rasterio, head over to the rasterio installation instructions for more details.

We also use the python package gdal which depends on libgdal that has been installed (see comment above). It is important to install matching version, so first check with gdalinfo --version what version of libgdal you have installed and then install the corresponding python package with pip install gdal==x.x.x.

$ uv pip install GeoRacoon

$ git clone https://github.com/GeoRacoon/GeoRacoon.git
$ cd GeoRacoon
$ uv pip install -e .

Usage

Head over to the examples/ folder for full end-to-end examples. Also, refer to the project's documentation page for more details.

GeoRacoon provides high-level functions that allow you to do many things in just a few lines of code:

from riogrande.io import Source
from convster import parallel as cvpara
from convster.filters import bpgaussian  # border-preserving Gaussian

source = Source("landcover.tif")

# Kernel: 30 km sigma, 1 km resolution → 30 pixels
params_filter = dict(sigma=30, truncate=3, preserve_range=True)

cvpara.apply_filter(
    source=source,
    output_file="landcover_blurred.tif",
    block_size=(200, 200),
    img_filter=bpgaussian,
    filter_params=params_filter,
    data_as_dtype="float32",
    n_jobs=4,
)

Minimal Examples

from riogrande.io import Source, Band

# Open a GeoTIFF as a Source
source = Source("elevation.tif")

# Import the file's profile (size, CRS, dtype, …)
profile = source.import_profile()

# Tag a band and retrieve it by tag later
source.set_tags(bidx=1, tags={"category": "elevation_mean"})
band = source.get_band(category="elevation_mean")

# Or just grab a band by index
band = source.get_band(bidx=1)
print(band.tags)

from riogrande.io import Source
from convster import parallel as cvpara
from convster.filters import bpgaussian  # border-preserving Gaussian

source = Source("landcover.tif")

# Kernel: 30 km sigma, 1 km resolution → 30 pixels
params_filter = dict(sigma=30, truncate=3, preserve_range=True)

cvpara.apply_filter(
    source=source,
    output_file="landcover_blurred.tif",
    block_size=(200, 200),
    img_filter=bpgaussian,
    filter_params=params_filter,
    data_as_dtype="float32",
    n_jobs=4,
)

import numpy as np
from riogrande.io import Source, Band
from coonfit import parallel as lfpara

# Set up response and predictor bands
response_band = Band(Source("lst.tif"), bidx=1)

pred_source = Source("elevation.tif")
pred_source.set_tags(bidx=1, tags={"category": "elevation"})
predictor_band = pred_source.get_band(category="elevation")

# Fit the model — returns a dict of {band: weight}
weights = lfpara.compute_weights(
    response=response_band,
    predictors=[predictor_band],
    block_size=(200, 200),
    include_intercept=True,
    no_data=np.nan,
    n_jobs=4,
)
print(weights)

# Apply the fitted weights to produce a prediction raster
lfpara.compute_model(
    predictors=[predictor_band],
    optimal_weights=weights,
    output_file="lst_predicted.tif",
    block_size=(200, 200),
    n_jobs=4,
)

Contributing

We are so happy you landed here, and hopefully came with a bag full of fresh ideas or just discovered some things which need improvement. In any case we highly encourage you to help making GeoRacoon a better package.

As we know, racoons come in a gaze (that's right - we also had to look this up) and therefore they are never alone. So instead of merely 'gazing' at the repository, feel free to jump right in.

And when doing so, please consider some guidelines to help you get started here.

Authors

License

GeoRacoon is distributed under a MIT license: LICENSE.