Files
ANSCustomModels/ANSCustomFireNSmokeDetection/README.md
T

98 lines
5.3 KiB
Markdown
Raw Normal View History

# ANSCustomFireNSmokeDetection
The ANSVIS Fire & Smoke custom model (`ANSCustomFireNSmokeDetection.dll` inside
the `ANS_FireSmoke_v2.0` package), judged by the **same verifier the ANSMIND
`vision.fire_smoke` node runs**. ANSVIS loads the DLL into its server; ANSMIND
runs either its native node or this DLL through `ans-custom-host` (the Custom
Model node). Since 2026-11-01 all three judge a scene identically.
## Why it was rewritten
The first generation found a detection in one section of the frame, latched a
crop round it and voted on tracked boxes inside that crop. Measured on the
field recordings, that was itself the main false-alarm source:
* the detector needs **context** — a floodlight is `fake_fire` on the whole
frame and `fire` on a tight crop of the same lamp;
* the active window lost the rest of the picture, and a PTZ tour broke the
latch (the camera moved, the crop did not);
* the colour / flicker / movement gates were hand-tuned on a few clips and
did not survive the Tay Son PTZ: lit mist, statues, radar domes, a red flag.
ANSMIND's node replaced that with a whole-frame-first verifier whose every cue
is box-relative and carried by global motion (PTZ-safe), native-resolution
zoom re-checks for fire only, a look-alike filter, and a ladder of physical
gates measured on real and false recordings (`static`, `rigid`, `plain-red`,
`lamp`, `glare`, `travelling`, `night-brief`, `unlocalised`, `in-haze`,
`featureless`, `grain`, ...). That verifier is `vendor/engine/fire_smoke.hpp`,
pure C++ with no OpenCV, vendored verbatim from ANSMINDCORE (see
`vendor/README.txt` for the commit; re-copy to sync, never edit here).
## What the DLL does per frame
1. ANSLIB runs the package's `detector.onnx` (YOLO11m: fire / fake_fire /
smoke / fake_smoke) on the **whole frame** at a low floor
(`CandidateScore`, 0.15), then class-agnostic NMS: fire and fake_fire on the
same flame are one candidate, and which the model preferred is the evidence.
2. When there is a candidate, ANSLIB runs `filter.onnx` (COCO) on the frame;
a candidate inside a vehicle or a small screen is explained away by the
verifier.
3. Each candidate gets its box-relative cues (`patchCues`: flame hue, white
core, plain red, contrast, 24x24 grey patch for the change statistics).
4. For the few small **fire** candidates the verifier picks (`ZoomChecks`),
the detector runs again on a native crop (3x the box, at least 320 px,
never more than half the frame); the crop's verdict may only boost.
5. `Verifier::update` tracks, gates and decides. Only **confirmed** tracks
come back, as `CustomObject`s with the package's `fire` / `smoke` class,
the track id, and `extraInfo = fs_seconds=..;fs_track=..;evidence=..;held=..`,
every frame while they last.
The detector is not run faster than `MaxFps` (6): evidence is per second of
scene, and between runs the last verdict is returned unchanged.
## Parameters (`ConfigureParameters`)
| Name | Type | Default | Meaning |
|---|---|---|---|
| `Sensitivity` | float 0..1 | 0.5 | How much evidence an alarm needs: under 0.34 = the node's `low`, over 0.66 = `high`, else `balanced`. The physical gates never move. |
| `SmokeSeconds` | float 0..600 | 0 | Seconds smoke must have been seen **at the place** before it may alarm (wildfire / PTZ landscapes: 20). |
| `DetectFire` / `DetectSmoke` | Boolean | true | Which families to watch. |
| `ZoomChecks` | float 0..8 | 2 | Native-resolution re-checks per frame (fire only). |
| `MaxFps` | float 1..30 | 6 | Detector rate ceiling in frames of scene time per second. |
| `CandidateScore` | float 0..1 | 0.15 | Detector floor for a candidate; the alarm threshold is the verifier's evidence, never this. |
| `MinObjectSize` | float 0..10 | 0.03 | Minimum candidate box size as a percentage of the frame area; smaller boxes are noise. |
| `ExclusiveROIs` | rectangles | none | Candidates touching one are dropped. |
The threshold ANSVIS opens the model with is not an alarm threshold either;
a confirmed alarm is reported at least at that confidence so no downstream
score filter can drop it.
## Build
```
cmake -S . -B build-vs -G "Visual Studio 18 2026" -A x64 # from the repo root
cmake --build build-vs --config Release --target ANSCustomFireNSmokeDetection FireNSmokeDetection_Run FireNSmokeDetection_Tests
```
Links `ANSLIB` (`C:\ProgramData\ANSCENTER\Shared`) and `opencv_world4130`
(`C:\ANSLibs\opencv`). The DLL and the harnesses load the ANS Runtime Engine's
DLLs from `C:\ProgramData\ANSCENTER\Shared`, so put that folder on `PATH` to
run them.
## Replay harness (parity with ANSMIND's `firesmoke-run`)
```
set PATH=C:\ProgramData\ANSCENTER\Shared;%PATH%
build-vs\bin\Release\FireNSmokeDetection_Run.exe <model dir> <video> [--max-fps 6] [--sensitivity 0.5] [--smoke-seconds 0] [--start S] [--end S] [--log]
```
Feeds the recording on the **video's** clock (`SetFrameClock`, a harness-only
method outside the plugin contract) and prints each alarm once. The model
dir is the decrypted package folder (`detector.onnx`, `detector.names`,
`filter.onnx`, `filter.names`, `Categories/`); hand it a backslash path —
ANSCORE's engine-path code splits on `/` only. The first run on a GPU builds
TensorRT engines (minutes); they cache beside the models.
`ANSCUSTOM_FS_LOG=1` (or `--log`) prints the verifier's per-track cue line
per frame to stderr, the same line the ANSMIND node logs with `ANSMIND_FS_LOG`.