chain.fft_filtering_chain

Module for a FFT Filtering chain with overlap-add strip management

gridr.chain.fft_filtering_chain.check_oa_strip_size(arr, fil, strip_size)[source]

Check the strip size against array and filter dimension.

The method returns 0 if either :

the half number of lines in the array is lesser than the strip size
the number of rows in the filter is greater than or equal to the half number of lines in the input array.

Otherwise, it returns the given strip_size.

Parameters:

arr (Union[np.ndarray, ArrayProfile]) – The input image array.
fil (np.ndarray) – The filter given as an array in the spatial domain.
strip_size (int) – The chunk target number of rows.

Returns:

The original strip_size or 0.

Return type:

int

gridr.chain.fft_filtering_chain.fft_array_filter_fallback(ds_in, ds_out, band, fil, boundary, out_mode, binary=False, binary_threshold=0.001, zoom=1, round_out=True)[source]

Wrapper to the fft_array_filter core method in case of no strip.

Parameters:

ds_in (rasterio.io.DatasetReader) – Opened input image dataset.
ds_out (rasterio.io.DatasetWriter) – Opened output dataset.
band (int) – Band to consider in the input dataset.
fil (numpy.ndarray) – The filter given as an array in the spatial domain.
boundary (BoundaryPad) – The edge management rule as a single value (similar for each side) or a tuple ((top, bottom), (left, right)). The rule is defined by the BoundaryPad enum.
out_mode (ConvolutionOutputMode) – The output mode for the returned array.
binary (bool, optional) – Option to save output as binary (0 or 1). Defaults to False.
binary_threshold (float, optional) – In case the binary option is activated, all values greater or equal to binary_threshold are set to 1, 0 otherwise. Defaults to 1e-3.
zoom (int or tuple, optional) –
The zoom factor. It can either be a single integer or a tuple of two integers representing the rational P/Q and given as (P, Q).

Defaults to 1.
round_out (bool, optional) – Option to round the written output to the nearest integer. Defaults to True.

Returns:

This function performs an in-place operation on ds_out and does not return any value.

Return type:

NoReturn

Notes

This function acts as a fallback when strip processing is not required or not applicable, directly calling the core fft_array_filter method.

gridr.chain.fft_filtering_chain.fft_filtering_oa_strip_chain(ds_in, ds_out, band, fil, boundary, out_mode, strip_size=512, binary=False, binary_threshold=0.001, zoom=1, round_out=True, logger=None)[source]

Compute the FFT Filtering of an opened rasterio input dataset.

The read and write operations are performed by chunks of whole rows, also called strips. This method wraps the fft_array_filtering implemented in the core.convolution.fft_filtering module.

Parameters:

ds_in (rasterio.io.DatasetReader) – Opened input image dataset.
ds_out (rasterio.io.DatasetWriter) – Opened output dataset.
band (int) – Band to consider in the input dataset.
fil (numpy.ndarray) – The filter given as an array in the spatial domain.
boundary (BoundaryPad) – The edge management rule as a single value (similar for each side) or a tuple ((top, bottom), (left, right)). The rule is defined by the BoundaryPad enum.
out_mode (ConvolutionOutputMode) – The output mode for the returned array.
strip_size (int, optional) – The chunk target number of rows. Defaults to 512.
binary (bool, optional) – Option to save output as binary (0 or 1). Defaults to False.
binary_threshold (float, optional) – In case the binary option is activated, all values greater or equal to binary_threshold are set to 1, 0 otherwise. Defaults to 1e-3.
zoom (int or tuple, optional) – The zoom factor. It can either be a single integer or a tuple of two integers representing the rational P/Q and given as (P, Q). Defaults to 1.
round_out (bool, optional) – Option to round the written output to the nearest integer. Defaults to True.
logger (logging.Logger, optional) – Python logger object to use for logging. If None, a logger is initialized internally. Defaults to None.

Returns:

Returns 1 upon successful completion of the filtering process.

Return type:

int

Notes

Input chunks do not overlap in order to limit the number of operations. The overlap-add method is used to build the whole output image with no boundary effects (see Wikipedia entry for Overlap-add method).

The two last strips are merged if the last strip does not match the defined strip size. Strips are processed sequentially.

This method directly falls back to the wrapped method depending on dataset and filter shapes. More precisely:

The input raster number of rows must be greater than twice the strip size.
The input raster number of rows must be greater than twice the filter size.

Examples

A binary option can be set to True to activate a binary output. In that case, the binary_threshold must be set to define the threshold between 0 and 1 used for the binary conversion. Please also note that the output dataset has to be opened with the correct option in order to save it as a true binary (1bit per pixel) raster.

For instance:

import rasterio
import numpy as np
from gridr.chain.enums import BoundaryPad, ConvolutionOutputMode

# Assuming ds_in is an opened rasterio dataset
file_out = "output_binary.tif"
with rasterio.open(file_out, "w",
                    driver="GTiff",
                    dtype=np.uint8,
                    height=ds_in.height,
                    width=ds_in.width,
                    count=1,
                    nbits=1) as ds_out_binary:
    fft_filtering_oa_strip_chain(
        ds_in=ds_in,
        ds_out=ds_out_binary,
        band=1,
        fil=np.ones((3, 3)), # Example filter
        boundary=BoundaryPad.REFLECT,
        out_mode=ConvolutionOutputMode.SAME,
        binary=True,
        binary_threshold=0.5
    )