Developer Application Interface (ARC API) v4.5.8
ARC, Inc. GenIV Application Interface
arc::gen4::CArcFitsFile< T > Class Template Reference

#include <CArcFitsFile.h>

Inheritance diagram for arc::gen4::CArcFitsFile< T >:
arc::gen4::CArcBase

Public Member Functions

 CArcFitsFile (void)
 
virtual ~CArcFitsFile (void)
 
const std::string getType (void) const noexcept
 
void create (const std::filesystem::path &tFileName, std::uint32_t uiCols, std::uint32_t uiRows)
 
void create3D (const std::filesystem::path &tFileName, std::uint32_t uiCols, std::uint32_t uiRows)
 
void open (const std::filesystem::path &tFileName, arc::gen4::fits::fitsMode_e eMode=arc::gen4::fits::fitsMode_e::READMODE)
 
void close (void) noexcept
 
std::unique_ptr< arc::gen4::CArcStringListgetHeader (void) const
 
const std::filesystem::path getFileName (void) const
 
arc::gen4::fits::keywordValue_t readKeyword (const std::string &sKey, arc::gen4::fits::fitsKeyType_e eType) const
 
void writeKeyword (const std::string &sKey, void *pValue, arc::gen4::fits::fitsKeyType_e eType, const std::string &sComment=""s) const
 
void updateKeyword (const std::string &sKey, void *pValue, arc::gen4::fits::fitsKeyType_e eType, const std::string &sComment=""s) const
 
std::unique_ptr< arc::gen4::fits::fitsParameter_tgetParameters (void) const
 
std::uint32_t getNumberOfFrames (void) const
 
std::uint32_t getRows (void) const
 
std::uint32_t getCols (void) const
 
std::uint32_t getNAxis (void) const
 
std::uint32_t getBitsPerPixel (void) const
 
void generateTestData (void) const
 
void reOpen (void)
 
void flush (void) const
 
bool compare (CArcFitsFile< T > &cFitsFile) const
 
void reSize (const std::uint32_t uiCols, const std::uint32_t uiRows)
 
void write (const T *pBuf) const
 
void write (const T *pBuf, const std::int64_t i64Bytes, const std::int64_t i64Pixel=1) const
 
void writeSubImage (const T *pBuf, const arc::gen4::fits::point_t lowerLeftPoint, const arc::gen4::fits::point_t upperRightPoint) const
 
std::unique_ptr< T[], arc::gen4::fits::ArrayDeleter< T > > readSubImage (arc::gen4::fits::point_t lowerLeftPoint, arc::gen4::fits::point_t upperRightPoint) const
 
std::unique_ptr< T[], arc::gen4::fits::ArrayDeleter< T > > read (void) const
 
void read (T *pBuf, const std::uint32_t uiCols, const std::uint32_t uiRows) const
 
void write3D (const T *pBuf) const
 
void reWrite3D (const T *pBuf, const std::uint32_t uiImageNumber) const
 
std::unique_ptr< T[], arc::gen4::fits::ArrayDeleter< T > > read3D (std::uint32_t uiImageNumber) const
 
fitsfile * getBaseFile (void) const
 
std::uint32_t maxTVal (void) const
 
- Public Member Functions inherited from arc::gen4::CArcBase
virtual ~CArcBase (void)
 

Static Public Member Functions

static const std::string version (void) noexcept
 
static const std::string cfitsioVersion (void) noexcept
 
- Static Public Member Functions inherited from arc::gen4::CArcBase
static const std::string version (void)
 
static void zeroMemory (void *pDest, std::size_t uiSize)
 
static void copyMemory (void *pDest, void *pSrc, std::size_t uiSize)
 
template<typename T >
static std::tuple< T *, T * > copyAndIncrement (void *pDest, void *pSrc, const std::size_t uiSize)
 
template<typename ErrCode >
requires std::is_integral_v<ErrCode>
static const std::string getSystemErrorMessage (ErrCode iErrCode)
 
static const std::string getSystemErrorMessage (void)
 
static std::uint32_t getSystemError (void) noexcept
 
static pStringList_t splitString (const std::string &sString, const char &zDelim=' ')
 
static std::string formatString (const char *pszFmt,...)
 
static const std::filesystem::path incrementFileName (const std::filesystem::path &tFilePath="", const std::int32_t iStartValue=-1)
 
static std::string convertWideToAnsi (const wchar_t wzString[]) noexcept
 
static std::string convertWideToAnsi (const std::wstring &wsString)
 
static std::wstring convertAnsiToWide (const char *pszString)
 
static std::string cmdToString (const std::uint32_t uiCmd)
 
template<typename T >
static std::string iterToString (T *begin, T *end, const char zSeperator=' ')
 
static std::string setDots (const std::string &sText, const std::size_t uiMaxLength, const char szDot='.')
 
