Metadata-Version: 2.4
Name: grime3
Version: 0.1.0
Summary: GRIME 3: Image-based water level measurement
Author: Kenneth W. Chapman
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: Pillow
Requires-Dist: fastapi
Requires-Dist: pydantic<3,>=2
Requires-Dist: uvicorn
Requires-Dist: click
Provides-Extra: dev
Requires-Dist: pytest<10,>=9; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Provides-Extra: release
Requires-Dist: pyinstaller>=6; extra == "release"
Requires-Dist: packaging>=24; extra == "release"
Dynamic: license-file

# GRIME3

GRIME3 is the current GaugeCam water-level measurement application.

It is the successor to GRIME2 and is being developed as a Python application
with a browser-based user interface for image-based water-level measurement,
calibration, batch processing, diagnostic review, and research workflows.

GRIME3 is licensed under the Apache License, Version 2.0.

## Current status

GRIME3 is under active pre-public development.

The current production architecture includes:

- Python 3.11;
- OpenCV for image processing;
- NumPy for numerical processing;
- FastAPI and Uvicorn for the local browser application;
- a browser-based user interface;
- deterministic octagon detection and refinement;
- deterministic waterline measurement;
- canonical Site Configuration JSON files;
- calibrated stage computation;
- single-image and folder measurement;
- CSV and JSON summaries;
- decision-overlay output;
- timestamp extraction from EXIF or filenames.

GRIME3 is intended to support:

- Linux development and deployment;
- Windows packaged applications;
- Conda-based development environments;
- Docker-based Linux distribution.

Formal public packaging remains in progress.

## Scientific foundation

GRIME3 continues the GaugeCam / GRIME research program for image-based
water-level measurement.

The scientific and engineering basis includes prior GRIME and GaugeCam work
on:

- camera-based water-level measurement;
- octagonal calibration targets;

> **IMPORTANT - calibration image resolution requirement:** The detected
> calibration octagon must be at least **100 pixels wide AND 100 pixels high
> in the original source image**. GRIME3 rejects calibration when either
> dimension is smaller. Do not use resized or downsampled calibration images
> if resizing reduces the octagon below 100 x 100 pixels. **Force
> small-octagon detection mode does not override this minimum-resolution
> requirement.**

- image-to-world coordinate transformation;
- waterline detection;
- camera and target geometry;
- field measurement uncertainty;
- stage and discharge estimation.

GRIME3 preserves deterministic and auditable measurement behavior while
modernizing the software architecture and user workflow.

## Repository layout

Important locations include:

    src/grime3/                 production Python package
    src/grime3/web/             browser application backend
    src/grime3/web/static/      browser HTML, CSS, and JavaScript
    src/grime3/core/            scientific algorithms
    src/grime3/models/          canonical data models
    src/grime3/io/              persistent I/O
    src/grime3/cli/             command-line workflows
    tests/                      automated tests and regression tests
    docs/                       current and historical documentation
    scripts/dev/                maintained developer diagnostic tools
    packaging/                  release packaging support

## RC8.4 user installation choices

GRIME3 0.1.0 RC8.4 supports four evaluated distribution paths:

- Windows x64 PyInstaller one-folder ZIP;
- Linux x86_64 PyInstaller one-folder `.tar.gz`;
- Conda package distributed through the CoffeeSig RC8.4 static channel
  at `https://coffeesig.com/gaugecam/conda/rc8.4`;
- Linux/amd64 Docker/OCI container.

All four expose the same deterministic measurement implementation and
canonical Site Configuration model.

RC8.4 Conda users can install from the CoffeeSig RC8.4 channel after publication:

```bash
conda create -n grime3-rc8.4 \
  --override-channels \
  -c conda-forge \
  -c https://coffeesig.com/gaugecam/conda/rc8.4 \
  python=3.11 \
  grime3=0.1.0
```

The exact `.conda` artifact is also distributed directly with the release.

User documentation:

