API Reference
georastertools
Every raster tools can be activated with their own API:
|
Raster tool that applies a filter on a raster image. |
|
Raster tool that computes the hillshades of a Digital Elevation / Surface / Height Model corresponding to a given solar position. |
|
Raster tool that computes radiometric indices of a raster product. |
|
Raster tool that computes the time derivative (speed) of raster images. |
|
Raster tool that computes the Sky View Factor (SVF) of a Digital Elevation / Surface / Height Model. |
|
Raster tool that tiles a raster following the geometries of a grid. |
|
Raster tool that generates the time series of raster images. |
|
Raster tool that computes zonal statistics of a raster product. |
All these objects provide:
a fluent API to configure the processing. The methods are all named with the following pattern “with_<something>” and return the current instance so that the methods can be chained.
methods to process a single file or a set of files (see
eolab.georastertools.Rastertool.process_fileandeolab.georastertools.Rastertool.process_files)
Example of use:
from eolab.georastertools import Radioindice
proc = Radioindice(Radioindice.ndvi)
outputs = proc.with_output(".", merge=False)
.with_roi("./roi.geojson")
.process_file("./SENTINEL2B_20181023-105107-455_L2A_T30TYP_D.zip")
print(outputs)
Raster products
georastertools provides a useful API to open raster products that are provided as an archive or a directory containing several images.
The API is very simple to use:
from eolab.georastertools.product import RasterProduct
import rasterio
with RasterProduct("tests/tests_data/SENTINEL2B_20181023-105107-455_L2A_T30TYP_D.zip") as rp:
with rasterio.Env(GDAL_VRT_ENABLE_PYTHON=True):
with rp.open(roi="tests/tests_data/COMMUNE_32001.shp") as dataset:
data = dataset.read([1, 2, 3], masked=True)
Adding custom raster types
To add custom raster types, use the method eolab.georastertools.add_custom_rastertypes.
- eolab.georastertools.add_custom_rastertypes(rastertypes)[source]
Add definition of new raster types. The json string shall have the following format:
{ "rastertypes": [ { "name": "RGB_TIF", "product_pattern": "^RGB_TIF_(?P<date>[0-9_]*)\.(tif|TIF)$", "bands": [ { "channel": "red", "description": "red" }, { "channel": "green", "description": "green" }, { "channel": "blue", "description": "blue" }, { "channel": "nir", "description": "nir" } ], "date_format": "%Y%m%d_%H%M%S", "nodata": 0 }, { "name": "RGB_TIF_ARCHIVE", "product_pattern": "^RGB_TIF_(?P<date>[0-9\_]*).*$", "bands_pattern": "^TIF_(?P<bands>{}).*\.(tif|TIF)$", "bands": [ { "channel": "red", "identifier": "r", "description": "red" }, { "channel": "green", "identifier": "g", "description": "green" }, { "channel": "blue", "identifier": "b", "description": "blue" }, { "channel": "nir", "identifier": "n", "description": "nir" } ], "date_format": "%Y%m%d_%H%M%S", "nodata": 0 } ] }
name : unique name of raster type
product_pattern: regexp to identify raster product matching the raster type. Regexp can contain catching groups that identifies metadata: date (groupe name=date), relative orbit number (relorbit), tile number (tile), any other group (free name of the group).
bands_pattern (optional) : when the raster product of this type is an archive (zip, tar, tar.gz, etc.), the pattern enables to identify the files of the different raster bands. The raster product can contain one raster file per band or one multi-bands raster file. In the first case, the pattern must contain a group that identify the band to which the file corresponds. This group must be defined as follows (?P<bands>{}) in which the variable part {} will be replaced by the identifier of the band (see below).
date_format (optional): date format in the product name. By default: %Y%m%d-%H%M%S
nodata (optional): no data value of raster bands. By default: -10000
masknnodata (optional): nodata value in the mask band
For every bands:
channel: channel of the band. Must be one of: blue, green, red, nir, mir, swir, red_edge1, red_edge2, red_edge3, red_edge4, blue_60m, nir_60m and mir_60m.
identifier (optional): string that identifies the band in the filenames of a raster product that it is an archive. This identifier is inserted in the group
bandsof the bands_pattern.description (optional): band description that will be reused in the generated products.
For every masks:
identifier (optional): string that identifies the mask band in the filenames of a raster product that it is an archive. This identifier is inserted in the group
bandsof the bands_pattern.description (optional): mask band description that will be reused in the generated products.
maskfunc (optional): fully qualified name of the python function that converts the mask band values to a binary mask (0 = masked; 1 = unmasked)
- Parameters:
rastertypes – JSON string that contains the new raster types definition
Example of use:
from eolab.georastertools import add_custom_rastertypes
my_rastertypes = {
"rastertypes": [
{
"name": "RGB_TIF",
"product_pattern": "^RGB_TIF_(?P<date>[0-9_]*)_test\\.(tif|TIF)$",
"bands": [
{
"channel": "red",
"description": "red"
},
{
"channel": "green",
"description": "green"
},
{
"channel": "blue",
"description": "blue"
},
{
"channel": "nir",
"description": "nir"
}
],
"date_format": "%Y%m%d_%H%M%S",
"nodata": 0
},
{
"name": "RGB_TIF_ARCHIVE",
"product_pattern": "^RGB_TIF_(?P<date>[0-9\\_]*).*$",
"bands_pattern": "^TIF_(?P<bands>{}).*\\.(tif|TIF)$",
"bands": [
{
"channel": "red",
"identifier": "r",
"description": "red"
},
{
"channel": "green",
"identifier": "g",
"description": "green"
},
{
"channel": "blue",
"identifier": "b",
"description": "blue"
},
{
"channel": "nir",
"identifier": "n",
"description": "nir"
}
],
"date_format": "%Y%m%d_%H%M%S",
"nodata": 0
}
]
}
add_custom_rastertypes(json)
# now any georastertools can handle products of the two new rastertypes
...
Design rules of raster tools
Every raster tool object inherits from base class eolab.georastertools.Rastertool.
If the process supports windowing, the raster tool can also inherit from eolab.georastertools.Windowable.
Base class for every raster tool which contains the common configuration: |
|
Decorator of a |
A rastertool raises a eolab.georastertools.RastertoolConfigurationException when invalid
input parameter is provided.
|
This class defines an exception that is raised when the configuration of the raster tool is invalid (wrong input parameter) |
Moreover, a rastertool can raise any type of Exception during its execution. The best practice is thus to catch exceptions that can raise as follows:
from eolab.georastertools import Radioindice, RastertoolConfigurationException
proc = Radioindice(Radioindice.ndvi)
try:
outputs = proc.with_output("unknown_dir", merge=False)
.process_file("./SENTINEL2B_20181023-105107-455_L2A_T30TYP_D.zip")
except RastertoolConfigurationException as rce:
# do something
print(f"Invalid configuration of radioindice processing: {rce}")
except Exception as err:
# do something
print(f"An unexpected error occurs while processing file: {err}")
In this example, a RastertoolConfigurationException is raises because the specified output dir does not exist.