Extra API

class faster_coco_eval.extra.Curves(cocoGt=None, cocoDt=None, iouType='bbox', min_score=0, iou_tresh=0.0, recall_count=100, useCats=False, kpt_oks_sigmas=None)

Bases: ExtraEval

build_ced_curve(mae_count=1000)

Build the CED (Cumulative Error Distribution) curve for all categories.

Parameters:

mae_count (int) – Number of points to use for the CED curve. Defaults to 1000.

Returns:

List of dictionaries containing CED curve data for each category.

Return type:

list[dict]

Raises:

AssertionError – If self.eval is None (evaluate() was not called).
ValueError – If the iouType is not ‘keypoints’ (other types are not supported).

build_curve(label)

Build the curve for a given label.

Parameters:

label (str) – The label to build the curve for.

Returns:

A list of dictionaries containing: the curve data for each category.

Return type:

list[dict]

Raises:

AssertionError – If self.eval is None (evaluate() was not called).

plot_ced_metric(curves=None, normalize=True, return_fig=False)

Plot the CED metric curve.

Parameters:

curves (list[dict] | None) – List of curves to plot. If None, will build the curves. Defaults to None.
normalize (bool | None) – Whether to normalize the curve. Defaults to True.
return_fig (bool | None) – Return the figure object. Defaults to False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

plotly.graph_objs._figure.Figure or None

plot_f1_confidence(curves=None, label='category_id', return_fig=False)

Plot the F1 confidence curve.

Parameters:

curves (list[dict] | None) – List of curves to plot. If None, it will build the curves. Defaults to None.
label (str | None) – Label for the curves. Defaults to “category_id”.
return_fig (bool | None) – Return the figure object. Defaults to False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

plotly.graph_objs._figure.Figure or None

plot_pre_rec(curves=None, label='category_id', return_fig=False)

Plot the precision-recall curve.

Parameters:

curves (list[dict] | None) – List of curves to plot. If None, it will build the curves. Defaults to None.
label (str | None) – Label for the curves. Defaults to “category_id”.
return_fig (bool | None) – Return the figure object. Defaults to False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

plotly.graph_objs._figure.Figure or None

class faster_coco_eval.extra.PreviewResults(cocoGt=None, cocoDt=None, iouType='bbox', min_score=0, iou_tresh=0.0, recall_count=100, useCats=False, kpt_oks_sigmas=None)

Bases: ExtraEval

compute_confusion_matrix()

Compute the confusion matrix for the current evaluation.

Returns:: The confusion matrix.
Return type:: ndarray
Raises:: AssertionError – If self.eval is None (evaluate() was not run).

display_image(image_id=1, display_fp=True, display_fn=True, display_tp=True, display_gt=True, show_false_only=False, data_folder=None, categories=None, gt_ann_ids=None, dt_ann_ids=None, return_fig=False)

Display the image with the results.

Parameters:

image_id (int) – Image id.
display_fp (bool) – Display false positives.
display_fn (bool) – Display false negatives.
display_tp (bool) – Display true positives.
display_gt (bool) – Display ground truth.
show_false_only (bool) – If True, only display images that contains false positives or false negatives.
data_folder (str | None) – Data folder.
categories (list | None) – Categories to display.
gt_ann_ids (set | None) – Ground truth annotation ids.
dt_ann_ids (set | None) – Detected annotation ids.
return_fig (bool) – Return the figure.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[Any]

display_matrix(normalize=False, conf_matrix=None, return_fig=False)

Display the confusion matrix.

Parameters:

normalize (bool) – Normalize the matrix.
conf_matrix (ndarray | None) – Confusion matrix to display. If None, compute it.
return_fig (bool) – Return the figure.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[Any]

display_tp_fp_fn(image_ids=['all'], display_fp=True, display_fn=True, display_tp=True, display_gt=False, show_false_only=False, data_folder=None, categories=None)

Display true positives, false positives, and false negatives for given images.

Parameters:

