StarNet2 CLI for macOS x64 - 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.

System requirements: macOS 13.4 or newer on an Intel Mac, or on Apple Silicon
through Rosetta 2.

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

Installer asks you to agree to the included license before installing.
Command-line installation has no agreement UI; arrange acceptance first.

The macOS .pkg installer is the easiest OS-integrated installation option. It
places starnet2 in /usr/local/bin and the model/runtime files in
/usr/local/lib/starnet2. After that, starnet2 can be run from any terminal
without manually copying files.

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>


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

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 --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 lib/opencv-licenses/.
