CFITSIO: An Open Source Library Based on C++

CFITSIO is a C language library for reading and writing FITS format files. FITS is a widely used data format in the field of astronomy, supporting not only images but also multi-dimensional arrays, tabular data, and more. CFITSIO simplifies the complexity of handling FITS files for programmers by providing a series of high-level functions, making it an indispensable tool in astronomical data processing.

This article references or cites some content from online resources, aiming to provide comprehensive information. Some of this information may come from unofficial sources, and it is recommended to consult official documentation for the most accurate and up-to-date guidance when dealing with critical applications.

🔭 Core Features of CFITSIO

CFITSIO provides a complete API for manipulating FITS files, and its main functionalities can be summarized as follows:

2. File and Data Unit Operations

   • File Access: Supports creating, opening, and closing FITS files.
   • HDU Management: FITS files consist of multiple Header Data Units (HDUs), and CFITSIO provides functionality to move between HDUs, read information, and create new HDUs. For example, you can use the fits_movabs_hdu function to move to a specified HDU.

4. Image Data Processing

   • Supports reading and writing multi-dimensional image data. For instance, the fits_read_pix and fits_write_pix functions can be used to read and write image pixels.
   • Can retrieve basic information such as image dimensions and data types.

6. Table Data Processing

   • Supports reading, writing, and creating ASCII tables and binary tables.
   • Notably, it supports reading and writing variable-length arrays, which is very useful when dealing with irregular data.

8. Header Keyword Operations

   • Can read, modify, add, or delete keywords in the header information. The header contains metadata about the data, which is crucial for astronomical data processing.

10. Other Useful Features

    • Data Compression: Supports various image compression formats.
    • Error Reporting: Provides detailed error reporting for easier debugging.

🛠️ How to Use CFITSIO

Basic Programming Model

When programming with CFITSIO, the following steps are typically followed:

2. Declaration and Initialization: First, declare a fitsfile structure pointer and a status variable status. Almost all CFITSIO functions require status as a parameter, which should be initialized to 0 before calling.
4. Open or Create File: Use fits_open_file to open an existing file or fits_create_file to create a new file.
6. Perform Operations: Such as reading and writing data, manipulating header information, etc.
8. Error Checking: After each CFITSIO function call, check the status variable. If it is not 0, use fits_report_error to output the error information.
10. Close File: Use fits_close_file to close the file.

Code Example

Below is a simple example demonstrating how to open a FITS file and read its basic information and keywords from the header:

#include <stdio.h>
#include "fitsio.h"

int main() {
    fitsfile *fptr;       // FITS file pointer
    int status = 0;       // Status variable, must be initialized to 0
    int naxis;            // Image dimensions
    long naxes[2] = {1, 1}; // Image size, initialized to 1x1
    char dateobs[80];     // Store the value of the DATE-OBS keyword

    // Open FITS file (read-only mode)
    fits_open_file(&fptr, "example.fits", READONLY, &status);
    if (status) {
        fits_report_error(stderr, status);
        return 1;
    }

    // Get image dimensions
    fits_get_img_dim(fptr, &naxis, &status);
    // Get image size
    fits_get_img_size(fptr, 2, naxes, &status);

    // Read the DATE-OBS keyword from the header
    fits_read_key(fptr, TSTRING, "DATE-OBS", dateobs, NULL, &status);

    if (status) {
        fits_report_error(stderr, status);
    } else {
        printf("Image Dimensions: %d\n", naxis);
        printf("Image Size: %ld x %ld\n", naxes[0], naxes[1]);
        printf("Observation Date: %s\n", dateobs);
    }

    // Close file
    fits_close_file(fptr, &status);
    return 0;
}

When compiling the above program, link the CFITSIO library:

gcc -o my_program my_program.c -lcfitsio -lm

Installing CFITSIO

The method of installing CFITSIO varies across different operating systems:

• Linux: Typically installed from source code.
  2. Download the source package and extract it.
  4. Navigate to the extracted directory and execute ./configure.
  6. Execute make to compile.
  8. Finally, execute sudo make install to install.
• macOS: Can be installed via Homebrew: brew install cfitsio.
• Windows: Can be installed using a WSL environment to simulate Linux installation or by using precompiled binaries.

💡 Main Advantages and Features of CFITSIO

CFITSIO is widely used in the field of astronomy due to the following features:

• Cross-Platform: Runs on Linux, macOS, and Windows.
• Multi-Language Support: In addition to C, it also provides interfaces for Fortran.
• High Performance: Efficiently handles large FITS files.
• Active Maintenance: As a mature and widely used library, CFITSIO is continuously updated to fix issues.
• Rich Documentation and Examples: Provides detailed user manuals and example code, reducing the learning curve.

🔄 Collaboration with Other Tools

As a low-level C library, CFITSIO’s functionality is also encapsulated by other high-level languages or tools, such as:

• Python: Libraries like astropy.fits and fitsio use CFITSIO at their core, providing convenient FITS file manipulation interfaces for Python users.
• MATLAB: MATLAB also provides low-level FITS functions based on CFITSIO, allowing users to directly call CFITSIO functionalities within the MATLAB environment.
• C++: Although CFITSIO is a C library, C++ programs can call it directly. Additionally, there are C++ wrappers based on CFITSIO, such as CCfits.

⚠️ Usage Considerations

• Status Checking: Always check the status value after each CFITSIO function call, which is key to ensuring the program runs correctly.
• Resource Management: Ensure that opened files are properly closed after use.
• Data Type Matching: When reading and writing data, pay attention to CFITSIO’s data types (e.g., TINT, TFLOAT, TDOUBLE, etc.) matching the data types of your program’s variables.
• String Handling: In some cases, CFITSIO may clear unrelated strings, so be cautious.

💎 Conclusion

CFITSIO is a powerful, efficient, and reliable astronomical data I/O library. Whether you are an astronomer needing to directly handle FITS files or a software engineer developing astronomical data processing tools, CFITSIO is a trustworthy tool.