StarNet Command-line Tool Documentation

Documentation

This section collects technical notes and usage guides for StarNet and DeepSNR: 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.5.2 across Linux, Windows, Intel Mac, and Apple Silicon Mac.

Running options

USAGE:

  starnet2  [-ehqu] [--version] [-m <string>] [-n <string>] [-o <string>]
            [-s <int>] [-w <string>] -i <string>

Options:
  -i <string>, --input <string>
      Required input image filename. Recommended: TIFF/TIF or PNG.

  -o <string>, --output <string>
      Output image filename. TIFF/PNG default to 16-bit unless --eight is used.

  -m <string>, --mask <string>
      Optional mask output filename. Disabled unless provided. TIFF/PNG default
      to 16-bit unless --eight is used.

  -n <string>, --unscreen <string>
      Unscreen star-layer output filename. TIFF/PNG default to 16-bit unless
      --eight is used.

  -w <string>, --weights <string>
      Override path to the model checkpoint.

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

  -u, --upsample
      Use intermediate 2× upsampling.

  -q, --quiet
      Do quiet run with no terminal output.

  -e, --eight
      Write TIFF and PNG starless, mask, and unscreen outputs as 8-bit instead
      of the default 16-bit.

  --, --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 or PNG, 8-bit or 16-bit integer,
               grayscale or RGB.
  Might work: JPEG/JPG and BMP through OpenCV,
              but these formats were not tested.
  Not accepted: floating-point images, alpha channels,
                unsupported channel/depth layouts.

Outputs:
  TIFF and PNG outputs are saved as 16-bit or 8-bit with --eight.
  TIFF outputs are always saved with LZW compression.

Package layout:
  Portable archive:
    To run from the extracted archive, keep these files together:
    starnet2/
      starnet2 or starnet2.exe
      StarNet2_weights.onnx
      lib/ or runtime DLLs
      README.txt
      LICENSE.txt

  Installed package:
    Native installers place the executable in a system bin directory and keep
    model/runtime files in the matching StarNet2 support directory. See CLI
    installer locations for OS-specific paths.

StarNet2 v2.5.2

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
Write all StarNet outputs in one run: starnet2 --input input.tif --output starless.tif --mask starmask.tif --unscreen stars.tif
Force 8-bit TIFF or PNG output: starnet2 --input input.tif --output starless.png --eight

Inputs and outputs

File formats: TIFF/TIF and PNG are the recommended tested input formats. JPEG/JPG and BMP might work through OpenCV, but they were not tested for this release. JPEG is lossy and is not recommended for scientific or archival data.
Bit depth: 8-bit and 16-bit integer inputs are supported. Unsupported input depths, including 32-bit floating-point images, are rejected; convert them to 16-bit integer before running the tool.
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 in normal mode.
Default output depth: TIFF and PNG starless, mask, and unscreen outputs are written as 16-bit integer images by default.
--eight: Use this only when you intentionally want 8-bit TIFF or PNG output. It applies to starless, mask, and unscreen outputs.
Compression: TIFF outputs are always saved with LZW compression. PNG output uses the default OpenCV encoding. Other output formats are written as 8-bit images.

StarNet-specific options

--mask, -m: Writes an optional mask output. Use it when the workflow needs a mask rather than only a starless image.
--unscreen, -n: Writes an unscreen star-layer output. This is independent from --mask; either, both, or neither optional output can be requested.
--upsample, -u: Uses intermediate 2× upsampling. Use it for tight stars or difficult structures; expect higher runtime cost.
Short option clustering: Short boolean switches can be combined. For example, -equ is equivalent to -e -q -u. Options that take values, such as -i, -o, -m, -n, -w, and -s, must be provided separately.