---
license: apache-2.0
library_name: pytorch
tags:
  - wildfire
  - smoke-detection
  - object-detection
  - temporal
---

# Temporal Smoke Model (bbox-tube-temporal)

> **Latest release:** [`v0.2.0`](https://huggingface.co/pyronear/temporal-model/tree/v0.2.0) — pin this revision for reproducibility, or omit `revision=` to always get the latest. All releases: the **Files and versions** tab.

A temporal wildfire-**smoke** classifier for short sequences of camera frames. A
YOLO detector proposes boxes, boxes are linked across frames into temporal
**tubes**, each tube's image patches are classified by a DINOv2 ViT + transformer
head, and a logistic calibrator turns the tube logits into a calibrated
probability and a keep/discard decision.

This repo ships a single self-contained **`model.zip`**, versioned by HuggingFace
revision/tag (`v<version>`). Each release bundles everything needed to run:

| file | purpose |
|---|---|
| `manifest.yaml` | version + provenance (train git SHA, backbone, detector) |
| `yolo_weights.pt` | the companion YOLO detector |
| `classifier.ckpt` | the temporal ViT classifier |
| `config.yaml` | inference + decision config |
| `logistic_calibrator.json` | the calibrated decision head |

The model runs YOLO **itself** — you pass only raw frames, no detections.

## Usage

Install the inference package (`temporal_model.core`):

```bash
pip install "git+https://github.com/pyronear/temporal-model.git#subdirectory=core"
```

Download a versioned `model.zip` and run it on a **temporally ordered** sequence
of frames:

```python
from pathlib import Path

from huggingface_hub import hf_hub_download
from temporal_model.core.model import BboxTubeTemporalModel

# 1. Download a specific release (pin the revision).
model_zip = hf_hub_download("pyronear/temporal-model", "model.zip", revision="v0.2.0")

# 2. Temporally-ordered frames. Filenames carry timestamps
#    (<prefix>_<YYYY-MM-DDTHH-MM-SS>.jpg); the order is the time order.
frame_paths = sorted(Path("my_sequence").glob("*.jpg"))

# 3. Load (device=None → auto cuda → mps → cpu) and predict.
#    hf_hub_download returns a str, so wrap it in Path().
model = BboxTubeTemporalModel.from_package(Path(model_zip), device=None)
out = model.predict_sequence(frame_paths)

print("is_smoke:           ", out.is_positive)
print("trigger_frame_index:", out.trigger_frame_index)  # 0-based; None if no smoke

# Per-tube breakdown (logits, calibrated probabilities, bboxes, decision).
kept = out.details.get("tubes", {}).get("kept", [])
print("kept tubes:         ", len(kept))
```

`predict_sequence(frame_paths)` returns a `TemporalModelOutput`:

- `is_positive: bool` — the smoke verdict.
- `trigger_frame_index: int | None` — 0-based frame where smoke first crosses the
  decision threshold (time-to-detection, in frames; `None` when no smoke).
- `details: dict` — per-tube logits, calibrated probabilities, bboxes, and the
  decision (`aggregation`, `threshold`, trigger tube).

## Served API (Docker)

The same model is also served as a FastAPI image with the `model.zip` baked in
(auto-uses the GPU with `--gpus all`):

```bash
docker run --gpus all -p 8000:8000 \
  -e TEMPORAL_API_S3_BUCKET=<frames-bucket> \
  -e TEMPORAL_API_S3_ENDPOINT_URL=<s3-endpoint> \
  pyronear/temporal-model-api:0.2.0
# POST /predict  {"frames": ["<s3-key>", ...]}      GET /health
```

## Provenance

Every `model.zip` manifest records how it was built — the training git SHA, the
classifier backbone (`vit_small_patch14_dinov2.lvd142m`), and the exact companion
detector (e.g. `pyronear/yolo11s_nimble-narwhal_v6.0.0`, verified by SHA-256). So
a served model always traces back to its detector + training code.

Source & pipeline: <https://github.com/pyronear/temporal-model>