Skip to content

Module fordead.masking_vi

Created on Fri Nov 20 17:29:17 2020

@author: Raphael Dutrieux

Functions

bdforet_paths_in_zone

def bdforet_paths_in_zone(
    example_raster,
    dep_path,
    bdforet_dirpath
)

Returns list of shapefile in the zone given by the raster, as well as the polygon extent of the raster

Parameters
----------
example_raster : xarray DataArray
    Raster from which to copy the extent and resolution for the mask
dep_path : str
    Path to shapefile containg departements with code_insee column.
bdforet_dirpath : str
    Path to directory containing IGN's BDFORET with one directory per departements.

Returns
-------
bdforet_paths : list
    List of paths to BDFORET shapefiles of departements intersecting the example_raster
tile_extent : geopandas GeoDataFrame
    Polygon of the extent of the example_raster

clip_oso

def clip_oso(
    path_oso,
    path_example_raster,
    list_code_oso
)

Creates binary mask from CESBIO's soil occupation map (http://osr-cesbio.ups-tlse.fr/~oso/) by clipping it using a given raster's extent and filtering on listed values.

Parameters
----------
path_oso : str
    Path to CESBIO's OSO map.
path_example_raster : str
    Path to raster used for clipping.
list_code_oso : list
    List of codes used for filtering

Returns
-------
forest_mask : xarray DataArray
    Boolean DataArray containing True where pixels's values in CESBIO's OSO map are in the list list_code_oso.

compute_masks

def compute_masks(
    stack_bands,
    soil_data,
    date_index
)

Computes mask from SENTINEL data, includes updated soil detection, clouds, shadows and pixels outside swath

Parameters
----------
stack_bands : xarray DataArray
    3D xarray with band dimension
soil_data : xarray DataSet
    DataSet where variable "state" is True where pixels are detected as cut, variable "count" gives the number of successive soil anomalies, and "first_date" gives the date index of the first anomaly
date_index : int
    Index of the date

Returns
-------
mask : xarray DataArray
    Binary DataArray, holds True where pixels are masked

compute_user_mask

def compute_user_mask(
    stack_bands,
    formula_mask
)

Compute mask from single date SENTINEL data, using a logical operation formula involving Sentinel-2 bands, as well as two default masks:
    any negative value in the first band of the stack is considered outside the satellite swath and masked
    any pixel with a 0 value in any band is considered a shadow and masked

Parameters
----------
stack_bands : xarray DataArray
    3D xarray with band dimension
