detect-lib 0.1.7

A modular video object detection toolkit with a clean det-v1 JSON schema, pluggable backends, and optional model export.

detect

A modular video object detection toolkit with a clean det-v1 JSON schema, pluggable backends, and optional model export.

Current backend:

• Ultralytics YOLO (bbox / pose / segmentation)

By default, detect does not write any files. You opt-in to saving JSON, frames, or annotated video via flags.

---

det-v1 output (returned + optionally saved)

detect always produces a canonical JSON payload in-memory with:

• schema_version: always "det-v1"
• video: input metadata (path, fps, frame_count, width, height)
• detector: detector settings used for the run (name, weights, classes, conf/imgsz/device/half)
• frames: per-frame detections
  • bbox detection: bbox = [x1, y1, x2, y2]
  • pose detection: keypoints = [[x, y, score], ...]
  • segmentation: segments = [[[x, y], ...], ...] (polygons)

Minimal schema example

{
  "schema_version": "det-v1",
  "video": {
    "path": "in.mp4",
    "fps": 30.0,
    "frame_count": 120,
    "width": 1920,
    "height": 1080
  },
  "detector": {
    "name": "yolo_bbox",
    "weights": "yolo26n",
    "classes": null,
    "conf_thresh": 0.25,
    "imgsz": 640,
    "device": "cpu",
    "half": false
  },
  "frames": [
    {
      "frame": 0,
      "file": "000000.jpg",
      "detections": [
        {
          "det_ind": 0,
          "bbox": [100.0, 50.0, 320.0, 240.0],
          "score": 0.91,
          "class_id": 0,
          "class_name": "person"
        }
      ]
    }
  ]
}

Returned vs saved

• Returned (always): the full det-v1 payload is available as DetectResult.payload (Python) or printed to stdout (CLI).
• Saved (opt-in): nothing is written unless you enable artifacts:
  • --json saves detections.json
  • --frames saves frames under frames/
  • --save-video saves an annotated video

When no artifacts are enabled, no output directory/run folder is created.

---

Install with pip (PyPI)

Use this if you want to install and use the tool without cloning the repo.

Python version

Requires Python 3.11+.

Install

pip install detect-lib

Optional dependencies (pip extras)

Export helpers (ONNX + ONNXRuntime):

pip install "detect-lib[export]"

TensorFlow export paths (heavy):

pip install "detect-lib[tf]"

OpenVINO export:

pip install "detect-lib[openvino]"

CoreML export (macOS):

pip install "detect-lib[coreml]"

---

CLI usage (pip)

Global help:

python -m detect.cli.detect_video -h
python -m detect.cli.export_model -h

List detectors:

python -c "import detect; print(detect.available_detectors())"

List models (registry + installed):

python -m detect.cli.detect_video --list-models
python -m detect.cli.export_model --list-models

Basic command (detection):

python -m detect.cli.detect_video \
  --video <in.mp4> \
  --detector yolo_bbox \
  --weights yolo26n

Basic command (export):

python -m detect.cli.export_model \
  --weights yolo26n \
  --formats onnx \
  --out-dir models/exports --run-name y26_onnx

---

Python usage (import)

You can use detect as a library after installing detect-lib with pip.

Quick sanity check

python -c "import detect; print(detect.available_detectors())"

Python API reference (keywords)

detect.detect_video(...)

Required

• video (str | Path): input video path.
• detector (str): detector name (e.g. yolo_bbox, yolo_pose, yolo_seg).
• weights (str | Path): registry key, local weights path, or URL.

Common options

• classes (list[int] | None): restrict to specific class ids.
• conf_thresh (float): confidence threshold (default 0.25).
• imgsz (int): inference image size (default 640).
• device (str): device selector (e.g. auto, cpu, mps, 0).
• half (bool): enable FP16 inference where supported.

Artifacts (all off by default)

• save_json (bool): save detections.json.
• save_frames (bool): save extracted frames under frames/.
• save_video (str | None): filename for annotated video (e.g. "annotated.mp4").
• out_dir (str | Path): output root (used only if saving artifacts; default out).
• run_name (str | None): run folder name under out_dir.
• progress (bool): enable/disable progress bar.
• display (bool): show live window (press q to quit).

Returns a DetectResult with payload (det-v1 JSON) and paths (only populated when saving).

Run detection from a Python file

Create run_detect.py:

from detect import detect_video

res = detect_video(
    video="in.mp4",
    detector="yolo_bbox",
    weights="yolo26n",
)

payload = res.payload
print(payload["schema_version"], len(payload["frames"]))
print(res.paths)  # populated only if you enable saving artifacts

Run:

python run_detect.py

Run model export from a Python file

Requires export extras based on the type of export needed (e.g., pip install "detect-lib[export]").

detect.export_model(...)

Required

• weights (str | Path): registry key, local weights path, or URL (must be a .pt PyTorch model for export).

Common options

• formats (list[str] | str): formats to export (default "onnx").
• imgsz (int | tuple[int,int]): export image size (default 640).
• device (str | None): export device (e.g. "cpu", "mps", "0").
• half (bool): FP16 export where supported.
• int8 (bool): INT8 export (format/toolchain-dependent).
• data (str | None): dataset YAML for INT8 calibration (when required).
• fraction (float): fraction of dataset for calibration (default 1.0).
• dynamic (bool): dynamic shapes where supported.
• batch (int): export batch size (default 1).
• opset (int | None): ONNX opset.
• simplify (bool): simplify ONNX graph.
• workspace (int | None): TensorRT workspace (GB).
• nms (bool): add NMS where supported.
• out_dir (str | Path): output root (default models/exports).
• run_name (str | None): export run folder name under out_dir.

