TOMTOM17/wildfire-research-ai

Wildfire research AI: detection, flame masks and tentative behavior rank

What this project is for

This independent, noncommercial research project explores how camera photos can help people notice possible wildfire activity and examine visible fire conditions. It looks for fire and smoke, estimates which image pixels show flame, and produces tentative fire-behavior rank scores. Its purpose is to support experimentation with affordable camera monitoring and improve understanding of what these models can reliably recognize.

The planned hardware system uses a Raspberry Pi to capture images from a rotating camera platform, with a Windows computer running the AI. This repository provides the AI photo-analysis software; camera capture and motor control are separate. Its results are research observations and require human interpretation. It is not a validated emergency warning system, and a negative prediction does not establish that an area is safe or fire-free.

A local, image-first research pipeline with three retained components:

1. Fire/smoke detector: unchanged D-Fire-trained YOLOv8n from rabahdev.
2. Visible-flame segmenter: project SegFormer v13, with v16 small-island cleanup.
3. Rank specialist: frozen DINOv2-small plus the project's v15 Rank 1-3 linear head.

The repository contains working CPU inference code and model assets, not a hosted web service. It processes a photo or a timestamped photo sequence and writes JSON, mask images, overlays and an HTML report. It does not control motors or cameras, send external alerts, or calculate physical fire spread in metres/minute.

Research prototype: not field validated. Public validated ranks remain unknown / unsure. Tentative rank scores are uncalibrated and displayed separately. An unsure rank does not mean no fire. Detection and mask analysis continue independently.

Co-researchers and producers

• Giordano Cesar Sant'anna
• Rodolfo Vasques Shuenquener Araújo

These credits describe this wildfire research project. Original model and dataset authors are credited separately in NOTICE.md.

Run locally

Use Python 3.12 and a virtual environment. Download this entire repository so the three model files, preprocessing contracts and source stay together. Package versions in requirements.txt record the tested CPU environment.

After publication, download the complete repository with the Hugging Face CLI:

python -m pip install huggingface-hub==0.36.2
hf download TOMTOM17/wildfire-research-ai --local-dir wildfire-research-ai
cd wildfire-research-ai

python -m pip install -r requirements.txt
python infer.py --image /path/to/photo.jpg --output outputs/example

Choose a new output directory for each run. The default detector size is 640 with confidence 0.25. --detector-image-size 1280 is an optional, slower research setting. Both specialists use their existing float32 CPU ONNX graphs with four threads. Read the generated inference.json for errors and model identity.

For a sequence, provide JSONL with one actual capture per line:

{"image_path":"photos/0001.jpg","capture_seconds":0.0,"frame_id":"0001","camera_id":"camera-1","view_id":"A","camera_state":"fixed"}
{"image_path":"photos/0002.jpg","capture_seconds":1.0,"frame_id":"0002","camera_id":"camera-1","view_id":"A","camera_state":"fixed"}

python infer.py --manifest /path/to/photos.jsonl --output outputs/sequence

Relative image paths resolve against the manifest directory. Use fixed only for an actually stationary unchanged view; alternatives are unknown, moving, and settling. Preserve actual timestamps and gaps. A single photo cannot confirm a continuing event or establish an area trend.

Architecture and interpretation

The detector produces RGB-image boxes. Suitable isolated crops with 15% context feed the ranker; the ranker does not use the flame mask. The segmenter processes the full RGB image using 512-pixel letterboxing, threshold 0.55, and removal of 8-connected islands below 16 model-input pixels, scaled to source geometry. The ranker letterboxes the complete crop to 224 and uses ImageNet normalization. The saved graph combines the 768-dimensional CLS/mean-patch representation with the trained linear head. Use supplied preprocessing, not a generic center crop.

Photo software associates detections and confirms observations with 3/5 recent positives plus at least 1 second of support within 4 seconds, with a 2-second gap limit. These are engineering defaults. Registration and full image support are required for geometry-dependent measurement. Shared mask components are counted once in a combined group; group membership is not a count of physical fires.

Only sufficiently covered 60-second histories produce a predicted-mask-pixel trend. Missing flame masks under confirmed fire detections and unsupported registered borders suppress those measurements. Mask changes may reflect flicker, smoke, occlusion or model error. Physical spread speed, flame length, intensity, crown fire and spotting are not established by this model.

