Skip to content

Latest commit

 

History

325 Commits

Folders and files

Repository files navigation

PyroNear Logo

CI Status Documentation Status Test coverage percentage ruff

PyPi Version DockerHub version Supported Python versions license

PyroEngine repository

This repository contains two main components used in Pyronear wildfire detection deployments: pyroengine and pyro_camera_api

Directory Description
pyroengine/ Detection engine that runs the wildfire model on edge devices
pyro_camera_api/ Camera control API that exposes a unified interface for multiple adapters
scripts/ Shell scripts for deployment and debugging
src/ Helper scripts for camera control, focus, calibration and experiments
tests/ Test suite for the detection engine

Both components can run independently or together in the same deployment.


PyroEngine: wildfire detection on edge devices

PyroEngine provides a high level interface to use deep learning models in production while being connected to the alert API.

Quick example

from pyroengine.core import Engine
from PIL import Image

engine = Engine()

im = Image.open("path/to/your/image.jpg").convert("RGB")

prediction = engine.predict(im)

PyroCamera API: unified camera control

The pyro_camera_api package provides a REST API and a Python client to control cameras and retrieve images in a unified way.

The API supports multiple camera adapters through a common abstraction:

  • reolink adapter, for Reolink PTZ or static cameras
  • linovision adapter, for Linovision PTZ cameras using ISAPI
  • hikvision adapter, for Hikvision PTZ cameras using ISAPI
  • rtsp adapter, for RTSP streams
  • url adapter, for HTTP snapshot URLs
  • rest adapter, for HTTP APIs needing auth headers or returning a JSON-wrapped image
  • ctronics adapter, for CTronics cameras exposing an authenticated HTTP snapshot endpoint and optional ONVIF PTZ/focus
  • mock adapter, for development and tests

Each adapter has its own class and inherits from the same base interface. The system selects the correct implementation at runtime based on the adapter field in credentials.json. The API routes are the same for all camera types. PTZ cameras use pose and movement, other cameras ignore pose parameters without failing.

If your camera is not covered by the adapters above, see the camera adapter guide. It explains what an adapter is responsible for, how to tell whether a generic adapter already fits, and how to write a new one.

Simple API usage example

from pyro_camera_api_client import Client

client = Client("http://localhost:8000")

# Move a PTZ camera to a pose
client.move("ptz_camera_1", pose=2)

# Get a snapshot as bytes
image_bytes = client.snapshot("url_camera_1")

Setup

Python 3.11 or higher and uv are required.

Developer installation

git clone https://github.com/pyronear/pyro-engine.git
cd pyro-engine
uv sync --locked

Environment variables

Deployments usually rely on a .env file. A .env.example is provided at the root of the repository as a reference:

API_URL=https://api.pyronear.org
CAM_USER=my_dummy_login
CAM_PWD=my_dummy_pwd
MEDIAMTX_SERVER_IP=1.2.3.4
PYRO_ENGINE_VERSION=latest
LOG_LEVEL=INFO

PYRO_ENGINE_VERSION controls which Docker image tag is pulled for the services (defaults to latest if unset).

Optional temporal validation of alerts: with COMPOSE_PROFILES=temporal and TEMPORAL_API_URL=http://localhost:8082 in .env, the stack also starts pyro_temporal_api. While an alert is ongoing, the engine sends the last frames and boxes of that camera pose to it every round and uploads each box with the smoke probability of the tube covering it (temporal_model_scores); boxes at or below 0.2 or outside every scored tube are dropped, and the API applies its own threshold instead of running the temporal model itself. If the service is unreachable the frames go out without scores until it answers again, and the API scores the sequences the device never scored. Leave both unset to send alerts as before. On first start the service downloads its model into data/temporal_models: the temporal-model release on Hugging Face (pyronear/temporal-model, revision v0.6.1, trained on pyro-dataset v4.7.0), pinned in pyro_temporal_api/main.py. Set TEMPORAL_MODEL_PATH to load another package instead. The release package carries split backbone/head graphs. With those, the service embeds only real frames and keeps per-frame ViT embeddings across rounds, so re-scoring a window one frame longer only costs the new frame (as long as the tube's crop window does not move). A fused single-graph package still loads, without these savings.

LOG_LEVEL sets the verbosity of both services (defaults to INFO). At INFO a quiet patrol round is one summary line per camera cycle and one per inference round; detections, alerts and failures are always reported. Set LOG_LEVEL=DEBUG to also get per-pose captures, raw model predictions, ffmpeg output and HTTP access logs.

Docker builds and runtime isolation

Both images install only locked runtime dependencies into /opt/venv with uv. Dependency layers are built before application code, and BuildKit cache mounts reuse downloaded wheels. Git, uv, Python package installers and build caches stay outside the final runtime. The engine uses headless OpenCV without an FFmpeg/GUI installation; FFmpeg remains in the camera service for RTSP/SRT streaming.

BuildKit is required (enabled by default in current Docker versions):

make build-app
make build-api
# Or build both services from their committed locks:
docker compose build

