DeepSNR CLI for macOS x64 - ONNX Runtime Backend
================================================

DeepSNR is a deep-learning-based tool for noise reduction in astronomical
images. This package uses the ONNX Runtime backend and includes the executable,
model weights, and package-local runtime libraries together.

System requirements: macOS 13.4 or newer on an Intel Mac, or on Apple Silicon
through Rosetta 2.

Keep ./deepsnr, DeepSNR_weights_v1.onnx, DeepSNR_weights_v2.onnx, and
lib/ directory together. The executable uses the bundled weights next to
itself by default. Use --model 1 or --model 2
to select a bundled model; use --weights only to override the bundled
model file. Do not mix files from different DeepSNR packages.

Output paths are resolved relative to the current working directory unless
absolute.

Native Installer
----------------

Installer asks you to agree to the included license before installing.
Command-line installation has no agreement UI; arrange acceptance first.

The macOS .pkg installer is the easiest OS-integrated installation option. It
places deepsnr in /usr/local/bin and the model/runtime files in
/usr/local/lib/deepsnr. After that, deepsnr can be run from any terminal without
manually copying files.

Install-Style Layout
--------------------

Portable archive:
  Extract the archive and run from that directory. Keep the executable,
  model weights, README, license, and bundled lib/ directory as shipped.

Manual install:
  To run deepsnr from anywhere, place the files like this:

    /usr/local/bin/deepsnr
    /usr/local/lib/deepsnr/<model weights>
    /usr/local/lib/deepsnr/<runtime libraries>


Quick Start
-----------

Run the executable from the extracted package directory, or invoke it by
path from another working directory:

  ./deepsnr --input input.tif --output denoised.tif

Model 2 is the default and supports RGB and grayscale images. Model 1 is the
older model line and is intended for RGB images.


Options
-------

  -i, --input <file>
      Input image filename. Required for processing. Recommended: TIFF/TIF, PNG, or supported FITS.

  -o, --output <file>
      Denoised output image filename. Default: denoised.jpg. Use .fit, .fits, or .fts for FITS output; FITS input storage type and scaling are preserved.

  -m, --model <1|2>
      Select model version 1 or 2 (default: 2). Model 2 supports RGB and
      grayscale; model 1 requires RGB. With --weights, this still selects
      the model interpretation and must match the supplied weights.

  -w, --weights <file>
      Override the bundled model file. Normally omit this option and use
      --model 1 or --model 2 to select DeepSNR_weights_v1.onnx or
      DeepSNR_weights_v2.onnx from the package directory.

  -s, --stride <int>
      Tile stride. Default: 480. The value must be even and between 2 and
      the 512 pixel processing window size. Zero and negative values are invalid.

  --linear
      Brighten linear images with per-channel MTF (midtones transfer function)
      for neural processing, then reverse the stretch.

  --shadows-clipping <number>
      Linear MTF shadows factor in normalized MAD units. Default: -2.80.
      Requires --linear.

  --target-background <number>
      Linear MTF target background between 0 and 1. Default: 0.25.
      Requires --linear.

  -q, --quiet
      Suppress routine output; warnings and errors remain. Explicitly requested
      machine progress is still emitted.


  --machine-info
      Print machine-readable product information as JSON and exit.

  --check-updates
      Check the latest CLI version for this platform and exit. Some builds may
      report that update checking is not available.

  --machine-progress
      Print machine-readable progress events as JSON Lines on stderr.


Inputs And Outputs
------------------

Tested input formats are TIFF/TIF, PNG, and supported FITS. TIFF inputs are
tested in uncompressed, LZW, and Deflate variants. JPEG/JPG and BMP might
work through OpenCV, but these formats were not tested for this release. JPEG
is lossy and not recommended for scientific or archival data.

