Skip to content

Focal

focal_filter(raster, method='mean', size=3, shape='circle')

Apply a basic focal filter to the input raster.

Parameters:

Name Type Description Default
raster DatasetReader

The input raster dataset.

 required
method Literal[mean, median]

The method to use for filtering. Can be either "mean" or "median". Default to "mean".

 'mean'
size int

The size of the filter window. E.g., 3 means a 3x3 window. Default to 3.

 3
shape Literal[square, circle]

The shape of the filter window. Can be either "square" or "circle". Default to "circle".

 'circle'

Returns:

Type Description
tuple[ndarray, dict]

The filtered raster array.

Raises:

Type Description
InvalidRasterBandException

If the input raster has more than one band.
InvalidParameterValueException

If the filter size is smaller than 3. If the filter size is not an odd number. If the shape is not "square" or "circle".
Source code in eis_toolkit/raster_processing/filters/focal.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@beartype
def focal_filter(
    raster: rasterio.io.DatasetReader,
    method: Literal["mean", "median"] = "mean",
    size: int = 3,
    shape: Literal["square", "circle"] = "circle",
) -> tuple[np.ndarray, dict]:
    """
    Apply a basic focal filter to the input raster.

    Args:
        raster: The input raster dataset.
        method: The method to use for filtering. Can be either "mean" or "median". Default to "mean".
        size: The size of the filter window. E.g., 3 means a 3x3 window. Default to 3.
        shape: The shape of the filter window. Can be either "square" or "circle". Default to "circle".

    Returns:
        The filtered raster array.

    Raises:
        InvalidRasterBandException: If the input raster has more than one band.
        InvalidParameterValueException: If the filter size is smaller than 3.
            If the filter size is not an odd number.
            If the shape is not "square" or "circle".
    """
    _check_inputs(raster, size)

    kernel = _basic_kernel(size, shape)

    raster_array = raster.read()
    raster_array = reduce_ndim(raster_array)
    raster_array = nodata_to_nan(raster_array, raster.nodata)

    if method == "mean":
        out_array = _apply_correlated_filter(raster_array, kernel)
    elif method == "median":
        out_array = _apply_generic_filter(raster_array, _focal_median, kernel)

    out_array = nan_to_nodata(out_array, raster.nodata)
    out_array = cast_array_to_float(out_array, cast_float=True)
    out_meta = raster.meta.copy()

    return out_array, out_meta

gaussian_filter(raster, sigma=1, truncate=4, size=None)

Apply a gaussian filter to the input raster.

Parameters:

Name Type Description Default
raster DatasetReader

The input raster dataset.

 required
sigma Number

The standard deviation of the gaussian kernel.

 1
truncate Number

The truncation factor for the gaussian kernel based on the sigma value. Only if size is not given. Default to 4.0. E.g., for sigma = 1 and truncate = 4.0, the kernel size is 9x9.

 4
size Optional[int]

The size of the filter window. E.g., 3 means a 3x3 window. If size is not None, it overrides the dynamic size calculation based on sigma and truncate. Default to None.

 None

Returns:

Type Description
tuple[ndarray, dict]

The filtered raster array.

Raises:

Type Description
InvalidRasterBandException

If the input raster has more than one band.
InvalidParameterValueException

