How OpenFloodAI Works

From Video to Warning Support

VIDEO
  ↓
1. Can we read the video?               DONE
  ↓
2. Extract frames / metadata            DONE
  ↓
3. Select the river region (ROI)        DONE
  ↓
4. Measure change in that region        BASIC VERSION DONE
  ↓
5. Identify actual WATER                NOT DONE YET
  ↓
6. Track water level/coverage over time NEEDS IMPROVEMENT
  ↓
7. Convert signals into risk            PROTOTYPE ONLY
  ↓
8. Human review / validation            BASIC TOOLS DONE
  ↓
9. ML model                             NOT STARTED
  ↓
10. Live camera / edge device           LATER
  ↓
11. Alert / siren / app                 LATER

Done: Read a Video and Create Frame Metadata

src/openfloodai/ingestion/video_file.py opens a local video using OpenCV and walks through the frames. It records information such as frame number, timestamp, frame size, FPS, and a frame hash.

Done: Check Whether the Video Can Be Trusted

src/openfloodai/ingestion/feed_health.py checks whether the input exists, opens correctly, and has readable frames.

Camera unavailable
      ↓
Do NOT say: NORMAL
      ↓
Say: UNKNOWN / DEGRADED

Done: Select the River Area to Watch

OpenFloodAI supports a configured reference region, also called an ROI (Region of Interest). Instead of analyzing the entire image, we can monitor only the useful area, such as the lower part of a bridge pillar or a river channel.

Full camera image
┌─────────────────────────────┐
│ trees / road / sky          │
│                             │
│   ┌─────────────────────┐   │
│   │ WATCH THIS AREA     │   │
│   │ ~~~~~ river ~~~~~   │   │
│   └─────────────────────┘   │
└─────────────────────────────┘

Basic version done: Compare the Selected Region

src/openfloodai/vision/simple_signals.py can compare two frames or the same selected region across two frames and produce a region_change_score.

Frame 1 ROI
     ↓
compare
     ↓
Frame 2 ROI
     ↓
region_change_score

This tells us that something changed, but it does not yet tell us what changed.

Missing: Identify Which Pixels Are Actually Water

This is the major ML/computer-vision gap. Today we mostly know that pixels changed. Later, a water-segmentation model can help answer a better question:

IMAGE
  ↓
ML segmentation model
  ↓
Which pixels are WATER?

A segmentation model could produce something conceptually like:

0 0 0 0 0 0 0
0 0 0 0 0 0 0
0 0 1 1 1 1 0
0 1 1 1 1 1 1

0 = not water
1 = water

Then normal code can calculate water coverage, for example 38%, 45%, or 62%.

Needs work: Track Change Across the Whole Video

Flood behavior is about change over time, not only two frames. In the future, we want a water-aware time series such as:

FUTURE EXAMPLE ONLY

00:00 → 31% water coverage
00:10 → 33%
00:20 → 36%
00:30 → 43%
00:40 → 52%
00:50 → 64%

Prototype: Convert Evidence into a Risk State

src/openfloodai/risk_engine/rule_based.py already contains a rule-based skeleton that can produce states such as NORMAL, WATCH, WARNING_CANDIDATE, or UNKNOWN.

The current thresholds are test thresholds only. They are not validated flood thresholds.

Visual / water evidence
        +
Camera health
        ↓
Rule-based risk engine
        ↓
NORMAL / WATCH / WARNING_CANDIDATE / UNKNOWN

Done: A Small Pipeline Already Connects the Pieces

src/openfloodai/pipeline/local_poc.py connects the current software pieces:

Video
 ↓
Health check
 ↓
Frame metadata
 ↓
Sample usable frames across the review period
 ↓
Reference region
 ↓
Visual comparison
 ↓
Risk engine
 ↓
Save records

This is a proof of concept. It proves the software pieces can work together. It does not prove that OpenFloodAI detects real floods.

What We Have vs. What We Still Need

Before ML: Validate More Videos

The current validation base can run multiple local videos, create one summary report, document hard cases, and explain upper, middle, and lower reference-region changes.

Now: local multi-video validation
  ↓
Next: compare matching time windows
  ↓
Next: add safe hard-case clips
  ↓
Next: create a small locked validation set
  ↓
Later: ML only after better labels and validation evidence

Simple meaning: first test more reviewed videos and write down where the system agrees, disagrees, or cannot compare. Then improve the selected-region signal using that evidence.

The Simplest Way to Remember It

Current system:
ROI → pixel / visual change → risk prototype

Future system:
ROI → ML water segmentation → water coverage / level over time
    → risk engine → human review → alert support