- `docs/GRIME3_0.1.0_RC8_Complete_User_Guide_Rev1.5.pdf`
- `docs/grime3_0_1_0_rc8_4_windows_quick_start.md`
- `docs/grime3_0_1_0_rc8_4_linux_quick_start.md`
- `docs/grime3_0_1_0_rc8_4_conda_quick_start.md`
- `docs/grime3_0_1_0_rc8_4_docker_quick_start.md`
- `docs/cli.md`

## Developer setup

The supported developer setup is documented in:

    DEVELOPING.md

The current development environment uses Python 3.11.

A typical existing Conda environment can be activated with:

    conda activate grime3

Install the package in editable mode with the development dependencies:

    python -m pip install -e '.[dev]'

Verify the installation:

    python -m pytest -q

## Run the browser application

From the repository root:

    python -m uvicorn \
      grime3.web.app:create_app \
      --factory \
      --host 127.0.0.1 \
      --port 8000

Then open:

    http://127.0.0.1:8000

The server intentionally defaults to the loopback interface for local use.

## Site Configuration

GRIME3 uses one canonical Site Configuration JSON file for each measurement
site/configuration.

A Site Configuration contains the information required to reproduce calibrated
measurement, including:

- site identity;
- source-image identity and provenance;
- octagon search ROI;
- waterline search ROI;
- octagon calibration;
- pixel/world homographies;
- octagon facet length;
- world units;
- bottom-left octagon corner water level;
- grid-density setting;
- small-octagon mode;
- audit provenance.

The browser interface can create, load, save, and save-as Site Configuration
files.

Separate production ROI JSON and calibration JSON inputs are no longer part of
the supported workflow.

## Command-line measurement

The single-folder deterministic measurement command is:

    grime3 measure folder \
      --images /path/to/images \
      --site-config /path/to/site_config.json \
      --output-dir /path/to/output

The folder-of-folders command is:

    grime3 measure folders \
      --images-root /path/to/dataset_root \
      --site-config /path/to/site_config.json \
      --output-dir /path/to/output

Use command help for the current option set:

    grime3 measure folder --help

    grime3 measure folders --help

## Measurement outputs

Depending on the selected workflow and output settings, GRIME3 can produce:

- per-image measurement data;
- JSON summaries;
- CSV summaries;
- decision overlays;
- contact sheets;
- difference summaries;
- run manifests containing build, configuration, and run provenance.

The browser Help tab describes the normal hydrologist-facing workflow.

## Developer diagnostics

Maintained developer diagnostic workflows are documented under `docs/`.

For octagon detection/refinement diagnostics, see:

    docs/octagon_detector_debug_workflow.md

Historical release-candidate documents are retained as
records of earlier GRIME3 development stages. Commands in those historical
documents are not the current production interface.

## Testing

Run the complete automated suite with:

    python -m pytest -q

Before committing changes:

    git diff --check
    python -m pytest -q

Scientific changes should also run the most relevant targeted regression tests
before the complete suite.

## Dependency and license policy

GRIME3 uses a conservative distribution policy.

Official distributed builds should:

- use commercially friendly, permissive dependencies where practical;
- not include Qt;
- not include GPL-family runtime components;
- avoid LGPL dependencies where practical;
- especially avoid LGPL-3.0 dependencies unless explicitly reviewed.

PyPI and standalone-build workflows use `opencv-python-headless`. The Conda package instead uses the conda-forge OpenCV headless build and explicitly selects an LGPL FFmpeg variant so the Conda runtime does not introduce Qt or the GPL FFmpeg variant.

See:

    THIRD_PARTY_NOTICES.md
    docs/browser_gui_architecture.md

for current dependency and release-policy details.

## Command-line reference

The supported RC8.4 command-line interface is documented in
[`docs/cli.md`](docs/cli.md). It covers single-image, folder, and
folder-of-folders measurement, scripting behavior, output files, and
Ctrl+C durability semantics.

## License

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

See `LICENSE` for the complete license text and `THIRD_PARTY_NOTICES.md` for
third-party dependency notices.

Copyright 2026 Kenneth W. Chapman.
