deeptrees.modules

deeptrees.modules.indices

deeptrees.modules.indices.gci(raster, red_idx=0, green_idx=1, nir_idx=3, axis=0)

Calculate Green Chlorophyll Index (GCI). GCI = (NIR / GREEN) - 1

deeptrees.modules.indices.hue(raster, red_idx=0, green_idx=1, blue_idx=2, axis=0)

Calculate hue from RGB.

deeptrees.modules.indices.ndvi(raster, red_idx=0, nir_idx=3, axis=0)

Calculate Normalized Difference Vegetation Index (NDVI). NDVI = (NIR - RED) / (NIR + RED)

deeptrees.modules.indices.ndvi_xarray(img, red, nir)

Calculates the Normalized Difference Vegetation Index (NDVI) from a given image.

NDVI is calculated using the formula: (NIR - Red) / (NIR + Red + 1E-10). The input image bands are implicitly converted to Float32 for the calculation.

Parameters: img (xarray.DataArray): The input image as an xarray DataArray. red (int or str): The band index or name corresponding to the red band. nir (int or str): The band index or name corresponding to the near-infrared (NIR) band.

Returns: xarray.DataArray: The NDVI values as an xarray DataArray.

deeptrees.modules.losses

class deeptrees.modules.losses.BinarySegmentationLoss(iou_weight=0.5, **kwargs)

Bases: _Loss

Combines binary cross entropy loss with -log(iou). Works with probabilities, so after applying sigmoid activation.

__init__(iou_weight=0.5, **kwargs)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(y_pred, y_true)

Computes the custom loss function which is a combination of Binary Cross-Entropy (BCE) loss and Intersection over Union (IoU) loss. Parameters: ———– y_pred : torch.Tensor

The predicted output tensor from the model. It should have the same shape as y_true.

y_truetorch.Tensor

The ground truth tensor. It should have the same shape as y_pred.

Returns:

torch.Tensor

The computed loss value which is a weighted sum of BCE loss and the negative logarithm of IoU.

Notes:

• The BCE loss is weighted by (1 - self.iou_weight).

• The IoU loss is weighted by self.iou_weight and is computed as the negative logarithm of the IoU.

• Ensure that iou function is defined and computes the Intersection over Union correctly.

class deeptrees.modules.losses.BinarySegmentationLossWithLogits(iou_weight=0.5, **kwargs)

Bases: _Loss

Combines binary cross entropy loss with -log(iou). Works with logits - don’t apply sigmoid to your network output.

__init__(iou_weight=0.5, **kwargs)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(y_pred, y_true)

Computes the loss by combining Binary Cross-Entropy (BCE) loss and Intersection over Union (IoU) loss. :type y_pred: torch.Tensor :param y_pred: The predicted output tensor from the model. This tensor typically contains

the predicted probabilities for each class.

Parameters:

y_true (torch.Tensor) – The ground truth tensor. This tensor contains the actual class labels.

Returns:

The computed loss value which is a combination of BCE loss and IoU loss.

Return type:

torch.Tensor

The loss is calculated as follows: 1. Compute the BCE loss between the predicted and true values. 2. Compute the IoU loss between the predicted and true values. 3. Combine the two losses using the iou_weight attribute to balance their contributions. .. note:

- The `iou_weight` attribute should be defined in the class to control the balance between BCE and IoU losses.
- The `bceloss` method should be defined in the class to compute the BCE loss.
- The `iou_with_logits` function should be defined to compute the IoU loss with logits.

deeptrees.modules.metrics

deeptrees.modules.metrics.iou(y_pred, y_true)

Calculate the Intersection over Union (IoU) between two tensors. The IoU is a measure of the overlap between two sets, defined as the intersection divided by the union of the sets. It is commonly used in image segmentation tasks to evaluate the accuracy of predictions. :type y_pred: torch.Tensor :param y_pred: Predicted tensor, typically a binary mask. :type y_pred: torch.Tensor :type y_true: torch.Tensor :param y_true: Ground truth tensor, typically a binary mask. :type y_true: torch.Tensor

Returns:

The IoU score, a value between 0 and 1, where 1 indicates

perfect overlap and 0 indicates no overlap.

Return type:

float

Note

• The function uses a small epsilon value to avoid division by zero.

• Both input tensors should have the same shape.

