DeepSNR Command-line Tool Documentation

Documentation

This section collects technical notes and usage guides for StarNet and DeepSNR: PixInsight and command-line references, input behavior, data-quality guidance, and workflow examples.

DeepSNR command-line tool reference

This page describes the current DeepSNR command-line options, example commands, supported inputs, model selection, and output behavior. The current command-line packages are DeepSNR 1.3.2 on Linux, Windows, Intel Mac, and Apple Silicon Mac. Windows packages support DirectML acceleration and CPU fallback.

Running options

Help from the Linux ONNX/ORT package is shown below. Package layouts differ by platform; Apple Silicon packages use CoreML model packages. See CLI installer locations for installed paths.

USAGE: 

   deepsnr  [-hq] [--check-updates] [--linear] [--machine-info]
            [--machine-progress] [--version] [-m <int>] [-o <string>] [-s
            <int>] [-w <string>] [--shadows-clipping <number>]
            [--target-background <number>] -i <string>


Where: 

   -i <string>,  --input <string>
     (required) Input image filename. Recommended: TIFF/TIF, PNG, or
     supported FITS.

   -o <string>,  --output <string>
     Output image filename. See Outputs below for sample-type policy.

   -w <string>,  --weights <string>
     Override path to the model checkpoint (optional)

   -s <int>,  --stride <int>
     Stride value. Must be even and between 2 and 512.

   -m <int>,  --model <int>
     Model version to use, 1 or 2. Default is 2. Model 1 requires RGB
     input.

   --shadows-clipping <number>
     Linear MTF shadows-clipping factor in normalized MAD units. Must be
     negative.

   --target-background <number>
     Linear MTF target background. Must be strictly between 0 and 1.

   --linear
     Brighten linear images with per-channel MTF (midtones transfer
     function) for neural processing, then reverse the stretch. Fixed
     sample-format scaling only; values above 1 are clipped with a warning.

   -q,  --quiet
     Suppress routine output (warnings and errors remain visible)

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

   --check-updates
     Check the latest DeepSNR CLI version and exit.

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

   --,  --ignore_rest
     Ignores the rest of the labeled arguments following this flag.

   --version
     Displays version information and exits.

   -h,  --help
     Displays usage information and exits.

   
    DeepSNR CLI, ONNX Runtime backend.
   
    Inputs:
      Recommended: TIFF/TIF, PNG, or supported FITS.
      Non-FITS images: 8-bit or 16-bit integer, grayscale or RGB.
      FITS: standard image HDUs in .fit/.fits/.fts or
            .fit.gz/.fits.gz/.fts.gz, including
            2D grayscale images and simple 3-channel RGB cubes.
            Integer FITS uses fixed sample-format scaling; floats use scale
   1.
            Float FITS normally uses normalized [0,1] samples.
            With --linear, values above 1 are clipped before MTF, with a
   loss warning.
            No automatic range normalization. Normalize float ADU input
   upstream.
            Warnings remain visible with --quiet; header extrema never set
   the scale.
            Non-finite/undefined FITS samples are rejected in both modes.
      Default stderr diagnostics describe formats, ranges, headers and
   processing.
      --quiet suppresses routine output, not data-loss/unit/fallback
   warnings.
      --machine-progress uses JSON Lines for progress and diagnostics on
   stderr.
      FITS/AstroTIFF outputs preserve same-family astronomy metadata.
      Might work: JPEG/JPG and BMP through OpenCV,
                  but these formats were not tested.
      Not accepted: floating-point non-FITS images, alpha channels,
                    unsupported non-FITS channel/depth layouts,
                    arbitrary scientific FITS cubes, FITS tables,
                    and unsupported FITS HDU layouts.
   
    Models:
      Model 1: RGB/color images only.
      Model 2: RGB/color and grayscale/monochrome images.
   
      RGB images with identical planes are treated as grayscale and require
   model 2.
      Both models support RGB composites from monochrome cameras.
      Drizzle-integrated images from one-shot color cameras
        might work as well.
      DeepSNR works best on uncorrelated high-frequency noise;
        correlated noise, such as walking noise, will yield poor results.
   
    Outputs:
      TIFF/PNG outputs preserve 8- or 16-bit non-FITS input depth.
      FITS inputs converted to TIFF/PNG use 16-bit output.
      Display output maps normalized white to 255 (8-bit) or 65535
   (16-bit).
      FITS-to-FITS output preserves source storage type, scaling and source
   units.
      Linear MTF/inverse uses float64; only neural inference uses float32.
      With --linear, constant channels retain prepared values; singular
   varying MTF rejects.
      TIFF/PNG exports remain normalized display data, not physical ADU
   values.
      A FITS output is a new single-image FITS built from the selected
      supported image HDU. Other HDUs and their headers are not copied.
      FITS outputs from other input formats use 32-bit floating point.
      TIFF outputs are always saved with LZW compression.
      Astronomy metadata is not converted between FITS and TIFF.
   
    Package layout:
      Portable archive:
        To run from the extracted archive, keep these files together:
        deepsnr/
          deepsnr
          DeepSNR_weights_v1.onnx
          DeepSNR_weights_v2.onnx
          lib/
          README.txt
          LICENSE.txt
   
      Manual install:
        To run deepsnr from anywhere, place the files like this:
        /usr/local/bin/deepsnr
        /usr/local/lib/deepsnr/DeepSNR_weights_v1.onnx
        /usr/local/lib/deepsnr/DeepSNR_weights_v2.onnx
        /usr/local/lib/deepsnr/<runtime libraries>
   
      Package managers can use:
        /usr/bin/deepsnr
        /usr/lib/deepsnr/...
   
    DeepSNR v1.3.2
   
    Copyright (c) 2026 Mikita (Nikita) Misiura | https://starnetastro.com