Images retain the current root identity to read pi-manager's root-owned data and credentials. A non-root deployment migration is deferred to the station deployment work. The writable data bind mount holds model downloads, Hugging Face caches, backups, camera-control debug captures and the engine heartbeat. Compose uses a read-only root filesystem, drops Linux capabilities and disallows privilege escalation. /tmp and optional camera focus_debug images use bounded temporary filesystems; focus-debug captures are cleared when the container stops. To retain those debug images, override /usr/src/app/focus_debug with a writable bind mount.

make lock and make lock-api update the corresponding locks and legacy requirements exports. Image builds consume the committed locks and fail if dependency declarations do not match them; they do not resolve newer packages implicitly.

Data directory

A ./data directory is expected with at least:

  • credentials.json, see Camera configuration to understand how to fill it
  • optionally model.onnx to override weights from Hugging Face
  • optionally config.json to override model configuration

Camera configuration and adapters

The camera configuration is stored in credentials.json. Each key represents a camera identifier and the entry defines how to access and control it.

The important field for the camera API is:

  • adapter which selects the camera implementation

Other fields such as type, pose_ids, poses, or bbox_mask_url are used by the engine and the API.

pose_ids contains the pose IDs from the pyro-api database. For static cameras it is a list with a single element; for PTZ cameras each entry corresponds positionally to the matching physical preset in poses. If bbox_mask_url is set, occlusion mask files are fetched at {bbox_mask_url}_{pose_id}.json.

Below is one generic example for each adapter: url, rtsp, reolink static, reolink PTZ and mock.

{
  "url_camera_1": {
    "name": "url_camera_1",
    "adapter": "url",
    "url": "http://user:password@camera-host:1234/cgi-bin/snapshot.cgi",
    "pose_ids": [10],
    "id": "10",
    "bbox_mask_url": "",
    "poses": [],
    "token": "JWT_TOKEN_HERE",
    "type": "static"
  },

  "rtsp_camera_1": {
    "name": "rtsp_camera_1",
    "adapter": "rtsp",
    "rtsp_url": "rtsp://user:password@camera-host:554/live/STREAM_ID",
    "pose_ids": [11],
    "id": "11",
    "bbox_mask_url": "https://example.com/occlusion-masks/rtsp_camera_1",
    "poses": [],
    "token": "JWT_TOKEN_HERE",
    "type": "static"
  },

  "192.168.1.11": {
    "name": "reolink_static_1",
    "adapter": "reolink",
    "type": "static",
    "pose_ids": [12],
    "id": "12",
    "poses": [],
    "bbox_mask_url": "https://example.com/occlusion-masks/reolink_static_1",
    "token": "JWT_TOKEN_HERE"
  },

  "192.168.1.12": {
    "name": "reolink_ptz_1",
    "adapter": "reolink",
    "type": "ptz",
    "id": "13",
    "poses": [0, 1, 2, 3],
    "pose_ids": [20, 21, 22, 23],
    "bbox_mask_url": "https://example.com/occlusion-masks/reolink_ptz_1",
    "token": "JWT_TOKEN_HERE"
  },

  "192.168.1.13": {
    "name": "linovision_ptz_1",
    "adapter": "linovision",
    "type": "ptz",
    "poses": [0, 1, 2, 3],
    "pose_ids": [30, 31, 32, 33],
    "azimuth_offset_deg": 90,
    "bbox_mask_url": "https://example.com/occlusion-masks/linovision_ptz_1",
    "token": "JWT_TOKEN_HERE"
  },

  "mock_camera_1": {
    "name": "mock_camera_1",
    "adapter": "mock",
    "type": "static",
    "pose_ids": [0],
    "id": "14",
    "poses": [],
    "bbox_mask_url": "",
    "token": "JWT_TOKEN_HERE"
  }
}

These examples are only for illustration. Real deployments use real URLs and real tokens generated by the alert API. For Linovision/Hikvision, username/password override the global CAM_USER/CAM_PWD, azimuth_offset_deg aligns camera coordinates to real azimuths, and snapshot_channel/ptz_channel let you pick the right ISAPI channels.

For CTronics, use adapter: "ctronics" with ip_address (or the configuration key), optional username/password, and optionally port, protocol, snapshot_path, snapshot_command, and timeout. Set type to "ptz" to enable ONVIF PTZ and focus controls; onvif_port defaults to 8080 and can be configured per camera. onvif_wsdl_dir, onvif_profile_token, focus_min, and focus_max are also supported for ONVIF setup and focus calibration. The tested default snapshot endpoint is /tmpfs/snap.jpg?usr=...&pwd=...; verify the endpoint on other models before deployment.

For the full list of adapters with their required fields, and for adding support for a camera none of them handles, see the camera adapter guide.


Documentation

The full package documentation is available here:

https://pyronear.org/pyro-engine/

It covers engine usage, configuration and deployment details.


Contributing

Please refer to CONTRIBUTING if you wish to contribute to this project.


License

Distributed under the Apache 2 License. See LICENSE for more information.

Releases

Sponsor this project

Used by

Contributors

Languages

⌂ 换网址