DeepSNR CLI for macOS arm64 - CoreML Backend
============================================

DeepSNR is a deep-learning-based tool for noise reduction in astronomical
images. This package uses the native CoreML backend and includes the
executable and model packages together.

System requirements: macOS 13.1 or newer on Apple Silicon.

This is the recommended macOS lane for Apple Silicon.

Keep ./deepsnr, DeepSNR_weights_v1.mlpackage, and
DeepSNR_weights_v2.mlpackage, and the 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 package. 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 packages 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, lib/ directory, README, and licenses 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 and notices from lib/>


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 package. Normally omit this option and use
      --model 1 or --model 2 to select DeepSNR_weights_v1.mlpackage or
      DeepSNR_weights_v2.mlpackage 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. This package uses Apple's system
CoreML framework and does not redistribute CoreML runtime libraries.
OpenCV license and dependency notices are included in lib/opencv-licenses/.
