File and HDU handlers

Detailed Description

Service classes to read and write FITS files.

General concepts

EleFits is split into service classes, known as handlers, in the package EleFits, and data classes in EleFitsData.

File handlers (MefFile and SifFile) store the index and type of the HDUs, access and create HDUs. HDU handlers (ImageHdu, Header, BintableColumns...) only provide read/write services. Records, images and tables are never stored by those classes (to know where they are, refer to Data classes). Instead, when you access an HDU, you just access a set of services to read and write items in this HDU.

FitsFile is mostly en empty shell for opening and closing operations. You could instantiate and destroy a FitsFile: this would just create a file with empty Primary, and not even give you access to it! Services of iterest lie in the MefFile and SifFile classes. They both extend FitsFile, therefore when a MefFile or SifFile is created, the Primary HDU is initialized with an empty image. This means:

• That you don't create the Primary HDU yourself, and the header is immediately accessible;
• That you have to reshape the Primary array in order to write data to it.

The rationale is that a FitsFile should always represent a valid FITS file, and therefore have at the minimum one image HDU with all the mandatory keyword records.

Multi-extension Fits

Multi-extension FITS (MEF) files are manipulated through the MefFile class.

All in all, MefFile is a mere container of HDUs, each of which is either of type ImageHdu or BintableHdu. There are methods to access the HDUs by index or by name, to select and iterate over HDUs, and to create new HDUs. Classes ImageHdu and BintableHdu extend Hdu, a parent class which implements the common services. The header units are manipulated by Header objects. The data units of image and binary table HDUs are respectively manipulated by ImageRaster and BintableColumns or objects.

Conceptually, MefFile is a tree of objects, which can be minimalistically represented as follows (there are actually many more methods available):

MefFile services:

• create, open and close the MEF file
• access HDUs as ImageHdus and BintableHdus
• loop over selected HDUs
• create new HDUs

ImageHdu services:

• get properties (index, name, checksums...)
• access the header unit as Header
  • read records
  • write records
• access the data unit as ImageRaster
  • read pixels
  • write pixels

BintableHdu services:

• get properties (index, name, checksums...)
• access the header unit as Header
  • read records
  • write records
• access the data unit column-wise as BintableColumns
  • read columns
  • write columns
• access the data unit row-wise as BintableRows
  • read rows
  • write rows

Single image Fits

Although they can be seen as simplistic instances of a MEF file, Single Image FITS (SIF) files have specificities which deserve a dedicated class: SifFile. Shortcuts are provided to read and write the image data, and to access directly the header unit. Of course, it is possible to effectively handle a SIF file with a MefFile object, but this is more verbose, and does not enforce or guarantee that the file is and remains a SIF.

For comparison with MefFile, here is a much simplified tree view of SifFile:

SifFile services:

• create, open and close the SIF file
• get properties (checksums...)
• access the header unit as Header
  • read records
  • write records
• access the data unit as ImageRaster
  • read pixels
  • write pixels

Wrap-up

The organization of the service classes matches that of a FITS file:

• A FITS file can be either of type SIF or MEF;
• A MEF file contains HDUs, which themeselves contain records in a header and data in the form of an image or binary table;
• As a specific case, a SIF file is made of one header and one image.

All of the classes presented above only provide services to read and write data. The classes which own the said data are presended in Data classes.

Modules
	File handlers
	Access and create files and HDUs.
	HDU selectors and iterators
	Iterate over HDUs with selected categories and/or states.
	Header unit handlers
	Read and write header units.
	Image data unit handlers
	Read and write image data units.
	Binary table data unit handlers
	Read and write binary table data units.
	File-level strategies
	Register actions to be performed automatically according to some criteria.
	Image compression
	Compress and decompress image HDUs.