DeepSNR CLI for Linux - 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.

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
----------------

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

Optional GPU Acceleration
-------------------------

The bundled ONNX Runtime files use CPU execution and require no GPU setup.
Advanced NVIDIA users can replace the bundled ONNX Runtime files with a
compatible ONNX Runtime GPU runtime and make the required CUDA/cuDNN runtime
libraries visible to the dynamic loader. If CUDA initializes successfully,
DeepSNR reports:

  Backend: ONNX Runtime (CUDA execution provider)

If CUDA is unavailable or incomplete, DeepSNR falls back to CPU execution from
the same executable. Restore the original package files if a manual GPU runtime
change causes startup or processing failures.

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>

  Package managers can use /usr/bin/deepsnr and /usr/lib/deepsnr/ instead.


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 32-bit floating-point FITS output.

  -m, --model <1|2>
      Select bundled model version 1 or 2 from the package directory.
      Default: 2. Model 2 supports RGB and grayscale images. Model 1 is
      the older model line and is intended for RGB images. This option is
      ignored when --weights is provided.

  -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 no larger than
      the 512 pixel processing window.

  -q, --quiet
      Suppress progress output.

  -e, --eight
      Write TIFF and PNG output as 8-bit instead of the default 16-bit.


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

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


Short Option Clustering
-----------------------

Short boolean switches can be combined. For example, -eq is equivalent to
-e -q. Only switches without values can be clustered; options that take values,
such as -i, -o, -m, -w, and -s, must be provided separately.


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, or .fts 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 are read as floating-point samples. 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. Images with alpha channels or other channel counts
are rejected. Images must be at least 512x512 pixels.

Both models work on images from monochrome CCD cameras. 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 are saved as 16-bit or 8-bit with --eight. TIFF outputs
are always saved with LZW compression. PNG output uses OpenCV default encoding.
FITS outputs are saved as 32-bit floating-point standard image HDUs.

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.