static std::string trim (const std::string &sText) noexcept
 
static const std::chrono::time_point< std::chrono::high_resolution_clock > startCodeTime (void) noexcept
 
template<typename T >
static constexpr auto endCodeTime (const std::chrono::time_point< std::chrono::high_resolution_clock > tStartTimePoint) noexcept
 

Additional Inherited Members

- Protected Member Functions inherited from arc::gen4::CArcBase
 CArcBase (void)=default
 
 CArcBase (const CArcBase &)=delete
 
 CArcBase (CArcBase &&)=delete
 
CArcBaseoperator= (const CArcBase &)=delete
 
CArcBaseoperator= (CArcBase &&)=delete
 
- Static Protected Attributes inherited from arc::gen4::CArcBase
static const std::string m_sVersion
 

Detailed Description

template<typename T = arc::gen4::fits::BPP_16>
class arc::gen4::CArcFitsFile< T >

ARC FITS file interface class. Utilizes the cfitsio library for all actions.

See also
arc::gen4::CArcBase

Definition at line 169 of file CArcFitsFile.h.

Constructor & Destructor Documentation

◆ CArcFitsFile()

template<typename T = arc::gen4::fits::BPP_16>
arc::gen4::CArcFitsFile< T >::CArcFitsFile ( void  )

Constructor Creates an empty FITS file object.

◆ ~CArcFitsFile()

template<typename T = arc::gen4::fits::BPP_16>
virtual arc::gen4::CArcFitsFile< T >::~CArcFitsFile ( void  )
virtual

Destructor

Member Function Documentation

◆ version()

template<typename T = arc::gen4::fits::BPP_16>
static const std::string arc::gen4::CArcFitsFile< T >::version ( void  )
staticnoexcept

Returns a textual representation of the library version.

Returns
A string representation of the library version.

◆ cfitsioVersion()

template<typename T = arc::gen4::fits::BPP_16>
static const std::string arc::gen4::CArcFitsFile< T >::cfitsioVersion ( void  )
staticnoexcept

Returns a textual representation of the cfitsio library version.

Returns
A string representation of the cfitsio library version.

◆ getType()

template<typename T = arc::gen4::fits::BPP_16>
const std::string arc::gen4::CArcFitsFile< T >::getType ( void  ) const
noexcept

Returns the class bits-per-pixel typename as a string. Example: "unsigned short", etc.

Returns
The class bits-per-pixel typename as a string. Example: "unsigned short", etc.

◆ create()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::create ( const std::filesystem::path &  tFileName,
std::uint32_t  uiCols,
std::uint32_t  uiRows 
)

Creates a new single image file on disk with the specified image dimensions.

Parameters
tFileName- The new FITS file name.
uiCols- The image column size ( in pixels ).
uiRows- The image row size ( in pixels ).
Exceptions
std::runtime_error
std::filesystem_error
std::invalid_argument

◆ create3D()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::create3D ( const std::filesystem::path &  tFileName,
std::uint32_t  uiCols,
std::uint32_t  uiRows 
)

Creates a new data cube file on disk with the specified image dimensions.

Parameters
tFileName- The new FITS file name.
uiCols- The image column size ( in pixels ).
uiRows- The image row size ( in pixels ).
Exceptions
std::runtime_error
std::filesystem_error
std::invalid_argument

◆ open()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::open ( const std::filesystem::path &  tFileName,
arc::gen4::fits::fitsMode_e  eMode = arc::gen4::fits::fitsMode_e::READMODE 
)

Opens an existing file. Can be used to open a file containing a single image or data cube ( a file with multiple image planes ).

Parameters
tFileName- The file name.
eMode- The mode with which to open the file ( default = fitsMode_e::READMODE ).
Exceptions
std::runtime_error
std::filesystem_error
std::invalid_argument

◆ close()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::close ( void  )
noexcept

Closes the file.

◆ getHeader()

template<typename T = arc::gen4::fits::BPP_16>
std::unique_ptr< arc::gen4::CArcStringList > arc::gen4::CArcFitsFile< T >::getHeader ( void  ) const

Returns the FITS header as a list of strings.

See also
arc::gen4::CArcStringList
std::unique_ptr
Returns
A std::unique_ptr to a arc::gen4::CArcStringList.
Exceptions
std::runtime_erroron error.

◆ getFileName()

template<typename T = arc::gen4::fits::BPP_16>
const std::filesystem::path arc::gen4::CArcFitsFile< T >::getFileName ( void  ) const

Returns the filename.

Returns
The FITS filename associated with this object.
Exceptions
std::runtime_error
std::filesystem_error

◆ readKeyword()

template<typename T = arc::gen4::fits::BPP_16>
arc::gen4::fits::keywordValue_t arc::gen4::CArcFitsFile< T >::readKeyword ( const std::string &  sKey,
arc::gen4::fits::fitsKeyType_e  eType 
) const

