perceptionmetrics.utils package

Submodules

perceptionmetrics.utils.conversion module

perceptionmetrics.utils.conversion.get_ontology_conversion_lut(old_ontology, new_ontology, ontology_translation=None, classes_to_remove=None, lut_dtype=<class 'numpy.uint8'>)

Build a LUT that links old ontology and new ontology indices. If class names don’t match between the provided ontologies, user must provide an ontology translation dictionary with old and new class names as keys and values, respectively

Parameters:

• old_ontology (dict) – Origin ontology definition

• new_ontology (dict) – Target ontology definition

• ontology_translation (Optional[dict], optional) – Ontology translation dictionary, defaults to None

• classes_to_remove (Optional[List[str]], optional) – Classes to be removed from the old ontology, defaults to None

• lut_dtype (Optional[np.dtype], optional) – Type for the ontology conversion LUT, defaults to np.uint8

Returns:

numpy array associating old and new ontology indices

Return type:

np.ndarray

perceptionmetrics.utils.conversion.hex_to_rgb(hex)

Convert HEX color code to sRGB

Parameters:

hex (str) – HEX color code

Returns:

sRGB color value

Return type:

Tuple[int, …]

perceptionmetrics.utils.conversion.label_to_rgb(label, ontology)

Convert an image with raw label indices to RGB mask

Parameters:

• label (Image.Image) – Raw label indices as PIL image

• ontology (dict) – Ontology definition

Returns:

RGB mask

Return type:

Image.Image

perceptionmetrics.utils.conversion.ontology_to_rgb_lut(ontology)

Given an ontology definition, build a LUT that links indices and RGB values

Parameters:

ontology (dict) – Ontology definition

Returns:

numpy array containing RGB values per index

Return type:

np.ndarray

perceptionmetrics.utils.detection_metrics module

class perceptionmetrics.utils.detection_metrics.DetectionMetricsFactory(iou_threshold=0.5, num_classes=None)

Bases: object

Factory class for computing detection metrics including precision, recall, AP, and mAP.

Parameters:

• iou_threshold (float, optional) – IoU threshold for matching predictions to ground truth, defaults to 0.5

• num_classes (Optional[int], optional) – Number of classes in the dataset, defaults to None

compute_auc_pr()

Compute the Area Under the Precision-Recall Curve (AUC-PR).

Returns:

Area under the precision-recall curve

Return type:

float

compute_coco_map()

Compute COCO-style mAP (mean AP over IoU thresholds 0.5:0.05:0.95).

Returns:

mAP@[0.5:0.95]

Return type:

float

compute_metrics()

Compute per-class precision, recall, AP, and mAP.

Returns:

Dictionary mapping class IDs to metric dictionaries, plus mAP under key -1

Return type:

Dict[int, Dict[str, float]]

get_metrics_dataframe(ontology)

Get results as a pandas DataFrame.

Parameters:

ontology (dict) – Mapping from class name → { “idx”: int }

Returns:

DataFrame with metrics as rows and classes as columns (with mean)

Return type:

pd.DataFrame

get_overall_precision_recall_curve()

Get overall precision-recall curve data (aggregated across all classes).

Returns:

Dictionary with ‘precision’ and ‘recall’ keys containing curve data

Return type:

Dict[str, List[float]]

update(gt_boxes, gt_labels, pred_boxes, pred_labels, pred_scores)

Add a batch of predictions and ground truths.

Parameters:

• gt_boxes (List[ndarray]) – Ground truth bounding boxes, shape (num_gt, 4)

• gt_labels (List[int]) – Ground truth class labels

• pred_boxes (List[ndarray]) – Predicted bounding boxes, shape (num_pred, 4)

• pred_labels (List[int]) – Predicted class labels

• pred_scores (List[float]) – Prediction confidence scores

perceptionmetrics.utils.detection_metrics.compute_ap(tps, fps, fn)

Compute Average Precision (AP) using VOC-style 11-point interpolation.

Parameters:

• tps (List[bool] or np.ndarray) – List of true positive flags

• fps (List[bool] or np.ndarray) – List of false positive flags

• fn (int) – Number of false negatives

Returns:

Tuple of (AP, precision array, recall array)

Return type:

Tuple[float, np.ndarray, np.ndarray]

perceptionmetrics.utils.detection_metrics.compute_iou(boxA, boxB)

Compute Intersection over Union (IoU) between two bounding boxes.

Parameters:

• boxA (array-like) – First bounding box [x1, y1, x2, y2]

• boxB (array-like) – Second bounding box [x1, y1, x2, y2]

Returns:

IoU value between 0 and 1

Return type:

float

perceptionmetrics.utils.detection_metrics.compute_iou_matrix(pred_boxes, gt_boxes)

Compute IoU matrix between pred and gt boxes.

Parameters:

