cfitsio.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_ocm_libfits
 * @copyright 2022 ESO - European Southern Observatory
 *
 * @brief Contains functions and data structures related to cfitsio.
 */
#ifndef DAQ_OCM_DAQ_FITS_CFITSIO_HPP_
#define DAQ_OCM_DAQ_FITS_CFITSIO_HPP_
#include <cstddef>
#include <memory>
#include <optional>
#include <stdexcept>
#include <iosfwd>
 
#include <cfitsio/fitsio.h>
 
#include <daq/fits/keyword.hpp>
 
namespace daq::fits {
enum class HduType : int {
    Image = IMAGE_HDU,
    Ascii = ASCII_TBL,
    Binary = BINARY_TBL,
};
 
/**
 * Format HduType @a hdu_type to @a os.
 */
std::ostream& operator<<(std::ostream& os, HduType hdu_type);
 
enum class OpenMode : uint8_t { ReadOnly, ReadWrite };
 
/**
 * Defines unique ownership type to cfitsio fitsfile.
 *
 * @ingroup daq_ocm_libfits
 */
using UniqueFitsFile = std::unique_ptr<fitsfile, void (*)(fitsfile*) noexcept>;
 
/**
 * In-memory FITS file.
 */
class MemoryFitsFile {
public:
    /**
     * Creates empty file.
     */
    MemoryFitsFile() noexcept;
    /**
     * Creates empty file.
     */
    explicit MemoryFitsFile(std::size_t initial_buffer_size);
    explicit MemoryFitsFile(MemoryFitsFile&& other) noexcept = default;
    MemoryFitsFile& operator=(MemoryFitsFile&& other) noexcept = default;
 
    /**
     * Get fits pointer
     *
     * @return In-memory FITS file pointer.
     */
    fitsfile* GetFile() const noexcept {
        return m_file.get();
    }
 
    /**
     * Move out ptr.
     *
     * @warning Object lifetime of this object must exeed the UniqueFits file as it
     * references memory owned associated by this object.
     *
     * @return Owned FITS file.
     */
    UniqueFitsFile GetOwnedFile() && {
        return std::move(m_file);
    }
 
private:
    /** In-memory buffer used by FITS */
    struct FitsMemory {
        FitsMemory(std::size_t initial_size);
        ~FitsMemory() noexcept;
        void* buffer;
        std::size_t size;
    };
 
    std::unique_ptr<FitsMemory> m_memory;
    UniqueFitsFile m_file;
};
 
/**
 * Represents errors from cfitsio.
 *
 * @ingroup daq_ocm_libfits
 */
class CfitsioError : public std::runtime_error {
public:
    CfitsioError(int status, char const* message);
    CfitsioError(int status, std::string const& message);
 
    /**
     * @return cfitsio status code causing the exception.
     */
    int GetStatus() const noexcept;
 
private:
    int m_status;
};
 
/**
 * Select current HDU number.
 * @param hdu_num HDU number starting with primary HDU == 1.
 */
void SelectHduNum(fitsfile* ptr, int hdu_num);
 
/**
 * Default close function that is used by UniqueFitsFile as a deleter.
 *
 * @ingroup daq_ocm_libfits
 */
void DefaultClose(fitsfile* ptr) noexcept;
 
/**
 * Creates empty FITS file using @c fits_create_file and returns a pointer with a deleter that will
 * close the file.
 *
 * @ingroup daq_ocm_libfits
 */
UniqueFitsFile CreateEmpty(char const* filename);
 
/**
 * Open file
 *
 * @param filename Path to file to open.
 * @param mode File open mode.
 * @throw CfitsioError on errors.
 */
UniqueFitsFile Open(char const* filename, OpenMode mode);
 
/**
 * Initializes an empty FITS file with an empty primary HDU (no keywords)
 *
 * @pre ptr != nullptr
 *
 * @param ptr Valid FITS file.
 * @throw CfitsioError on error.
 */
void InitPrimaryHduEmpty(fitsfile* ptr);
 
/**
 * Initializes an empty FITS file with a primary HDU
 *
 * Mandatory keywords are set and primary HDU added if necessary.
 *
 * Mandatory keywords are initialized as:
 * - SIMPLE = T
 * - BITPIX = 8
 * - NAXIS = 0
 *
 * @pre ptr != nullptr
 *
 * @param ptr Valid FITS file.
 * @throw CfitsioError on error.
 */
void InitPrimaryHduNoImage(fitsfile* ptr);
 
/**
 * Read keywords from HDU identifed by absolute position @a hdu_num.
 *
 * @param ptr FITS file to read from.
 * @param hdu_num HDU number. HDU numbers are 1-indexed, so primary HDU is 1.
 * @throw CfitsioError on error.
 */
std::vector<LiteralKeyword> ReadKeywords(fitsfile* ptr, int hdu_num);
 
/**
 * Delete all keywords from HDU
 *
 * @param ptr FITS file to delete keywords from.
 * @param hdu_num HDU number. HDU numbers are 1-indexed, so primary HDU is 1.
 * @throw CfitsioError on error.
 */
void DeleteAllKeywords(fitsfile* ptr, int hdu_num);
 
/**
 * Read keywords from HDU identifed by @a EXTNAME and @c EXTVER keywords.
 *
 * @param ptr FITS file to read from.
 * @param name HDU extension name as identified by @c EXTNAME keyword.
 * @param version HDU extension version as identified by @c EXTVER keyword. If version is not
 * provided the @c EXTVER will be ignored when looking up extension.
 * @throw CfitsioError on error.
 */
std::vector<LiteralKeyword>
ReadKeywords(fitsfile* ptr, std::string_view name, std::optional<int> version = std::nullopt);
 
/**
 * Write keywords to HDU identified by number @a hdu_num.
 *
 * @param ptr FITS file to write to.
 * @param hdu_num HDU number. HDU numbers are 1-indexed, so primary HDU is 1.
 * @param keywords Keywords to write.
 * @param [out] remaining_size optional parameter that is updated with remaining size in HDU before
 * any allocations. If this number is negative it means the HDU required to be allocated with an
 * associated performance penalty.
 *
 * @throw CfitsioError on error.
 */
void WriteKeywords(fitsfile* ptr,
                   int hdu_num,
                   std::vector<LiteralKeyword> const& keywords,
                   std::optional<ssize_t>* remaining_size = nullptr);
 
/**
 * Write or update checksum keywords DATASUM and CHECKSUM to HDU specified by @a hdu_num.
 *
 * @param hdu_num HDU to calculate and update checksum keywords for if necessary.
 * @throw CfitsioError on error.
 */
void WriteChecksum(fitsfile* ptr, int hdu_num);
 
}  // namespace daq::fits
 
#endif  // #define DAQ_OCM_DAQ_FITS_CFITSIO_HPP_