fitscube-rs

Documentation: Python API, CLI, and algorithm background at fitscube-rs.readthedocs.io; Rust API 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, taking the frequency or time axis from the image headers and keeping per-channel beams in a CASA BEAMS table, and extracts planes back out of a cube.

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 would run without it.

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), and validates its output against that package in the test suite. See NOTICE.md for full attributions.