Returns a dict with run_dir, artifacts (paths), and meta_path.

Create run_export.py:

from detect import export_model

res = export_model(
    weights="yolo26n",
    formats=["onnx"],
    imgsz=640,
    out_dir="models/exports",
    run_name="y26_onnx_py",
)

print("run_dir:", res["run_dir"])
print("artifacts:")
for p in res["artifacts"]:
    print(" -", p)

Run it:

python run_export.py

---

Install from GitHub (uv)

Use this if you are developing locally or want reproducible project environments.

Install uv:
https://docs.astral.sh/uv/getting-started/installation/#standalone-installer

Verify:

uv --version

Install dependencies

git clone https://github.com/Surya-Rayala/VideoPipeline-detection.git
cd VideoPipeline-detection
uv sync

Optional dependencies (uv extras)

uv sync --extra export
uv sync --extra tf
uv sync --extra openvino
uv sync --extra coreml

---

CLI usage (uv)

Global help:

uv run python -m detect.cli.detect_video -h
uv run python -m detect.cli.export_model -h

List detectors:

uv run python -c "import detect; print(detect.available_detectors())"

List models (registry + installed):

uv run python -m detect.cli.detect_video --list-models
uv run python -m detect.cli.export_model --list-models

Basic command (detection):

uv run python -m detect.cli.detect_video \
  --video <in.mp4> \
  --detector yolo_bbox \
  --weights yolo26n

Basic command (export):

uv run python -m detect.cli.export_model \
  --weights yolo26n \
  --formats onnx \
  --out-dir models/exports --run-name y26_onnx

---

TensorRT / engine export and run notes (important)

Exporting engine (TensorRT) typically requires an NVIDIA GPU + CUDA + TensorRT installed and version-compatible.

Export TensorRT engine:

uv run python -m detect.cli.export_model \
  --weights yolo26n \
  --formats engine \
  --device 0 \
  --out-dir models/exports --run-name y26_trt

Run / sanity-check the exported engine using this package (produces det-v1 output):

uv run python -m detect.cli.detect_video \
  --video in.mp4 \
  --detector yolo_bbox \
  --weights models/exports/y26_trt/yolo26n.engine \
  --device 0

Optionally save artifacts (JSON + annotated video):

uv run python -m detect.cli.detect_video \
  --video in.mp4 \
  --detector yolo_bbox \
  --weights models/exports/y26_trt/yolo26n.engine \
  --device 0 \
  --json \
  --save-video annotated_engine.mp4 \
  --out-dir out --run-name y26_trt_check

---

CLI arguments

Detection: detect.cli.detect_video

Required

• --video <path>: Path to the input video file.
• --detector <name>: Detector type (yolo_bbox, yolo_pose, or yolo_seg).
• --weights <id|path|url>: Registry key, local weights path, or URL to weights.

Detection options

• --classes <ids>: Filter to specific class IDs (comma/semicolon-separated), or omit for all classes.
• --conf-thresh <float>: Confidence threshold for detections (default 0.25).
• --imgsz <int>: Inference image size used by the backend (default 640).
• --device <str>: Device selector (e.g., auto, cpu, mps, 0).
• --half: Enable FP16 inference where supported.

Artifact saving (opt-in)

• --json: Save detections.json under the run directory.
• --frames: Save extracted frames as images under the run directory.
• --save-video <name.mp4>: Save an annotated video under the run directory.
• --display: Show live visualization window while running (press q to quit).

Output control

• --out-dir <dir>: Output root directory used only if saving artifacts (default out).
• --run-name <name>: Run folder name inside out-dir (auto-derived if omitted).

Model registry / downloads

• --models-dir <dir>: Directory where models are stored/downloaded (default models).
• --no-download: Disable automatic download for registry keys/URLs.

Misc

• --no-progress: Disable progress bar output.
• --list-models: Print registry + installed models then exit.

---

Export: detect.cli.export_model

Required

• --weights <id|path|url>: Registry key, local weights path, or URL to weights.

Export options

• --formats <list>: Comma/semicolon-separated export formats (default onnx).
• --imgsz <int|H,W>: Export image size as an int or H,W pair (default 640).
• --device <str>: Export device selector (e.g., cpu, mps, 0).
• --half: Enable FP16 export where supported.
• --int8: Enable INT8 quantization (format/toolchain-dependent).
• --data <yaml>: Dataset YAML for INT8 calibration (when required).
• --fraction <float>: Fraction of dataset used for calibration (default 1.0).
• --dynamic: Enable dynamic shapes where supported.
• --batch <int>: Export batch size (default 1).
• --opset <int>: ONNX opset version.
• --simplify: Simplify the ONNX graph.
• --workspace <int>: TensorRT workspace size in GB.
• --nms: Add NMS to exported model when supported by format/backend.

Output control

• --out-dir <dir>: Output root directory for exports (default models/exports).
• --run-name <name>: Export run folder name inside out-dir.

Model registry / downloads

• --models-dir <dir>: Directory where models are stored/downloaded (default models).
• --no-download: Disable automatic download for registry keys/URLs.

Misc

• --list-models: Print registry + installed models then exit.

---

License

MIT License. See LICENSE.