lsst.afw g28e9080985+60ce4897b0
Public Types | Public Member Functions | Public Attributes | List of all members
lsst::afw::fits::Fits Class Reference

A simple struct that combines the two arguments that must be passed to most cfitsio routines and contains thin and/or templated wrappers around common cfitsio routines. More...

#include <fits.h>

Public Types

enum  BehaviorFlags { AUTO_CLOSE = 0x01 , AUTO_CHECK = 0x02 }
 

Public Member Functions

std::string getFileName () const
 Return the file name associated with the FITS object or "<unknown>" if there is none. More...
 
int getHdu ()
 Return the current HDU (0-indexed; 0 is the Primary HDU). More...
 
void setHdu (int hdu, bool relative=false)
 Set the current HDU. More...
 
int countHdus ()
 Return the number of HDUs in the file. More...
 
template<typename T >
void updateKey (std::string const &key, T const &value, std::string const &comment)
 Set a FITS header key, editing if it already exists and appending it if not. More...
 
void updateKey (std::string const &key, char const *value, std::string const &comment)
 
template<typename T >
void updateKey (std::string const &key, T const &value)
 
void updateKey (std::string const &key, char const *value)
 
template<typename T >
void writeKey (std::string const &key, T const &value, std::string const &comment)
 Add a FITS header key to the bottom of the header. More...
 
void writeKey (std::string const &key, char const *value, std::string const &comment)
 
template<typename T >
void writeKey (std::string const &key, T const &value)
 
void writeKey (std::string const &key, char const *value)
 
template<typename T >
void updateColumnKey (std::string const &prefix, int n, T const &value, std::string const &comment)
 Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
 
void updateColumnKey (std::string const &prefix, int n, char const *value, std::string const &comment)
 
template<typename T >
void updateColumnKey (std::string const &prefix, int n, T const &value)
 
void updateColumnKey (std::string const &prefix, int n, char const *value)
 
template<typename T >
void writeColumnKey (std::string const &prefix, int n, T const &value, std::string const &comment)
 Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
 
void writeColumnKey (std::string const &prefix, int n, char const *value, std::string const &comment)
 
template<typename T >
void writeColumnKey (std::string const &prefix, int n, T const &value)
 
void writeColumnKey (std::string const &prefix, int n, char const *value)
 
void writeMetadata (daf::base::PropertySet const &metadata)
 Read a FITS header into a PropertySet or PropertyList. More...
 
void readMetadata (daf::base::PropertySet &metadata, bool strip=false)
 Read a FITS header into a PropertySet or PropertyList. More...
 
template<typename T >
void readKey (std::string const &key, T &value)
 Read a FITS header key into the given reference. More...
 
void forEachKey (HeaderIterationFunctor &functor)
 Call a polymorphic functor for every key in the header. More...
 
void createEmpty ()
 Create an empty image HDU with NAXIS=0 at the end of the file. More...
 
template<typename PixelT , int N>
void createImage (ndarray::Vector< ndarray::Size, N > const &shape)
 Create an image with pixel type provided by the given explicit PixelT template parameter and shape defined by an ndarray index. More...
 
template<int N>
void createImage (int bitpix, ndarray::Vector< ndarray::Size, N > const &shape)
 
template<typename PixelT >
void createImage (long x, long y)
 Create a 2-d image with pixel type provided by the given explicit PixelT template parameter. More...
 
template<typename T , int N, int C>
void writeImage (ndarray::Array< T const, N, C > const &array)
 Write an ndarray::Array to a FITS image HDU. More...
 
template<typename T >
void writeImage (image::ImageBase< T > const &image, ImageWriteOptions const &options, std::shared_ptr< daf::base::PropertySet const > header=std::shared_ptr< daf::base::PropertyList >(), std::shared_ptr< image::Mask< image::MaskPixel > const > mask=std::shared_ptr< image::Mask< image::MaskPixel > >())
 Write an image to FITS. More...
 
int getImageDim ()
 Return the number of dimensions in the current HDU. More...
 