formula_mask : str
    Logical operation involving Sentinel-2 bands, which can be named as B2, B3 etc... as well as B02, B03 and so on. See [compute_vegetation_index()](https://fordead.gitlab.io/fordead_package/reference/fordead/masking_vi/#compute_vegetation_index) for details.
Returns
-------
mask : xarray DataArray
    Binary DataArray, holds True where pixels are masked. Is an aggregation of user defined mask, shadows and outside swath masks.

compute_vegetation_index

def compute_vegetation_index(
    reflectance,
    vi='CRSWIR',
    formula=None,
    path_dict_vi=None
)

Computes vegetation index

Parameters
----------
reflectance : xarray DataArray or pandas DataFrame
    3D xarray with band dimension or pandas Dataframe with bands as attributes 
vi : str, optional
    Name of vegetation index, see get_dict_vi documentation to know available vegetation indices. A formula can be given instead The default is "CRSWIR".
formula : str, optional
    Formula used to calculate the vegetation index. Bands can be called by their name. All operations on xarrays and using numpy functions are possible.
    Examples :
        NDVI : formula = '(B8-B4)/(B8+B4)'
        Squared-root of B2 : formula = 'np.sqrt(B2)'
        Logical operations :  formula = '(B2 > 600) & (B11 > 1000) | ~(B3 <= 500)'
        The default is None.
path_dict_vi : str, optional
    Path to a text file containing vegetation indices formulas so they can be used using 'vi' parameter. See get_dict_vi documentation. The default is None.

Returns
-------
xarray DataArray
    Computed vegetation index

detect_clouds

def detect_clouds(
    stack_bands,
    soil_state,
    soil_anomaly
)

Detects clouds, is meant to detect even faint clouds in resinous forest by removing detected soil and using a 3 pixels dilation

Parameters
----------
stack_bands : xarray DataArray
    3D xarray with band dimension
soil_state : xarray DataArray
    DataArray which holds True where pixels are detected as cut
soil_anomaly : xarray DataArray
    Binary DataArray, holds True where soil anomalies are detected

Returns
-------
clouds : xarray DataArray
    Binary DataArray mask, holds True where clouds are detected

detect_soil

def detect_soil(
    soil_data,
    soil_anomaly,
    invalid,
    date_index
)

Updates soil detection using soil anomalies from a new date

Parameters
----------
soil_data : xarray DataSet
    DataSet where variable "state" is True where pixels are detected as cut, variable "count" gives the number of successive soil anomalies, and "first_date" gives the date index of the first anomaly
soil_anomaly : xarray DataArray
    Binary DataArray, holds True where soil anomalies are detected
invalid : xarray DataArray
    Binary DataArray, aggregates shadows, very visible clouds and pixels outside swath
date_index : int
    Index of the date

Returns
-------
soil_data : xarray DataSet
    Updated soil_data DataSet

get_bands_and_formula

def get_bands_and_formula(
    vi='CRSWIR',
    formula=None,
    path_dict_vi=None,
    forced_bands=[]
)

From the vegetation index used, infers which bands are necessary. Formula of vegetation index is also returned. A list of bands which are also necessary can be added.

Parameters
----------
vi : str
    Name of vegetation index, see get_dict_vi documentation to know available vegetation indices. A formula can be given instead The default is "CRSWIR".
formula : str
    Formula as can be used in the function [compute_vegetation_index](https://fordead.gitlab.io/fordead_package/reference/fordead/masking_vi/#compute_vegetation_index)
path_dict_vi : str, optional
    Path of the text file. 
    Each line of the text file corresponds to an index, in the format "INDEX_NAME FORMULA SIGN".
    FORMULA corresponds to a formula as can be used in the function compute_vegetation_index, SIGN can be - or +. The default is None.
forced_bands : list, optional
    List of bands which will be added to the returned band list whether or not they are used in the vegetation index formula. The default is [].

Returns
-------
bands : list
    List of bands used to calculate the vegetation index, along with the bands added through forced_bands
formula : str
    Formula of the vegetation index as found in the path_dict_vi file, and as used in compute_vegetation_index function.

get_dict_vi

def get_dict_vi(
    path_dict_vi=None
)

Imports dictionnary containing formula of vegetation indices, as well as the way it changes in case of dieback
CRSWIR, NDVI, BSI and NDWI can be used without specifying the formulas in a path_dict_vi text file.
Parameters
----------
path_dict_vi : str, optional
    Path of the text file. 
    Each line of the text file corresponds to an index, in the format "INDEX_NAME FORMULA SIGN".
    FORMULA corresponds to a formula as can be used in the function compute_vegetation_index, SIGN can be - or +. The default is None.

Returns
-------
dict_vi : dict
    Dictionnary containing formula of vegetation indices, as well as the way it changes in case of dieback

get_pre_masks

def get_pre_masks(
    stack_bands
)

Compute pre-masks from single date SENTINEL data

Parameters
----------
stack_bands : xarray DataArray
    3D xarray with band dimension

Returns
-------
soil_anomaly : xarray DataArray
    Binary DataArray, holds True where soil anomalies are detected
shadows : xarray DataArray
    Binary DataArray, holds True where shadows are detected
outside_swath : xarray DataArray
    Binary DataArray, holds True where pixels are outside swath
invalid : xarray DataArray
    Binary DataArray, aggregates shadows, very visible clouds and pixels outside swath

get_source_mask

def get_source_mask(
    band_paths,
    sentinel_source,
    extent=None
)

Imports source mask and converts it to binary. Keeps only 0 in THEIA mask, and only 4 and 5 in Scihub and PEPS mask.

Parameters
----------
band_paths : dict
    Dictionnary where keys are band names, and values are their paths.
sentinel_source : str
    Sentinel source (THEIA, Scihub or PEPS).
extent : list or 1D array, optional
    Extent used for cropping [xmin,ymin, xmax,ymax]. If None, there is no cropping. The default is None.

Returns
-------
binary_mask : xarray DataArray
    Binary array with value 1 when pixel is masked.

raster_full

def raster_full(
    path_example_raster,
    fill_value,
    dtype=None
)

Creates a raster with extent, resolution and projection system corresponding to a given raster, filled with a single value.

Parameters
----------
path_example_raster : str
    Path to raster used as a model.
fill_value : int or float
    Value used to fill the raster
dtype : type, optional
    Type of the fill_value. The default is None.

Returns
-------
filled_raster : xarray DataArray
    Raster filled with a single value.

rasterize_bdforet

def rasterize_bdforet(
    example_path,
    dep_path,
    bdforet_dirpath,
    list_forest_type=['FF2-00-00', 'FF2-90-90', 'FF2-91-91', 'FF2G61-61']
)

Creates forest mask from IGN's BDFORET

Parameters
----------
example_path : str
    Path to a raster from which to copy the extent and resolution for the mask
dep_path : str
    Path to shapefile containg departements with code_insee column.
bdforet_dirpath : str
    Path to directory containing IGN's BDFORET with one directory per departements.
list_forest_type : list, optional
    List of forest types to be kept in the forest mask, corresponds to the CODE_TFV of the BDFORET. The default is ["FF2-00-00", "FF2-90-90", "FF2-91-91", "FF2G61-61"].

Returns
-------
forest_mask : xarray DataArray
    Boolean DataArray containing True where pixels are in the selected forest types.

rasterize_polygons_binary

def rasterize_polygons_binary(
    polygons,
    example_raster
)

Rasterizes polygons into binary raster

Parameters
----------
polygons : geopandas GeoDataFrame
    Polygons to rasterize
example_raster : xarray DataArray
    Raster from which to copy the extent and resolution and crs for the mask

Returns
-------
forest_mask : xarray DataArray
    Boolean DataArray containing True where pixels are inside the polygons.

rasterize_vector

def rasterize_vector(
    vector_path,
    example_path
)

Creates binary raster mask from a vector, such as a shapefile containing polygons

Parameters
----------
vector_path : str
    Path to a vector containing polygons delimiting the areas of interest
example_path : str
    Path to a raster from which to copy the extent and resolution for the mask

Returns
-------
forest_mask : xarray DataArray
    Boolean DataArray containing True where pixels are in the polygons with the vector file.