image_ids (list[int] | list[str]) – List of image ids or [“all”] to display all images.
display_fp (bool) – Display false positives.
display_fn (bool) – Display false negatives.
display_tp (bool) – Display true positives.
display_gt (bool) – Display ground truth.
show_false_only (bool) – If True, only display images that contains false positives or false negatives.
data_folder (str | None) – Data folder.
categories (list | None) – Categories to display.

Returns:

None

Implementation modules

class faster_coco_eval.extra.curves.Curves(cocoGt=None, cocoDt=None, iouType='bbox', min_score=0, iou_tresh=0.0, recall_count=100, useCats=False, kpt_oks_sigmas=None)

build_ced_curve(mae_count=1000)

Build the CED (Cumulative Error Distribution) curve for all categories.

Parameters:

mae_count (int) – Number of points to use for the CED curve. Defaults to 1000.

Returns:

List of dictionaries containing CED curve data for each category.

Return type:

list[dict]

Raises:

AssertionError – If self.eval is None (evaluate() was not called).
ValueError – If the iouType is not ‘keypoints’ (other types are not supported).

build_curve(label)

Build the curve for a given label.

Parameters:

label (str) – The label to build the curve for.

Returns:

A list of dictionaries containing: the curve data for each category.

Return type:

list[dict]

Raises:

AssertionError – If self.eval is None (evaluate() was not called).

plot_ced_metric(curves=None, normalize=True, return_fig=False)

Plot the CED metric curve.

Parameters:

curves (list[dict] | None) – List of curves to plot. If None, will build the curves. Defaults to None.
normalize (bool | None) – Whether to normalize the curve. Defaults to True.
return_fig (bool | None) – Return the figure object. Defaults to False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

plotly.graph_objs._figure.Figure or None

plot_f1_confidence(curves=None, label='category_id', return_fig=False)

Plot the F1 confidence curve.

Parameters:

curves (list[dict] | None) – List of curves to plot. If None, it will build the curves. Defaults to None.
label (str | None) – Label for the curves. Defaults to “category_id”.
return_fig (bool | None) – Return the figure object. Defaults to False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

plotly.graph_objs._figure.Figure or None

plot_pre_rec(curves=None, label='category_id', return_fig=False)

Plot the precision-recall curve.

Parameters:

curves (list[dict] | None) – List of curves to plot. If None, it will build the curves. Defaults to None.
label (str | None) – Label for the curves. Defaults to “category_id”.
return_fig (bool | None) – Return the figure object. Defaults to False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

plotly.graph_objs._figure.Figure or None

class faster_coco_eval.extra.display.PreviewResults(cocoGt=None, cocoDt=None, iouType='bbox', min_score=0, iou_tresh=0.0, recall_count=100, useCats=False, kpt_oks_sigmas=None)

compute_confusion_matrix()

Compute the confusion matrix for the current evaluation.

Returns:: The confusion matrix.
Return type:: ndarray
Raises:: AssertionError – If self.eval is None (evaluate() was not run).

display_image(image_id=1, display_fp=True, display_fn=True, display_tp=True, display_gt=True, show_false_only=False, data_folder=None, categories=None, gt_ann_ids=None, dt_ann_ids=None, return_fig=False)

Display the image with the results.

Parameters:

image_id (int) – Image id.
display_fp (bool) – Display false positives.
display_fn (bool) – Display false negatives.
display_tp (bool) – Display true positives.
display_gt (bool) – Display ground truth.
show_false_only (bool) – If True, only display images that contains false positives or false negatives.
data_folder (str | None) – Data folder.
categories (list | None) – Categories to display.
gt_ann_ids (set | None) – Ground truth annotation ids.
dt_ann_ids (set | None) – Detected annotation ids.
return_fig (bool) – Return the figure.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[Any]

display_matrix(normalize=False, conf_matrix=None, return_fig=False)

Display the confusion matrix.

Parameters:

