standardize-sci-images

Standardize Scientific Images

Prepare comparable scientific images as a documented batch. Preserve raw files, apply only declared global operations, and fail when an honest scale bar or comparable display cannot be produced.

Start with the manifest

Read references/image_contract.md, then create a CSV manifest. At minimum it needs file, output_name, and um_per_pixel when a scale bar is requested. Add batch when images were acquired under different settings. The same comparison batch must share calibration and display settings.

python scripts/standardize_images.py manifest.csv \
  --outdir standardized --scale-bar-um 20

The command center-crops every image to a common pixel canvas and writes three practical derivatives: an unannotated display raster, a labelled preview, and an SVG panel whose faithful raster content remains embedded while scale bars and text stay editable vector/live layers. It also builds a montage and writes CSV/JSON audits containing source hashes and every operation. It never overwrites the source.

The requested overlay font defaults to Arial and must be installed. Use --allow-font-fallback only for draft previews; the audit records requested font, actual font, font file, fallback status, and whether the output is allowed for final delivery.

By default, the SVG physical width is set to the largest size that preserves 300 dpi. Use --panel-width-mm only for a known final slot; the command refuses a width that would fall below 300 dpi instead of inventing pixels.

Scientific integrity rules

• Treat raw acquisition files as immutable. Write derivatives to a new directory and record source SHA-256 hashes.
• Never invent a scale bar. Require calibration from image metadata, acquisition software, or an authoritative record.
• Do not infer calibration from another image unless the acquisition record proves they share it.
• Apply the same crop policy, intensity window, gamma, and LUT to images in the same comparison batch. Do not tune each experimental group separately.
• Default to no tone adjustment. If display adjustment is needed, declare fixed display_min, display_max, gamma, and lut settings in the manifest.
• Keep higher-bit-depth single-channel data at their native depth until display mapping. Require an explicit native-unit display window; never silently cast 16-bit data to 8-bit.
• Preserve a quantitative image/table separately. Display normalization is not a substitute for quantitative preprocessing.
• Do not erase, clone, selectively blur, locally enhance, or move biological structures.
• Do not resample by default. Equalize size by a common crop. If resampling is scientifically justified, perform it in a documented downstream workflow and update calibration.