Aggregator

class geodataset.aggregator.Aggregator(output_path, polygons_gdf, scores_names, other_attributes_names, scores_weights, tiles_extent_gdf, tile_ids_to_path, scores_weighting_method='weighted_geometric_mean', min_centroid_distance_weight=None, score_threshold=0.1, nms_threshold=0.8, nms_algorithm='iou', edge_band_buffer_percentage=0.05, best_geom_keep_area_ratio=0.5, pre_aggregated_output_path=None)

Bases: object

Class to aggregate polygons from multiple tiles, with different pixel coordinate systems, into a single GeoDataFrame with a common CRS, applying the Non-Maximum Suppression (NMS) algorithm.

This class should be instantiated using the ‘from_coco’ or ‘from_polygons’ class methods.

SUPPORTED_NMS_ALGORITHMS = ['iou', 'ioa-disambiguate']

SUPPORTED_SCORE_WEIGHTING_METHODS = ['weighted_arithmetic_mean', 'weighted_geometric_mean', 'weighted_harmonic_mean']

classmethod from_coco(polygon_type, output_path, tiles_folder_path, coco_json_path, scores_names=None, other_attributes_names=None, scores_weights=None, scores_weighting_method='weighted_geometric_mean', min_centroid_distance_weight=None, score_threshold=0.1, nms_threshold=0.8, nms_algorithm='iou', edge_band_buffer_percentage=0.05, best_geom_keep_area_ratio=0.5, pre_aggregated_output_path=None)

Instanciate and run an Aggregator from a COCO JSON file. The polygons will be read from the coco_json_path, and the tiles will be read from the tiles_folder_path.

Parameters:

• polygon_type (str) – The type of polygons to aggregate. Supported values are [‘bbox’, ‘segmentation’].

• output_path (str or Path) – The filename where to save the aggregated polygons. ‘.gpkg’, ‘.geojson’ are supported, as well as ‘.json’ for COCO format.

• tiles_folder_path (str or Path) – The folder where the tiles are stored.

• coco_json_path (str or Path) – The path to the COCO JSON file.

• scores_names (List[str]) –

  The names of the attributes in the COCO file annotations which should be used as scores. The code will look directly in the COCO annotations for these keys, and will also look in the ‘other_attributes’ key if the key is not found directly in the annotation.

  For example, if score_names = [‘detection_score’], the ‘detection_score’ attribute can be in 2 different places in each COCO annotation:

  "annotations": [
      {
          "id": 1,
          "image_id": 1,
          "category_id": 1,
          "segmentation": {
              "counts": "eNpjYBBgUD8rgjQmInZMmB0A",
              "size": [224, 224]
          },
          "area": 10000.0,
          "bbox": [100.0, 100.0, 100.0, 100.0],
          "iscrowd": 0,
          "detection_score": 0.8      # <- directly in the annotation
          "other_attributes": {
              "detection_score": 0.8  # <- in the 'other_attributes' key
          }
      },
      ...
  ]
  

• other_attributes_names (List[str]) – The names of the attributes in the COCO file annotations which should be kept in the output result (but won’t be used by the Aggregator itself). Same structure than “scores_names”.

• scores_weights (List[float]) –

  The weights to apply to each score set. The scores_weights should sum to 1 and there should be as many

  weights as there are scores_names. See the ‘scores_weighting_method’ parameter for more details.

• scores_weighting_method (str) –

  The method to use to weight the different sets of scores. Supported values are [‘weighted_arithmetic_mean’, ‘weighted_geometric_mean’, ‘weighted_harmonic_mean’].

  • ’weighted_arithmetic_mean’: The scores are simply averaged, but each score is weighted by its weight.

  • ’weighted_geometric_mean’: The scores are multiplied, but each score is weighted by its weight.

  • ’weighted_harmonic_mean’: The scores are averaged, but each score is weighted by its reciprocal.

• min_centroid_distance_weight (float or None) –

  The weight to apply to the polygon scores (after applying the scores_weights) based on the distance

  between the polygon centroid and its tile centroid. The smaller the value of min_centroid_distance_weight, the smaller the score will be for polygons at the edge of the tile.

• score_threshold (float) – The score threshold under which polygons will be removed, before applying the NMS algorithm.

• nms_threshold (float) –

  The threshold for the Non-Maximum Suppression algorithm. It serves different purposes depending on the ‘nms_algorithm’ chosen:

  • ’iou’: The threshold is used as the regular Intersection Over Union (IoU) threshold. If 2 polygons have an IoU above this threshold, the one with the lowest score will be removed.

  • ’ioa-disambiguate’: This is the threshold used to determine if a lesser-scored polygon should be

  discarded (entirely removed), or cut to remove its portion that overlaps with another higher-scored polygon. The equation is a bit different than IoU: it’s the area of the intersection divided by the area of the lesser-scored polygon (Intersection / Area_lower_scored_polygon).

