Human Label Format

This page explains the small JSON Lines format for human video review labels.

Simple meaning: a person watches a video or review images and writes down what they saw in a consistent way.

These labels are review evidence only. They do not create alerts or public warnings.

File Type

Use JSON Lines, with one label record per line.

Simple example:

{"video_id":"demo-river-001","time_window_seconds":[0,30],"human_label":"water_rising","confidence":"medium","note":"Water appears to move higher against the bridge pillar."}

Required Fields

Field Meaning
video_id A safe name for the video or input being reviewed.
time_window_seconds Start and end seconds for the reviewed part of the video.
human_label What the reviewer saw.

Simple example: [0, 30] means the reviewer watched from second 0 to second 30.

Optional Fields

Field Meaning
site_id Site name or ID, if known.
camera_id Camera name or ID, if known.
confidence How sure the reviewer is.
note Short human explanation.
reviewer_id Safe reviewer ID, if the project uses one.

Do not put personal phone numbers, emails, passwords, or private camera URLs in label files.

Human Labels

Prefer one of these values:

Label Simple Meaning
water_rising Water appears to move higher or cover more of the watched area.
water_falling Water appears to move lower or cover less of the watched area.
no_clear_change The reviewer does not see a clear water change.
camera_video_problem The video, camera view, or file has a problem.
cannot_judge The reviewer cannot safely decide from the image or video.

Simple example: use cannot_judge when the image is too dark, blurry, blocked, or confusing.

If your site needs a label that is not in the list, you may use a short custom value with letters, numbers, dashes, or underscores.

Simple example: bridge_pillar_covered can mean the water covers a known bridge-pillar mark at that site.

Keep custom labels simple. Do not put names, phone numbers, exact private locations, or long notes in human_label. Use the note field for the explanation.

Allowed Confidence Values

Use one of these values:

  • low
  • medium
  • high

Simple example: if water may be rising but glare makes it hard to see, use confidence: "low" and explain why in note.

Where To Put Labels

Put labels in the validation dataset structure:

data/sites/<site-name>/labels/

Safe demo example:

data/sites/example-site/labels/example-labels.jsonl

Real label files may contain sensitive notes. Keep them local unless they are approved for public sharing.

Creating Labels

Instead of manually editing JSON Lines files, use the labeling helper:

From the Home UI

Start the local UI:

python3 scripts/run_openfloodai_home_ui.py

Open http://127.0.0.1:8765/openfloodai-home-ui.html in your browser. Click Add Label in the top toolbar (or + Add Label on a site card). Choose the site, enter the video_id, start and end seconds, select an existing label, and optionally add confidence and reviewer notes. If the label you need is missing, type a short value in Manual label. Click Save Label Record.

From the Command Line

Run:

python3 scripts/create_human_label.py \
  --site-dir data/sites/example-site \
  --video-id rising-001 \
  --start 30 \
  --end 60 \
  --label water_rising \
  --confidence medium \
  --note "water appears higher near the bridge pillar"

Simple meaning: this helper validates the time window and label text, prevents accidental overwrites, and appends the record into the site's labels/ directory.

To replace an existing record for the same video and time window, add --overwrite.

Validation

OpenFloodAI can validate a label file:

python3 - <<'PY'
from pathlib import Path

from openfloodai.review import load_human_label_records

records = load_human_label_records(
    Path("data/sites/example-site/labels/example-labels.jsonl")
)

print(f"Valid labels: {len(records)}")
print(records[0])
PY

Simple meaning: this checks that each label has the required fields, uses safe label text, and has a valid time window.

After labels are valid, compare them with system output using the Human Label Comparison guide.

Current Boundary

This format does not train a model, score flood risk, send alerts, upload data, or create public warnings.

It only lets humans write review labels in a format the project can check later.