fitscube-rs 1.1.0

Combine single-frequency/single-time FITS images into a FITS cube (Rust port of fitscube)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# CLI usage

The `fitscube` binary is the command-line interface, a port of the
[`fitscube`](https://github.com/AlecThomson/fitscube) Python package. It
combines single-frequency/single-time FITS images into a FITS cube and extracts
individual planes back out. Install it with:

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

```{command-output} cargo run -q --bin fitscube -- --help
:cwd: ..
```

## Common workflows

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

```sh
fitscube combine chan_*.fits cube.fits
```

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

```sh
fitscube combine --overwrite --bounding-box chan_*.fits cube.fits
```

Build a cube along the time axis instead of frequency:

```sh
fitscube combine --time-domain epoch_*.fits cube.fits
```

Extract one channel back out of a cube:

```sh
fitscube extract cube.fits --channel-index 0 --output-path chan0.fits
```

## `fitscube combine`

```{command-output} cargo run -q --bin fitscube -- combine --help
:cwd: ..
```

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

## `fitscube extract`

```{command-output} cargo run -q --bin fitscube -- extract --help
:cwd: ..
```

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