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 60On 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.