normalize (bool) – Normalize the matrix.
conf_matrix (ndarray | None) – Confusion matrix to display. If None, compute it.
return_fig (bool) – Return the figure.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[Any]

display_tp_fp_fn(image_ids=['all'], display_fp=True, display_fn=True, display_tp=True, display_gt=False, show_false_only=False, data_folder=None, categories=None)

Display true positives, false positives, and false negatives for given images.

Parameters:

image_ids (list[int] | list[str]) – List of image ids or [“all”] to display all images.
display_fp (bool) – Display false positives.
display_fn (bool) – Display false negatives.
display_tp (bool) – Display true positives.
display_gt (bool) – Display ground truth.
show_false_only (bool) – If True, only display images that contains false positives or false negatives.
data_folder (str | None) – Data folder.
categories (list | None) – Categories to display.

Returns:

None

faster_coco_eval.extra.draw.display_image(cocoGt, cocoDt=None, image_id=1, iouType='bbox', display_fp=True, display_fn=True, display_tp=True, display_gt=True, show_false_only=False, data_folder=None, categories=None, gt_ann_ids=None, dt_ann_ids=None, return_fig=False)

Display the image with the results.

Parameters:

cocoGt (COCO) – Ground truth COCO object.
cocoDt (COCO, optional) – Detection COCO object. Default is None.
image_id (int, optional) – Image id to display. Default is 1.
iouType (str, optional) – Type of the annotation, one of ‘bbox’, ‘segm’, or ‘keypoints’. Default is “bbox”.
display_fp (bool, optional) – Display false positive annotations. Default is True.
display_fn (bool, optional) – Display false negative annotations. Default is True.
display_tp (bool, optional) – Display true positive annotations. Default is True.
display_gt (bool, optional) – Display ground truth annotations. Default is True.
show_false_only (bool) – If True, only display images that contains false positives or false negatives.
data_folder (str, optional) – Folder containing the images. Default is None.
categories (list, optional) – List of category ids to display. Default is None.
gt_ann_ids (set, optional) – Set of ground truth annotation ids to display. Default is None.
dt_ann_ids (set, optional) – Set of detection annotation ids to display. Default is None.
return_fig (bool, optional) – Return the figure object instead of displaying it. Default is False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[go.Figure]

faster_coco_eval.extra.draw.display_matrix(conf_matrix, labels, normalize=False, return_fig=False)

Display the confusion matrix.

Parameters:

conf_matrix (np.ndarray) – Confusion matrix (shape: [n_classes, n_classes + 2]).
labels (list) – List of class labels.
normalize (bool, optional) – If True, normalize each row, including the appended fp and fn columns, to percentages. Rows with a zero total remain zero. Default is False.
return_fig (bool, optional) – If True, return the figure object. Default is False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[go.Figure]

faster_coco_eval.extra.draw.generate_ann_polygon(ann, color, iouType='bbox', text=None, legendgroup=None, category_id_to_skeleton=None)

Generate annotation polygon for plotly.

Parameters:

ann (dict) – Annotation dictionary.
color (tuple) – Color of the annotation, as (R, G, B, A) tuple.
iouType (str, optional) – Type of the annotation. One of ‘bbox’, ‘segm’, or ‘keypoints’. Default is “bbox”.
text (str, optional) – Text to display on hover. Default is None.
legendgroup (str, optional) – Legend group to display. Default is None.
category_id_to_skeleton (dict, optional) – Dictionary mapping category_id to skeleton (for keypoints). Default is None.

Returns:

Plotly Scatter object representing the annotation polygon.

Return type:

go.Scatter

faster_coco_eval.extra.draw.plot_ced_metric(curves, normalize=False, return_fig=False)

Plot the Cumulative Error Distribution (CED) curve.

Parameters:

curves (list) – List of ced curves to plot. Each dict must have keys: ‘mae’ (dict), ‘category’ (dict), optionally ‘label’.
normalize (bool) – If True, normalize values to percent. Default is False.
return_fig (bool) – If True, return the figure object. Default is False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[go.Figure]

