GRIME3 Roadmap

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. CLI, Conda, and Docker options support automation, research workflows, and field or server deployment.

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

1. Stabilize Site Configuration and Scientific Behavior

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

• combine the current ROI and calibration JSON files into a single, versioned config.json unless implementation review identifies a compelling reason to keep them separate;
• preserve backward compatibility with existing ROI and calibration files;
• include configuration schema/version information;
• keep units, calibration geometry, search regions, measurement parameters, and related site settings together;
• validate configurations before processing begins;
• provide clear hydrologist-facing error messages;
• preserve one 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.

2. Complete and Document the GRIME3 CLI

• package the CLI as a standalone executable where appropriate;
• use the same calibration and measurement implementation as the browser interface;
• support single-image and folder/batch processing;
• preserve useful stdout, stderr, and exit-code behavior;
• support paths containing spaces;
• provide version and build/provenance reporting;
• test the packaged CLI executables themselves;
• provide representative end-to-end processing tests; and
• produce complete user documentation with copyable examples.

3. Provide Easy Standalone Installation

Windows

Windows x64 is a primary production target for both the browser GUI and CLI, including packaged-executable testing, provenance, licenses, checksums, and clear installation/removal instructions.

Linux

Linux x86_64 is also a primary production target for both interfaces, with modern Ubuntu/Xubuntu-class systems as the minimum baseline.

macOS

Browser and CLI packages are planned on a best-effort basis, with architecture clearly identified and automated CI testing where practical. Lack of dedicated Apple test hardware should not delay the strongly tested Windows and Linux distributions.

4. Provide Conda and Docker Installation Paths

Conda

Provide a GRIME3 package exposing both the browser and CLI for researchers already working in Python/scientific-computing environments.

Docker

Provide a maintained GRIME3 container supporting browser operation, CLI/batch processing, and unattended station operation where appropriate, with documented persistent storage for configuration, images, results, and databases.

5. Add Unattended Station Operation

The basic station workflow will be:

1. watch a configured input folder;
2. wait until a new image has finished being written;
3. process it 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.

The operational mode will also address duplicate processing, clean restart, failed measurements, understandable logs, and automatic startup/service operation where appropriate.

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

6. Add Browser Hydrograph Display

Display water-level history directly from the station measurement database.

• 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 record;
• access to measurement details;
• linkage between measurements and corresponding images where practical; and
• CSV export for spreadsheets, statistical software, and other hydrologic workflows.

7. Add Pluggable Water-Segmentation Models

Add a stable mechanism for GRIME3 to use interchangeable water-segmentation models, including models developed by GRIME AI, without coupling the measurement system to one neural-network architecture.

The core design will separate water segmentation from waterline measurement. A segmentation model should normally produce a water-probability map from the image or waterline-search ROI. GRIME3 will continue to own the downstream scientific measurement process.

The intended processing chain is:

water probability map → boundary / candidate points → validation and rejection → waterline fit → calibration → water level / stage

This separation allows different segmentation models to be evaluated while using the same GRIME3 geometry, calibration, line fitting, quality control, and stage calculation.

Planned work includes:

• define a small, versioned WaterSegmentationProvider interface;
• make GRIME AI the first supported source of compatible segmentation models without hard-coding GRIME3 to one model architecture;
• prefer a floating-point water-probability map as the normal model output rather than requiring the model itself to produce a final waterline;
• derive boundary locations and candidate points from the probability map, including probability transitions where useful for precise boundary localization;
• reuse GRIME3 candidate-point validation, outlier rejection, line fitting, calibration, and stage-measurement components;
• provide optional visualization of segmentation results, confidence information, candidate points, rejected points, and the final fitted waterline;
• expose the same model selection and inference configuration through both the browser interface and CLI;
• preserve one downstream scientific implementation whether the water evidence comes from the classical GRIME3 detector or an AI segmentation model;
• define a portable, versioned model-bundle format containing the model, metadata, preprocessing requirements, model/version identifiers, licensing information, backend information, and cryptographic hash;
• support PyTorch model bundles where appropriate and evaluate ONNX Runtime as an additional deployment backend;
• validate model bundles before processing and provide understandable errors for incompatible models;
• record model and inference provenance, including model ID, version, SHA-256, backend, important inference parameters, GRIME3 version, and GRIME3 source provenance;
• avoid requiring the standard GRIME3 distribution to contain a large AI runtime when AI segmentation is not needed;
• evaluate separate standard and AI-enabled standalone distributions where that provides the clearest deployment model; and
• preserve local-first operation so compatible segmentation models can operate without a cloud service.

Compatible model bundles should normally be data-driven rather than requiring arbitrary Python plug-in code. A more general Python provider interface may still be supported for research models that require custom inference behavior.

The browser interface should eventually allow selection between the classical GRIME3 detector and installed compatible segmentation models, selection of an inference device where relevant, adjustment of supported inference parameters, and display of segmentation diagnostics.

The CLI should expose the same capability for scripted and batch workflows, including model inspection and validation where useful.

Scientific evaluation should consider conventional segmentation metrics such as intersection-over-union, but the principal GaugeCam criterion will be the complete measurement task: how much water-level or stage measurement error does a segmentation model produce when used with the same GRIME3 downstream measurement pipeline?

The architecture should therefore support controlled comparison of the classical GRIME3 detector and multiple segmentation models using the same images, ROIs, calibrations, line-fitting logic, and reference measurements.

8. Add Demonstration / Playback Mode

Provide a demonstration mode using the real GRIME3 folder-processing and visualization components.

• process or replay images sequentially from a folder;
• show the detected waterline and selected overlays;
• update the hydrograph as images are displayed;
• pause and resume playback; and
• support repeated/looped playback.

9. Create a GaugeCam Reference Station Application

Create a one-download reference deployment followed by a simple setup wizard.

The hydrologist should need to provide only measurement-relevant information 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.

Python environments, service configuration, database initialization, ports, and other runtime details should normally remain hidden.

10. Complete Scientific, Operational, and Usability Validation

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

• calibration regression testing;
• octagon detection/refinement regression testing;
• waterline and stage regression testing;
• comparison with established GRIME datasets where appropriate;
• browser and CLI scientific consistency;
• fresh-install testing;
• folder/batch processing;
• configuration portability;
• unattended operation and restart/recovery;
• duplicate-image handling;
• hydrograph/database consistency;
• packaged executable testing;
• license and provenance audits; and
• task-oriented documentation and usability review from the perspective of a hydrologist.

11. Publish the Stable GRIME3 Baseline

The target release matrix is:

Additional installation methods will include Conda and Docker.

Release artifacts should identify version, build ID, source commit and tag, operating system, architecture, SHA-256 checksum, and applicable license notices.

Design Principles Through Completion

Hydrologists First

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

One Scientific Implementation

Browser, CLI, standalone packages, Conda, Docker, demo mode, and the unattended station must remain interfaces to the same scientific implementation.

Visual Verification

GRIME3 should continue to expose calibration, ROIs, candidate and rejected points, waterlines, staff-gauge information, and other diagnostics so users can visually evaluate results.

Portable and Traceable Results

Configurations, processed images, measurement records, and release artifacts should contain 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. Additional features should not automatically become completion requirements unless they fix a scientific problem, remove a meaningful usability barrier, improve reliability, or are required to maintain supported distributions.

Current Status

GRIME3 is currently in release-candidate development.

Major components already implemented include substantial browser-based calibration, measurement, folder-processing, visualization, diagnostic, provenance, and Windows packaging functionality.

Current development is focused on completing and packaging the CLI and then moving systematically through the remaining roadmap items.