Filters: keep only the detections you need

A model returns everything it might have seen, including guesses with a low score and classes you do not care about. Filters keep the detections you need. Each one is a method of Detections that returns a new Detections, so they chain, and the original stays as it was.

Python
import pixelflow as pf
from mayaku import from_pretrained

predictor = from_pretrained("mayaku-n-det")
result = predictor("street.jpg")
detections = pf.from_mayaku(result, labels=predictor.class_names)

person = predictor.class_names.index("Person")
people = detections.filter_by_confidence(0.5).filter_by_class_id(person)

print(len(detections), len(people))
Text only
279 8

The model returned 279 detections; 8 are people with a confidence of 0.5 or more.

Confidence and class

Filter Keeps
filter_by_confidence(threshold) detections with a confidence of threshold or more
filter_by_class_id(class_ids) detections whose class_id is in class_ids: one id or a list
remap_class_ids(from_ids, to_id) every detection, with the ids in from_ids changed to to_id

filter_by_class_id compares class numbers, not names. Get the numbers from the model's class names, as above, rather than writing them by hand: the same number means different classes in different models.

remap_class_ids merges several classes into one, for example to count every two-wheeler together:

Python
two_wheelers = [predictor.class_names.index(name) for name in ("Motorcycle", "Scooter", "Bicycle")]
vehicles = detections.filter_by_confidence(0.3).filter_by_class_id(two_wheelers)
vehicles = vehicles.remap_class_ids(two_wheelers, two_wheelers[0])

The remapped detections have class_name set to None, because the old name no longer matches the new number.

Size and shape

Filter Keeps detections whose box
filter_by_size(min_area=None, max_area=None) has an area, in pixels, within the range
filter_by_dimensions(min_width=None, max_width=None, min_height=None, max_height=None) has a width and height, in pixels, within the ranges
filter_by_aspect_ratio(min_ratio=None, max_ratio=None) has a width ÷ height within the range
filter_by_relative_size(min_percent=None, max_percent=None, frame_width=None, frame_height=None) covers a share of the image within the range, from 0 to 1

Leave out a limit to keep everything on that side. All limits are inclusive.

Pixel sizes depend on the image size: in the same photo at half the width and height, every box covers a quarter of the pixels. When your images come in different sizes, filter_by_relative_size keeps the same objects in all of them:

Python
# people covering at least 2% of a 1920x1280 image
close = people.filter_by_relative_size(min_percent=0.02, frame_width=1920, frame_height=1280)

An aspect ratio below 1 means taller than wide: max_ratio=0.8 keeps standing people and drops boxes that are wider than they are tall.

Position in the image

filter_by_position keeps detections by where the center of their box is:

Python
left = people.filter_by_position("left", margin_percent=0.25, frame_width=1920, frame_height=1280)
region Keeps detections whose center is
"left", "right", "top", "bottom" within margin_percent of that side (0.25 = the outer quarter)
"edge" within margin_percent of any side
"corners" within margin_percent of two sides at once
"center" further than margin_percent from every side

margin_percent defaults to 0.1. frame_width and frame_height are required.

For any other area, such as a doorway or a lane, draw it as a zone: filter_by_zones(zone_ids, exclude=False) keeps the detections inside the zones you name, or outside them with exclude=True. It reads what Zones recorded, so run the zones first. See Count objects in a zone.

Duplicates and overlaps

Filter Keeps
remove_duplicates(iou_threshold=0.8, keep="first") one detection from each group of boxes that overlap by iou_threshold or more
filter_overlapping(min_overlap=0.5, target_class_ids=None) detections that overlap another detection by min_overlap or more

Overlap is measured as IoU: the area two boxes share divided by the area they cover together, from 0 (apart) to 1 (the same box).

Some models, or two models whose results you combine, give the same object twice. remove_duplicates keeps one from each group: keep="first", "last" or "highest_confidence".

filter_overlapping finds objects that appear together. With target_class_ids, it only counts overlaps with those classes: for example, the detections that overlap a person.

Tracked objects

After the tracker and TimeTracker have run on a video, three more filters use what they recorded:

Filter Keeps
filter_tracked_objects(require_tracker_id=True) detections the tracker gave an id, or with False, the ones it did not
filter_by_tracking_duration(min_seconds=None, max_seconds=None) objects seen for a time within the range
filter_by_first_seen_time(start_time=None, end_time=None) objects first seen within the time range

filter_by_tracking_duration(min_seconds=2) is a simple way to ignore objects that appear for a moment: a false detection rarely lasts two seconds.