• pred_boxes (np.ndarray) – Predicted bounding boxes, shape (num_pred, 4)

• gt_boxes (np.ndarray) – Ground truth bounding boxes, shape (num_gt, 4)

Returns:

IoU matrix with shape (num_pred, num_gt)

Return type:

np.ndarray

perceptionmetrics.utils.io module

perceptionmetrics.utils.io.extract_wildcard_matches(pattern)

Given a pattern with wildcards, extract the matches

Parameters:

pattern (str) – ‘Globable’ pattern with wildcards

Returns:

Matches found in the pattern

Return type:

list

perceptionmetrics.utils.io.get_image_mode(fname)

Given an image retrieve its color mode using PIL

Parameters:

fname (str) – Input image

Returns:

PIL color image mode

Return type:

str

perceptionmetrics.utils.io.read_json(fname)

Read a JSON file

Parameters:

fname (str) – JSON filename

Returns:

Dictionary containing JSON file data

Return type:

dict

perceptionmetrics.utils.io.read_txt(fname)

Read a .txt file line by line

Parameters:

fname (str) – .txt filename

Returns:

List of lines found in the .txt file

Return type:

List[str]

perceptionmetrics.utils.io.read_yaml(fname)

Read a YAML file

Parameters:

fname (str) – YAML filename

Returns:

Dictionary containing YAML file data

Return type:

dict

perceptionmetrics.utils.io.write_json(fname, data)

Write a JSON file properly indented

Parameters:

• fname (str) – Target JSON filename

• data (dict) – Dictionary containing data to be dumped as a JSON file

perceptionmetrics.utils.lidar module

class perceptionmetrics.utils.lidar.Sampler(point_cloud_size, search_tree, sampler_name, num_classes, seed=42)

Bases: object

Init point cloud sampler

Parameters:

• point_cloud_size (int) – Total number of points in the point cloud

• search_tree (KDTree) – Search tree for the point cloud data

• sampler_name (str) – Sampler name (e.g. random, spatially_regular)

• num_classes (int) – Number of classes in the dataset

• seed (int, optional) – Random seed, defaults to 42

Raises:

NotImplementedError – _description_

random(points, num_points)

Random sampling

Parameters:

• points (np.ndarray) – Point cloud data

• num_points (int) – Number of points to sample

Returns:

Sampled points, and their respective indices and center point

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

spatially_regular(points, num_points=None, radius=None)

Spatially regular sampling

Parameters:

• points (np.ndarray) – Point cloud data

• num_points (Optional[int]) – Number of points to sample

• radius (Optional[float]) – Radius for spatially regular sampling

Returns:

Sampled points, and their respective indices and center point

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

perceptionmetrics.utils.lidar.build_point_cloud(points, colors)

Build a point cloud

Parameters:

• points (np.ndarray) – Point cloud data

• colors (np.ndarray) – Colors for the point cloud data

Returns:

Point cloud

Return type:

o3d.geometry.PointCloud

perceptionmetrics.utils.lidar.read_semantickitti_label(fname)

Read labels from a binary file in SemanticKITTI format

Parameters:

fname (str) – Binary file containing labels

Returns:

Numpy arrays containing semantic and instance labels

Return type:

Tuple[np.ndarray, np.ndarray]

perceptionmetrics.utils.lidar.read_semantickitti_points(fname, has_intensity=True)

Read points from a binary file in SemanticKITTI format

Parameters:

• fname (str) – Binary file containing points

• has_intensity (bool) – Whether the points have intensity values, defaults to True

Returns:

Numpy array containing points

Return type:

np.ndarray

perceptionmetrics.utils.lidar.recenter(points, dims)

Recenter a point cloud along the specified dimensions

Parameters:

• points (np.ndarray) – Point cloud data

• dims (List[int]) – Dimensions to recenter

Returns:

Recentred point cloud data

Return type:

np.ndarray

perceptionmetrics.utils.lidar.render_point_cloud(points, colors, camera_view='3rd_person', bg_color=[0.0, 0.0, 0.0, 1.0], color_jitter=0.05, point_size=3.0, resolution=(1920, 1080), render_origin=False, origin_size=0.5)

Render a given point cloud from a specific camera view and return the image

Parameters:

• points (np.ndarray) – Point cloud data

• colors (np.ndarray) – Colors for the point cloud data

• camera_view (Union[str, dict], optional) – Camera view (either ID or dictionary containing camera definition), defaults to “3rd_person”

• bg_color (Optional[List[float]], optional) – Background color, defaults to black -> [0., 0., 0., 1.]

• color_jitter (float, optional) – Jitters the colors by a random value between [-color_jitter, color_jitter], defaults to 0.05

• point_size (float, optional) – Point size, defaults to 3.0

• resolution (Tuple[int, int], optional) – Render resolution, defaults to (1920, 1080)

