# GRIME3 Roadmap

**Ground-based Remote Imaging for Measurement of the Environment**

GRIME3 is the modern open-source continuation of the GaugeCam / GRIME
image-based water-level measurement system.

This roadmap describes the work required to bring GRIME3 from its current
research and release-candidate state to a stable baseline that hydrologists
can install, configure, operate, and troubleshoot without requiring software
engineering expertise.

The goal is deliberately finite. GRIME3 is not intended to become a general
hydrologic data-management or analysis platform. Completion means making the
core GaugeCam water-level measurement workflow scientifically sound,
portable, dependable, and straightforward to use.

---

## What "GRIME3 Complete" Means

GRIME3 will have reached its intended baseline when a hydrologist can:

1. install GRIME3 using a supported standalone distribution without
   installing Python or development tools;
2. create or load a site calibration and measurement configuration;
3. inspect calibration and waterline diagnostics visually;
4. measure a single image;
5. process folders of images;
6. use the command-line interface when scripting or automation is desirable;
7. operate an unattended image-processing station;
8. review resulting measurements and a hydrograph in the browser;
9. export and move site configurations and results between computers; and
10. diagnose ordinary errors without needing assistance from a software
    engineer.

The browser interface is intended to be the primary interface for most
hydrologists. The CLI, Conda, and Docker distributions provide additional
options for automation, research workflows, and field/server deployment.

GRIME3 should remain local-first. Normal measurement, review, and station
operation should not require a cloud service or Internet connection once the
software and required site configuration are installed.

---

## Roadmap

### Approved release sequence — October 18, 2026

**Current published release: GRIME3 0.1.0 RC9**, source commit
`758c775dc3135fd81d76641278252ea80a826835`, immutable tag
`grime3-0.1.0-rc9`. RC10 through RC13 and v1.0.0 are planned milestones,
not functionality claimed for RC9. No release dates are promised.

| Milestone | Scope | Completion gate |
|---|---|---|
| RC10 — Operational measurement, history, and playback | Durable measurement database and PNG metadata; unattended ingestion, duplicate handling and recovery; hydrograph review, time controls, CSV/read API; demo/playback; basic station setup | A station processes incoming images, restarts safely, and exposes consistent history, review and exports in supported packages |
| RC11 — Annotation and dataset preparation | Browser Accept/Correct/Uncertain/Reject review, editable waterline, condition tags, annotation provenance, reproducible targets and dataset splits | Experts can efficiently create auditable training and evaluation datasets |
| RC12 — SDF measurement assistance | SDF training and held-out evaluation; conditioned inference; normal/always/disabled modes; model provenance and optional AI distributions | Useful stage/waterline performance and appropriate rejection are demonstrated on held-out data and in supported packages |
| RC13 — Bayesian analysis and production acceptance | Temporal inference and uncertainty, raw deterministic/SDF comparisons, final station integration, extended operation and documentation | The complete production workflow passes scientific, operational and installation acceptance |
| v1.0.0 — Stable production | Corrections from candidate evaluation, final production identity, coordinated artifacts and documentation | Accepted functionality is stable on supported distributions |

RC13 is the final planned candidate. A blocking defect can require a corrected
candidate; a release number does not override scientific or operational gates.

Within each candidate, complete substantive Linux development first. Perform a
small native Windows compatibility check when a new storage, background-worker
or inference capability first works, then finish Windows acceptance after the
Linux checkpoint and before publishing that candidate. Keep one shared
scientific implementation. Use the same accepted source and reference datasets
for Linux x86_64, native Windows x64, Conda and Docker validation.

Use large, independently gated, resumable work batches. Reuse validated RC9
dependency builds unless a change requires rebuilding. Keep one owned work
area per machine, check free space before builds, and include generated-file
cleanup and Git push verification in completion.

The detailed [RC10 working plan](docs/grime3_rc10_working_plan.md) defines the
starting inspection, implementation order, deliverables and acceptance criteria.
Artifact/tag naming for future candidates and the transition to v1.0.0 are
settled before their packaging; existing RC9 identities remain immutable.

---

### GRIME3 0.1.0 RC9 — Published Baseline

RC9 was published on October 16, 2026. It began directly from the immutable
RC8.4 release commit `ca8da588e47d4b5e5b9e2b787f1ea8ab70e4d711`.
The following retained implementation scope documents the integration release
that strengthens configuration identity, data discovery, measurement-quality
reporting, desktop usability, and lifecycle reliability while retaining the
RC8.4 deterministic scientific baseline.

#### Site Catalog, Data Roots, and Configuration Layout

- Complete the hybrid architecture consisting of a machine-local GRIME3
  catalog, portable site packages, and user-registered Data Roots.
- Preserve unrestricted user image-folder hierarchies. Folder names and paths
  are locations, not scientific identity.