Supported non-FITS input sample depths are 8-bit and 16-bit integer images.
Supported FITS inputs are standard image HDUs in .fit, .fits, .fts, .fit.gz,
.fits.gz, or .fts.gz files,
including 2D grayscale images and simple 3-channel RGB cubes. Integer FITS
inputs are normalized to the internal floating-point range. Float32 and float64
FITS inputs use divisor 1; conventional integers use their fixed format divisor
K: uint8=255, int8=127, uint16=65535, int16=32767, uint32=4294967295,
int32=2147483647. Signed values are not shifted. CFITSIO applies BSCALE/BZERO
once to decode physical samples. DATAMIN/DATAMAX are diagnostic only.
There is no observed-range rescaling. Normalize float ADU data upstream.
With --linear only, MTF (midtones transfer function) brightens linear images for
the neural network, then the stretch is reversed to return to linear data.
Samples above 1 after fixed-format scaling are clipped before MTF statistics. A loss warning gives
the maximum and affected count/percentage even with --quiet.
FITS storage precision does not imply lossless image processing.
Non-finite/undefined FITS samples are rejected in both modes. With --linear,
processing stops if a varying channel cannot be stretched safely. Constant
channels remain unchanged except for the upper clipping described above.
Floating-point output may contain values outside [0,1].
Output FITS retains source physical units, storage type and scaling.
Integer FITS rounds to the nearest storage value; source storage limits apply,
with a loss warning if output samples saturate, including with --quiet.
FITS HISTORY records processing provenance.
TIFF/PNG exports remain normalized display-format values, not physical ADU files.
Normalized white maps to 255 in 8-bit output and 65535 in 16-bit output,
with integer rounding and saturation at the storage limits.
Without --linear, out-of-range floating-point FITS remains rejected.
Processing diagnostics identify the executable, backend and selected model path.
Errors preserve the underlying detail and include model-path context. A successful
CPU fallback message means processing continues on CPU, not that the job failed
or finished. Include the full log for support; redact personal path segments.

Default stderr diagnostics report sample types, relevant headers, ranges, format
conversion, MTF and output interpretation. --quiet suppresses routine output:
warning-free success has empty stdout and stderr unless machine output was
explicitly requested. Data-loss, output-fidelity and requested-provider-fallback
warnings and fatal errors remain. --machine-progress emits JSON Lines on stderr;
dispatch progress and diagnostic records by their schema (see CLI user guide).
Arbitrary scientific FITS cubes, FITS tables, and unsupported FITS HDU layouts are rejected.

Model 1 accepts RGB/color images only. Model 2 accepts RGB/color and true
grayscale/monochrome images. RGB images with identical planes are treated as
grayscale and require model 2, including with --weights.
Images with alpha channels or other channel counts
are rejected. Images must be at least 512x512 pixels.

Both models support RGB composites from monochrome cameras; single-channel
grayscale images require model 2. Drizzle-integrated
images from one-shot color cameras might work as well. To expect good results,
your noise should be uncorrelated high-frequency noise; correlated noise, such
as walking noise, will yield poor results.

TIFF and PNG outputs preserve 8-bit or 16-bit non-FITS input depth. FITS
inputs converted to TIFF or PNG use 16-bit unsigned integer output. TIFF outputs
are always saved with LZW compression. PNG output uses OpenCV default encoding.
FITS-to-FITS outputs preserve the source storage type and numeric scaling.
FITS output from other input formats uses 32-bit floating-point standard image HDUs.
There is no output-depth option; sample type selection is automatic.

Each FITS output is a new single-image FITS built from the selected supported
image HDU. Applicable nonstructural header cards from that HDU are preserved;
other HDUs and their headers are not copied.
Same-family astronomy metadata is preserved: FITS headers for FITS outputs and
AstroTIFF ImageDescription tag 270 for TIFF outputs. Cross-format metadata
conversion is not performed. Ordinary paths containing spaces and parentheses
are supported when passed as one quoted shell argument.

Legal
-----

The DeepSNR neural-network architecture is based on the NAFNet repository:

  https://github.com/megvii-research/NAFNet

See LICENSE.txt for the DeepSNR license. CFITSIO license information is included with the bundled runtime files. ONNX Runtime license and third-party notices are included with the bundled runtime files.
OpenCV license and dependency notices are included in lib/opencv-licenses/.