• The tensors are expected to be of type torch.float32.

deeptrees.modules.metrics.iou_with_logits(y_pred, y_true)

Compute the Intersection over Union (IoU) score with logits. This function applies a sigmoid activation to the predicted logits and then calculates the IoU score between the predicted and true values. :type y_pred: torch.Tensor :param y_pred: The predicted logits tensor. This tensor should contain raw, unnormalized scores. :type y_pred: torch.Tensor :type y_true: torch.Tensor :param y_true: The ground truth binary tensor. This tensor should contain binary values (0 or 1). :type y_true: torch.Tensor

Returns:

The IoU score between the predicted and true values.

Return type:

float

Example

>>> y_pred = torch.tensor([[0.8, 0.4], [0.3, 0.9]])
>>> y_true = torch.tensor([[1, 0], [0, 1]])
>>> iou_score = iou_with_logits(y_pred, y_true)
>>> print(iou_score)

deeptrees.modules.polygon_metrics

deeptrees.modules.polygon_utils

deeptrees.modules.postprocessing

deeptrees.modules.rasterize_utils

Utils for creating ground truth raster files from polygons.

deeptrees.modules.rasterize_utils.filter_geometry(polygons, valid_classes='all', class_column_name='class')

Filter the provided polygons by keeping only valid classes.

Parameters:

• polygons (gpd.GeoDataFrame) – GeoDataFrame containing the polygons and class labels.

• valid_classes (Union[str, list]) – List of valid class labels. Defaults to ‘all’ (use all classes).

• class_column_name (str) – Column name of class labels in src. Defaults to ‘class’.

Returns:

filtered list of Polygons

Return type:

list[Polygon]

deeptrees.modules.rasterize_utils.get_bbox_polygon(input_file)

Get the Polygon representing the bounding box of the tile in input_file

Parameters:

input_file (str) – path to input file

Returns:

bounding box polygon

Return type:

Polygon

deeptrees.modules.rasterize_utils.get_xarray_trafo(arr)

Returns xmin, xmax, ymin, ymax, xres, yres of an xarray. xres and yres can be negative.

deeptrees.modules.rasterize_utils.rasterize(source_raster, features, dim_ordering='HWC')

Rasterizes the features (polygons/lines) within the extent of the given xarray with the same resolution, all in-memory.

Parameters:

• source_raster – Xarray

• features (list) – List of shapely objects

• dim_ordering (str) – One of CHW (default) or HWC (height, widht, channels)

Returns:

Rasterized features

deeptrees.modules.rasterize_utils.to_outline(polygons)

Parameters:

polygons (list[Polygon]) – list of polygons

Returns:

TODO type list of boundaries of the polygons

Return type:

_type_

deeptrees.modules.rasterize_utils.xarray_trafo_to_gdal_trafo(xarray_trafo)

deeptrees.modules.traits

deeptrees.modules.traits.chlorophyll_index(red, green, nir, save_to=None)

Calculate the Chlorophyll Index-Green (CIG) from the given bands. The Chlorophyll Index Green (CIG) is defined as (NIR/Green)-1. Parameters: red (numpy.ndarray): The red band values. green (numpy.ndarray): The green band values. nir (numpy.ndarray): The near-infrared (NIR) band values. save_to (str): The file path to save the calculated GCI values as a CSV file. Default is None. Returns: numpy.ndarray: The calculated Chlorophyll Index (CIG) values.

deeptrees.modules.traits.green_chlorophyll_index(red, green, nir, save_to=None)

Calculate the Green Chlorophyll Index (GCI) from the given bands. The Green Chlorophyll Index (GCI) is defined as (NIR-Green)/(NIR+Green). Parameters: red (numpy.ndarray): The red band values. green (numpy.ndarray): The green band values. nir (numpy.ndarray): The near-infrared (NIR) band values. save_to (str): The file path to save the calculated GCI values as a CSV file. Default is None. Returns: numpy.ndarray: The calculated Green Chlorophyll Index (GCI) values.

deeptrees.modules.traits.hue_index(red, green, blue, save_to=None)