- Use persistent UUIDs for Data Roots, Sites, and Site Configurations.
- Support optional portable `.grime3-root.json` Data Root markers and
  `.grime3/` site-package metadata without requiring GRIME3 to reorganize the
  user's image folders.
- Preserve the canonical Site Configuration as the scientific authority for
  calibration, ROIs, datum, units, processing settings, identities, schema
  version, and provenance.
- Preserve explicit configuration assignment using manual override, date/time
  range, relative path scope, and site default, with deterministic precedence
  and ambiguity treated as an error rather than guessed.
- Add browser workflows for registering, inspecting, and resolving Data Roots,
  Sites, Configurations, and assignments.
- Establish stable discovery and reporting models that support later
  hydrograph generation and browser, PDF, and CSV presentation.
- Maintain compatibility and migration behavior for supported existing Site
  Configurations without weakening validation or provenance.

#### User-configurable minimum calibration octagon size

- Expose the minimum accepted octagon corner width and height in original
  source-image pixels in the browser and calibration CLI.
- Save the value in the canonical Site Configuration; retain 100.0 as the
  default and fallback for existing configurations.
- Share positive finite validation, preserve other scientific validity checks,
  and apply the selected value during calibration creation and projection.

#### Image compatibility signature

Implemented in RC9: native decoded signatures, shared early compatibility
gates for calibration/template reuse/projection/measurement, explicit legacy
dimension-only provenance, checksum-verified CLI migration, and persistent
rejection JSON. The current 8-bit pipeline rejects higher-bit-depth inputs.
See [Image compatibility](docs/image_compatibility.md).

- Record the source image width, height, channel count or pixel organization,
  color model (for example grayscale or BGR), data type, and effective bit
  depth in each newly created Site Configuration.
- Validate this signature before applying calibration geometry, ROIs, or
  measurement settings to an image.
- Refuse incompatible configuration/image combinations with a clear diagnostic
  rather than attempting geometrically or photometrically invalid processing.
- Define explicit compatibility and migration behavior for older
  configurations that do not yet contain the signature.
- Preserve the observed image signature and compatibility decision in result
  provenance.

#### Image-quality and linefind-quality measurements

- RC9 checkpoint implemented: shared versioned native-ROI image evidence,
  selected-line support/coverage/gaps/residual/edge-response and cross-pass
  diagnostics, exhaustive success/error JSON, browser result display, and
  independent browser/CLI CSV selection. The 20-column CSV bound and existing
  scientific acceptance decisions remain unchanged. Physical causes such as
  fog, ice, and obstruction are not inferred from generic image statistics.
  See `docs/measurement_quality.md` for the documented heuristic formulas,
  availability rules, method versions, and reserved PNG metadata names.

- Add an `image_quality` score on a documented `0.0` to `1.0` scale describing
  whether image degradation may impair octagon or waterline processing.
- Retain diagnostic components and reason codes for relevant conditions such as
  blur, low contrast, fog or haze, ice, obstruction, exposure problems, and
  other measurable degradation. The composite score must not conceal the
  evidence used to produce it.
- Add a separate `linefind_quality` score on a documented `0.0` to `1.0` scale
  based on the waterline search evidence, including the found-point set,
  inlier support, residuals, spatial coverage, gaps, and stability where those
  quantities are available.
- Keep both scores distinct from measurement acceptance/rejection status. A
  score assists evaluation and filtering but does not replace explicit failure
  reasons or scientific validity checks.
- Always record both scores, their availability/status, method/version, and
  supporting diagnostics in the exhaustive result JSON.
- Add browser checkboxes and corresponding CLI options so either or both
  top-level scores can be selected for measurement CSV output while preserving
  the existing required CSV columns and bounded-column design.
- Reserve stable names and serialization rules so the same quality information
  can be written into output PNG metadata when PNG result output is added.
- Add unit, regression, range, missing-evidence, JSON-contract, CSV-selection,
  GUI, and CLI tests.

#### Native system file and folder browsing

RC9 checkpoint implemented: isolated Windows shell and Linux FileChooser v3+
providers; local launcher/origin/token guards; one-dialog locking; cancellation
without path changes; image/output/Data Root folders and Site Configuration
load/create/save integration with the existing browser fallback. Automated
provider, transport, security, and browser contracts accompany this checkpoint.
The RC9 release process completed desktop and packaged validation; these checks
remain regression gates for subsequent candidates.

- For local desktop installations, use the operating system's native picker:
  Windows `IFileOpenDialog` and Linux `xdg-desktop-portal`.
- Do not introduce Qt.
- Return backend-accessible absolute paths to the existing path controls.
- Preserve manual path entry and loading on Enter.
- Treat cancellation as no change and permit only one open native dialog at a
  time.
- Restrict native-dialog endpoints to verified local desktop operation.
- Retain the existing GRIME3 browser automatically for Docker, remote,
  headless, portal-unavailable, and otherwise unsupported environments.
- Add capability detection, Windows and Linux provider tests, fallback and
  security tests, packaged-build validation, and complete user documentation.

