fitscube-rs

Documentation for the Python API, CLI and algorithms is at fitscube-rs.readthedocs.io. The Rust API is at docs.rs/fitscube-rs.

A Rust port of the fitscube Python package. It stacks single-frequency or single-time FITS images into a cube, extracts planes from a cube, and compresses cubes with gzip or FITS tile compression (as fpack does). The frequency or time axis comes from the image headers. Per-channel beams go into a CASA BEAMS table.

Note: this is an experiment in LLM-assisted coding with Claude. Do not trust this software as far as you can throw it.

Installation

Python library

pip install fitscube-rs

CLI binary

Requires Rust 1.88+.

cargo install fitscube-rs

Usage

• Python API and quickstart: fitscube-rs.readthedocs.io/en/latest/quickstart.html
• CLI reference: fitscube-rs.readthedocs.io/en/latest/cli.html
• Rust API: docs.rs/fitscube-rs

Development

Install in editable mode:

uv pip install -e .

After changing the Python-facing Rust API in src/python.rs, rebuild with the stubgen feature (the default build omits _generate_stubs) and regenerate the type stubs:

uv run maturin develop --features stubgen
uv run --no-sync python -c "from fitscube_rs._fitscube_rs import _generate_stubs; _generate_stubs()"

This rewrites fitscube_rs/_fitscube_rs/__init__.pyi from the Rust signatures and docstrings. Commit it with the API change.

Running tests

Python tests need the compiled extension and the test extra, which includes fitscube for the parity tests. uv sync builds the extension into .venv. uvx pytest does not work, because it runs without the extension.

uv sync --extra test --reinstall-package fitscube-rs   # rebuild after Rust changes
uv run --no-sync pytest

Rust tests run with cargo test:

cargo test

Pre-commit hooks

prek runs the hooks in .pre-commit-config.yaml, the same checks as CI: ruff, ty, cargo fmt and cargo clippy.

uv sync --extra dev   # installs prek + ty into the venv
uvx prek install      # install the git hook (runs on every commit)
uvx prek run --all-files   # run all hooks manually

License

fitscube-rs is released under the BSD 3-Clause License.

It is a port of the fitscube Python package by Alec Thomson (BSD 3-Clause). The tests compare its output with that package. See NOTICE.md for full attributions.