• nms_algorithm (str) –

  The Non-Maximum Suppression algorithm to use. Supported values are [‘iou’ and ‘ioa-disambiguate’].

  • ’iou’: This algorithm uses the Intersection Over Union (IoU) to suppress overlapping polygons.

  • ’ioa-disambiguate’: Shouldn’t be used for detection bounding boxes, it was designed for instance segmentations. In addition to using IoU, this algorithm attempts to disambiguate overlapping polygons by cutting the intersecting parts and keeping only the largest resulting geometry, as long as it meets the best_geom_keep_area_ratio threshold.

• edge_band_buffer_percentage (float) – The percentage of the tile width/height to consider as an edge band. The polygons that intersect with this band will be removed before applying the NMS algorithm.

• best_geom_keep_area_ratio (float) – Only used when nms_algorithm is set to ‘ioa-disambiguate’. When removing part of a polygon due to the intersection with another one, that polygon may end-up being cut into multiple smaller and disconnected geometries. The algorithm will only consider keeping the largest of those geometries, and only keep it if it makes up at least ‘best_geom_keep_area_ratio’ percent of the original polygon (in terms of area).

• pre_aggregated_output_path (str or Path) – If provided, the polygons will be saved in this file before applying the NMS algorithm. This is useful to debug the polygons before the NMS algorithm is applied.

Return type:

Aggregator

classmethod from_gdf(output_path, gdf, tiles_paths_column, polygons_column, scores_column=None, other_attributes_columns=None, scores_weights=None, scores_weighting_method='weighted_geometric_mean', min_centroid_distance_weight=None, score_threshold=0.1, nms_threshold=0.8, nms_algorithm='iou', edge_band_buffer_percentage=0.05, best_geom_keep_area_ratio=0.5, pre_aggregated_output_path=None)

Instantiate and run an Aggregator from a GeoDataFrame containing polygon annotations. The GeoDataFrame may or may not have a CRS. If a CRS is not defined, it is assumed that the polygon coordinates are in pixel space and the method will call _prepare_polygons to convert them into CRS coordinates (using the tile file’s affine transform).

Parameters:

• output_path (str or Path) – The filename where to save the aggregated polygons. Supported extensions are ‘.gpkg’, ‘.geojson’ (spatial outputs) or ‘.json’ (COCO format).

• gdf (gpd.GeoDataFrame) – A GeoDataFrame where each row represents one polygon annotation.

• tiles_paths_column (str) – The name of the column in gdf that contains the tile (image) file path.

• polygons_column (str) – The name of the column in gdf that contains the polygon geometry.

• scores_column (str or List[str] or None, optional) – The column name(s) in gdf that contain score values for each polygon. If None, defaults to [‘score’].

• other_attributes_columns (List[str] or None, optional) – A list of additional column names in gdf to be included in the output.

• scores_weights (List[float] or None, optional) – The weights to apply to each score column. The weights should sum to 1. If None, equal weights will be used.

• scores_weighting_method (str, optional) – The method used to weight the different scores. Supported methods are ‘weighted_arithmetic_mean’, ‘weighted_geometric_mean’, and ‘weighted_harmonic_mean’.

• min_centroid_distance_weight (float or None) – The weight to adjust polygon scores based on the distance between the polygon centroid and the tile centroid.

• score_threshold (float) – The score threshold below which polygons will be removed before applying NMS.

• nms_threshold (float) – The threshold for the Non-Maximum Suppression (NMS) algorithm.

• nms_algorithm (str) – The NMS algorithm to use. Supported values are ‘iou’ and ‘ioa-disambiguate’.

• edge_band_buffer_percentage (float) – The percentage of the tile width/height to consider as an edge band. The polygons that intersect with this band will be removed before applying the NMS algorithm.

• best_geom_keep_area_ratio (float) – Parameter used in the ‘ioa-disambiguate’ NMS algorithm to decide which geometry to keep.

• pre_aggregated_output_path (str or Path, optional) – If provided, the intermediate (pre-NMS) polygons will be saved at this location.

Returns:

An instance of Aggregator initialized with data extracted from the GeoDataFrame.

Return type:

Aggregator