Example commands

Denoise with the default current model: deepsnr --input input.tif --output denoised.tif
Choose model 2 explicitly: deepsnr --input input.tif --output denoised.tif --model 2
Run the older RGB model line: deepsnr --input rgb-input.tif --output denoised.tif --model 1
Use a specific weights file: deepsnr --input input.tif --output denoised.tif --weights DeepSNR_weights_v2.onnx
Use quiet mode for scripts: deepsnr --input input.tif --output denoised.tif --quiet
Denoise a linear FITS image with automatic MTF: deepsnr --input "linear light.fits" --output "linear denoised.fits" --linear
Tune the automatic linear stretch: deepsnr --input linear.fits --output denoised.fits --linear --shadows-clipping -3.0 --target-background 0.2

Inputs and outputs

DeepSNR is intended for high-quality calibrated and integrated data where the remaining noise is mostly random and not strongly patterned. Correlated artifacts such as walking noise behave more like image structure and should be addressed before denoising.

File formats: TIFF/TIF, PNG, and standard FITS image HDUs are the recommended tested inputs. JPEG/JPG and BMP may work through OpenCV but are not recommended for scientific input. Compressed FITS input and ordinary paths containing spaces or parentheses are supported.
Bit depth: Non-FITS input supports 8-bit and 16-bit integer samples. Integer FITS uses fixed sample-format scaling; float32 and float64 FITS uses physical values without automatic range normalization. Without --linear, float FITS must be in [0,1]. Undefined and non-finite samples are rejected.
Linear FITS ranges: With --linear, negative calibration samples are accepted. Values above 1 after fixed sample-format scaling are clipped with a warning. Normalize float ADU data, such as 0..65535, before processing; neither image extrema nor header values set an automatic white level. Discarded highlights cannot be recovered from the outputs.
Diagnostics: --quiet suppresses routine messages but retains warnings and errors. For support, include --version, --machine-info, and the complete processing log, with personal path details removed.
Color and grayscale: Model 2 supports RGB and grayscale. Model 1 requires RGB with non-identical planes. RGB with three identical planes is treated as grayscale and requires model 2, including with --weights. Alpha channels and other channel counts are rejected.
Image size: Images must be at least 512 × 512 pixels.
Output sample type: TIFF and PNG output preserves 8-bit or 16-bit non-FITS input depth. FITS-to-TIFF or PNG uses 16-bit output, FITS-to-FITS preserves source storage type and numeric scaling, and non-FITS-to-FITS uses float32.
Astronomy metadata: Each FITS output is a new single-image file from the selected supported image HDU. Applicable WCS, observation, instrument, history, and comment metadata is preserved; other HDUs and their headers are not copied. AstroTIFF textual FITS metadata is preserved for TIFF-to-TIFF output; metadata is not converted across the FITS/TIFF boundary.
Compression: TIFF outputs are always saved with LZW compression. PNG output uses the default OpenCV encoding.

DeepSNR-specific options

--model, -m: Selects model 1 or 2; model 2 is the default and supports RGB and grayscale. Model 1 requires RGB with non-identical planes. The model ID and these input restrictions are checked even when --weights is supplied.
Automatic weights lookup: When --weights is omitted, DeepSNR finds the selected model in its package or installed support directory. ONNX/ORT packages use DeepSNR_weights_v1.onnx or DeepSNR_weights_v2.onnx; Apple Silicon CoreML packages use the corresponding .mlpackage directories. Keep model packages intact.
--stride, -s: Tile stride. It must be even and between 2 and 512. DeepSNR defaults to 480.
Short option clustering: The only current short boolean switch is -q. Options that take values, such as -i, -o, -m, -w, and -s, must be provided separately.