template<int N>
ndarray::Vector< ndarray::Size, N > getImageShape ()
 Return the shape of the current (image) HDU. More...
 
template<typename T >
bool checkImageType ()
 Return true if the current HDU is compatible with the given pixel type. More...
 
std::string getImageDType ()
 Return the numpy dtype equivalent of the image pixel type (e.g. More...
 
template<typename T , int N>
void readImage (ndarray::Array< T, N, N > const &array, ndarray::Vector< int, N > const &offset)
 Read an array from a FITS image. More...
 
void createTable ()
 Create a new binary table extension. More...
 
template<typename T >
int addColumn (std::string const &ttype, int size, std::string const &comment)
 Add a column to a table. More...
 
template<typename T >
int addColumn (std::string const &ttype, int size)
 Add a column to a table. More...
 
std::size_t addRows (std::size_t nRows)
 Append rows to a table, and return the index of the first new row. More...
 
std::size_t countRows ()
 Return the number of row in a table. More...
 
template<typename T >
void writeTableArray (std::size_t row, int col, int nElements, T const *value)
 Write an array value to a binary table. More...
 
template<typename T >
void writeTableScalar (std::size_t row, int col, T value)
 Write a scalar value to a binary table. More...
 
void writeTableScalar (std::size_t row, int col, std::string const &value)
 Write a string to a binary table. More...
 
template<typename T >
void readTableArray (std::size_t row, int col, int nElements, T *value)
 Read an array value from a binary table. More...
 
template<typename T >
void readTableScalar (std::size_t row, int col, T &value)
 Read an array scalar from a binary table. More...
 
void readTableScalar (std::size_t row, int col, std::string &value, bool isVariableLength)
 Read a string from a binary table. More...
 
long getTableArraySize (int col)
 Return the size of an array column. More...
 
long getTableArraySize (std::size_t row, int col)
 Return the size of an variable-length array field. More...
 
 Fits ()
 Default constructor; set all data members to 0. More...
 
 Fits (std::string const &filename, std::string const &mode, int behavior)
 Open or create a FITS file from disk. More...
 
 Fits (MemFileManager &manager, std::string const &mode, int behavior)
 Open or create a FITS file from an in-memory file. More...
 
void closeFile ()
 Close a FITS file. More...
 
void setImageCompression (ImageCompressionOptions const &options)
 Set compression options for writing FITS images. More...
 
ImageCompressionOptions getImageCompression ()
 Return the current image compression settings. More...
 
bool checkCompressedImagePhu ()
 Go to the first image header in the FITS file. More...
 
 ~Fits ()
 
 Fits (const Fits &)=delete
 
Fitsoperator= (const Fits &)=delete
 
 Fits (Fits &&)=delete
 
Fitsoperator= (Fits &&)=delete
 

Public Attributes

void * fptr
 
int status
 
int behavior
 

Detailed Description

A simple struct that combines the two arguments that must be passed to most cfitsio routines and contains thin and/or templated wrappers around common cfitsio routines.

This is NOT intended to be an object-oriented C++ wrapper around cfitsio; it's simply a thin layer that saves a lot of repetition, const/reinterpret casts, and replaces void pointer args and type codes with templates and overloads.

Like a cfitsio pointer, a Fits object always considers one HDU the "active" one, and most operations will be applied to that HDU.

All member functions are non-const because they may modify the 'status' data member.

Note
All functions that take a row or column number below are 0-indexed; the internal cfitsio calls are all 1-indexed.

Definition at line 297 of file fits.h.

Member Enumeration Documentation

◆ BehaviorFlags

Enumerator
AUTO_CLOSE 
AUTO_CHECK 

Definition at line 306 of file fits.h.

Constructor & Destructor Documentation

◆ Fits() [1/5]

lsst::afw::fits::Fits::Fits ( )
inline

Default constructor; set all data members to 0.

Definition at line 609 of file fits.h.

◆ Fits() [2/5]

lsst::afw::fits::Fits::Fits ( std::string const &  filename,
std::string const &  mode,
int  behavior 
)

Open or create a FITS file from disk.

Definition at line 1552 of file fits.cc.

◆ Fits() [3/5]

lsst::afw::fits::Fits::Fits ( MemFileManager manager,
std::string const &  mode,
int  behavior 
)

Open or create a FITS file from an in-memory file.

Definition at line 1582 of file fits.cc.

◆ ~Fits()

lsst::afw::fits::Fits::~Fits ( )
inline

Definition at line 637 of file fits.h.

◆ Fits() [4/5]

lsst::afw::fits::Fits::Fits ( const Fits )
delete

◆ Fits() [5/5]

lsst::afw::fits::Fits::Fits ( Fits &&  )
delete

Member Function Documentation

◆ addColumn() [1/2]

template<typename T >
int lsst::afw::fits::Fits::addColumn ( std::string const &  ttype,
int  size 
)

Add a column to a table.

If size <= 0, the field will be a variable length array, with max set by (-size), or left unknown if size == 0.

Definition at line 1127 of file fits.cc.

◆ addColumn() [2/2]

template<typename T >
int lsst::afw::fits::Fits::addColumn ( std::string const &  ttype,
int  size,
std::string const &  comment 
)

Add a column to a table.

If size <= 0, the field will be a variable length array, with max set by (-size), or left unknown if size == 0.

Definition at line 1140 of file fits.cc.

◆ addRows()

std::size_t lsst::afw::fits::Fits::addRows ( std::size_t  nRows)

Append rows to a table, and return the index of the first new row.

Definition at line 1149 of file fits.cc.

◆ checkCompressedImagePhu()

bool lsst::afw::fits::Fits::checkCompressedImagePhu ( )

Go to the first image header in the FITS file.

If a single image is written compressed, it appears as an extension, rather than the primary HDU (PHU). This method is useful before reading an image, as it checks whether we are positioned on an empty PHU and if the next HDU is a compressed image; if so, it leaves the file pointer on the compresed image, ready for reading.

Definition at line 1726 of file fits.cc.

◆ checkImageType()

template<typename T >
bool lsst::afw::fits::Fits::checkImageType

Return true if the current HDU is compatible with the given pixel type.

This takes into account the BSCALE and BZERO keywords, which can allow integer images to be interpreted as floating point.

Definition at line 1435 of file fits.cc.

◆ closeFile()

void lsst::afw::fits::Fits::closeFile ( )

Close a FITS file.

Definition at line 1623 of file fits.cc.

◆ countHdus()

int lsst::afw::fits::Fits::countHdus ( )

Return the number of HDUs in the file.

Definition at line 534 of file fits.cc.

◆ countRows()

std::size_t lsst::afw::fits::Fits::countRows ( )

Return the number of row in a table.

Definition at line 1159 of file fits.cc.

◆ createEmpty()

void lsst::afw::fits::Fits::createEmpty ( )

Create an empty image HDU with NAXIS=0 at the end of the file.

This is primarily useful to force the first "real" HDU to be an extension HDU by creating an empty Primary HDU. The new HDU is set as the active one.

Definition at line 1240 of file fits.cc.

◆ createImage() [1/3]

template<int N>
void lsst::afw::fits::Fits::createImage ( int  bitpix,
ndarray::Vector< ndarray::Size, N > const &  shape 
)
inline

Definition at line 450 of file fits.h.

◆ createImage() [2/3]

template<typename PixelT >
void lsst::afw::fits::Fits::createImage ( long  x,
long  y 
)
inline

Create a 2-d image with pixel type provided by the given explicit PixelT template parameter.

The new image will be in a new HDU at the end of the file, which may be the Primary HDU if the FITS file is empty.

Definition at line 462 of file fits.h.

◆ createImage() [3/3]

template<typename PixelT , int N>
void lsst::afw::fits::Fits::createImage ( ndarray::Vector< ndarray::Size, N > const &  shape)
inline

Create an image with pixel type provided by the given explicit PixelT template parameter and shape defined by an ndarray index.

Note
The shape parameter is ordered fastest-dimension last (i.e. [y, x]) as is conventional with ndarray.

The new image will be in a new HDU at the end of the file, which may be the Primary HDU if the FITS file is empty.

Definition at line 444 of file fits.h.

◆ createTable()

void lsst::afw::fits::Fits::createTable ( )

Create a new binary table extension.

Definition at line 1117 of file fits.cc.

◆ forEachKey()

void lsst::afw::fits::Fits::forEachKey ( HeaderIterationFunctor functor)

Call a polymorphic functor for every key in the header.

Each value is passed in as a string, and the single quotes that mark an actual string value are not removed (neither are extra spaces). However, long strings that make use of the CONTINUE keyword are concatenated to look as if they were on a single line.

Definition at line 781 of file fits.cc.

◆ getFileName()

std::string lsst::afw::fits::Fits::getFileName ( ) const

Return the file name associated with the FITS object or "<unknown>" if there is none.

Definition at line 498 of file fits.cc.

◆ getHdu()

int lsst::afw::fits::Fits::getHdu ( )

Return the current HDU (0-indexed; 0 is the Primary HDU).

Definition at line 507 of file fits.cc.

◆ getImageCompression()

ImageCompressionOptions lsst::afw::fits::Fits::getImageCompression ( )

Return the current image compression settings.

Definition at line 1495 of file fits.cc.

◆ getImageDim()

int lsst::afw::fits::Fits::getImageDim ( )

Return the number of dimensions in the current HDU.

Definition at line 1422 of file fits.cc.

◆ getImageDType()

std::string lsst::afw::fits::Fits::getImageDType ( )

Return the numpy dtype equivalent of the image pixel type (e.g.

"uint16", "float64").

Definition at line 1466 of file fits.cc.

◆ getImageShape()

template<int N>
ndarray::Vector< ndarray::Size, N > lsst::afw::fits::Fits::getImageShape ( )
inline

Return the shape of the current (image) HDU.

The order of dimensions is reversed from the FITS ordering, reflecting the usual (y,x) ndarray convention.

The template parameter must match the actual number of dimension in the image.

Definition at line 512 of file fits.h.

◆ getTableArraySize() [1/2]

long lsst::afw::fits::Fits::getTableArraySize ( int  col)

Return the size of an array column.

Definition at line 1217 of file fits.cc.

◆ getTableArraySize() [2/2]

long lsst::afw::fits::Fits::getTableArraySize ( std::size_t  row,
int  col 
)

Return the size of an variable-length array field.

Definition at line 1228 of file fits.cc.

◆ operator=() [1/2]

Fits & lsst::afw::fits::Fits::operator= ( const Fits )
delete

◆ operator=() [2/2]

Fits & lsst::afw::fits::Fits::operator= ( Fits &&  )
delete

◆ readImage()

template<typename T , int N>
void lsst::afw::fits::Fits::readImage ( ndarray::Array< T, N, N > const &  array,
ndarray::Vector< int, N > const &  offset 
)
inline

Read an array from a FITS image.

Parameters
[out]arrayArray to be filled. Must already be allocated to the desired shape.
[in]offsetIndices of the first pixel to be read from the image.

Definition at line 541 of file fits.h.

◆ readKey()

template<typename T >
void lsst::afw::fits::Fits::readKey ( std::string const &  key,
T &  value 
)

Read a FITS header key into the given reference.

Definition at line 774 of file fits.cc.

◆ readMetadata()

void lsst::afw::fits::Fits::readMetadata ( daf::base::PropertySet metadata,
bool  strip = false 
)

Read a FITS header into a PropertySet or PropertyList.

Parameters
[in,out]metadataA PropertySet or PropertyList that FITS header items will be added to.
[in]stripIf true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

Order will preserved if and only if the metadata object is actually a PropertyList.

Definition at line 1087 of file fits.cc.

◆ readTableArray()

template<typename T >
void lsst::afw::fits::Fits::readTableArray ( std::size_t  row,
int  col,
int  nElements,
T *  value 
)

Read an array value from a binary table.

Definition at line 1192 of file fits.cc.

◆ readTableScalar() [1/2]

void lsst::afw::fits::Fits::readTableScalar ( std::size_t  row,
int  col,
std::string value,
bool  isVariableLength 
)

Read a string from a binary table.

Definition at line 1201 of file fits.cc.

◆ readTableScalar() [2/2]

template<typename T >
void lsst::afw::fits::Fits::readTableScalar ( std::size_t  row,
int  col,
T &  value 
)
inline

Read an array scalar from a binary table.

Definition at line 595 of file fits.h.

◆ setHdu()

void lsst::afw::fits::Fits::setHdu ( int  hdu,
bool  relative = false 
)

Set the current HDU.

Parameters
[in]hduThe HDU to move to (0-indexed; 0 is the Primary HDU). The special value of DEFAULT_HDU moves to the first extension if the Primary HDU is empty (has NAXIS==0) and the the Primary HDU is the current one.
[in]relativeIf true, move relative to the current HDU.

Definition at line 513 of file fits.cc.

◆ setImageCompression()

void lsst::afw::fits::Fits::setImageCompression ( ImageCompressionOptions const &  options)

Set compression options for writing FITS images.

See also
ImageCompressionContext

Definition at line 1518 of file fits.cc.

◆ updateColumnKey() [1/4]

void lsst::afw::fits::Fits::updateColumnKey ( std::string const &  prefix,
int  n,
char const *  value 
)
inline

Definition at line 370 of file fits.h.

◆ updateColumnKey() [2/4]

void lsst::afw::fits::Fits::updateColumnKey ( std::string const &  prefix,
int  n,
char const *  value,
std::string const &  comment 
)
inline

Definition at line 365 of file fits.h.

◆ updateColumnKey() [3/4]

template<typename T >
void lsst::afw::fits::Fits::updateColumnKey ( std::string const &  prefix,
int  n,
T const &  value 
)

Definition at line 707 of file fits.cc.

◆ updateColumnKey() [4/4]

template<typename T >
void lsst::afw::fits::Fits::updateColumnKey ( std::string const &  prefix,
int  n,
T const &  value,
std::string const &  comment 
)

Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

Definition at line 691 of file fits.cc.

◆ updateKey() [1/4]

void lsst::afw::fits::Fits::updateKey ( std::string const &  key,
char const *  value 
)
inline

Definition at line 340 of file fits.h.

◆ updateKey() [2/4]

void lsst::afw::fits::Fits::updateKey ( std::string const &  key,
char const *  value,
std::string const &  comment 
)
inline

Definition at line 335 of file fits.h.

◆ updateKey() [3/4]

template<typename T >
void lsst::afw::fits::Fits::updateKey ( std::string const &  key,
T const &  value 
)

Definition at line 675 of file fits.cc.

◆ updateKey() [4/4]

template<typename T >
void lsst::afw::fits::Fits::updateKey ( std::string const &  key,
T const &  value,
std::string const &  comment 
)

Set a FITS header key, editing if it already exists and appending it if not.

Definition at line 659 of file fits.cc.

◆ writeColumnKey() [1/4]

void lsst::afw::fits::Fits::writeColumnKey ( std::string const &  prefix,
int  n,
char const *  value 
)
inline

Definition at line 384 of file fits.h.

◆ writeColumnKey() [2/4]

void lsst::afw::fits::Fits::writeColumnKey ( std::string const &  prefix,
int  n,
char const *  value,
std::string const &  comment 
)
inline

Definition at line 379 of file fits.h.

◆ writeColumnKey() [3/4]

template<typename T >
void lsst::afw::fits::Fits::writeColumnKey ( std::string const &  prefix,
int  n,
T const &  value 
)

Definition at line 715 of file fits.cc.

◆ writeColumnKey() [4/4]

template<typename T >
void lsst::afw::fits::Fits::writeColumnKey ( std::string const &  prefix,
int  n,
T const &  value,
std::string const &  comment 
)

Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

Definition at line 699 of file fits.cc.

◆ writeImage() [1/2]

template<typename T >
void lsst::afw::fits::Fits::writeImage ( image::ImageBase< T > const &  image,
ImageWriteOptions const &  options,
std::shared_ptr< daf::base::PropertySet const >  header = std::shared_ptr<daf::base::PropertyList>(),
std::shared_ptr< image::Mask< image::MaskPixel > const >  mask = std::shared_ptr<image::Mask<image::MaskPixel>>() 
)

Write an image to FITS.

This method is all-inclusive, and covers creating the HDU (with the correct BITPIX), writing the header and optional scaling and compression of the image.

Parameters
[in]imageImage to write to FITS.
[in]optionsOptions controlling the write (scaling, compression).
[in]headerFITS header to write.
[in]maskMask for image (used for statistics when scaling).

Definition at line 1296 of file fits.cc.

◆ writeImage() [2/2]

template<typename T , int N, int C>
void lsst::afw::fits::Fits::writeImage ( ndarray::Array< T const, N, C > const &  array)
inline

Write an ndarray::Array to a FITS image HDU.

The HDU must already exist and have the correct bitpix.

An extra deep-copy may be necessary if the array is not fully contiguous.

No compression or scaling is performed.

Definition at line 477 of file fits.h.

◆ writeKey() [1/4]

void lsst::afw::fits::Fits::writeKey ( std::string const &  key,
char const *  value 
)
inline

Definition at line 358 of file fits.h.

◆ writeKey() [2/4]

void lsst::afw::fits::Fits::writeKey ( std::string const &  key,
char const *  value,
std::string const &  comment 
)
inline

Definition at line 353 of file fits.h.

◆ writeKey() [3/4]

template<typename T >
void lsst::afw::fits::Fits::writeKey ( std::string const &  key,
T const &  value 
)

Definition at line 683 of file fits.cc.

◆ writeKey() [4/4]

template<typename T >
void lsst::afw::fits::Fits::writeKey ( std::string const &  key,
T const &  value,
std::string const &  comment 
)

Add a FITS header key to the bottom of the header.

If the key is HISTORY or COMMENT and the value is a std::string or C-string, a special HISTORY or COMMENT key will be appended (and the comment argument will be ignored if present).

Definition at line 667 of file fits.cc.

◆ writeMetadata()

void lsst::afw::fits::Fits::writeMetadata ( daf::base::PropertySet const &  metadata)

Read a FITS header into a PropertySet or PropertyList.

Parameters
[in]metadataA PropertySet or PropertyList whose items will be appended to the FITS header.

All keys will be appended to the FITS header rather than used to update existing keys. Order of keys will be preserved if and only if the metadata object is actually a PropertyList.

Definition at line 1095 of file fits.cc.

◆ writeTableArray()

template<typename T >
void lsst::afw::fits::Fits::writeTableArray ( std::size_t  row,
int  col,
int  nElements,
T const *  value 
)

Write an array value to a binary table.

Definition at line 1169 of file fits.cc.

◆ writeTableScalar() [1/2]

void lsst::afw::fits::Fits::writeTableScalar ( std::size_t  row,
int  col,
std::string const &  value 
)

Write a string to a binary table.

Definition at line 1178 of file fits.cc.

◆ writeTableScalar() [2/2]

template<typename T >
void lsst::afw::fits::Fits::writeTableScalar ( std::size_t  row,
int  col,
value 
)
inline

Write a scalar value to a binary table.

Definition at line 583 of file fits.h.

Member Data Documentation

◆ behavior

int lsst::afw::fits::Fits::behavior

Definition at line 651 of file fits.h.

◆ fptr

void* lsst::afw::fits::Fits::fptr

Definition at line 649 of file fits.h.

◆ status

int lsst::afw::fits::Fits::status

Definition at line 650 of file fits.h.


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