Reads a keyword value from the header.

Parameters
sKey- A valid FITS keyword.
eType- The keyword value type.
Exceptions
std::runtime_error
std::invalid_argument

◆ writeKeyword()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::writeKeyword ( const std::string &  sKey,
void *  pValue,
arc::gen4::fits::fitsKeyType_e  eType,
const std::string &  sComment = ""s 
) const

Writes a new keyword to the header.

'HIERARCH' keyword NOTE: This text will be prefixed to any keyword by the cfitsio library if the keyword is greater than 8 characters, which is the standard FITS keyword length. See the link below for details:

http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/f_user/node28.html

Parameters
sKey- A valid FITS keyword.
pValue- A pointer to the keyword value. The value type is determined by the eType parameter. Cannot equal nullptr.
eType- The keyword value type.
sComment- The optional header comment ( default = " " ).
Exceptions
std::runtime_error
std::invalid_argument

◆ updateKeyword()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::updateKeyword ( const std::string &  sKey,
void *  pValue,
arc::gen4::fits::fitsKeyType_e  eType,
const std::string &  sComment = ""s 
) const

Updates an existng header keyword.

'HIERARCH' keyword NOTE: This text will be prefixed to any keyword by the cfitsio library if the keyword is greater than 8 characters, which is the standard FITS keyword length. See the link below for details:

http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/f_user/node28.html

Parameters
sKey- A valid FITS keyword.
pValue- A pointer to the keyword value. The value type is determined by the eType parameter. Must not equal nullptr.
eType- The keyword value type.
sComment- The optional header comment ( default = " " ).
Exceptions
std::runtime_error
std::invalid_argument

◆ getParameters()

template<typename T = arc::gen4::fits::BPP_16>
std::unique_ptr< arc::gen4::fits::fitsParameter_t > arc::gen4::CArcFitsFile< T >::getParameters ( void  ) const

Returns the basic image parameters ( number of cols, rows, frames, dimensions and bits-per-pixel ).

Returns
Pointer to an arc::gen4::fits::fitsParameter_t type that contains all the image parameters.
Exceptions
std::runtime_erroron error.

◆ getNumberOfFrames()

template<typename T = arc::gen4::fits::BPP_16>
std::uint32_t arc::gen4::CArcFitsFile< T >::getNumberOfFrames ( void  ) const

Returns the number of frames. A single image file will return a value of 0.

Returns
The number of frames.
Exceptions
std::runtime_erroron error.

◆ getRows()

template<typename T = arc::gen4::fits::BPP_16>
std::uint32_t arc::gen4::CArcFitsFile< T >::getRows ( void  ) const

Returns the number of rows in the image.

Returns
The number of rows in the image.
Exceptions
std::runtime_erroron error.

◆ getCols()

template<typename T = arc::gen4::fits::BPP_16>
std::uint32_t arc::gen4::CArcFitsFile< T >::getCols ( void  ) const

Returns the number of columns in the image.

Returns
The number of columns in the image.
Exceptions
std::runtime_erroron error.

◆ getNAxis()

template<typename T = arc::gen4::fits::BPP_16>
std::uint32_t arc::gen4::CArcFitsFile< T >::getNAxis ( void  ) const

Returns the number of dimensions in the image.

Returns
The number of dimensions in the image.
Exceptions
std::runtime_erroron error.

◆ getBitsPerPixel()

template<typename T = arc::gen4::fits::BPP_16>
std::uint32_t arc::gen4::CArcFitsFile< T >::getBitsPerPixel ( void  ) const

Returns the image bits-per-pixel value.

Returns
The image bits-per-pixel value.
Exceptions
std::runtime_erroron error.

◆ generateTestData()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::generateTestData ( void  ) const

Generates a ramp test pattern image within the file. The size of the image is determined by the image dimensions supplied during the create() method call. This method is only valid for single image files.

Exceptions
std::runtime_erroron error.

◆ reOpen()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::reOpen ( void  )

Effectively closes and re-opens the underlying disk file.

Exceptions
std::runtime_erroron error.

◆ flush()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::flush ( void  ) const

Causes all internal data buffers to write data to the disk file.

Exceptions
std::runtime_erroron error.

◆ compare()

template<typename T = arc::gen4::fits::BPP_16>
bool arc::gen4::CArcFitsFile< T >::compare ( CArcFitsFile< T > &  cFitsFile) const

Compares this file image data to another. This method does not check headers, except for size values, and does not throw any exceptions. See the error message parameter if a false value is returned.

Parameters
cFitsFile- A reference to another valid FITS file.
Returns
true if the two file match; false otherwise.

◆ reSize()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::reSize ( const std::uint32_t  uiCols,
const std::uint32_t  uiRows 
)

