Metadata-Version: 2.4
Name: detect-lib
Version: 0.1.7
Summary: A modular video object detection toolkit with a clean det-v1 JSON schema, pluggable backends, and optional model export.
Project-URL: Repository, https://github.com/Surya-Rayala/VideoPipeline-detection.git
Project-URL: Issues, https://github.com/Surya-Rayala/VideoPipeline-detection/issues
Author-email: Surya Chand Rayala <suryachand2k1@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Surya Chand Rayala
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: tqdm>=4.67.3
Requires-Dist: ultralytics>=8.4.14
Provides-Extra: coreml
Requires-Dist: coremltools>=9.0; extra == 'coreml'
Provides-Extra: export
Requires-Dist: onnx>=1.20.1; extra == 'export'
Requires-Dist: onnxruntime>=1.24.1; extra == 'export'
Provides-Extra: openvino
Requires-Dist: openvino>=2025.4.1; extra == 'openvino'
Provides-Extra: tf
Requires-Dist: tensorflow>=2.20.0; extra == 'tf'
Description-Content-Type: text/markdown

# 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

```json
{
  "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

```bash
pip install detect-lib
```

### Optional dependencies (pip extras)

Export helpers (ONNX + ONNXRuntime):

```bash
pip install "detect-lib[export]"
```

TensorFlow export paths (heavy):

```bash
pip install "detect-lib[tf]"
```

OpenVINO export:

```bash
pip install "detect-lib[openvino]"
```

CoreML export (macOS):

```bash
pip install "detect-lib[coreml]"
```

---

### CLI usage (pip)

Global help:

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

List detectors:

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

List models (registry + installed):

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

Basic command (detection):

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

Basic command (export):

```bash
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

```bash
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`:

```python
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:

```bash
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`:

```python
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:

```bash
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:

```bash
uv --version
```

### Install dependencies

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

### Optional dependencies (uv extras)

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

---

## CLI usage (uv)

Global help:

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

List detectors:

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

List models (registry + installed):

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

Basic command (detection):

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

Basic command (export):

```bash
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:

```bash
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):

```bash
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):

```bash
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`.
