Home

torchfits reads and writes FITS files as PyTorch tensors and Arrow tables. Cutouts and where= filters do not have to load the whole file.

Core Capabilities¶

N-D arrays

torchfits.read returns a tensor of any rank. device="cuda" or "mps" places it after the file is read.

Core I/O Workflows
Tables

where="MAG < 20" returns an Arrow table. Polars, Pandas, and DuckDB can read it. The columns are zero-copy views over the decoded buffers, and this path does not import PyTorch.

Table Workflows
Cutouts

Read a box from a large image without loading the rest. Dataset and make_loader feed a training loop.

Machine Learning with FITS

At a Glance¶

Images to TensorsCatalog Filtering & DataFramesCutoutsShell CLI Tool

import torchfits

# Read an image. device= places the tensor after the read.
tensor = torchfits.read_tensor("science.fits", hdu="SCI", device="cuda")
print(f"Loaded tensor on {tensor.device} with shape {tensor.shape}")

# Read pixel data alongside header cards
data, header = torchfits.read("science.fits", return_header=True)
print("Object:", header.get("OBJECT"))

import torchfits

table = torchfits.table.read(
    "catalog.fits",
    hdu=1,
    columns=["RA", "DEC", "MAG_G"],
    where="MAG_G < 20.0 AND CLASS_STAR > 0.8",
)

import polars as pl

df = pl.from_arrow(table)

import torchfits

# Single bounding box cutout [x1, y1, x2, y2)
stamp = torchfits.read_subset("mosaic.fits", hdu=0, x1=100, y1=100, x2=228, y2=228)

# High-throughput batch cutouts using reusable file handle
with torchfits.open_subset_reader("survey_mosaic.fits", hdu=0) as reader:
    stamp_a = reader.read_subset(100, 100, 228, 228)
    stamp_b = reader.read_subset(500, 500, 628, 628)

# Inspect extensions, shapes, and data types
torchfits info science.fits

# Dump header keywords or build cross-file summary catalogs
torchfits header *.fits --keyword-table -k OBJECT -k FILTER

# Filter binary tables and export directly to Apache Parquet
torchfits convert catalog.fits bright.parquet -e 1 -w "MAG_G < 18.0"

Why torchfits?¶

Capability	Astropy (`io.fits`) / `fitsio`	`torchfits`
GPU Tensor Placement	Manual host read \(\rightarrow\) `.to(device)` copy	Host decode, then `device="cuda"` / `"mps"` places the tensor
Catalog Query & Slicing	Load full table to Python \(\rightarrow\) boolean mask	C++ in-engine `where=` pushdown to PyArrow
Mosaic Cutouts	Section indexing or full-frame slicing	Zero-overhead `read_subset` & `open_subset_reader`
Machine Learning Pipelines	Custom boilerplate wrapper classes	Native `FitsImageDataset` + multi-worker `make_loader`
Command-Line Suite	Disparate tools (`fitsinfo`, `imstat`, `fpack`)	Unified, multi-core `torchfits` CLI suite
Packaging & Installation	May require local C compilation	Prebuilt wheels with vendored CFITSIO

Benchmarks, parity, and migration notes are in Evaluation.

Documentation Pathways¶

Getting Started
- Installation Guide — Prebuilt wheels, CPU-only, CUDA builds, and source.
- Quick Start — 5-minute tour of core operations.
- Compatibility Matrix — Python, PyTorch, and platform support.
User Guides
- Python Workflows — Best practices for images, tables, and datasets.
- CLI Guide — Complete 15-command shell reference.
- CLI Recipes — Practical, copy-pasteable shell workflows.
- Transforms Gallery — Astronomical stretch and normalization gallery.
Reference & Internals
- API Reference — Full signatures, parameters, and return types.
- Core I/O & Tables API — Detailed class & function docs.
- Evaluation — Benchmarks, parity, and migration notes.

Docs channels: stable (latest release) · edge (main tip).