target_finder_toolkit.postprocess module

Utility functions to consume the detection callback output of TargetFinder.

This module provides helpers for:

  • Selection, sorting, and filtering of detections.

  • Drawing and exporting annotated frames (bounding boxes, labels).

  • Extracting and saving crops of detected widgets.

Expected data structures:

  • detections: list of dicts with keys {id, x, y, width, height, score, class_id, class_name}

  • frame: RGB image as a NumPy array.

target_finder_toolkit.postprocess.get_ids(detections)

Return sorted detection IDs (ascending).

Parameters:

detections (list[dict]) – Detections, each dict may contain key "id".

Returns:

Sorted IDs id.

Return type:

list[int]

target_finder_toolkit.postprocess.sort_detections(detections, key='id', reverse=False)

Return a new list of detections sorted by a given key.

Parameters:

  • detections (list[dict]) – Detection dictionaries.

  • key (str, optional) – Key to sort by (e.g., "id", "score", "x", "y", "width", "height"). Defaults to "id".

  • reverse (bool, optional) – If True, sort in descending order. Defaults to False.

Returns:

Sorted copy of the input detections.

Return type:

list[dict]

target_finder_toolkit.postprocess.summarize_change(detections, added, removed)

Build a compact summary of changes between two detection sets.

Parameters:

  • detections (list[dict]) – Current detections.

  • added (list[dict]) – Detections that appeared since the previous step.

  • removed (list[dict]) – Detections that disappeared since the previous step.

Returns:

Summary dictionary with keys:

  • total (int): Number of detections.

  • added_ids (list[int]): IDs of newly added detections.

  • removed_ids (list[int]): IDs of removed detections.

  • current_ids (list[int]): IDs of current detections.

Return type:

dict

target_finder_toolkit.postprocess.pretty_print_change(detections, added, removed)

Print a change summary (useful in quick logs / tests).

Parameters:

  • detections (list[dict]) – Current detections.

  • added (list[dict]) – Newly added detections.

  • removed (list[dict]) – Removed detections.

target_finder_toolkit.postprocess.draw_bboxes(frame_rgb, detections, draw_ids=True, color=(0, 255, 0), thickness=2)

Draw bounding boxes and labels on a copy of an RGB frame.

The label format is "<class_name>:<score>[#<id>]" when draw_ids=True.

Parameters:

  • frame_rgb (np.ndarray) – HxWx3 RGB image.

  • detections (list[dict]) – Detection dicts with keys x, y, width, height (and optionally class_name, score, id).

  • draw_ids (bool, optional) – If True, append #<id> to the label when present. Defaults to True.

  • color (tuple[int, int, int], optional) – Box color in BGR. Defaults to (0, 255, 0).

  • thickness (int, optional) – Line thickness. Defaults to 2.

Returns:

Annotated RGB image.

Return type:

np.ndarray

target_finder_toolkit.postprocess.save_annotated(path, frame_rgb, detections, draw_ids=True)

Save an annotated PNG image.

Parameters:

  • path (str | Path) – Output file path.

  • frame_rgb (np.ndarray) – HxWx3 RGB image.

  • detections (list[dict]) – Detections to draw.

  • draw_ids (bool, optional) – If True, include IDs in labels when available.

Returns:

Path to the saved image.

Return type:

Path

target_finder_toolkit.postprocess.save_detections_json(path, detections)

Save detections to a JSON file.

Parameters:

  • path (str | Path) – Output JSON path.

  • detections (list[dict]) – Detections to serialize.

Returns:

Path to the saved JSON file.

Return type:

Path

target_finder_toolkit.postprocess.extract_crops(frame_rgb, detections, clamp=True)

Extract cropped widget images from a screen frame. This utility takes the full RGB screenshot and a list of detections, then returns individual image crops (sub-images) corresponding to each detected GUI widget (e.g., button, slider, text field).

Parameters:

  • frame_rgb (np.ndarray) – HxWx3 RGB image.

  • detections (list[dict]) – Detection dicts with keys x, y, width, height (and optionally id).

  • clamp (bool, optional) – If True, crop boxes are clamped to image bounds. Defaults to True.

Returns:

List of (det_id, crop), where det_id is the widget ID.

Return type:

list[tuple[int, np.ndarray]]

target_finder_toolkit.postprocess.save_crops(outdir, crops, prefix='crop', ext='.png')

Save a list of crops to a directory.

Filenames follow the pattern:

<prefix>_<index>[_id<ID>]<ext>

Examples: crop_0000.png - crop_0001_id12.png

Parameters:

  • outdir (str | Path) – Output directory.

  • crops (list[tuple[int, np.ndarray]]) – List of (det_id, crop) pairs as returned by extract_crops().

  • prefix (str, optional) – Filename prefix. Defaults to "crop".

  • ext (str, optional) – File extension (e.g., ".png"). Defaults to ".png".

Returns:

Paths to the saved crops.

Return type:

list[Path]