StarNet2 CLI for Windows - 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 DLLs together.

System requirements: 64-bit Windows 10 or newer. The bundled backend uses
DirectML when compatible and has CPU fallback.

Keep starnet2.exe, StarNet2_weights.onnx, and the bundled DLLs 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
----------------

Interactive setup asks you to accept the included license before installing.
Silent setup has no agreement UI; administrators must arrange acceptance first.

The Windows setup installer is the easiest OS-integrated installation option.
It places starnet2.exe under C:\Program Files\StarNet2\bin and the model file
under C:\Program Files\StarNet2\lib\starnet2. The installer can also add the
bin directory to the system PATH, so starnet2.exe can be run from new terminals
without manually copying files.

Optional GPU Acceleration
-------------------------

The bundled ONNX Runtime files include DirectML support on Windows. StarNet2
first tries CUDA if a compatible CUDA-enabled ONNX Runtime is present, then
tries DirectML, then falls back to CPU. DirectML does not require CUDA or cuDNN
installation. If DirectML initializes successfully, StarNet2 reports:

  Backend: ONNX Runtime (DirectML execution provider)

Advanced NVIDIA users can still replace the bundled ONNX Runtime files with a
compatible ONNX Runtime CUDA runtime. CUDA is attempted when
onnxruntime_providers_cuda.dll is next to starnet2.exe; the required CUDA/cuDNN
runtime DLLs must also be loadable by Windows, either from PATH or from the same
directory. If CUDA initializes successfully, StarNet2 reports:

  Backend: ONNX Runtime (CUDA execution provider)

If GPU providers are 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 runtime DLLs as shipped.

Manual install:
  To run starnet2.exe from anywhere, place the files like this:

    C:\Program Files\StarNet2\bin\starnet2.exe
    C:\Program Files\StarNet2\lib\starnet2\<model weights>

  Runtime DLLs must stay next to starnet2.exe.


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

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

  starnet2.exe --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.exe --input input.tif --output starless.tif --mask starmask.tif

For RGB or grayscale input, stars are computed from the final starless image
after any 2x downsampling, accounting for main-output storage rounding. Difference stars remain
positive-only and capped at 1 in normalized units; unscreen retains its input
clamps and near-saturation protection.

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

  starnet2.exe --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 FITS output; FITS input storage type and scaling are preserved.

  -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 between 2 and
      the 512 pixel processing window size. Zero and negative values are invalid.

  -u, --upsample
      Use intermediate 2x cubic upsampling, then return to the original size.
      This is slower and uses more memory.

  --linear
      Brighten linear images with per-channel MTF (midtones transfer function)
      for neural processing, then reverse the stretch.
      Original forward-shadow-clipped samples are restored automatically after
      final resampling. Upper-clipped highlights are not restored.

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

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

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


Short Option Clustering
-----------------------

Short boolean switches can be combined. For example, -dqu is equivalent to
-d -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, .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.
Negative samples are retained until forward shadows clipping; original clipped
shadows are restored after final resampling. Samples above 1 after fixed format
scaling are clipped before MTF statistics and never restored. 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].
Main/difference 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.
StarNet2-only auxiliary outputs: difference is K * clamp((E-main)/K,0,1),
where E is the effective source in physical units; the upper cap is intentional.
Float unscreen FITS uses dimensionless fractions (BUNIT=1, identity BSCALE/BZERO)
with a units warning; integer unscreen encodes fractions using the full format
range. Decode that fraction U and reconstruct as starless + U * (K - starless),
subject to caps, guards and storage quantization.
Reconstruction targets the effective upper-clipped source, never discarded
highlights. Stars are calculated against the stored main samples.
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.

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, or 256x256 pixels with --upsample. Output retains the original size.

TIFF and PNG starless, mask, and unscreen 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 starless and difference outputs preserve source storage type and
numeric scaling. Float unscreen has the dimensionless scaling exception above. 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
-----

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.
OpenCV license and dependency notices are included in opencv-licenses/.
