Getting Started with CFITSIO: A Beginner’s Guide to FITS File Handling

FITS (Flexible Image Transport System) is the standard data format in astronomy for images, tables, and metadata. CFITSIO is a widely used C library for reading and writing FITS files. This guide walks you through installing CFITSIO, understanding FITS structure, basic read/write operations, common use cases, and troubleshooting tips so you can start working with astronomical data quickly.

1. What is CFITSIO?

CFITSIO is a C library maintained by NASA’s HEASARC that provides robust, high-performance routines to read, write, and manipulate FITS files. It supports images, binary and ASCII tables, headers, compressed FITS, and many FITS conventions used in astronomy.

2. Installing CFITSIO

On macOS (Homebrew):

Code
brew install cfitsio

On Debian/Ubuntu:

Code
sudo apt-get update sudo apt-get install libcfitsio-dev

From source:
1. Download latest source from HEASARC: https://heasarc.gsfc.nasa.gov/fitsio/
2. Extract and build:
```
Code
./configure make sudo make install 
```

Verify installation: check header and library:

Code
ls /usr/local/include /usr/include | grep fitsio

3. FITS file basics

HDU (Header Data Unit): Each FITS file consists of one or more HDUs; the first is the primary HDU (often an image).
Header: ASCII keyword/value/comment records describing the data (e.g., NAXIS, BITPIX).
Data unit: Image pixels or table rows follow the header.
Common types: Image HDU, ASCII table (TABLE), binary table (BINTABLE).

4. A minimal CFITSIO C example

Below is a concise example that opens a FITS file, reads the primary image dimensions, and prints one pixel value.

c
#include 
#include “fitsio.h”

int main() {
fitsfile fptr;
    int status = 0, naxis = 0;
    long naxes[2] = {1,1};
    long fpixel[2] = {1,1};
    double pixel;

    if (fits_open_file(&fptr, “example.fits”, READONLY, &status)) {
        fits_report_error(stderr, status);
        return status;
    }

    fits_get_img_dim(fptr, &naxis, &status);
    fits_get_img_size(fptr, 2, naxes, &status);
    printf(“Image dimensions: %ld x %ld “, naxes[0], naxes[1]);

    if (fits_read_pix(fptr, TDOUBLE, fpixel, 1, NULL, &pixel, NULL, &status)) {
        fits_report_error(stderr, status);
    } else {
        printf(“Pixel [1,1] = %g “, pixel);
    }

    fits_closefile(fptr, &status);
    return status;
}

Compile: gcc -o readfits readfits.c -lcfitsio

Run: ./readfits

5. Writing a simple FITS image

Example to create a 100×100 float image and fill it with values:

c
#include #include #include “fitsio.h” int main() { fitsfilefptr; int status = 0; long naxes[2] = {100, 100}; float image; long fpixel[2] = {1,1}; image = (float ) malloc(naxes[0] naxes[1] sizeof(float)); for (long i = 0; i < naxes[0]naxes[1]; i++) image[i] = (float)i; if (fits_create_file(&fptr, ”!” “newimage.fits”, &status)) { fits_report_error(stderr, status); return status; } fits_create_img(fptr, FLOAT_IMG, 2, naxes, &status); long nelements = naxes[0] naxes[1]; if (fits_write_img(fptr, TFLOAT, 1, nelements, image, &status)) fits_report_error(stderr, status); fits_close_file(fptr, &status); free(image); return status; }

Note: “!” before filename overwrites existing files.

6. Working with tables

Use fits_create_tbl, fits_insert_col, fits_write_col for binary/ASCII tables.

Use structure arrays (e.g., long, int, double, char*) to populate columns.

Remember to set column formats (TFORMn) and names (TTYPEn) via CFITSIO routines.

7. Common tasks and tips

Read header keywords: fits_read_key to fetch values like CRVAL, CDELT.

Modify header: fits_update_key to add/change keywords.

Iterate HDUs: fits_movabs_hdu or fits_movrel_hdu to access extensions.

Memory: For large images use chunked reads or memory-mapping strategies.

Error handling: Always check and propagate the status integer; use fits_report_error for readable messages.

Compression: CFITSIO supports tile-compressed images; use functions documented in the CFITSIO manual.

8. Integrations and higher-level interfaces

Python: Astropy’s fits module (astropy.io.fits) is built on top of CFITSIO and provides a Pythonic API.

Other languages: wrappers exist for Fortran and IDL; many astronomy tools use CFITSIO under the hood.

9. Resources

CFITSIO User’s Guide and reference (HEASARC): https://heasarc.gsfc.nasa.gov/fitsio/

Example codes included with the CFITSIO distribution.

Astropy docs for Python usage: https://docs.astropy.org/

10. Troubleshooting

“Undefined reference to fits_open_file”: link with -lcfitsio and ensure library path is correct.

Corrupt FITS: check header for missing END card or incorrect NAXIS values.

Permission errors: verify file paths and overwrite flag “!” when creating files.

Getting comfortable with CFITSIO requires reading the manual and experimenting with small programs. Start by inspecting headers and reading simple images, then progress to tables and writing routines.

Getting Started with CFITSIO: A Beginner’s Guide to FITS File Handling