Development results: retained models

These small development sets were repeatedly reused for selection. They are not fresh independent tests or measurements of camera/field reliability.

Segmenter development subset	Images	Flame IoU	Recall	Empty-photo false masks
Original BoWFire VAL	34	83.50%	91.68%	3/16
ESFD VAL	15	26.11%	65.08%	6/12
wUUNet partial VAL	8	not a dense-mask metric	83.95% labeled-core only	1/3
GWFP partial VAL	6	not a dense-mask metric	80.35% labeled-core only	1/3

The difficult ESFD result is a substantial generalization weakness. Partial-core labels cannot establish full visible-flame recall or area accuracy. Cleanup reduced original VAL empty-photo errors from 6/16 to 3/16 but removed 1,304 true flame pixels; it may remove small real flames in unfamiliar views.

Retained v15 rank development subset	Crops	Accuracy	Macro F1	Balanced accuracy
Original VAL crops	161	120/161 (74.53%)	0.6853	72.87%
Detector-crop VAL	32	29/32 (90.63%)	0.8869	95.83%

All 32 detector crops are smoke-class boxes from only two filename families. The same-set original classifier had macro F1 0.6521/0.5091 respectively. Original VAL Rank 2 recall fell from 49/69 to 47/69 with v15; not every marker improved.

The rank TRAIN set has 1,502 crops from 452 parent images and five conservative filename families. One family supplies over 98% of Rank 2/3 crops. A five-fold TRAIN-family holdout diagnostic, refitting the linear training procedure, achieved only 0.4163 pooled macro F1 and 17.28% Rank 2 recall. This is a diagnostic of the procedure, not a new test score of the saved head. High raw scores also failed to reliably identify mistakes under that shift, hence the retained unsure policy.

Historical baseline TEST, different model versions

The original SegFormer baseline, before v13/cleanup, scored IoU 0.7244 and Dice 0.8402 on 34 held-out BoWFire images, with false masks on 9/16 empty images. The original YOLO rank classifier scored macro F1 0.6396, balanced accuracy 0.7355 and accuracy 73.21% on 168 held-out crops. Those scores do not belong to the retained v13/v15 models. Do not compare older TEST with newer VAL as a same-set improvement.

Original TRAIN/VAL/TEST: segmentation 493/34/34, rank 1,230/161/168. Later development TRAIN pools grew separately; source images/frames/crops and known duplicates were kept together. All FLAME imagery belongs to TRAIN. Filename/duplicate grouping does not prove independent fires, and pretrained-data overlap is not auditable.

What is excluded and unproven

Latest v80/v81 smoke-proposal filters were rejected and are not distributed here. On 89 reused development photos with 70 source smoke boxes, v81 reduced negative photos with smoke boxes from 6/19 to 0/19 at 640, but reduced matched smoke boxes from 8/70 to 6/70. That genuine-smoke loss failed preservation criteria. Original detector stays selected.

No real-fire recordings from the intended Pi camera were available in the project evidence used for this release. Indoor background checks are not a real-fire test. The model is not an emergency-alert product or validated fire-behavior assessment. No new training or independent TEST evaluation was performed for packaging.

Reproducibility and licenses

models/manifest.json binds the shipped model/preprocessing bytes to SHA-256 and records source checkpoint identities. verification.json describes release checks; software/parity checks do not create a new accuracy benchmark. The copied workflow contains the v71 missing-mask and v75 registered-border fixes.

The release passed 67 software regression tests, numerical parity checks on four TRAIN segmentation photos and six TRAIN rank crops, and two complete photo-to-report CLI checks. Flame probability maps matched the retained ONNX runtime exactly; the largest rank-score difference from the native model was 0.000000477. These checks verify packaging, not real-world detection performance. release-manifest.json lists the files and their SHA-256 hashes.

See LICENSE for the component-specific terms and NOTICE.md for upstream models, dataset attribution and modifications. The SegFormer-derived model is restricted to noncommercial research/evaluation by NVIDIA's license. The unchanged detector and inference code have AGPL-3.0 terms; the DINOv2 backbone and project rank head have Apache-2.0 terms. No dataset images, private camera photos, credentials, cloud leases or personal handoff records are uploaded.