Crate fitsio

fitsio - a thin wrapper around the cfitsio C library.

• HDU access
• Header keys
• Reading file data
  • Images
  • Tables

This library wraps the low level cfitsio bindings: fitsio-sys and provides a more native experience for rust users.

The main interface to a fits file is FitsFile. All file manipulation and reading starts with this class.

Opening a file:

use fitsio::FitsFile;

// let filename = ...;
let fptr = FitsFile::open(filename).unwrap();

Alternatively a new file can be created on disk with the companion method create:

use fitsio::FitsFile;

// let filename = ...;
let fptr = FitsFile::create(filename).unwrap();

From this point, the current HDU can be queried and changed, or fits header cards can be read or file contents can be read.

HDU access

Information about the current HDU can be fetched with various functions, for example getting the current HDU type:

use fitsio_sys::HduType;

match fptr.hdu_type() {
    Ok(HduType::IMAGE_HDU) => println!("Found image"),
    Ok(HduType::BINARY_TBL) => println!("Found table"),
    _ => {},
}

or fetching metadata about the current HDU:

// image HDU
if let Ok(HduInfo::ImageInfo { dimensions, shape }) = fptr.fetch_hdu_info() {
   println!("Image is {}-dimensional", dimensions);
   println!("Found image with shape {:?}", shape);
}

// tables
if let Ok(HduInfo::TableInfo { column_names, num_rows, .. }) = fptr.fetch_hdu_info() {
    println!("Table contains {} rows", num_rows);
    println!("Table has {} columns", column_names.len());
}

The current HDU can be selected either by absolute number (0-indexed) or string-like:

fptr.change_hdu(1).unwrap();
assert_eq!(fptr.hdu_number(), 1);

fptr.change_hdu("TESTEXT").unwrap();
assert_eq!(fptr.hdu_number(), 1);

Header keys

Header keys are read through the read_key function, and is generic over types that implement the ReadsKey trait:

let int_value: i64 = fptr.read_key("INTTEST").unwrap();

// Alternatively
let int_value = fptr.read_key::<i64>("INTTEST").unwrap();

// Or let the compiler infer the types (if possible)

Reading file data

Images

Image data can be read through either read_section which reads contiguous pixels between a start index and end index, or read_region which reads rectangular chunks from the image.

// Read the first 100 pixels
let first_row: Vec<i32> = fptr.read_section(0, 100).unwrap();

// Read a square section of the image
use fitsio::positional::Coordinate;

let lower_left = Coordinate { x: 0, y: 0 };
let upper_right = Coordinate { x: 10, y: 10 };
let chunk: Vec<i32> = fptr.read_region(&lower_left, &upper_right).unwrap();

Tables

Columns can be read using the read_col function, which can convert data types on the fly. See the ReadsCol trait for supported data types.

let integer_data: Vec<i32> = fptr.read_col("intcol").unwrap();

The columns method returns an iterator over all of the columns in a table.

Modules

positional

Definitions of positional related types

Structs

ColumnIterator
FitsError	Error type
FitsFile	Main entry point to the FITS file format

Enums

Column
HduInfo	Description of the current HDU

Traits

DescribesHdu	Hdu description type
ReadsCol	Trait for reading a fits column
ReadsImage	Reading fits images
ReadsKey	Trait applied to types which can be read from a FITS header
WritesKey	Writing a fits keyword

Type Definitions

Result

FITS specific result type