#### Installation, version, and server lifecycle usability

- Publish a one-line Conda installation command that can be copied directly
  from the website into Anaconda Prompt or another documented target shell;
  do not require continuation backslashes for the primary copyable command.
- Detect and clearly report a conflicting or stale GRIME3 server, occupied
  port, or different running build rather than silently opening an older
  process.
- Make the running build identity visible and preserve graceful shutdown and
  restart behavior when the browser closes, the launcher exits, or a prior
  process was not shut down normally.
- Provide safe, platform-appropriate remediation without terminating unrelated
  processes.
- Test previous-version conflicts, stale process/port handling, repeated
  launches, browser-close behavior, packaged launchers, and clean restart on
  supported platforms.

#### RC9 cross-cutting requirements and implementation order

- Keep the browser as the only GRIME3 GUI.
- Use native Windows tooling for Windows development and validation; do not use
  WSL for native Windows work.
- Preserve the commercial-friendly dependency policy: no Qt, no GPL-family
  components in distributed artifacts, and avoid LGPL dependencies where
  practical.
- Keep official release documentation generic and audience-neutral.
- Update the complete user guide, quick starts, CLI reference, browser help,
  architecture documentation, release notes, and public roadmap as applicable.
- Validate Linux, native Windows, Conda, Docker, and packaged fallback behavior
  before RC9 release acceptance.

Implementation proceeds in dependency order: define schemas and contracts;
complete catalog/Data Root/site-package services; add browser catalog and
assignment workflows; enforce image compatibility; add quality metrics and
output contracts; add native picker providers and fallback behavior; harden
launcher/server lifecycle and installation instructions; then complete
cross-platform packaging, documentation, regression testing, and release
acceptance. Demonstration playback and hydrograph work follow in RC10.

---

### RC10 — Operational Measurement, History, and Playback

RC10 expands the previously deferred Demonstration Playback and Hydrograph
work into a complete deterministic operational workflow. All items below are
planned until the RC10 acceptance gates pass.

- Preserve RC9 calibration, deterministic measurement, image compatibility,
  quality scores, catalog/configuration identity, native browsing and launchers.
- Store authoritative measurement history with site/image identity, capture
  time and timezone interpretation, stage/units, outcome, quality information,
  configuration/calibration identity, application provenance and artifact links.
- Write a portable measurement/provenance copy into generated PNG metadata.
- Add unattended folder/tree ingestion with completed-write checks, explicit
  configuration resolution, duplicate prevention, controlled reprocessing,
  interruption recovery, understandable failures and operational status.
- Add hydrograph review with independent start/end sliders and precise time
  inputs, honest gaps/statuses, measurement/image inspection, live refresh,
  selected-range CSV and a bounded, documented external read API/export contract.
- Add folder/tree demo playback with overlays and a synchronized hydrograph,
  pause/resume, stop and looping, using production processing components.
- Keep demo session state separate from authoritative station history.
- Add basic station setup and supported automatic operation on Linux and
  Windows, with documented backup/recovery and user-facing diagnostics.
- Complete Linux standalone, native Windows standalone, Conda and Docker
  acceptance, current documentation, checksums, licenses and build provenance.

RC11 owns annotation/dataset preparation; RC12 owns SDF; RC13 owns Bayesian
temporal analysis and final integration. RC10 does not reintroduce the retired
RC7 AI runtime, FFmpeg or OpenCV videoio, and does not add video encoding,
RPi/ARM64 or general hydrologic modeling.

See [RC10 working plan](docs/grime3_rc10_working_plan.md).

---

### 1. Stabilize Site Configuration and Scientific Behavior

Create a simple, portable site configuration format that contains the
information needed to reproduce a GRIME3 measurement setup.

Planned work includes:

- maintain one canonical, versioned Site Configuration containing the
  calibration, ROI, datum, units, processing settings, and provenance needed
  to reproduce a measurement;
- before the first public release, keep this as a clean baseline rather than
  carrying legacy ROI/calibration import or migration paths;
- include configuration schema/version information;
- assign persistent UUID identities to Sites and Site Configurations so file
  names, display names, and filesystem paths are not treated as identity;
- assign persistent UUID identities to registered Data Roots using portable
  `.grime3-root.json` markers that remain valid when a Data Root is moved or
  mounted at a different path;
- keep units, calibration geometry, search regions, measurement parameters,
  and related site settings together;
- validate configurations before processing begins;
- provide clear hydrologist-facing error messages for incomplete or invalid
  configurations;
- preserve a single scientific implementation shared by the browser and CLI;
- maintain regression datasets and numerical tolerances for calibration,
  octagon detection/refinement, waterline measurement, and stage results;
- maintain centralized version, source-commit, build, and provenance
  information; and
- version externally useful output formats so future software changes do not
  silently make older measurements unusable.