Resizes a single image file by modifying the NAXES keyword and increasing the image data portion of the file.

Parameters
uiCols- The number of cols the new FITS file will have.
uiRows- The number of rows the new FITS file will have.
Exceptions
std::runtime_error
std::invalid_argument

◆ write() [1/2]

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::write ( const T *  pBuf) const

Writes image data to a single image file.

Parameters
pBuf- The image buffer to write. Buffer access violation results in undefined behavior.
Exceptions
std::runtime_error
std::invalid_argument

◆ write() [2/2]

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::write ( const T *  pBuf,
const std::int64_t  i64Bytes,
const std::int64_t  i64Pixel = 1 
) const

Writes the specified number of bytes to a single image file. The start position of the data within the file image can be specified.

Parameters
pBuf- The image buffer to write. Buffer access violation results in undefined behavior.
i64Bytes- The number of bytes to write.
i64Pixel- The start pixel within the file image. ( default = 1 ).
Exceptions
std::runtime_error
std::invalid_argument

◆ writeSubImage()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::writeSubImage ( const T *  pBuf,
const arc::gen4::fits::point_t  lowerLeftPoint,
const arc::gen4::fits::point_t  upperRightPoint 
) const

Writes a sub-image of the specified buffer to a single image file.

Parameters
pBuf- The image buffer to write. Buffer access violation results in undefined behavior.
lowerLeftPoint- The lower left point { col, row } of the sub-image.
upperRightPoint- The upper right point { col, row } of the sub-image.
Exceptions
std::runtime_error
std::invalid_argument

◆ readSubImage()

template<typename T = arc::gen4::fits::BPP_16>
std::unique_ptr< T[], arc::gen4::fits::ArrayDeleter< T > > arc::gen4::CArcFitsFile< T >::readSubImage ( arc::gen4::fits::point_t  lowerLeftPoint,
arc::gen4::fits::point_t  upperRightPoint 
) const

Reads a sub-image from a single image file.

Parameters
lowerLeftPoint- The lower left point { col, row } of the sub-image.
upperRightPoint- The upper right point { col, row } of the sub-image.
Returns
A pointer to the sub-image data.
Exceptions
std::runtime_error
std::invalid_argument

◆ read() [1/2]

template<typename T = arc::gen4::fits::BPP_16>
std::unique_ptr< T[], arc::gen4::fits::ArrayDeleter< T > > arc::gen4::CArcFitsFile< T >::read ( void  ) const

Read the image from a single image file.

Returns
A pointer to the image data.
Exceptions
std::runtime_error
std::invalid_argument

◆ read() [2/2]

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::read ( T *  pBuf,
const std::uint32_t  uiCols,
const std::uint32_t  uiRows 
) const

Read the image from a single image file into the specified user buffer.

Parameters
pBuf- The user supplied buffer.
uiCols- The buffer column length ( in pixels ).
uiRows- The buffer row length ( in pixels ).
Exceptions
std::runtime_error
std::invalid_argument
std::length_error

◆ write3D()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::write3D ( const T *  pBuf) const

Writes an image to the end of a data cube file.

Parameters
pBuf- The image buffer to write. Buffer access violation results in undefined behavior.
Exceptions
std::runtime_error
std::invalid_argument

◆ reWrite3D()

template<typename T = arc::gen4::fits::BPP_16>
void arc::gen4::CArcFitsFile< T >::reWrite3D ( const T *  pBuf,
const std::uint32_t  uiImageNumber 
) const

Re-writes an existing image in a data cube file. The image data MUST match in size to the exising images within the data cube.

Parameters
pBuf- The image buffer. Buffer access violation results in undefined behavior.
uiImageNumber- The number of the data cube image to replace.
Exceptions
std::runtime_error
std::invalid_argument

◆ read3D()

template<typename T = arc::gen4::fits::BPP_16>
std::unique_ptr< T[], arc::gen4::fits::ArrayDeleter< T > > arc::gen4::CArcFitsFile< T >::read3D ( std::uint32_t  uiImageNumber) const

Reads an image from a data cube file.

Parameters
uiImageNumber- The image number.
Returns
A pointer to the image data.
Exceptions
std::runtime_error
std::invalid_argument

◆ getBaseFile()

template<typename T = arc::gen4::fits::BPP_16>
fitsfile * arc::gen4::CArcFitsFile< T >::getBaseFile ( void  ) const

Returns the underlying cfitsio file pointer.

Returns
A pointer to the internal cfitsio file pointer ( may be nullptr ).

◆ maxTVal()

template<typename T = arc::gen4::fits::BPP_16>
std::uint32_t arc::gen4::CArcFitsFile< T >::maxTVal ( void  ) const

Determines the maximum value for a specific data type. Example, for std::uint16_t: 2^16 = 65536.

Returns
The maximum value for the data type currently in use.