fitsUtils.hpp

Go to the documentation of this file.

/** \file fitsUtils.hpp
 * \brief Declares and defines utilities to work with FITS files
 * \ingroup fits_processing_files
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 */
 
//***********************************************************************//
// Copyright 2015-2022 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef ioutils_fits_fitsUtils_hpp
#define ioutils_fits_fitsUtils_hpp
 
#include <iostream>
#include <cstdlib>
#include <cstring>
#include <complex>
 
#include <fitsio.h>
 
#include "../stringUtils.hpp"
 
namespace mx
{
namespace fits
{
 
/// The standard width of the value entry in a header card
#define stdValWidth ( 20 )
 
// #define fitsTUNKNOWN (-5000)
struct fitsUnknownType
{
};
 
// #define fitsTCOMMENT (-5001)
struct fitsCommentType
{
    fitsCommentType()
    {
    }
 
    explicit fitsCommentType( char *v )
    {
        static_cast<void>( v );
    }
 
    explicit fitsCommentType( const char *v )
    {
        static_cast<void>( v );
    }
};
 
// #define fitsTHISTORY (-5002)
 
struct fitsHistoryType
{
    fitsHistoryType()
    {
    }
 
    explicit fitsHistoryType( char *v )
    {
        static_cast<void>( v );
    }
 