A Site Configuration should be easy to archive, copy to another GRIME3
installation, and associate with a field site. Its persistent Site and
Configuration identities travel with the configuration. Data Root identity
belongs to the portable Data Root marker and local catalog rather than to the
Site Configuration itself. User image-folder hierarchies remain unrestricted.

Portable site packages may use a `.grime3/` directory containing `site.json`,
`assignments.json`, and `configs/`. The portable site package is the
scientific authority for site identity, configuration identity, and explicit
configuration assignments; the machine-local GRIME3 catalog is a lookup index
for registered Data Roots, Sites, and Configurations.

Configuration assignment is explicit rather than inferred from arbitrary
directory names. Initial assignment mechanisms are manual override, date/time
range, relative folder/path scope, and a site default. Resolution precedence
is manual override, then matching date/time range, then the longest matching
relative path scope, then the default configuration. Ambiguity at the winning
level is an error rather than a guessed choice. Filename-pattern and
camera-pattern assignment rules are intentionally outside the first
implementation.

---

### 2. Complete and Document the GRIME3 CLI

Turn the existing GRIME3 command-line functionality into a supported
end-user interface.

Planned work includes:

- package the CLI as a standalone executable where appropriate;
- expose the same calibration and measurement implementation used by the
  browser interface;
- support single-image and folder/batch processing;
- preserve useful stdout, stderr, and exit-code behavior for scripting;
- support paths containing spaces;
- provide version and build/provenance reporting;
- test packaged CLI executables, rather than testing only Python modules;
- provide representative end-to-end CLI tests using GRIME3 test data; and
- produce complete user documentation for all supported CLI commands and
  options.

CLI documentation will include copyable examples for Windows Command Prompt,
PowerShell, and Unix-like shells where syntax differs.

---

### 3. Provide Easy Standalone Installation

Produce downloadable GRIME3 distributions that do not require users to
install Python, Conda, compilers, or development tools.

#### Windows

Primary production target:

- browser GUI distribution;
- CLI distribution;
- native x64 packaging;
- packaged-executable smoke and end-to-end tests;
- build provenance;
- required licenses and notices;
- SHA-256 checksums; and
- clear installation, startup, security-warning, and removal instructions.

#### Linux

Primary production target:

- browser GUI distribution;
- CLI distribution;
- modern x86_64 Ubuntu/Xubuntu-class systems as the minimum baseline;
- evaluation of the most practical portable standalone format;
- packaged-executable testing;
- build provenance, licenses, and checksums; and
- clear installation and removal instructions.

#### macOS

Supported on a best-effort basis:

- browser GUI distribution;
- CLI distribution;
- architecture clearly identified;
- automated build and packaged-executable testing on GitHub-hosted macOS
  runners where practical;
- documentation of Gatekeeper and unsigned-build behavior; and
- clear installation and removal instructions.

Because current development and field testing do not have dedicated Apple
hardware, macOS packaging should not delay completion of the strongly tested
Windows and Linux distributions.

---

### 4. Provide Conda and Docker Installation Paths

Standalone installers are intended for most hydrologists. Conda and Docker
will provide additional reproducible installation methods.

#### Conda

Provide a GRIME3 package that exposes both:

- the browser interface; and
- the command-line interface.

The Conda package is primarily intended for researchers and users already
working in Python/scientific-computing environments.

#### Docker

Provide a maintained GRIME3 container capable of supporting:

- browser operation;
- CLI/batch operation; and
- unattended station operation where appropriate.

Docker deployment should use documented persistent locations for
configuration, incoming images, processed images, results, and databases.

Docker Compose may be used where it materially simplifies installation and
operation.


#### Future Distribution Hardening and Repository Publication

The RC8 distribution work establishes the initial supported delivery
baseline. The following are post-RC8 distribution-hardening goals and
should not delay completion of the deterministic RC8 baseline.

##### SDF-capable Docker distributions

When the future SDF learned-waterline model reaches a release-candidate
stage:

- extend the maintained GRIME3 Docker path rather than creating a separate
  scientific implementation;
- retain a deterministic-capable container;
- provide an SDF-capable CPU image;
- evaluate an optional GPU-accelerated image when it provides a meaningful
  operational benefit;
- preserve the future SDF execution modes `normal`, `always`, and `disabled`;
- keep model/version provenance in measurement outputs;
- use versioned, immutable OCI image tags and content digests; and
- document persistent data/configuration locations identically across CPU
  and GPU variants.

The learned-model Docker runtime must remain an interface to the same GRIME3
application and scientific implementation used by standalone, Conda, and
native installations.

##### Debian and Ubuntu packaging

Develop a standards-compliant Debian packaging path for Linux:

- create a proper Debian source package and binary `.deb`;
- define dependencies explicitly rather than embedding unnecessary system
  libraries;
- provide clean install, upgrade, and removal behavior;
- test package installation on supported Ubuntu releases;
- evaluate a GRIME3 PPA or project-controlled APT repository for
  pre-archive releases;