Calculate the Hue Index from the given bands. The Hue Index is defined as arctan((2*green - red - blue) / sqrt(3) * (red - blue)). Parameters: red (numpy.ndarray): The red band values. green (numpy.ndarray): The green band values. blue (numpy.ndarray): The blue band values. save_to (str): The file path to save the calculated Hue Index values as a CSV file. Default is None. Returns: numpy.ndarray: The calculated Hue Index values.

deeptrees.modules.traits.longest_cross_spread(polygon)

Calculate the longest cross spread of a given polygon. The longest cross spread is defined as the maximum distance between two points on the polygon’s boundary that are perpendicular to the longest spread line of the polygon. Parameters: polygon (shapely.geometry.Polygon): The input polygon for which the longest cross spread is calculated. Returns: tuple: A tuple containing:

• max_cross_distance (float): The maximum cross distance found.

• cross_point_pair (tuple): A tuple of two shapely.geometry.Point objects representing the endpoints of the longest cross spread. If the polygon is None or invalid, or if no valid cross spread is found, returns (None, None).

deeptrees.modules.traits.longest_spread(polygon)

Calculate the longest distance between any two points on the exterior of a polygon. Parameters: polygon (shapely.geometry.Polygon): A shapely Polygon object. If the polygon is None or not a valid polygon, the function returns (None, None). Returns: tuple: A tuple containing the maximum distance (float) and the pair of points (tuple of shapely.geometry.Point) that are farthest apart.

If the polygon is invalid, returns (None, None).

deeptrees.modules.utils

deeptrees.modules.utils.array_to_tif(array, dst_filename, num_bands='multi', save_background=True, src_raster='', transform=None, crs=None)

Takes a numpy array and writes a tif. Uses deflate compression.

Parameters:

• array (np.ndarray) – Numpy array.

• dst_filename (str) – Destination file name/path.

• num_bands (str) – ‘single’ or ‘multi’. If ‘single’ is chosen, everything is saved into one layer.

• save_background (bool) – Whether or not to save the last layer, which is often the background class.

• src_raster (str) – Raster file used to determine the corner coords.

• transform – A geotransform in the gdal format.

• crs – A coordinate reference system as proj4 string.

deeptrees.modules.utils.calc_band_stats(fpath)

Calculates the mean and standard deviation of each band in a raster file.

Parameters:

fpath (str) – Path to the raster file.

Returns:

A dictionary containing the mean and standard deviation of each band.

Return type:

dict

deeptrees.modules.utils.compute_pyramid_patch_weight_loss(width, height)

Compute a weight matrix that assigns bigger weight on pixels in center and less weight to pixels on image boundary. This weight matrix is then used for merging individual tile predictions and helps dealing with prediction artifacts on tile boundaries.

Parameters:

• width (int) – Tile width.

• height (int) – Tile height.

Returns:

The weight mask.

Return type:

np.ndarray

deeptrees.modules.utils.create_batch_of_patches(input_tensor, patch_size, patch_ixs, offset, local_batch_size)

Helper function to create a batch of small patches.

Parameters:

• input_tensor (torch.Tensor) – Original input tensor.

• patch_size (int) – Small patch size.

• patch_ixs (list) – List of tuples specifying (x_start, y_start) for the small patches in the input tensor.

• offset (int) – Offset of current batch in patch_ixs.

• local_batch_size (int) – Size of the batch of small patches.

Returns:

One batch of small patches to be used in inference.

Return type:

torch.Tensor

deeptrees.modules.utils.dilate_img(img, size=10, shape='square')

Dilates an image using a specified structuring element.

Parameters:

• img (np.ndarray) – The input image.

• size (int) – The size of the structuring element.

• shape (str) – The shape of the structuring element (‘square’ or ‘disk’).

Returns:

The dilated image.

Return type:

np.ndarray

deeptrees.modules.utils.extent_to_poly(xarr)

Returns the bounding box of an xarray as a shapely polygon.

Parameters:

xarr – The xarray.

Returns:

The bounding box polygon.

Return type:

Polygon

deeptrees.modules.utils.gdal_trafo_to_xarray_trafo(gdal_trafo)

Converts a GDAL transform to an xarray transform.

Parameters:

gdal_trafo – The GDAL transform.

Returns:

The xarray transform.

Return type:

tuple

deeptrees.modules.utils.get_crs(array)

Retrieves the CRS from an xarray.

Parameters:

array (xarray.DataArray) – The input xarray.

Returns:

The CRS.

Return type:

