nicholaskajoh/ivy

Ivy is a single-process Python video analytics pipeline for object counting. The architecture is centered on reading frames from a video source, detecting objects, tracking them across frames, and incrementing counts when tracked objects cross a configured region.

1. Runtime entrypoint and orchestration

- main.py is the application entrypoint.

- It likely wires together configuration, detector selection, video/job setup, the tracker, the counter, and the debug UI.

- ObjectCounter.py appears to be the top-level counting workflow/class that coordinates per-frame processing.

2. Core processing pipeline

- The main data flow is: video/frame source → detector → detection post-processing → tracker → counter → logs/debug output.

- Each frame is analyzed independently, but object identity is preserved across frames by tracking.

- The system is designed around continuous streaming rather than batch processing.

3. Detector abstraction boundary

- detectors/detector.py defines the detector interface/contract.

- The concrete detector implementations are:

- detectors/yolo.py

- detectors/tfoda.py

- detectors/detectron2.py

- detectors/haarcascade.py

- This is the main pluggable boundary in the repo: detection backend can be swapped without changing downstream tracking/counting logic.

4. Detection backends and external ML dependencies

- YOLO, TensorFlow Object Detection API, Detectron2, and Haar cascades are supported.

- These are not just libraries; they materially change deployment/runtime requirements.

- The README indicates optional framework installation depending on detector choice, so the repository supports multiple ML stacks under a common interface.

5. Tracking subsystem

- tracker.py maintains object continuity across frames.

- Its role is to transform per-frame detections into persistent tracked objects, which is necessary for stable counting and for avoiding double-counting.

- Tracking is a separate concern from detection, which keeps detector output simple and lets the counting logic operate on identities rather than raw boxes.

6. Counting and object state

- counter.py implements the counting rules.

- It likely consumes tracked objects and decides when an object has entered/exited a region of interest or crossed a counting boundary.

- util/object_info.py and util/blob.py likely carry object state, geometry, and per-object metadata used by the counter and tracker.

7. Spatial and geometry utilities

- util/bounding_box.py handles box math and intersection/centroid logic.

- util/detection_roi.py likely defines the count line or region-of-interest boundary.

- util/image.py probably provides frame/image preprocessing and annotation helpers.

- These utilities form the geometric layer between raw detector output and higher-level counting decisions.

8. Debugging and visualization

- util/debugger.py and the README’s debug mode indicate an interactive visualization layer.

- The app can display the live processing window, pause/play, capture screenshots, and log clicked coordinates.

- This is an important operational boundary: it does not affect counting logic directly, but it is essential for tuning and validation.

9. Configuration and job model

- settings.py, .env.example, and util/job.py suggest runtime configuration is driven by environment variables plus a job/config object.

- The job layer probably encapsulates video source, detector choice, model paths, thresholds, and output options.

- This keeps deployment settings separate from the processing code.

10. Logging and observability

- util/logger.py centralizes logging behavior.

- The README explicitly mentions analyzing logs, so logs are a first-class output of the application.

- Logging likely captures counts, tracker events, detector selection, and debug/runtime issues.

11. Input data and model assets

- The data/ directory is the local asset boundary for sample videos, detector weights, and demo content.

- The README’s demo package unpacks into data, so runtime assets are expected to live there rather than being fetched dynamically.

12. Testing boundary

- tests/ covers utility components such as blobs, bounding boxes, debugger, job, logger, and vehicle/object info.

- The test suite is focused on deterministic logic rather than model accuracy, which makes sense for a pipeline that depends on external detector frameworks.

- pytest.ini and coverage config show the repo is structured for unit testing of core geometry/state logic.

13. Deployment and packaging

- Dockerfile provides containerized execution.

- .github/workflows/ivy.yml indicates CI automation, likely for tests and linting.

- requirements.txt, .pylintrc, and .coveragerc reinforce that the repo is packaged as a Python application with quality gates.

14. Architectural summary

- Ivy’s main architectural split is between:

- perception: detector backends,

- temporal continuity: tracking,

- business logic: counting,

- supporting concerns: config, logging, debugging, and geometry utilities.

- The most important diagram boundary is the interface between detector output and tracker/counter input, because that is where a raw CV model becomes a counted object stream.