- pursue Debian archive inclusion when the package and release process are
  sufficiently stable;
- pursue Ubuntu archive availability through normal Debian synchronization
  or Ubuntu sponsorship/review where appropriate; and
- maintain the same browser and CLI entry points as other distributions.

Official Debian/Ubuntu repository inclusion is a long-term distribution
goal, not a requirement for completing the initial GRIME3 release.

##### Windows installer, WinGet, and Microsoft Store

Evolve the Windows ZIP/PyInstaller baseline into a conventional signed
Windows installation path:

- provide a reliable installer with install, upgrade, repair, and uninstall
  behavior;
- establish Authenticode/code-signing for publicly distributed Windows
  installers where practical;
- publish a Windows Package Manager (`winget`) manifest once a stable,
  versioned installer URL exists;
- evaluate MSIX as the preferred Microsoft Store packaging format;
- pursue Microsoft Store publication after installer identity, signing,
  upgrade behavior, and release operations are stable; and
- retain command-line access to the same `GRIME3.exe` browser and
  `measure` interface.

##### Python package publication

Evaluate publication of GRIME3 source distributions and wheels on PyPI for
Python-native researchers and developers.

PyPI should remain a secondary installation path. Normal scientific users
should not be required to manage a Python environment merely to run GRIME3.

##### Container registry and architecture coverage

Publish maintained Docker/OCI images to a durable registry such as GitHub Container Registry (GHCR) or another appropriate public registry.

Distribution testing should eventually evaluate:

- `linux/amd64`;
- `linux/arm64` where the dependency stack and scientific validation allow
  it; and
- multi-architecture manifests where practical.

ARM64 support is especially relevant to future compact or low-power
GaugeCam field-station deployments, but should be added only after
scientific and runtime equivalence are validated.

##### Release signing, SBOMs, and supply-chain provenance

As GRIME3 approaches a stable public release, strengthen distribution
provenance with:

- SHA-256 checksums for downloadable artifacts;
- cryptographic artifact or package signing where practical;
- Software Bill of Materials (SBOM) generation using an established format
  such as SPDX or CycloneDX;
- automated dependency and license inventory;
- automated checks for prohibited Qt/GPL runtime components;
- reproducible or independently verifiable build provenance where
  practical; and
- immutable release tags and artifact identities.

These controls should cover standalone packages, Conda packages, Debian
packages, Windows installers, and Docker/OCI images as applicable.

##### macOS package-manager distribution

If macOS support later advances beyond best-effort status, evaluate a
Homebrew distribution path or another conventional macOS installation
method.

macOS package-manager work should not delay the strongly supported Windows
and Linux distributions.

---

### 5. Add Unattended Station Operation

Scheduled for RC10; see its working plan and operational acceptance gates.

Add a mode in which GRIME3 can operate continuously as part of a GaugeCam
field or laboratory station.

The basic workflow will be:

1. watch a configured input folder;
2. wait for a new image to arrive and finish being written;
3. process the image using the selected GRIME3 site configuration;
4. create the required result/overlay image;
5. place processed output in the configured output location;
6. write measurement information into PNG metadata;
7. record the authoritative measurement result in a database; and
8. continue waiting for the next image.

Operational behavior should include:

- safe detection of completed image writes;
- prevention of accidental duplicate processing;
- clean restart after computer or application shutdown;
- handling of failed or rejected measurements;
- understandable logs and error reporting;
- configurable input and output locations; and
- automatic startup/service operation where appropriate.

PNG metadata will provide a portable copy of important measurement and
provenance information. The database will remain the authoritative source for
measurement history and hydrograph display.

---

### 6. Add Browser Hydrograph Display

Scheduled for RC10, including the external read API/export contract.

Use the station measurement database to display water-level history directly
in the GRIME3 browser interface.

The initial hydrologist-oriented hydrograph capability should include:

- an interactive browser time-range control with independently adjustable
  start and stop timestamps;
- a dual-handle left/right range slider that updates the hydrograph in real
  time as either endpoint is moved;
- visible start and stop date/time values plus precise date/time input controls
  for fine adjustment and accessibility;
- enforcement that the start timestamp remains earlier than the stop
  timestamp;
- stage versus time;
- accepted and rejected measurements where appropriate;
- visible gaps in the measurement record;
- access to measurement details;
- linkage between a measurement and its corresponding image where practical;
  and
- export of selected measurement history to CSV for use in spreadsheets,
  statistical software, and other hydrologic workflows.

The intent is to support measurement review and station diagnostics, not to
turn GRIME3 into a general hydrologic analysis package.

---


### 7. Add Waterline Annotation and SDF Waterline Model Pipeline

Annotation and dataset preparation are scheduled for RC11. SDF training,
evaluation and optional inference are scheduled for RC12. These capabilities
follow the RC10 operational baseline and remain part of the pre-v1.0.0 plan.