    explicit fitsHistoryType( const char *v )
    {
        static_cast<void>( v );
    }
};
 
/** \ingroup fits_utils
 * @{
 */
 
/// Return the cfitsio constant for a given data type.
/**
 *
 * \tparam scalarT is the type
 *
 * \returns a constant defined in cfitsio corresponding to the native type
 * \returns -1 if not a define type in cfitsio
 *
 * \ingroup fits_utils
 */
template <typename scalarT>
constexpr int fitsType()
{
    return -5000; // This is the same as unknownType
}
 
template <>
constexpr int fitsType<char *>()
{
    return TSTRING;
}
 
template <>
constexpr int fitsType<std::string>()
{
    return TSTRING;
}
 
template <>
constexpr int fitsType<bool>() // mxlib extension, treated as uchar.
{
    return -14002;
}
 
template <>
constexpr int fitsType<char>()
{
    return TSBYTE;
}
 
template <>
constexpr int fitsType<unsigned char>()
{
    return TBYTE;
}
 
template <>
constexpr int fitsType<short>()
{
    return TSHORT;
}
 
template <>
constexpr int fitsType<unsigned short>()
{
    return TUSHORT;
}
 
template <>
constexpr int fitsType<int>()
{
    return TINT;
}
 
template <>
constexpr int fitsType<unsigned int>()
{
    return TUINT;
}
 
template <>
constexpr int fitsType<long>()
{
    return TLONG;
}
 
template <>
constexpr int fitsType<unsigned long>()
{
    return TULONG;
}
 
template <>
constexpr int fitsType<long long>()
{
    return TLONGLONG;
}
 
template <>
constexpr int fitsType<unsigned long long>()
{
    return TULONGLONG;
}
 
template <>
constexpr int fitsType<float>()
{
    return TFLOAT;
}
 
template <>
constexpr int fitsType<std::complex<float>>()
{
    return TCOMPLEX;
}
 
template <>
constexpr int fitsType<double>()
{
    return TDOUBLE;
}
 
template <>
constexpr int fitsType<std::complex<double>>()
{
    return TDBLCOMPLEX;
}
 
template <>
constexpr int fitsType<fitsUnknownType>()
{
    return -5000;
}
 
template <>
constexpr int fitsType<fitsCommentType>()
{
    return -5001;
}
 
template <>
constexpr int fitsType<fitsHistoryType>()
{
    return -5002;
}
 
/** Return the cfitsio BITPIX value for a given data type.
 *
 * \tparam scalarT is the type
 * \retval int > 0 if a constant is defined in cfitsio corresponding to the native type
 * \retval -1 if not a defined type in cfitsio
 */
template <typename scalarT>
constexpr int fitsBITPIX();
 
template <>
constexpr int fitsBITPIX<char>()
{
    return SBYTE_IMG;
}
 
template <>
constexpr int fitsBITPIX<signed char>()
{
    return SBYTE_IMG;
}
 
template <>
constexpr int fitsBITPIX<unsigned char>()
{
    return BYTE_IMG;
}
 
template <>
constexpr int fitsBITPIX<short>()
{
    return SHORT_IMG;
}
 
template <>
constexpr int fitsBITPIX<unsigned short>()
{
    return USHORT_IMG;
}
 
template <>
constexpr int fitsBITPIX<int>()
{
    return LONG_IMG; // Yes, this is right.  This returns 32
}
 
template <>
constexpr int fitsBITPIX<unsigned int>()
{
    return ULONG_IMG; // Yes, this is right, this returns 40
}
 
template <>
constexpr int fitsBITPIX<long>()
{
    return LONGLONG_IMG; // Yes, this is right, this returns 64
}
 
template <>
constexpr int fitsBITPIX<unsigned long>()
{
    return ULONGLONG_IMG; // Yes, this is right, this returns 64
}
 
template <>
constexpr int fitsBITPIX<long long>()
{
    return LONGLONG_IMG; // Yes, this is right, this returns 64
}
 
template <>
constexpr int fitsBITPIX<unsigned long long>()
{
    return ULONGLONG_IMG; // Yes, this is right, this returns 64
}
 
template <>
constexpr int fitsBITPIX<float>()
{
    return FLOAT_IMG;
}
 
template <>
constexpr int fitsBITPIX<double>()
{
    return DOUBLE_IMG;
}
 
/// Strip the apostrophes from a FITS value string
/** The argument is modified if the first and/or last non-whitespace character is '
 *
 * \param s is the string from which to strip apostrophes
 *
 * \retval int containing the number of stripped apostrophes
 */
int fitsStripApost( std::string &s );
 
/// Populate a fits header card with the value string copied verbatim
/**
 * \param headStr is a c-string which must be 81 characters in length, including the '\n'
 * \param keyword is the keyword name
 * \param value is the value string
 * \param comment is the comment string
 */
void fitsPopulateCard( char headStr[81], char *keyword, char *value, char *comment );
 
/// Write a header card to a file
/** This is a templatized wrapper for the cfitsio routine fits_write_key.
 *
 * \tparam typeT is the type of the value
 *
 * \param fptr is a pointer to an open fits file
 * \param keyword is a c-string containing the keyword
 * \param value is a pointer to the memory location of the value
 * \param comment is a c-string, possibly NULL, containing a comment string
 *
 * \retval int containing the status returned by the cfitsio routine.
 *
 * \ingroup fits_utils
 */
template <typename typeT>
int fits_write_key( fitsfile *fptr, char *keyword, void *value, char *comment )
{
    int fstatus = 0;
 
    fits_write_key( fptr, fitsType<typeT>(), keyword, value, comment, &fstatus );
 
    return fstatus;
}
 
template <>
int fits_write_key<char *>( fitsfile *fptr, char *keyword, void *value, char *comment );
 
template <>
int fits_write_key<std::string>( fitsfile *fptr, char *keyword, void *value, char *comment );
 
/// Specialization to handle the case bool
/** This gets converted to unsigned char.
 */
template <>
int fits_write_key<bool>( fitsfile *fptr, char *keyword, void *value, char *comment );
 
template <>
int fits_write_key<fitsUnknownType>( fitsfile *fptr, char *keyword, void *value, char *comment );
 
int fits_write_comment( fitsfile *fptr, char *comment );
 
int fits_write_history( fitsfile *fptr, char *history );
 
/// Generate a rich error meesage from a FITS status code.
void fitsErrText( std::string &explan,         ///< [out] the explanatory message
                  const std::string &filename, ///< [in] the FITS file's name which generated the problem
                  int fstatus                  ///< [in] the cfitstio status code
);
///@}
 
} // namespace fits
} // namespace mx
 
#endif // ioutils_fits_fitsUtils_hpp