GeoRacoon 1.0.0

Package to compute diversity measures in land cover type (LCT) maps

GeoRacoon

Out and about
<>
ready to tackle Geographic Raster

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 can be installed directly from GitHub into your virtual environment. Simply run:

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

Development installation

You can also clone the repository and install the package from your local copy. This is the recommended strategy if you intend to work on the source code, allowing you to modify the files in-place.

To install:

1. Clone this repository
2. cd into the repository

On macOS and Linux:

$ python -m pip install -e .

On Windows:

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.

Installation with `uv`

If you prefer using uv for faster package management, you can install GeoRacoon as follows:

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

For development installation with uv:

$ 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",
    nbrcpu=4,
)

Minimal Examples

RioGrande — open a GeoTIFF and work with Sources and Bands

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)

Convster — apply a spatial filter to a raster

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",
    nbrcpu=4,
)

CoonFit — fit a linear model and generate a prediction raster

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,
    nbrcpu=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),
    nbrcpu=4,
)

Contributing

We welcome contributions from the community!

Here are some guidelines to help you get started:

1. Seeking Support or Reporting Issues: If you need help or encounter unexpected behaviour, head over to the issue page. Before opening a new issue, please check the existing ones (including closed issues) — someone may have run into the same problem. When opening an issue, include as much detail as possible: steps to reproduce, your operating system, Python version, and any error messages.

2. Software Contributions: We encourage contributions directly via pull requests on the GeoRacoon repository. Before starting your work, please first create an issue describing the contribution you wish to make. This allows us to discuss and agree on the best way to integrate your contribution into the package.

   In case you are unsure about how to proceed with a contribution, you can follow these steps:

   1. Fork GeoRacoon from https://github.com/GeoRacoon/GeoRacoon/fork
   2. Create your feature branch (git checkout -b feature-new)
   3. Make your changes
   4. Commit your changes (git commit -am 'Add some new feature')
   5. Push to the branch (git push origin feature-new)
   6. Create a new pull request

Authors

License

GeoRacoon is distributed under a MIT license: LICENSE.