The purpose is to improve waterline finding in difficult field conditions where
the deterministic GRIME3 method can fail or correctly refuse a measurement.

Important difficult conditions include:

- biofouling;
- sun glint and reflections;
- shadows;
- turbulence and waves at the waterline;
- flying or swimming birds;
- deer;
- bison;
- vegetation and other occlusions;
- snow;
- ice;
- difficult illumination;
- low light;
- overexposure;
- floating debris; and
- camera motion or related environmental disturbances.

#### Initial learned model: signed distance field (SDF)

The first learned waterline model should predict a
**signed distance field (SDF)** around the waterline rather than perform
general-purpose whole-image semantic segmentation.

The learned model should operate on an automatically expanded context crop
around the existing conditioned waterline-search ROI. The model may use
context outside the ROI to improve robustness, but final line extraction and
the calibrated GRIME3 measurement must remain constrained to the original
waterline-search ROI.

The deterministic GRIME3 method remains the primary measurement path. The SDF
model is intended first for difficult or low-confidence cases such as
biofouling, glare, reflections, shadows, occlusions, turbulence, and other
conditions where the deterministic method fails or appropriately refuses a
measurement.

When the SDF implementation is added, support three execution modes:

- **normal** — run learned inference only when the pre-inference heuristic
  indicates that it is needed;
- **always** — run learned inference on every image for research, validation,
  and data collection while recording whether the heuristic would have
  requested it; and
- **disabled** — do not run learned inference.

These modes are future SDF functionality and are not part of the RC8
deterministic baseline.

The SAM2 / GRIME AI mask-segmentation path used for the internal RC7
biofouling evaluation was a temporary research implementation. It is preserved
by the immutable RC7 archive and does not define the future GRIME3 AI
architecture.

#### Conditioned model input

GRIME3 already supplies a trusted waterline-search ROI. The learned system
should use that conditioning rather than attempting to solve the future GRIME4
whole-image problem.

The initial architecture is:

    original image
            ->
    existing waterline-search ROI
            ->
    automatically expanded context crop around the search ROI
            ->
    SDF model
            ->
    semantic probabilities / logits
            ->
    use predictions only inside the original waterline-search ROI
            ->
    GRIME3 geometric waterline extraction / fitting / rejection
            ->
    calibrated stage

The context crop is generated automatically. It is not another ROI that the
user must draw or maintain.

An initial experimental/default context rule is to expand the waterline-search
ROI by approximately 50 percent of its width and height on each side, clipped
to the image bounds.

That context amount is a tunable experimental parameter, not an immutable
scientific constant. Different context sizes should be compared later if the
initial value is not robust.

Human ground-truth labeling remains confined to the original trusted
waterline-search ROI even though the model may see surrounding image context.

#### Initial segmentation target

Inside the trusted waterline-search ROI, the initial semantic classes are:

1. above waterline;
2. waterline / meniscus transition; and
3. below waterline.

Pixels outside the trusted labeling region may use an IGNORE target during
training.

The model should provide semantic probabilities or logits rather than only a
hard mask. GRIME3 can then use confidence, transition strength, and spatial
consistency while deriving candidate waterline evidence.

The learned model performs scene interpretation. GRIME3 continues to own the
final geometric measurement process, including candidate extraction, line
fitting, rejection, calibration, diagnostics, and stage computation.

#### Browser annotation and review workflow

Add a browser workflow that walks sequentially through processed images.

For each image, show at least:

- the image;
- the original waterline-search ROI;
- the deterministic proposed waterline; and
- relevant deterministic diagnostics.

The reviewer should have four primary actions:

**ACCEPT**

The deterministic waterline is correct. One click records the proposed
waterline as trusted human ground truth.

**CORRECT**

Display a two-handle editable line. The reviewer moves the two endpoints to the
true waterline and confirms the corrected result.

**UNCERTAIN**

The image can remain available for review, investigation, or research, but it
must not be treated as trusted ground truth.

**REJECT**

The image cannot provide a trustworthy waterline and must not be used as
ground truth.

The key design goal is tractable expert annotation. Reviewers should not be
required to draw whole-image masks.

For ACCEPT and CORRECT records, GRIME3 should automatically convert the
trusted two-handle line into the initial above-waterline,
waterline/meniscus-transition, and below-waterline semantic target inside the
original waterline-search ROI.

Target-generation parameters such as transition-band thickness must be stored
with the annotation so datasets can be regenerated and experiments remain
reproducible.

#### Annotation record and dataset provenance

Each reviewed record should preserve enough information to reproduce and audit
the training target.

Store at least:

- source image identity;
- source image hash where practical;
- timestamp when available;
- waterline-search ROI geometry;
- deterministic proposed waterline;
- accepted or corrected human-truth line;
- review status;
- SDF-target generation parameters;
- calibration association and calibration/schema version where useful;
- GRIME3 version/source provenance;
- reviewer/session provenance where appropriate; and
- environmental or failure-condition tags.