• render_origin (bool, optional) – Whether to render the origin axes, defaults to False

• origin_size (float, optional) – Size of the origin axes, defaults to 0.5

Returns:

Rendered point cloud

Return type:

Image

perceptionmetrics.utils.lidar.view_point_cloud(points, colors)

Visualize a single point cloud

Parameters:

• points (np.ndarray) – Point cloud data

• colors (np.ndarray) – Colors for the point cloud data

perceptionmetrics.utils.segmentation_metrics module

class perceptionmetrics.utils.segmentation_metrics.SegmentationMetricsFactory(n_classes)

Bases: object

‘Factory’ class to accumulate results and compute metrics for segmentation tasks

Parameters:

n_classes (int) – Number of classes to evaluate

METRIC_NAMES = ['tp', 'fp', 'fn', 'tn', 'precision', 'recall', 'accuracy', 'f1_score', 'iou']

get_accuracy(per_class=True)

Accuracy = (TP + TN) / (TP + FP + FN + TN)

Parameters:

per_class (bool, optional) – Return per class accuracy, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, float]

get_averaged_metric(metric_name, method, weights=None)

Get average metric value

Parameters:

• metric (str) – Name of the metric to compute

• method (str) – Method to use for averaging (‘macro’, ‘micro’ or ‘weighted’)

• weights (Optional[np.ndarray], optional) – Weights for weighted averaging, defaults to None

• metric_name (str)

Returns:

Average metric value

Return type:

float

get_confusion_matrix()

Get confusion matrix

Returns:

Confusion matrix

Return type:

np.ndarray

get_f1_score(per_class=True)

F1-score = 2 * (Precision * Recall) / (Precision + Recall)

Parameters:

per_class (bool, optional) – Return per class F1 score, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, float]

get_fn(per_class=True)

False negatives

Parameters:

per_class (bool, optional) – Return per class FN, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, int]

get_fp(per_class=True)

False Positives

Parameters:

per_class (bool, optional) – Return per class FP, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, int]

get_iou(per_class=True)

IoU = TP / (TP + FP + FN)

Parameters:

per_class (bool, optional) – Return per class IoU, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, float]

get_metric_names()

Get available metric names

Returns:

List of available metric names

Return type:

List[str]

get_metric_per_name(metric_name, per_class=True)

Get metric value by name

Parameters:

• metric_name (str) – Name of the metric to compute

• per_class (bool, optional) – Return per class metric, defaults to True

Returns:

Metric value

Return type:

Union[np.ndarray, float, int]

get_precision(per_class=True)

Precision = TP / (TP + FP)

Parameters:

per_class (bool, optional) – Return per class precision, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, float]

get_recall(per_class=True)

Recall = TP / (TP + FN)

Parameters:

per_class (bool, optional) – Return per class recall, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, float]

get_tn(per_class=True)

True negatives

Parameters:

per_class (bool, optional) – Return per class TN, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, int]

get_tp(per_class=True)

True Positives

Parameters:

per_class (bool, optional) – Return per class TP, defaults to True

Returns:

True Positives

Return type:

Union[np.ndarray, int]

update(pred, gt, valid_mask=None)

Accumulate results for a new batch

Parameters:

• pred (np.ndarray) – Array containing prediction

• gt (np.ndarray) – Array containing ground truth

• valid_mask (Optional[np.ndarray], optional) – Binary mask where False elements will be igonred, defaults to None

perceptionmetrics.utils.segmentation_metrics.get_metrics_dataframe(metrics_factory, ontology)

Build a DataFrame with all metrics (global and per class) plus confusion matrix

Parameters:

• metrics_factory (SegmentationMetricsFactory) – Properly updated SegmentationMetricsFactory object

• ontology (dict) – Ontology dictionary

Returns:

DataFrame with all metrics

Return type:

pd.DataFrame

perceptionmetrics.utils.torch module

perceptionmetrics.utils.torch.data_to_device(data, device)

Move provided data to given device (CPU or GPU)

Parameters:

• data (Union[tuple, list]) – Data provided (it can be a single or multiple tensors)

• device (torch.device) – Device to move data to

Returns:

Data moved to device

Return type:

Union[tuple, list]

perceptionmetrics.utils.torch.get_data_shape(data)

Get the shape of the provided data

Parameters:

data (Union[tuple, list]) – Data provided (it can be a single or multiple tensors)

Returns:

Data shape

Return type:

Union[tuple, list]

perceptionmetrics.utils.torch.unsqueeze_data(data, dim=0)

Unsqueeze provided data along given dimension

Parameters:

• data (Union[tuple, list]) – Data provided (it can be a single or multiple tensors)

• dim (int, optional) – Dimension that will be unsqueezed, defaults to 0

Returns:

Unsqueezed data

Return type:

Union[tuple, list]

Module contents