womprat

KO | EN

gitlite — search

#golang #go #rust #deep-learning #docker #macos #nodejs #java #windows #awesome #kubernetes #vue #ios #openai

(★ 21)

CPU-only single-target drone tracker (C-UAS) — classical CV, no GPU required

womprat 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# womprat — single-target drone tracker (C-UAS)

A clean-room, CPU-only visual tracker for small/distant **drones (UAS)** in video.
It locks onto one target and follows it frame-to-frame, designed to run on
edge hardware (e.g. a quad-core Raspberry Pi, no GPU). The Python package is
named `womprat`; the repo directory is `womprat`.

## Goal

Counter-UAS (C-UAS) tracking: given a video feed and an initial target box,
keep a stable lock on a drone that is often only ~30–60 px across, against sky
clutter, birds, and camera motion — recovering the lock after brief occlusion
or detector dropout. Accuracy is measured with standard MOT metrics
(IDF1, MOTA, center RMSE, lost-frames, ID switches) plus a small-target
"tracked@gate" rate, all at real-time FPS.

## Design

Womprat combines a classical blob detector, Kalman motion model, gated
association, lightweight appearance cues, and explicit lock/recovery states.
Its canonical `small` profile has been tuned and validated across six datasets
while retaining deterministic CPU-only execution.

> Datasets, local analysis material, model weights, and generated media are
> git-ignored and are not part of the source distribution.

## Layout

```
src/womprat/               Core tracker library (the package)
  api.py                  Tracker: profiles, lock(), update(); detector + manager wiring
  detector/blob.py        Motion + top-hat blob detector (CPU, tiled morphology)
  tracking/               kalman.py, association.py (IoU/center-distance), track.py, manager.py
  appearance.py           Template + descriptor for re-association/recovery
  types.py, telemetry.py  Detection/TrackResult dataclasses; instrumentation
src/webapp/               FastAPI live demo "track console" (app.py, annotate.py, sources.py)
benchmark/                Eval + tuning harness (see below)
tests/                    33 pytest modules (unit + dataset + e2e)
data/                     Datasets (git-ignored): anti-uav300, dvb-videos, dvb-annotations, uploads
reports/                  Benchmark output (git-ignored): written by the harness
yolo26n.pt, yolov8n.pt    Optional YOLO detector weights (alternative to blob detector)
```

The web console is a development/demo harness with no authentication. Run it
only on localhost or a trusted network; it is not a production web service.

## Setup

Python 3.10+. Create a local virtual environment and install the development
and web extras:

```bash
# (re)create if needed:
python -m venv .venv && .venv/bin/pip install -e '.[dev,web]'
```

Core deps: `numpy`, `scipy`, `opencv-python-headless`, `motmetrics`.
Extras: `[dev]` → pytest; `[web]` → fastapi, uvicorn, python-multipart.

## Run the live web demo (track console)

```bash
PYTHONPATH=src .venv/bin/python -m webapp      # serves on 0.0.0.0:8000
```

Open http://localhost:8000/ . The UI lets you pick/upload a clip, click-to-lock
a single target, and watch the annotated MJPEG track stream.

API routes (`src/webapp/app.py`):
- `GET /` — track-console UI
- `GET /api/sources` — list available clips (built-in + uploads)
- `POST /api/upload` — upload a video (`.mp4/.avi/.mpg/.mov/.mkv`, ≤500 MB)
- `GET /first_frame?source=…` — first frame (for drawing the lock box)
- `GET /stream?source=…&lock=x,y,w,h&profile=…&<detector params>` — annotated MJPEG track stream

## Library usage

```python
from womprat import Tracker
tracker = Tracker(profile="small")        # default | small | pi4-target
tracker.lock(frame0, bbox=(x, y, w, h))   # seed the single target
for frame in video:
    results = tracker.update(frame, dt=None)   # dt seconds for variable-rate; None = fixed 1/30
    # each result: id, state, cx/cy, bbox, confidence, speed, reason, frame
```

Profiles live in `src/womprat/api.py` (`_PROFILES` / `_DETECTOR_PROFILES`). The
`small` profile is the canonical small/distant-drone config, tuned and validated
against the benchmark suite below — validate any change to it the same way.

## Testing

```bash
.venv/bin/python -m pytest -q              # full suite (pythonpath=src is auto-set)
.venv/bin/python -m pytest tests/test_anti_uav.py -q   # dataset smoke (expects 2 passed)
.venv/bin/python -m pytest tests/test_webapp.py -q     # web API tests
```

## End-to-end / benchmark evaluation

The `benchmark/` package scores the tracker against annotated footage and is
how tracker changes are validated (run from the repo root with the venv).

**Multi-sequence suite** (the primary e2e gate — writes `suite_report.md` +
`suite_aggregate.json`):

```bash
.venv/bin/python -m benchmark.suite \
  --manifest benchmark/manifests/anti_uav300_val_small.json \
  --out reports/my-run --profile small [--baseline] [--save-baseline]
.venv/bin/python -m benchmark.suite --select        # regenerate suite_manifest.json from test split
```

**Single sequence** (writes `report.md` + MOT `predictions.txt`):

```bash
.venv/bin/python -m benchmark.run_benchmark <seq_dir> [modality] [profile]
```

Other harness entry points: `benchmark/tune_tracker.py` (param search),
`benchmark/calibrate_detector.py` / `calibrate_detector_small.py` (detector
calibration), `benchmark/motion_detect_eval.py`, `benchmark/locked_eval.py`,
and the YOLO alternative-detector path `benchmark/yolo_train.py` /
`benchmark/yolo_detect_eval.py` (`recall|track|combo`).

### Datasets (`data/`, git-ignored)

| Dataset | Path | What |
|---|---|---|
| Anti-UAV300 | `data/anti-uav300/{train,val,test}` | Per-frame drone boxes + target-exists flags; primary small-target benchmark |
| Drone-vs-Bird | `data/dvb-videos/`, `data/dvb-annotations/` | DvB Challenge clips + annotations (drone/bird discrimination) |

**Split policy:** tune on `train`, promote on `val`, and treat `test` as a
final holdout only (do **not** tune against it). Fixed manifests are committed
under `benchmark/manifests/`.

## Changing the tracker

Tracker changes are validated as measured experiments: record the benchmark
suite before the change, make one scoped change, and re-run the suite on the
same manifest. Tune on `train`, promote on `val`, and leave `test` as a holdout.

## License

Womprat is licensed under the Apache License 2.0. See `LICENSE` and `NOTICE`.
Third-party datasets, media, and optional model weights are not included in the
license grant and remain subject to their own terms.

womprat

womprat 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

womprat

womprat 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README