#include <MefFile.h>

Detailed Description

Multi-Extension FITS file reader-writer.

In addition to FitsFile's methods, this class provides HDU access and creation services.

A MefFile can roughly be seen as a sequence of image HDUs and binary table HDUs (see What's a FITS file?). Methods to access HDUs, header units or data units all return constant references, because they are stateless views on the MefFile object, which is the only handler modified by write operations.

At creation, a MefFile already contains a Primary, which is empty but can be resized and filled. HDUs are accessed either directly by their index, e.g. with access() or operator [], or by finding a {type, name, version} triplet with find(). Although it should not be an issue for most files (even with hundreds of HDUs), the second option is much slower because it consists in reading each header unit until a match is found. Once an HDU has been accessed, the reference can be safely reused (please don't re-find an already accessed HDU). It is possible to specify the return type of access() and find() to best fit target usage, e.g.:

const auto& p = f.primary(); // ImageHdu
const auto& hdu = f[1]; // Hdu
const auto& hdu = f.access<Hdu>(1);
const auto& hdu = f.access<ImageHdu>(1);
const auto& hdu = f.access<BintableHdu>(1);
const auto& h = f.access<Header>(1);
const auto& du = f.access<ImageRaster>(1);
const auto& du = f.access<BintableColumns>(1);

Creating extensions can be done in three ways:

Header only: A header unit is created, the data unit is empty;
Null data: A header unit is created, as well as a data unit which is filled with null values (as defined by the header contents, e.g. with record BLANK);
Complete: A header unit is created, as well as a data unit which is filled with provided values.

MefFile also follows a so-called strategy (see File-level strategies), which is made of actions triggered automatically at various moments (e.g. at file closure). One or some of them may be compression actions, which enable internal compression of image extensions (see Image compression). The strategy can be defined at construction, or with methods strategy(). By default, the strategy consists of a CiteEleFits action, which can be disabled with strategy().clear().

Note: Single Image FITS files can be handled by this class, but SifFile is better suited: it is safer and provides shortcuts.

See also: File and HDU handlers; HDU selectors and iterators; File-level strategies; Image compression; Optimization and good practices

Examples: EleFitsBintableExample.cpp, and EleFitsTutorial.cpp.

Public Member Functions
Construction

template<typename... TActions>
	MefFile (const std::string &filename, FileMode mode, TActions &&... actions)
	Create a new FITS file handler with given filename and permission. More...

virtual	~MefFile ()
	Destroy the object and close the file. More...

void	close () override
	Close the file. More...

Properties

long	hdu_count () const
	Get the number of HDUs. More...

std::vector< std::string >	read_hdu_names ()
	Read the name of each HDU. More...

std::vector< std::pair< std::string, long > >	read_hdu_names_versions ()
	Read the name and version of each HDU. More...

const Strategy &	strategy () const
	Get the strategy.

Strategy &	strategy ()
	Get the strategy.

Element access

template<class T = Hdu>
const T &	access (long index)
	Access the HDU at given 0-based index. More...

const Hdu &	operator[] (long index)
	Shortcut for `access<Hdu>(long)`

template<class T = Hdu>
const T &	find (const std::string &name, long version=0)
	Access the first HDU with given name, type and version. More...

template<class T = Hdu>
const T &	access (const std::string &name, long version=0)
	Access the only HDU with given name, type and version. More...

const ImageHdu &	primary ()
	Access the Primary HDU. More...

template<typename T = Hdu>
HduSelector< T >	filter (const HduFilter &categories=HduCategory::Any)
	Get an iterable object which represents a filtered set of HDUs. More...

Data modifiers

template<typename... TActions>
void	strategy (TActions &&... actions)
	Shortcut for `strategy().append()`.

template<typename T = Hdu>
const T &	append (const T &hdu)
	Append a copy of a given HDU. More...

template<typename T = unsigned char>
const ImageHdu &	append_image_header (const std::string &name="", const RecordSeq &records={})
	Append a new image extension with empty data unit (`NAXIS = 0`).

template<typename T , long N = 2>
const ImageHdu &	append_null_image (const std::string &name, const RecordSeq &records, const Position< N > &shape)
	Append a new image extension and fill the data unit with null values. More...

template<typename TRaster >
const ImageHdu &	append_image (const std::string &name, const RecordSeq &records, const TRaster &raster)
	Append and write a new image extension. More...

template<typename... TInfos>
const BintableHdu &	append_bintable_header (const std::string &name="", const RecordSeq &records={}, const TInfos &... infos)
	Append a binary table extension with empty data unit (0 rows, and possibly 0 columns).

template<typename... TInfos>
const BintableHdu &	append_null_bintable (const std::string &name, const RecordSeq &records, long row_count, const TInfos &... infos)
	Append a binary table extension and fill it with null values. More...

template<typename... TColumns>
const BintableHdu &	append_bintable (const std::string &name, const RecordSeq &records, const TColumns &... columns)
	Append and write a new binary table extension.

template<typename TColumns , std::size_t Size = std::tuple_size<TColumns>::value>
const BintableHdu &	append_bintable (const std::string &name, const RecordSeq &records, const TColumns &columns)
	Append and write a new binary table extension.

void	remove (long index)
	Remove the HDU with given index.

Deprecated

long	hduCount () const

std::vector< std::string >	readHduNames ()

std::vector< std::pair< std::string, long > >	readHduNamesVersions ()

template<typename T = unsigned char>
const ImageHdu &	appendImageHeader (const std::string &name="", const RecordSeq &records={})

template<typename T , long N = 2>
const ImageHdu &	appendNullImage (const std::string &name, const RecordSeq &records, const Position< N > &shape)

template<typename TRaster >
const ImageHdu &	appendImage (const std::string &name, const RecordSeq &records, const TRaster &raster)

template<typename... TInfos>
const BintableHdu &	appendBintableHeader (const std::string &name="", const RecordSeq &records={}, const TInfos &... infos)

template<typename... TInfos>
const BintableHdu &	appendNullBintable (const std::string &name, const RecordSeq &records, long row_count, const TInfos &... infos)

template<typename... TColumns>
const BintableHdu &	appendBintable (const std::string &name, const RecordSeq &records, const TColumns &... columns)

Public Member Functions inherited from FitsFile
	FitsFile (const std::string &filename, FileMode permission=FileMode::Read)
	Create a new FITS file handler with given filename and permission.

virtual	~FitsFile ()
	Destroy the object and close the file. More...

std::string	filename () const
	Get the file name.

bool	is_open () const
	Check whether the file is open.

void	reopen ()
	Reopen the file. More...

void	close_remove ()
	Close and delete the file.

fitsfile *	handover_to_cfitsio ()
	Get CFITSIO's `fitsfile*`. More...

bool	isOpen () const

void	closeAndDelete ()

fitsfile *	handoverToCfitsio ()

The documentation for this class was generated from the following file:

EleFits/EleFits/MefFile.h

Detailed Description

Public Member Functions