Copyright (C) 2026 Code Metal

this is top level documentation and the parameter file

implemented as python modules: python -m truth_data_processing.georef_grab_frame

Pipeline order:

1. georef_grab_frame.py -- scrub the video, save one stable frame to anchor geometry of entire video

2. georef_pick_points.py -- click ground points on that frame, right click those points in google maps to get lat,lon. get 4+ points, try 6 points well spread out

3. georef_yolo_track.py -- run detection+tracking, project to lat/lon

--- Notes for collaborators (Marshall et al., different camera/site) -----

This pipeline is meant to be site-agnostic: this file is a documented

template -- copy it to README.yaml (or anything else) and fill in your own

values, or pass --config path/to/your.yaml to any script to point at your

own copy. README.yaml itself holds live per-deployment values with minimal

comments; this file is where the full explanations live.

Recent changes worth knowing about:

- start_s/end_s (added 2026-08-05): optional time window in seconds into

video. If set, georef_yolo_track.py auto-cuts+caches a clip via

ffmpeg (keyframe seek, no re-encode) instead of slow-seeking the full

video -- see that script's docstring. Omit both for the whole video.

- headless (added 2026-08-05): moved from a --headless CLI flag to this

config so it round-trips with the rest of the deployment's settings.

- out_pkl filenames get a _<start>-<end>s suffix auto-appended when

start_s/end_s are set, so time-windowed runs don't clobber a full-video

pkl (or each other).

- tracker_cfg default is botsort_persistent.yaml (BoT-SORT+ReID) rather

than bytetrack_persistent.yaml, specifically to reduce track-ID swaps

when objects cross paths -- see that yaml's comments before changing.

- botsort_persistent.yaml (2026-08-05): ReID model changed from "auto"

(reuses detector features -- not identity-discriminative) to

yolov8n-cls.pt (a real appearance embedder), and proximity_thresh

lowered 0.5->0.35 so ReID kicks in earlier during a crossing. Mike is

visually verifying this on his footage; if you're on different camera

hardware/framing, re-verify before trusting it -- see that yaml's

comments for the reasoning and revert path.

- export_mp4/export_speedup (added 2026-08-05): optional composited

16:9 review export, see below.

---------------------------------------------------------------------------

Source video for this deployment. Any resolution is fine -- everything

downstream works in this video's native pixel coordinates.

video: data_products/20260716/20260716_094852.mp4

Frame grabbed by georef_grab_frame.py, consumed by georef_pick_points.py.

frame_image: analysis_tools/truth_data_processing/georef_frame.png

Homography fit by georef_pick_points.py, consumed by georef_yolo_track.py.

Only valid for the exact frame resolution/framing it was fit against.

homography_yaml: analysis_tools/truth_data_processing/georef_homography.yaml

Where georef_yolo_track.py writes the final tracks.

out_pkl: data_products/20260716/camera_tracks.pkl

YOLO weights + tracker config

weights: analysis_tools/yolov8n.pt

botsort_persistent.yaml (BoT-SORT + ReID) fixes track-ID swaps that plain

ByteTrack (IoU-only, no appearance matching) is prone to when two

people/vehicles cross paths or pass close together -- see that yaml's

comments for why. bytetrack_persistent.yaml was dropped since it was just

a strict subset of botsort_persistent.yaml's tuned values with ReID

disabled; set tracker_type: bytetrack in a copy of this file if you need

the faster IoU-only tracker and can tolerate more ID swaps.

tracker_cfg: analysis_tools/truth_data_processing/botsort_persistent.yaml

Optional time window (seconds into the video) for georef_yolo_track.py.

Omit either or both to process from the start / to the end of the video.

Cuts a temp clip with ffmpeg (stream copy, no re-encode) instead of

seeking cv2.VideoCapture directly -- CAP_PROP_POS_FRAMES seeking has to

decode forward from the nearest keyframe, which is painfully slow for a

seek hours into a long video.

start_s: 30

end_s: 90

Skip the two live cv2.imshow preview windows in georef_yolo_track.py --

~35% faster (20.5fps -> 32fps in a profiling run). Omit or set false to

watch tracking live; use true for batch/full-video reprocessing.

headless: false

Optional: also (or instead -- works headless too) write the two views

(detection overlay + OSM map) composited side-by-side into one 16:9 MP4

at this path. Omit to skip exporting.

export_mp4: data_products/20260716/camera_tracks_review.mp4

Playback speedup for export_mp4: every frame is still written (no dropped

detections/frames), just tagged with a higher fps so a player runs through

it faster -- e.g. 6 plays the export at 6x speed. Omit/1 for real-time.

export_speedup: 6

Basemap center for the live map view in georef_yolo_track.py

basemap_center_lat: 42.3570028 basemap_center_lon: -71.0587402

OSM usage policy (https://operations.osmfoundation.org/policies/tiles/)

please replace with yourself

osm_user_agent: "georef_basemap.py (city_of_boston analysis_tools; mike@codemetal.ai)"