Suggested condition tags include:

- `biofouling`;
- `glint`;
- `shadow`;
- `turbulence`;
- `bird`;
- `deer`;
- `bison`;
- `vegetation`;
- `snow`;
- `ice`;
- `low-light`;
- `overexposure`;
- `debris`;
- `camera-motion`; and
- `other`.

These tags are primarily intended for evaluation, stratification, dataset
balancing, and failure analysis. They are not assumed to be direct model
inputs.

Training, validation, and test splits should avoid accidental leakage between
near-duplicate images, bursts from the same sequence, or otherwise highly
correlated observations.

#### Scientific evaluation

Do not judge the learned method primarily by segmentation intersection over
union.

Segmentation metrics may remain useful diagnostics, but the principal GRIME3
question is measurement performance.

Compare the deterministic and SDF-assisted methods using metrics such
as:

- waterline pixel error;
- angular error where relevant;
- mean and median error;
- high-percentile error;
- percentage of measurements within useful pixel-error tolerances;
- resulting calibrated stage error;
- catastrophic-error rate;
- rejection rate;
- uncertainty behavior; and
- performance stratified by environmental challenge.

Industrial robustness includes correctly refusing to measure when the
waterline is genuinely unobservable.

Evaluation should therefore distinguish at least:

- correct accepted measurements;
- incorrect accepted measurements;
- correct rejections;
- incorrect rejections; and
- uncertain cases requiring review.

The comparison must hold downstream geometry and calibration as constant as
practical so the scientific question remains whether the SDF model provides
better waterline evidence than the deterministic detector under difficult
conditions.

#### Provider and deployment architecture

The existing separation between segmentation evidence and GRIME3 measurement
logic remains useful.

A versioned water-segmentation provider interface may continue to isolate
model-specific inference from the rest of GRIME3, but the first implementation
should support the SDF model rather than expanding immediately into a catalog of
models.

Model packaging should record:

- model ID;
- model version;
- model SHA-256;
- architecture;
- preprocessing requirements;
- class definitions;
- training-dataset/version information where appropriate;
- backend;
- inference parameters;
- license information; and
- GRIME3 version/source provenance.

The standard deterministic GRIME3 installation should not be forced to carry a
large ML runtime when the user does not need learned segmentation. Separate
optional AI dependencies or an AI-enabled distribution may be used if that
produces a cleaner installation and maintenance model.

Browser and CLI workflows should eventually expose the same conditioned
SDF inference and diagnostic behavior.

#### Boundary with future GRIME4

This work is **conditioned GRIME3 machine learning**.

The SDF model receives an automatically expanded context crop around an already
known waterline-search ROI, and predictions are trusted only inside that
original search region.

Whole-image or otherwise unconditioned discovery of water, waterline location,
or measurement regions belongs primarily to future GRIME4 work.

The GRIME3 annotation pipeline may later provide useful training data and
engineering experience for GRIME4, but GRIME3 should not expand this roadmap
item into the whole-image unconditioned problem.


---

### 8. Add Demonstration / Playback Mode

Scheduled for RC10, with demo sessions separated from station history.

Provide a simple demonstration mode based on the existing folder-processing
workflow.

The demonstration should:

- process or replay images sequentially from a folder;
- show the detected waterline and other selected overlays;
- update the hydrograph as images are displayed;
- allow playback to pause and resume;
- support repeated/looped playback; and
- use the real GRIME3 processing and visualization components rather than a
  separate simulated implementation.

This mode should be useful for demonstrations, teaching, validation, and
reviewing datasets.

---

### 9. Create a GaugeCam Reference Station Application

Basic station setup and automatic operation are RC10 work; final integrated
production acceptance is RC13 work.

Create a reference deployment that demonstrates how GRIME3 can be used as a
complete operational GaugeCam processing station.

The goal is a one-download installation followed by a simple setup wizard.

A hydrologist should be asked only for information that is meaningful to the
measurement workflow, such as:

- incoming image folder;
- site configuration/calibration;
- processed-image/output folder;
- measurement database location;
- whether unattended processing should start automatically; and
- other essential station settings.

Implementation details such as Python environments, service configuration,
database initialization, ports, and runtime internals should normally remain
hidden.

Windows and Linux should receive the strongest reference-station support.

---

### 10. Complete Scientific, Operational, and Usability Validation

Each candidate has its own acceptance gate. RC13 completes integrated
acceptance, including Bayesian temporal analysis, before v1.0.0.

Before declaring the baseline complete, GRIME3 should pass an end-to-end
validation process covering both scientific correctness and ordinary use.

Validation should include:

