StarNet2 CLI for Linux - ONNX Runtime Backend
=============================================

StarNet2 removes stars from astronomical images. This package uses the ONNX Runtime
backend and includes the executable, model weights, and package-local runtime libraries together.

Keep ./starnet2, StarNet2_weights.onnx, and lib/ directory together. The
executable uses the bundled weights next to itself by default. Use
--weights only to override the bundled model file.
Do not mix files from different StarNet2 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 starnet2 in /usr/bin and the model/runtime files in /usr/lib/starnet2.
After that, starnet2 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,
StarNet2 reports:

  Backend: ONNX Runtime (CUDA execution provider)

If CUDA is unavailable or incomplete, StarNet2 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 starnet2 from anywhere, place the files like this:

    /usr/local/bin/starnet2
    /usr/local/lib/starnet2/<model weights>
    /usr/local/lib/starnet2/<runtime libraries>

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


Quick Start
-----------

Run the executable from the extracted package directory, or invoke it by
path from another working directory:

  ./starnet2 --input input.tif --output starless.tif

By default StarNet2 writes only the starless image. To also write a star
mask, provide a mask filename:

  ./starnet2 --input input.tif --output starless.tif --mask starmask.tif

Optional unscreen star-layer output (disabled unless --unscreen is provided):

  ./starnet2 --input input.tif --output starless.tif --unscreen stars.tif


Options
-------

  -i, --input <file>
      Input image filename. Required for processing. Recommended: TIFF/TIF, PNG, or supported FITS.

  -o, --output <file>
      Starless output image filename. Default: starless.jpg. Use .fit, .fits, or .fts for 32-bit floating-point FITS output.

  -m, --mask <file>
      Optional star mask output filename. Disabled unless provided.

  -n, --unscreen <file>
      Optional unscreen star-layer output filename. Disabled unless provided.

  -w, --weights <file>
      Override the bundled model file. Normally omit this option; the
      executable loads StarNet2_weights.onnx from its package directory.

  -s, --stride <int>
      Tile stride. Default: 256. The value must be even and no larger than
      the 512 pixel processing window.

  -u, --upsample
      Use intermediate 2x upsampling before inference, then downsample outputs.
      This is slower and uses more memory.

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

  -q, --quiet
      Suppress progress output.

  -e, --eight
      Write TIFF and PNG starless, mask, and unscreen outputs 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, -equ is equivalent to
-e -q -u. Only switches without values can be clustered; options that take
values, such as -i, -o, -m, -n, -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.

Supported inputs are grayscale or RGB/color images. Images with alpha channels
or other channel counts are rejected. Images must be at least 512x512 pixels in
normal mode.

TIFF and PNG starless, mask, and unscreen 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 starless, mask, and unscreen outputs
are saved as 32-bit floating-point standard image HDUs.

Legal
-----

See LICENSE.txt for the StarNet2 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.
