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

StarNet command-line tool reference

This page describes the current StarNet command-line options, example commands, supported inputs, and output behavior. Current command-line packages are StarNet2 2.6.2 on Linux, Windows, Intel Mac, and Apple Silicon Mac.

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: 

   starnet2  [-dhqu] [--check-updates] [--linear] [--machine-info]
             [--machine-progress] [--version] [-m <string>] [-n <string>]
             [-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.

   -m <string>,  --mask <string>
     Optional mask output filename. Disabled unless provided. See Outputs
     below for sample-type policy.

   -n <string>,  --unscreen <string>
     Unscreen star-layer output 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.

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

   -u,  --upsample
     Use intermediate 2x upsampling

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

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

   -d,  --disable-highlights-protection
     Disable starless output highlight protection for comparison or
     troubleshooting.

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

   --check-updates
     Check the latest StarNet2 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.

   
    StarNet2 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.
      With --linear only, negative shadows are restored after MTF.
   
    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 main/difference preserves source storage type and
   scaling.
      Linear MTF/inverse uses float64; only neural inference uses float32.
      Main/difference FITS retains source units. Float unscreen uses
   fractions,
      BUNIT=1 and identity FITS scaling; integer unscreen uses full-range
   encoding.
      Difference is clamped to [0,1] in normalized units. Reconstruction is
      limited by caps, guards and storage quantization.
      Discarded highlights are not restored by either star-layer output.
      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:
        starnet2/
          starnet2
          StarNet2_weights.onnx
          lib/
          README.txt
          LICENSE.txt
   
      Manual install:
        To run starnet2 from anywhere, place the files like this:
        /usr/local/bin/starnet2
        /usr/local/lib/starnet2/StarNet2_weights.onnx
        /usr/local/lib/starnet2/<runtime libraries>
   
      Package managers can use:
        /usr/bin/starnet2
        /usr/lib/starnet2/...
   
    StarNet2 v2.6.2
   
    Copyright (c) 2026 Mikita (Nikita) Misiura | https://starnetastro.com

Example commands

Write a starless image: starnet2 --input input.tif --output starless.tif
Write a starless image and subtractive star mask: starnet2 --input input.tif --output starless.tif --mask starmask.tif
Write a starless image and unscreen star layer: starnet2 --input input.tif --output starless.tif --unscreen stars.tif
Use 2× upsampling for a difficult image: starnet2 --input input.tif --output starless.tif --upsample
Compare output without highlight protection: starnet2 --input input.tif --output starless.tif --disable-highlights-protection
Write all StarNet outputs in one run: starnet2 --input input.tif --output starless.tif --mask starmask.tif --unscreen stars.tif
Process a linear FITS image with automatic MTF: starnet2 --input "linear light.fits" --output "linear starless.fits" --linear
Tune the automatic linear stretch: starnet2 --input linear.fits --output starless.fits --linear --shadows-clipping -3.0 --target-background 0.2

Inputs and outputs

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: RGB/color and grayscale inputs are accepted. Images with alpha channels or other channel counts are rejected.
Image size: Images must be at least 512 × 512 pixels, or 256 × 256 with --upsample. Output retains the original image size.
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, main and difference FITS outputs preserve 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.

StarNet-specific options

--mask, -m: Writes the positive difference between the input and starless image, clamped to [0,1] in normalized units. FITS output retains source units. Clipping and storage quantization limit exact reconstruction.
--unscreen, -n: Writes an unscreen star layer independently from --mask. Float FITS stores dimensionless fractions with BUNIT=1 and identity scaling; integer FITS encodes fractions over the full format range. Guards, clipping, and storage quantization limit reconstruction.
--upsample, -u: Uses intermediate 2× upsampling and returns the original image size. Use it for tight stars or difficult structures; expect higher runtime and memory costs.
Short option clustering: Short boolean switches can be combined. For example, -qu is equivalent to -q -u. Options that take values, such as -i, -o, -m, -n, -w, and -s, must be provided separately.