faster_coco_eval.extra.draw.plot_f1_confidence(curves, return_fig=False)

Plot the F1 confidence curve.

Parameters:

curves (list) – List of curves to plot. Each element is a dict with keys: ‘recall_list’, ‘precision_list’, ‘scores’, ‘label’.
return_fig (bool) – If True, return the figure object. Default is False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[go.Figure]

faster_coco_eval.extra.draw.plot_pre_rec(curves, return_fig=False)

Plot the precision-recall curve.

Parameters:

curves (list) – List of curves to plot. Each element is a dict with keys: ‘recall_list’, ‘precision_list’, ‘scores’, ‘name’.
return_fig (bool) – If True, return the figure object. Default is False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[go.Figure]

faster_coco_eval.extra.draw.show_anns(cocoGt, image_id, ann_ids=None, iouType='bbox', data_folder=None, return_fig=False)

Show ground truth annotations on an image.

Parameters:

cocoGt (COCO) – COCO object containing ground truth data.
image_id (int) – Image id to display.
ann_ids (list[int] | None) – List of annotation ids to show. Default is None (show all).
iouType (Literal['segm', 'bbox']) – Type of the annotation, one of ‘bbox’ or ‘segm’. Default is “bbox”.
data_folder (str | None) – Folder containing the images. Default is None.
return_fig (bool) – Return the figure object instead of displaying it. Default is False.

Returns:

The figure object if return_fig is True, otherwise None.

Return type:

Optional[go.Figure]

class faster_coco_eval.extra.extra.ExtraEval(cocoGt=None, cocoDt=None, iouType='bbox', min_score=0, iou_tresh=0.0, recall_count=100, useCats=False, kpt_oks_sigmas=None)

Extra evaluation for coco dataset.

drop_cocodt_by_score(min_score)

Removes detection annotations with score below min_score from cocoDt.

Parameters:: min_score (float) – Minimum score threshold for detections.
Raises:: AssertionError – If cocoDt is None.

evaluate()

Runs COCO evaluation and accumulates results.

Raises:: AssertionError – If cocoDt is None.

property fn_image_ann_map: dict[int, set[int]]

Gets a mapping from image IDs to sets of annotation IDs for false negatives.

Returns:: Mapping from image_id to set of annotation IDs marked as false negatives.
Return type:: Dict[int, Set[int]]

property fp_image_ann_map: dict[int, set[int]]

Gets a mapping from image IDs to sets of annotation IDs for false positives.

Returns:: Mapping from image_id to set of annotation IDs marked as false positives.
Return type:: Dict[int, Set[int]]

faster_coco_eval.extra.utils.conver_mask_to_poly(mask, bbox, boxes_margin=0.1)

Convert a mask (uint8) to a list of polygons in COCO style.

Parameters:

mask (ndarray) – The mask image as a numpy array.
bbox (list) – Bounding box of the annotation in the format [x, y, w, h].
boxes_margin (float) – Margin factor to increase the bounding box size. Defaults to 0.1.

Returns:

List of polygons in COCO format (list of lists of coordinates).

Return type:

list

faster_coco_eval.extra.utils.convert_ann_rle_to_poly(ann)

Convert annotation segmentation from RLE to polygon style and save RLE in the ‘counts’ variable.

Parameters:: ann (dict) – Annotation dictionary with at least ‘segmentation’ (RLE) and ‘bbox’ fields.
Returns:: Annotation dictionary with ‘segmentation’ converted to polygons and original RLE stored in ‘counts’.
Return type:: dict
Raises:: Exception – If OpenCV is not available and conversion is required.

faster_coco_eval.extra.utils.convert_rle_to_poly(rle, bbox)

Convert RLE (Run-Length Encoding) to a list of polygons in COCO style.

Parameters:

rle (dict) – RLE of the mask image (COCO format).
bbox (list) – Bounding box of the annotation in the format [x, y, w, h].

Returns:

List of polygons in COCO format (list of lists of coordinates).

Return type:

list