classmethod from_polygons(output_path, tiles_paths, polygons, scores, other_attributes, scores_weights=None, scores_weighting_method='weighted_geometric_mean', min_centroid_distance_weight=None, score_threshold=0.1, nms_threshold=0.8, nms_algorithm='iou', edge_band_buffer_percentage=0.05, best_geom_keep_area_ratio=0.5, pre_aggregated_output_path=None)

Instanciate and run an Aggregator from a list of polygons for each tile.

Parameters:

• output_path (str or Path) – The filename where to save the aggregated polygons. ‘.gpkg’, ‘.geojson’ are supported, as well as ‘.json’ for COCO format.

• tiles_paths (List[str or Path]) – The list of paths to the tiles.

• polygons (List[List[Polygon]]) – A list of lists of polygons, where each list of polygons corresponds to a tile.

• scores (List[List[float]] or Dict[str, List[List[float]]]) –

  It can be a list of lists of floats if only 1 set of scores is passed, where each list of floats corresponds to a tile.

  It can also be a dictionary of lists of lists of floats if multiple types of scores are passed, example:

  {
      'detection_score': [[0.1, 0.2, ...], [0.2, 0.5, ...], ...],
      'segmentation_score': [[0.4, 0.2, ...], [0.8, 0.9, ...], ...]
  }
  

  This is useful if you possibly have multiple scores for each polygon, such as detection confidence score and/or segmentation confidence score.

• other_attributes (Dict[str, List[List[float]]]) – Used to pass other polygons information, not used by the Aggregator but used for your downstream tasks. Structure is similar to “scores”, a dict with keys being the attribute (=output gpkg columns) names and values being lists of lists, one value for each associated polygon.

• scores_weights (Dict[str, float]) –

  The weights to apply to each score set. The scores_weights should sum to 1 and there should be as many

  weights as there are scores_names. See the ‘scores_weighting_method’ parameter for more details.

• scores_weighting_method (str) –

  The method to use to weight the different sets of scores. Supported values are [‘weighted_arithmetic_mean’, ‘weighted_geometric_mean’, ‘weighted_harmonic_mean’].

  • ’weighted_arithmetic_mean’: The scores are simply averaged, but each score is weighted by its weight.

  • ’weighted_geometric_mean’: The scores are multiplied, but each score is weighted by its weight.

  • ’weighted_harmonic_mean’: The scores are averaged, but each score is weighted by its reciprocal

• min_centroid_distance_weight (float or None) – The weight to apply to the polygon scores (after applying the scores_weights) based on the distance between the polygon centroid and its tile centroid. The smaller the value of min_centroid_distance_weight, the smaller the score will be for polygons at the edge of the tile.

• score_threshold (float) – The score threshold under which polygons will be removed, before applying the NMS algorithm.

• nms_threshold (float) –

  The threshold for the Non-Maximum Suppression algorithm. It serves different purposes depending on the ‘nms_algorithm’ chosen:

  • ’iou’: The threshold is used as the regular Intersection Over Union (IoU) threshold. If 2 polygons have an IoU above this threshold, the one with the lowest score will be removed.

  • ’ioa-disambiguate’: This is the threshold used to determine if a lesser-scored polygon should be

  discarded (entirely removed), or cut to remove its portion that overlaps with another higher-scored polygon. The equation is a bit different than IoU: it’s the area of the intersection divided by the area of the lesser-scored polygon (Intersection / Area_lower_scored_polygon).

• nms_algorithm (str) –

  The Non-Maximum Suppression algorithm to use. Supported values are [‘iou’ and ‘ioa-disambiguate’].

  • ’iou’: This algorithm uses the Intersection Over Union (IoU) to suppress overlapping polygons.

  • ’ioa-disambiguate’: Shouldn’t be used for detection bounding boxes, it was designed for instance segmentations. In addition to using IoU, this algorithm attempts to disambiguate overlapping polygons by cutting the intersecting parts and keeping only the largest resulting geometry, as long as it meets the best_geom_keep_area_ratio threshold.

• edge_band_buffer_percentage (float) – The percentage of the tile width/height to consider as an edge band. The polygons that intersect with this band will be removed before applying the NMS algorithm.

• best_geom_keep_area_ratio (float) – Only used when nms_algorithm is set to ‘ioa-disambiguate’. When removing part of a polygon due to the intersection with another one, that polygon may end-up being cut into multiple smaller and disconnected geometries. The algorithm will only consider keeping the largest of those geometries, and only keep it if it makes up at least ‘best_geom_keep_area_ratio’ percent of the original polygon (in terms of area).

• pre_aggregated_output_path (str or Path) – If provided, the polygons will be saved in this file before applying the NMS algorithm. This is useful to debug the polygons before the NMS algorithm is applied.

Return type:

Aggregator