discover_objects

rapidtools.processing.street_tracking.discover_objects(observations: Sequence[Observation], method: str = 'tracks', camera_height_m: float = 2.4, min_range_m: float = 2.0, max_range_m: float = 60.0, min_area_fraction: float = 5e-06, bearing_sigma_deg: float = 0.75, min_parallax_deg: float = 8.0, max_merge_m: float = 6.0, merge_floor_m: float = 0.5, track_gap_frames: int = 2, merge_pieces_of_neighbours: bool = True, close_range_m: float = 20.0, far_min_parallax_deg: float = 45.0, far_max_sigma_m: float = 0.5, min_sighting_deg: float = 6.0, report_single_views: bool = False, abeam_window_deg: float = 0.0, min_path_distance_m: float = 1.5, min_object_width_m: float = 1.0, object_height_m: float = 1.5, object_size_m: float = 4.5, vote_cell_m: float = 0.5, min_vote_score: float = 1.5, max_single_view_range_m: float = 30.0, frames: Sequence[CameraFrame] | None = None, witness_radius_m: float = 12.0) → tuple[list[ObjectEstimate], dict[str, int], Callable[[float, float], tuple[float, float]]]

Turn the sightings of one class into object estimates.

Parameters:

• observations – Sightings of one class (any number of sequences).

• method – 'tracks' for track-then-triangulate with covariance merging, 'voting' for the ray-voting baseline.

• camera_height_m – Camera height above the ground, for single-view ranges.

• min_range_m – Closest plausible object.

• max_range_m – Farthest triangulated position reported.

• min_area_fraction – Outline area below which a detection is decoding noise; the default only removes garbage.

• bearing_sigma_deg – One-sigma bearing error.

• min_parallax_deg – Smallest bearing separation that counts as parallax.

• max_merge_m – Farthest two estimates can be and still be one object.

• merge_floor_m – Viewpoint-dependent centre wander added to the merge gate.

• track_gap_frames – Frames a track may miss before it is closed.

• merge_pieces_of_neighbours – After the position merge, fold objects whose closest sightings show a better-located neighbour into that neighbour (see merge_pieces()): the second track a detector’s split outline or a tracker sliding between vehicles lined up along the line of sight leaves behind.

• close_range_m – Range within which an object must have been seen to be trusted. Ground-contact ranges read from farther away are off by a third and the tracker hops between vehicles lined up down the road, so an object never seen within this range whose closest rays point at an object within 15 m that was seen up close is a far sighting of that object and is dropped, unless it is well triangulated regardless: parallax of at least far_min_parallax_deg and uncertainty of at most far_max_sigma_m. One whose rays point elsewhere, a car in a driveway behind the kerb, stays. Also the range the piece merge judges sightings by. 0 keeps every object.

• far_min_parallax_deg – Parallax that lets a far-only object through.

• far_max_sigma_m – Uncertainty that lets a far-only object through.

• min_sighting_deg – An object must have been seen at least once with an outline this wide or tall, in degrees of the panorama (6 degrees is 34 pixels on a 2048-pixel thumbnail and 225 on the original). What was never more than a speck cannot be identified by anyone and is not reported; a drive-by survey sees anything worth counting properly in some frame. The specks still take part in tracking, where they lend parallax. 0 keeps every object.

• report_single_views – Keep objects placed from ground-contact ranges alone, without parallax. Their positions are guesses and, on the surveys tried, none was worth keeping; off by default.

• abeam_window_deg – Objects are built only from the sightings made while passing them, within this many degrees of abeam on either side of the direction of travel (see split_by_view()). A drive-by survey passes everything worth counting, and the passing frames carry the widest parallax and the largest outlines; the frames looking ahead or behind down the road have rays nearly parallel to it, cannot place anything, and are where tracks slide between vehicles that line up. Those sightings are attached afterwards to the objects their rays point at (attach_approach_sightings()), so records stay complete, but they never create an object. Off (0) by default: on the Spokane survey a 75-degree window lost 17 of 382 verified vehicles, because the track classification (the moving-vehicle, parallax and size tests) was tuned on tracks that include the approach, and a pass alone trips them; with the far-sighting gates in place it removed few duplicates in return. Kept as an option for when the classifier is reworked for passes alone.

• min_path_distance_m – Objects closer than this to the line the camera drove are discarded: the survey vehicle passed through that spot, so whatever was seen there was moving (or is the vehicle itself).

• min_object_width_m – Objects narrower than this at their estimated distance are fragments or false detections.

• object_height_m – Typical height of the class, for the occlusion-aware moving check.

• object_size_m – Object footprint used by the voting baseline.

• vote_cell_m – Grid cell of the voting baseline.

• min_vote_score – Peak threshold of the voting baseline.

• max_single_view_range_m – A single-view position whose nearest sighting is farther than this is not reported: at that distance the ground-contact range is a guess, not a measurement. Such far fragments still take part in merging first, so a far view of a well-located object joins it rather than being lost. 0 disables the cut.

• frames – Every frame of the survey as CameraFrame records, including frames with no sighting of the class. When given, estimates that nearby same-day frames should have seen but did not are dropped (see prune_unwitnessed()).

• witness_radius_m – Radius of that check; 0 disables it.

Returns:

tuple – (estimates, counts, unproject) where counts reports 'sightings', 'with_bearing', 'duplicates' (detector outlines resolved within a frame), 'tracks', 'moving', 'fragment', 'on_path', 'far_single_view', 'unwitnessed' and 'objects', and unproject converts local metres back to (lon, lat).