- calibration regression tests;
- octagon detection/refinement regression tests;
- waterline and stage regression tests;
- comparison with established GRIME results and datasets where appropriate;
- browser and CLI scientific consistency;
- fresh-install testing;
- paths containing spaces and normal filesystem edge cases;
- folder/batch processing;
- configuration portability;
- unattended operation;
- restart and recovery behavior;
- duplicate-image handling;
- hydrograph/database consistency;
- packaged executable tests on supported operating systems;
- license and third-party notice audit;
- build and source provenance audit;
- task-oriented documentation covering installation, site configuration,
  calibration, single-image measurement, folder processing, unattended
  operation, result review, export, and troubleshooting; and
- documentation and usability review from the perspective of a hydrologist
  rather than a software developer.

Visual diagnostics remain an important part of validation. Users should be
able to inspect the calibration target, calibration grid, ROIs, candidate
points, rejected points, waterline, staff gauge, and other relevant overlays
to determine whether a result is credible.

---

### 11. Publish the Stable GRIME3 Baseline

The target stable production version is v1.0.0, after RC13 acceptance and
necessary stabilization corrections.

The final baseline release should provide a simple public download and
documentation structure.

The target release matrix is:

| Platform | Browser GUI | CLI |
|---|---|---|
| Windows x64 | Supported and strongly tested | Supported and strongly tested |
| Linux x86_64 | Supported and strongly tested | Supported and strongly tested |
| macOS | Best-effort supported | Best-effort supported |

Additional installation methods:

- Conda
- Docker

Each downloadable release artifact should identify:

- GRIME3 version;
- build ID;
- source commit and release tag;
- operating system;
- architecture;
- SHA-256 checksum; and
- applicable license and third-party notices.

GitHub should serve as the authoritative source-code and release location.
GaugeCam project sites may provide the hydrologist-facing project
description, roadmap, documentation, and convenient links to the official
downloads.

---

## Design Principles Through Completion

The remaining work will follow several constraints.

### Hydrologists First

Features should be evaluated primarily by whether they make GRIME3 easier,
safer, or more useful for scientists measuring water level.

Software infrastructure that does not materially support that goal should
not delay completion.

### One Scientific Implementation

The browser, CLI, standalone packages, Conda package, Docker image, demo
mode, and unattended station must remain interfaces to the same GRIME3
scientific implementation.

Platform-specific copies of calibration, octagon, waterline, or stage
algorithms should not be created.

### Visual Verification

GRIME3 should continue to make its decisions visible through overlays and
diagnostics whenever practical.

A hydrologist should be able to inspect what the software found rather than
being required to trust a numerical result without context.

### Portable and Traceable Results

Configurations, processed images, measurement records, and release artifacts
should carry enough version and provenance information to determine how a
result was produced.

### A Finite Finish Line

GRIME3 is intended to reach a stable, maintainable baseline.

New capabilities beyond the roadmap should not automatically become
requirements for completing GRIME3. Additional work should be accepted when
it fixes a scientific problem, removes a meaningful usability barrier,
improves reliability, or is required to keep the supported distributions
maintainable.

---

## Current Status

GRIME3 0.1.0 RC9 is the current published release. Its immutable source tag is
`grime3-0.1.0-rc9`, at commit
`758c775dc3135fd81d76641278252ea80a826835`.

The approved sequence is RC10 operations/history/playback, RC11 annotation and
datasets, RC12 SDF, RC13 Bayesian analysis and final acceptance, then v1.0.0.
These milestones are planned; this documentation update does not implement
new application functionality or change RC9 release artifacts.

---

GRIME3 is free and open source under the Apache License, Version 2.0.

Copyright 2026 Kenneth W. Chapman

---

## Post-RC8 public roadmap synchronization

This continuing synchronization requirement began after RC8. Keep the public
roadmap at `coffeesig.com/gaugecam` synchronized with this canonical
`ROADMAP.md`, including the release sequence approved on October 18, 2026.

The public roadmap update must reflect:

- the roadmap ordering adopted through RC8;
- the deterministic RC8 baseline;
- the CLI, Conda, Windows, Linux, and Docker distribution sequence;
- the future Debian/Ubuntu, WinGet, Microsoft Store, PyPI, OCI registry, ARM64, signing/SBOM, and SDF-container distribution goals;
- the Site Catalog, Data Roots, and portable Site Configuration architecture;
- the hydrograph and unattended-station sequence;
- the annotation/training workflow;
- the signed distance field (SDF) waterline-model direction;
- the future SDF execution modes (`normal`, `always`, and `disabled`);
- the later Bayesian time-domain analysis work;
- the RC10 through RC13 sequence and v1.0.0 acceptance boundary; and
- subsequent explicitly accepted scope/order changes.

Treat the repository `ROADMAP.md` as the canonical source when updating the
public coffeesig roadmap.

The source documentation update must be committed and pushed to the verified
GitHub development repository. Public website changes must be committed and
pushed to the verified GitLab website repository, with remote branch identities
checked after each push. Update the main download page where its current or
next-release statements conflict; preserve historical release archives and
RC9 download identities. Do not merge unrelated default-branch history or
rewrite published release tags as part of roadmap synchronization.