dict

deeptrees.modules.utils.get_map_extent(gdal_raster)

Returns a dict of {xmin, xmax, ymin, ymax, xres, yres} of a given GDAL raster file. Returns None if no geo reference was found.

Parameters:

gdal_raster – File opened via gdal.Open().

Returns:

A dictionary containing the map extent.

Return type:

dict

deeptrees.modules.utils.get_rioxarray_trafo(arr)

Get the transform from a raster tile.

Parameters:

arr (xarray.DataArray) – Raster tile.

Returns:

The transform of the raster tile.

Return type:

tuple

deeptrees.modules.utils.get_xarray_extent(arr)

Returns the extent of an xarray.

Parameters:

arr – The xarray.

Returns:

The extent of the xarray.

Return type:

tuple

deeptrees.modules.utils.get_xarray_trafo(arr)

Returns the transform of an xarray.

Parameters:

arr – The xarray.

Returns:

The transform of the xarray.

Return type:

tuple

deeptrees.modules.utils.gpu(x, device='cuda', dtype=torch.float32)

Moves a tensor to the GPU if available.

Parameters:

• x (torch.Tensor) – The tensor to move.

• device (str) – The device to move the tensor to.

• dtype (torch.dtype) – The data type of the tensor.

Returns:

The tensor on the specified device.

Return type:

torch.Tensor

deeptrees.modules.utils.load_filtered_polygons(file, rasters, minimum_area=0, maximum_area=1000000, filter_dict={}, operators=[<built-in function eq>])

Loads those polygons from a given shapefile which fit into the extents of the given rasters.

Polygons will be cropped to fit the given raster extent.

Parameters:

• file (str) – Shapefile path.

• rasters (list) – List of xarrays.

• minimum_area (float) – Minimum polygon area in map units (typically m²), measured after cropping to extent.

• maximum_area (float) – Maximum polygon area in map units (typically m²), measured after cropping to extent.

• filter_dict (dict) – Dictionary of key value pairs to filter polygons by.

• operators (list) – A list of built-in python comparison operators from the ‘operator’ package.

Returns:

A list of lists containing polygons in the same order as the rasters.

Return type:

list

deeptrees.modules.utils.load_model_weights(model, path)

Loads the models weights and sets the batch norm momentum to 0.9.

Parameters:

• model – The model to load weights into.

• path (str) – Path to the weights file.

Returns:

The model with loaded weights.

deeptrees.modules.utils.mask_and_save_individual_trees(tiff_path, polygons, output_dir, scale_factor=1)

Masks and optionally scales raster images based on given polygons.

Parameters:

• tiff_path (str) – Path to the input GeoTIFF file.

• polygons (list) – A list of shapely geometries (polygons).

• output_dir (str) – Directory to save the masked raster files.

• scale_factor (int) – Factor by which to scale the output raster dimensions.

deeptrees.modules.utils.overlay_heatmap(image, entropy_map, output_path, filename)

Overlay an entropy heatmap on top of the image and save the result.

Parameters: - image: Original image (as a NumPy array or PIL image). - entropy_map: 2D array representing the entropy values. - output_path: Path to save the overlaid image. - filename: Name of the file to save the overlaid image.

deeptrees.modules.utils.predict_on_array(model, arr, in_shape, out_bands, stride=None, drop_border=0, batchsize=64, dtype='float32', device='cuda', augmentation=False, no_data=None, verbose=False, report_time=False)

Applies a pytorch segmentation model to an array in a strided manner.

Call model.eval() before use!

Parameters:

• model – Pytorch model - make sure to call model.eval() before using this function!

• arr (np.ndarray) – HWC array for which the segmentation should be created.

• in_shape (tuple) – Input shape.

• out_bands (int) – Number of output bands.

• stride (int) – Stride with which the model should be applied. Default: output size.

• drop_border (int) – Number of pixels to drop from the border.

• batchsize (int) – Number of images to process in parallel.

• dtype (str) – Desired output type (default: float32).

• device (str) – Device to run on (default: cuda).

• augmentation (bool) – Whether to average over rotations and mirrorings of the image or not.

• no_data – A no-data value. It’s used to compute the area containing data via the first input image channel.

• verbose (bool) – Whether or not to display progress.

• report_time (bool) – If true, returns (result, execution time).

