Pool condition detection design doc #10

Merged

eliribble merged 1 commit from issue-9-pool-condition-detection into main

2026-07-28 16:03:08 +00:00

ned commented

2026-07-28 16:00:58 +00:00

Member

Design document and implementation plan for adding pool condition detection (blue, dry, green, murky, covered) to nemish.

What is in this PR

A single new file: doc/pool-condition-detection.md — the design document.

Architecture

Two-stage hybrid (B2 + B1):

B2 — Multi-class segmentation: Extends the existing SMP UNet to output 6 channels (background + 5 conditions). Same training pipeline, just more classes.
B1 — Per-pool MLP classifier: A lightweight ~4.5K-parameter MLP that runs on per-pool color features (RGB stats + HSV histogram), producing one condition label per polygon.

Implementation phases

Phase	What	Est. time
1	Multi-class training support (ConditionSegmentationSpec, mask conversion)	~2 days
2	Per-pool MLP classifier (ConditionClassifier + train-condition CLI)	~1 day
3	Daemon integration (load condition model, per-polygon condition properties)	~1 day
4	Label Studio annotation updates (condition brush labels)	~1 day
5	Integration testing & docs	~1 day

Each phase has a concrete validation checkpoint so we know whether it is working before moving on.

Key design decisions

Binary masks (0/255) convert to blue (class 1) automatically — no data loss
Condition runs inside the existing inference worker (~1ms/pool on CPU)
Per-polygon condition in GeoJSON properties, distinct from the mask PNG
B1 fallback: if no MLP checkpoint, uses B2 majority vote per pool
Both B2 and B1 can be toggled independently via environment variables

Design document and implementation plan for adding pool condition detection (blue, dry, green, murky, covered) to nemish. ## What is in this PR A single new file: `doc/pool-condition-detection.md` — the design document. ## Architecture **Two-stage hybrid (B2 + B1):** 1. **B2 — Multi-class segmentation:** Extends the existing SMP UNet to output 6 channels (background + 5 conditions). Same training pipeline, just more classes. 2. **B1 — Per-pool MLP classifier:** A lightweight ~4.5K-parameter MLP that runs on per-pool color features (RGB stats + HSV histogram), producing one condition label per polygon. ## Implementation phases | Phase | What | Est. time | |-------|------|-----------| | 1 | Multi-class training support (ConditionSegmentationSpec, mask conversion) | ~2 days | | 2 | Per-pool MLP classifier (ConditionClassifier + train-condition CLI) | ~1 day | | 3 | Daemon integration (load condition model, per-polygon condition properties) | ~1 day | | 4 | Label Studio annotation updates (condition brush labels) | ~1 day | | 5 | Integration testing & docs | ~1 day | Each phase has a concrete validation checkpoint so we know whether it is working before moving on. ## Key design decisions - Binary masks (0/255) convert to blue (class 1) automatically — no data loss - Condition runs inside the existing inference worker (~1ms/pool on CPU) - Per-polygon condition in GeoJSON properties, distinct from the mask PNG - B1 fallback: if no MLP checkpoint, uses B2 majority vote per pool - Both B2 and B1 can be toggled independently via environment variables

ned added 1 commit

2026-07-28 16:00:59 +00:00

Add pool condition detection design doc

CI / container-image (push) Successful in 19s

Details

CI / lint-and-test (push) Successful in 10s

Details

CI / container-image (pull_request) Successful in 18s

Details

CI / lint-and-test (pull_request) Successful in 5s

Details

CI / type-check (push) Failing after 1m8s

Details

CI / type-check (pull_request) Failing after 1m8s

Details

80a2922372

Eli approved the two-stage hybrid approach (B2 multi-class segmentation
+ B1 per-pool MLP classifier) for detecting pool condition (blue, dry,
green, murky, covered).

This design document captures:
- Architecture decision and rationale
- Training pipeline changes (multi-class masks, ConditionSegmentationSpec,
  per-pool MLP classifier)
- Daemon inference pipeline changes (condition feature extraction,
  per-polygon GeoJSON properties)
- Five-phase implementation plan with per-phase validation checkpoints
- Risk assessment and mitigations

ned referenced this pull request

2026-07-28 16:01:03 +00:00

Add pool condition detection #9