CLI usage

The fitscubers binary is the command-line interface, a port of the fitscube Python package. It combines single-frequency/single-time FITS images into a FITS cube and extracts individual planes back out. Install it with:

cargo install fitscube-rs

Note

The help text on this page is generated by running the binary at docs build time, so it always matches the documented version.

$ cargo run -q --bin fitscubers -- --help
Combine single-frequency/single-time FITS images into a cube, or extract a plane

Usage: fitscubers <COMMAND>

Commands:
  combine  Combine FITS files into a cube (in frequency or time order)
  extract  Extract a plane (channel or timestep) from a FITS cube
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Common workflows

Combine a set of single-channel images into a cube:

fitscubers combine chan_*.fits cube.fits

Overwrite an existing output and trim the all-blank border of every plane to a common bounding box:

fitscubers combine --overwrite --bounding-box chan_*.fits cube.fits

Build a cube along the time axis instead of frequency:

fitscubers combine --time-domain epoch_*.fits cube.fits

Extract one channel back out of a cube:

fitscubers extract cube.fits --channel-index 0 --output-path chan0.fits

fitscubers combine

$ cargo run -q --bin fitscubers -- combine --help
Combine FITS files into a cube (in frequency or time order)

Usage: fitscubers combine [OPTIONS] <FILE_LIST>... <OUT_CUBE>

Arguments:
  <FILE_LIST>...  FITS files to combine (in frequency or time order)
  <OUT_CUBE>      Output FITS cube path

Options:
  -o, --overwrite                  Overwrite the output file if it exists
      --create-blanks              Try to create a cube with evenly spaced frequencies/times (blank gaps)
      --time-domain                Build a time-domain cube (DATE-OBS) instead of frequency (FREQ/REFFREQ)
      --spec-file <SPEC_FILE>      File of frequencies (Hz) or times (MJD s), one per line
      --specs <SPECS>...           Frequencies (Hz) or times (MJD s) given on the command line
      --ignore-spec                Ignore frequency/time information and just stack
  -v, --verbosity...               Increase output verbosity (repeatable)
      --max-workers <MAX_WORKERS>  Maximum number of in-flight planes (concurrency bound)
      --bounding-box               Trim blank padding around the data using a common bounding box
      --invalidate-zeros           Set pixels whose values are exactly zero to NaN
      --floating <FLOATING>        Output float precision in bits (32 or 64). Defaults to the input [possible values: 32, 64]
  -h, --help                       Print help

The spectral (or time) axis is built from the per-image headers. Frequencies are read from, in priority order:

1. An explicit --spec-file or inline --specs list (overrides the headers).

2. The spectral WCS keywords of each input image (CRVAL/CTYPE/CUNIT of the relevant axis).

Even spacing is detected automatically and recorded as a linear axis; uneven spacing is preserved as a per-plane table. Per-channel beams, when present, are written to a CASA BEAMS binary-table extension (CASAMBM=T).

fitscubers extract

$ cargo run -q --bin fitscubers -- extract --help
Extract a plane (channel or timestep) from a FITS cube

Usage: fitscubers extract [OPTIONS] <FITS_CUBE>

Arguments:
  <FITS_CUBE>  The cube to extract a plane from

Options:
      --channel-index <CHANNEL_INDEX>  Frequency channel index to extract
      --time-index <TIME_INDEX>        Timestep index to extract
      --hdu-index <HDU_INDEX>          HDU index of the cube data [default: 0]
  -v, --verbosity...                   Increase output verbosity (repeatable)
      --overwrite                      Overwrite the output file if it exists
      --output-path <OUTPUT_PATH>      Output path. Generated from the cube name if omitted
  -h, --help                           Print help

extract is the inverse of combine: pick a plane by --channel-index (for frequency cubes) or --time-index (for time cubes) and write it as a 2D image, optionally reading from a non-primary HDU with --hdu-index.