Returns:

An array containing the segmentation.

Return type:

np.ndarray

deeptrees.modules.utils.predict_on_array_cf(model, arr, in_shape, out_bands, stride=None, drop_border=0, batchsize=64, dtype='float32', device='cuda', augmentation=False, no_data=None, verbose=False, aggregate_metric=False)

Applies a pytorch segmentation model to an array in a strided manner.

Channels first version.

Call model.eval() before use!

Parameters:

• model – Pytorch model - make sure to call model.eval() before using this function!

• arr (np.ndarray) – CHW array for which the segmentation should be created.

• in_shape (tuple) – Input shape.

• out_bands (int) – Number of output bands.

• stride (int) – Stride with which the model should be applied. Default: output size.

• drop_border (int) – Number of pixels to drop from the border.

• batchsize (int) – Number of images to process in parallel.

• dtype (str) – Desired output type (default: float32).

• device (str) – Device to run on (default: cuda).

• augmentation (bool) – Whether to average over rotations and mirrorings of the image or not.

• no_data – A no-data vector. Its length must match the number of layers in the input array.

• verbose (bool) – Whether or not to display progress.

• aggregate_metric (bool) – If true, returns (result, metric).

Returns:

A dict containing result, time, nodata_region and time.

Return type:

dict

deeptrees.modules.utils.predict_on_tile(model, input_tensor, patch_size=256, local_batch_size=32, stride=128)

Predict on a single tile of arbitrary dimension.

The tile is split into smaller patches that satisfy the criterion given by the segmentation model that edge length must be divisible by 32. The stride parameter controls the overlap of these small patches. Inference is run on all small patches in a memory-efficient way. The output is collected and weighted with the pyramid weight function to reduce artefacts where the patches overlap.

The output tensor contains mask, outline, and distance transform in the same shape as the input tensor.

Parameters:

• model – Trained DeepTrees model.

• input_tensor (torch.Tensor) – Tensor with the values of the raster tile.

• patch_size (int, optional) – Patch size used in inference. Defaults to 256.

• local_batch_size (int, optional) – Length of the batch of patches. Defaults to 32.

• stride (int, optional) – Apply patches in a strided manner. Defaults to 128.

Returns:

Model output for the input raster.

Return type:

torch.Tensor

deeptrees.modules.utils.read_img(input_file, dim_ordering='HWC', dtype='float32', band_mapping=None, return_extent=False)

Reads an image from disk and returns it as numpy array.

Parameters:

• input_file (str) – Path to the input file.

• dim_ordering (str) – One of HWC or CHW, C=Channels, H=Height, W=Width.

• dtype (str) – Desired data type for loading, e.g. np.uint8, np.float32.

• band_mapping (dict) – Dictionary of which image band to load into which array band.

• return_extent (bool) – Whether or not to return the raster extent in the form (ymin, ymax, xmin, xmax).

Returns:

Numpy array containing the image and optionally the extent.

Return type:

np.ndarray

deeptrees.modules.utils.save_polygons(polygons, dest_fname, crs, driver='SQLite', mode='w')

Save a list of polygons into a shapefile with given coordinate reference system.

Parameters:

• polygons (list) – List of shapely polygons to save.

• dest_fname (str) – Path to file.

• crs – Coordinate reference system, e.g. from fiona.crs.from_epsg().

• driver (str) – One of fiona’s supported drivers e.g. ‘ESRI Shapefile’ or ‘SQLite’.

• mode (str) – Either ‘w’ for write or ‘a’ for append. Not all drivers support both.

deeptrees.modules.utils.set_batchnorm_momentum(model, momentum)

Set the momentum for all BatchNorm layers in the given model.

Parameters:

• model – The model (either scripted or non-scripted) where batchnorm layers are modified.

• momentum – The momentum value to set for the BatchNorm layers.

deeptrees.modules.utils.write_info_file(path, **kwargs)

Writes key-value pairs to a file.

Parameters:

• path (str) – The path to the file.

• **kwargs – Key-value pairs to write to the file.

deeptrees.modules.utils.xarray_trafo_to_gdal_trafo(xarray_trafo)

Converts an xarray transform to a GDAL transform.

Parameters:

xarray_trafo – The xarray transform.

Returns:

The GDAL transform.

Return type:

tuple

Contents