If the filter size is smaller than 3. If the filter size is not an odd number. If the resulting radius is smaller than 1.
Source code in eis_toolkit/raster_processing/filters/focal.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@beartype
def gaussian_filter(
    raster: rasterio.io.DatasetReader,
    sigma: Number = 1,
    truncate: Number = 4,
    size: Optional[int] = None,
) -> tuple[np.ndarray, dict]:
    """
    Apply a gaussian filter to the input raster.

    Args:
        raster: The input raster dataset.
        sigma: The standard deviation of the gaussian kernel.
        truncate: The truncation factor for the gaussian kernel based on the sigma value.
            Only if size is not given. Default to 4.0.
            E.g., for sigma = 1 and truncate = 4.0, the kernel size is 9x9.
        size: The size of the filter window. E.g., 3 means a 3x3 window.
            If size is not None, it overrides the dynamic size calculation based on sigma and truncate.
            Default to None.

    Returns:
        The filtered raster array.

    Raises:
        InvalidRasterBandException: If the input raster has more than one band.
        InvalidParameterValueException: If the filter size is smaller than 3.
            If the filter size is not an odd number.
            If the resulting radius is smaller than 1.
    """
    _check_inputs(raster, size, sigma, truncate)

    kernel = _gaussian_kernel(sigma, truncate, size)

    raster_array = raster.read()
    raster_array = reduce_ndim(raster_array)
    raster_array = nodata_to_nan(raster_array, raster.nodata)

    out_array = _apply_correlated_filter(raster_array, kernel)
    out_array = nan_to_nodata(out_array, raster.nodata)

    out_array = cast_array_to_float(out_array, cast_float=True)
    out_meta = raster.meta.copy()

    return out_array, out_meta

mexican_hat_filter(raster, sigma=1, truncate=4, size=None, direction='circular')

Apply a mexican hat filter to the input raster.

Circular: Lowpass filter for smoothing. Rectangular: Highpass filter for edge detection. Results may need further normalization.

Parameters:

Name Type Description Default
raster DatasetReader

The input raster dataset.

 required
sigma Number

The standard deviation.

 1
truncate Number

The truncation factor. E.g., for sigma = 1 and truncate = 4.0, the kernel size is 9x9. Default to 4.0.

 4
size Optional[int]

The size of the filter window. E.g., 3 means a 3x3 window. Default to None.

 None
direction Literal[rectangular, circular]

The direction of calculating the kernel values. Can be either "rectangular" or "circular". Default to "circular".

 'circular'

Returns:

Type Description
tuple[ndarray, dict]

The filtered raster array.

Raises:

Type Description
InvalidRasterBandException

If the input raster has more than one band.
InvalidParameterValueException

If the filter size is smaller than 3. If the filter size is not an odd number. If the resulting radius is smaller than 1.
Source code in eis_toolkit/raster_processing/filters/focal.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
@beartype
def mexican_hat_filter(
    raster: rasterio.io.DatasetReader,
    sigma: Number = 1,
    truncate: Number = 4,
    size: Optional[int] = None,
    direction: Literal["rectangular", "circular"] = "circular",
) -> tuple[np.ndarray, dict]:
    """
    Apply a mexican hat filter to the input raster.

    Circular: Lowpass filter for smoothing.
    Rectangular: Highpass filter for edge detection. Results may need further normalization.

    Args:
        raster: The input raster dataset.
        sigma: The standard deviation.
        truncate: The truncation factor.
            E.g., for sigma = 1 and truncate = 4.0, the kernel size is 9x9.
            Default to 4.0.
        size: The size of the filter window. E.g., 3 means a 3x3 window. Default to None.
        direction: The direction of calculating the kernel values.
            Can be either "rectangular" or "circular". Default to "circular".

    Returns:
       The filtered raster array.

    Raises:
        InvalidRasterBandException: If the input raster has more than one band.
        InvalidParameterValueException: If the filter size is smaller than 3.
            If the filter size is not an odd number.
            If the resulting radius is smaller than 1.
    """
    _check_inputs(raster, size, sigma, truncate)

    kernel = _mexican_hat_kernel(sigma, truncate, size, direction)

    raster_array = raster.read()
    raster_array = reduce_ndim(raster_array)
    raster_array = nodata_to_nan(raster_array, raster.nodata)

    out_array = _apply_correlated_filter(raster_array, kernel)
    out_array = nan_to_nodata(out_array, raster.nodata)

    out_array = cast_array_to_float(out_array, cast_float=True)
    out_meta = raster.meta.copy()

    return out_array, out_meta