GRIME3 Command-Line Interface

GRIME3 provides one supported command-line entry point:

grime3

The command exposes the browser server and deterministic water-level measurement workflows. The CLI and browser use the same canonical Site Configuration and the same scientific measurement implementation.

Top-level commands

grime3 --version
grime3 --help
grime3 web --help
grime3 calibrate --help
grime3 measure --help

grime3 measure contains three measurement operations:

grime3 measure image
grime3 measure folder
grime3 measure folders

Pre-public batch command names are not part of the RC9 public interface.

Site Configuration

Measurement commands require one canonical GRIME3 Site Configuration JSON file:

--site-config PATH

The same Site Configuration can be reused for any number of independent single-image, folder, or folder-of-folders runs. A measure folders run applies the selected Site Configuration to each child folder in that run.

ROI geometry, calibration, datum, world units, grid settings, and other site-specific scientific state come from that file. Measurement commands do not expose separate legacy ROI, calibration, unit, datum, or small-octagon options.

Calibrate using an existing Site Configuration (RC9)

grime3 calibrate uses the existing configuration as an input template: octagon ROI, waterline ROI, physical facet length, units, datum, and detector mode. Select an image to which those ROI coordinates apply. The command runs the same calibration service as the browser and writes a new canonical configuration. It preserves the Site ID and creates a new Configuration ID.

grime3 calibrate --site-config "/path/to/existing.json" --image "/path/to/source.png" --output "/path/to/new.json" --operator "Operator Name" --minimum-octagon-span-pixels 60

On Windows, use the same options with quoted Windows paths.

Omit --minimum-octagon-span-pixels to use the template's saved value; old configurations without the setting use 100.0. An override must be a positive finite number and is applied to both corner spans in original image pixels. The effective value is recorded in the output configuration and calibration metadata. The template remains unchanged when a different output path is used. An existing output requires --overwrite.

This command supplies CLI calibration for an existing configuration. Initial ROI authoring and first configuration creation remain available in the browser. Measurement commands validate image compatibility before applying this file.

Migrate an older image signature (RC9)

New configurations record image dimensions, native decoded channels/color model, dtype, effective bit depth, and EXIF orientation. Those fields must match before projection or measurement. Older configurations retain dimension-only checks with an explicit provenance warning. The current scientific pipeline supports 8-bit grayscale, BGR, and BGRA; it rejects higher-bit-depth inputs instead of silently truncating them.

To add a signature without recalibrating, supply the exact original image:

grime3 migrate-image-signature --site-config "/path/to/legacy.json" --source-image "/path/to/original.jpg" --output "/path/to/signed.json" --operator "Operator Name"

Migration verifies the saved source checksum and preserves existing identities, ROI/calibration geometry, settings, and component audit history. File-save provenance records the operator. Existing outputs require --overwrite. Changed or unavailable original images require recalibration. See Image compatibility for signature definitions, legacy decisions, and result provenance.

Measure one image

Unix-like shell:

grime3 measure image \
  --image "/path/to/images/image 001.jpg" \
  --site-config "/path/to/site config.json" \
  --output-dir "/path/to/results"

Windows Command Prompt:

grime3 measure image ^
  --image "C:\Data\Images\image 001.jpg" ^
  --site-config "C:\Data\site config.json" ^
  --output-dir "C:\Data\results"

PowerShell:

grime3 measure image `
  --image "C:\Data\Images\image 001.jpg" `
  --site-config "C:\Data\site config.json" `
  --output-dir "C:\Data\results"

Use:

grime3 measure image --help

for the authoritative option list.

Measure one folder

Unix-like shell:

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

Add --recursive when supported images should also be found below subdirectories.

Timestamp selection is controlled with:

--timestamp-source auto
--timestamp-source exif
--timestamp-source filename
--timestamp-source none

When filename timestamps are used, a strptime-compatible pattern can be supplied with:

--timestamp-filename-format FORMAT

Optional scientific CSV fields can be selected by repeating:

--csv-column FIELD

Required measurement columns are always retained by the CSV contract.

For image, folder, or folder-of-folders measurement, include either or both quality scores with --csv-image-quality and --csv-linefind-quality. These augment the default CSV columns, or an explicit --csv-column selection when supplied. The equivalent explicit field names are image_quality and linefind_quality. Both scores and their diagnostic evidence are always in result JSON, including unavailable/error records. CSV remains limited to 20 selected columns; unavailable scores are blank. Quality never changes measurement acceptance or the official water level. See Measurement quality evidence for formulas and limits.

Decision overlays can be written during the same scientific run:

--decision-overlays
--overlay-scale 50

The overlay scale accepts integer percentages from 10 through 100.

Measure a folder of folders

For a data root whose immediate child directories are independent image folders:

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

Each non-empty immediate child folder is processed independently. Parent rollups combine the completed child results.

The command supports the corresponding timestamp, CSV-column, recursive, decision-overlay, and overlay-scale options shown by:

grime3 measure folders --help

Reusing one Site Configuration

A Site Configuration is not consumed or modified by a measurement run. Therefore one configuration can be reused for multiple datasets.

For example, a Unix-like shell can define the path once:

SITE_CONFIG="/data/site/site_config.json"

grime3 measure folder \
  --images "/data/run_01" \
  --site-config "$SITE_CONFIG" \
  --output-dir "/results/run_01"

grime3 measure folder \
  --images "/data/run_02" \
  --site-config "$SITE_CONFIG" \
  --output-dir "/results/run_02"

The CLI intentionally does not maintain hidden session state for a "currently loaded" configuration. Each invocation records the explicit configuration path in its provenance. Future Site Catalog and Data Root assignment functionality can provide higher-level persistent configuration selection without making individual measurement commands ambiguous.

Measurement outputs

Single-image and folder measurement use the same underlying output contract.

The exhaustive scientific information is retained in JSON. The primary scientific CSV is intentionally curated and contains no more than 20 user-selectable fields, while always retaining its required fields.

Typical folder outputs include:

waterline_measurement_summary.json
waterline_measurement_summary.csv
dual_pass_batch_summary.json
dual_pass_batch_summary.csv
run_manifest.json

Per-image exhaustive JSON is written using the image stem and the _dual_pass_waterline.json suffix.

When decision overlays are enabled, they are written beneath:

decision_overlays/

Folder-of-folders runs additionally produce child status information and combined parent rollups such as:

folder_child_run_summary.json
folder_child_run_summary.csv
all_waterline_measurement_summary.json
all_waterline_measurement_summary.csv
all_dual_pass_batch_summary.json
all_dual_pass_batch_summary.csv

CSV durability

During folder measurement, GRIME3 durably checkpoints the scientific CSV after every 10 completed images. RC9 keeps this interval fixed.

At normal completion, any remaining partial checkpoint group is also flushed and the final CSV is written.

Ctrl+C behavior

For folder and folder-of-folders measurement, the first Ctrl+C requests a cooperative stop.

GRIME3 finishes the image currently being processed, finalizes completed outputs, and exits with a nonzero interrupted status.

For single-image measurement, a first Ctrl+C likewise requests completion of the current image followed by normal output finalization and an interrupted exit status.

A second Ctrl+C forces immediate interruption. The incremental CSV writer is closed through the shared folder execution finally path, preserving rows that were already completed, although a forced second interruption can prevent later summary or manifest finalization.

Exit behavior

A normal successful measurement exits with status 0.

Invalid input, processing failure, or a completed run containing scientific processing errors exits nonzero.

A cooperative or forced Ctrl+C interruption exits with status 130.

Programs and shell scripts should use the process exit status rather than parsing human-readable status messages.

Paths with spaces

All supported CLI path arguments use normal filesystem path handling and are tested with paths containing spaces. Quote such paths according to the active shell.

Browser server

The same installed package also starts the browser interface:

grime3 web --help

The browser and CLI are interfaces over the same GRIME3 scientific implementation; they are not separate measurement engines.

Local desktop browsing uses the operating system picker when started on a loopback address, for example grime3 web --host 127.0.0.1 --open-browser. Use the browser URL printed by that launcher. Non-loopback servers, Docker, SSH sessions, headless operation, and unavailable native providers use GRIME3's existing browser. Manual paths and Enter-to-load remain available. See Native path browsing for providers, fallback behavior, and desktop/package validation. Native selection does not write files; the existing Create/Save actions perform those operations and retain overwrite checks.