LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
fits.h
Go to the documentation of this file.
1 // -*- lsst-c++ -*-
2 #ifndef LSST_AFW_fits_h_INCLUDED
3 #define LSST_AFW_fits_h_INCLUDED
4 
5 /*
6  * Utilities for working with FITS files. These are mostly thin wrappers around
7  * cfitsio calls, and their main purpose is to transform functions signatures from
8  * void pointers and cfitsio's preprocessor type enums to a more type-safe and
9  * convenient interface using overloads and templates.
10  *
11  * This was written as part of implementing the afw/table library. Someday
12  * the afw/image FITS I/O should be modified to use some of these with the goal
13  * of eliminating a lot of code between the two.
14  */
15 
16 #include <climits>
17 #include <string>
18 #include <set>
19 
20 #include <boost/format.hpp>
21 
22 #include "lsst/base.h"
23 #include "lsst/pex/exceptions.h"
24 #include "lsst/daf/base.h"
25 #include "ndarray.h"
27 #include "lsst/afw/fitsDefaults.h"
28 
29 namespace lsst {
30 namespace afw {
31 namespace fits {
32 
37 
38 
42 
50 public:
51  virtual void operator()(std::string const& key, std::string const& value, std::string const& comment) = 0;
52 
54 };
55 
64 std::string makeErrorMessage(std::string const& fileName = "", int status = 0, std::string const& msg = "");
65 inline std::string makeErrorMessage(std::string const& fileName, int status, boost::format const& msg) {
66  return makeErrorMessage(fileName, status, msg.str());
67 }
68 
78 std::string makeErrorMessage(void* fptr, int status = 0, std::string const& msg = "");
79 inline std::string makeErrorMessage(void* fptr, int status, boost::format const& msg) {
80  return makeErrorMessage(fptr, status, msg.str());
81 }
82 
99  std::set<std::string> const& excludeNames = {});
100 
105 #define LSST_FITS_EXCEPT(type, fitsObj, ...) \
106  type(LSST_EXCEPT_HERE, lsst::afw::fits::makeErrorMessage((fitsObj).fptr, (fitsObj).status, __VA_ARGS__))
107 
111 #define LSST_FITS_CHECK_STATUS(fitsObj, ...) \
112  if ((fitsObj).status != 0) throw LSST_FITS_EXCEPT(lsst::afw::fits::FitsError, fitsObj, __VA_ARGS__)
113 
115 template <typename T>
116 int getBitPix();
117 
122 public:
129  MemFileManager() : _ptr(nullptr), _len(0), _managed(true) {}
130 
137  explicit MemFileManager(std::size_t len) : _ptr(nullptr), _len(0), _managed(true) { reset(len); }
138 
146  MemFileManager(void* ptr, std::size_t len) : _ptr(ptr), _len(len), _managed(false) {}
147 
153  void reset();
154 
163  void reset(std::size_t len);
164 
173  void reset(void* ptr, std::size_t len) {
174  reset();
175  _ptr = ptr;
176  _len = len;
177  _managed = false;
178  }
179 
181 
182  // No copying
183  MemFileManager(const MemFileManager&) = delete;
185 
186  // No moving
189 
191  void* getData() const { return _ptr; }
192 
194  std::size_t getLength() const { return _len; }
195 
196 private:
197  friend class Fits;
198 
199  void* _ptr;
200  std::size_t _len;
201  bool _managed;
202 };
203 
207 template <typename T, int N, int C>
208 ndarray::Array<T const, N, N> const makeContiguousArray(ndarray::Array<T, N, C> const& array) {
209  ndarray::Array<T const, N, N> contiguous = ndarray::dynamic_dimension_cast<N>(array);
210  if (contiguous.empty()) contiguous = ndarray::copy(array);
211  return contiguous;
212 }
213 
222 
224  template <typename T>
226 
228  template <typename T>
230 
232  explicit ImageWriteOptions(ImageCompressionOptions const& compression_ =
234  ImageScalingOptions const& scaling_ = ImageScalingOptions())
235  : compression(compression_), scaling(scaling_) {}
236 
238  explicit ImageWriteOptions(ImageScalingOptions const& scaling_)
239  : compression(ImageCompressionOptions::NONE), scaling(scaling_) {}
240 
266 
279 };
280 
297 class Fits {
298  void createImageImpl(int bitpix, int nAxis, long const* nAxes);
299  template <typename T>
300  void writeImageImpl(T const* data, int nElements);
301  template <typename T>
302  void readImageImpl(int nAxis, T* data, long* begin, long* end, long* increment);
303  void getImageShapeImpl(int maxDim, long* nAxes);
304 
305 public:
307  AUTO_CLOSE = 0x01, // Close files when the Fits object goes out of scope if fptr != NULL
308  AUTO_CHECK = 0x02 // Call LSST_FITS_CHECK_STATUS after every cfitsio call
309  };
310 
312  std::string getFileName() const;
313 
315  int getHdu();
316 
326  void setHdu(int hdu, bool relative = false);
327 
329  int countHdus();
330 
332  template <typename T>
334  void updateKey(std::string const& key, T const& value, std::string const& comment);
335  void updateKey(std::string const& key, char const* value, std::string const& comment) {
336  updateKey(key, std::string(value), comment);
337  }
338  template <typename T>
339  void updateKey(std::string const& key, T const& value);
340  void updateKey(std::string const& key, char const* value) { updateKey(key, std::string(value)); }
342 
344 
351  template <typename T>
352  void writeKey(std::string const& key, T const& value, std::string const& comment);
353  void writeKey(std::string const& key, char const* value, std::string const& comment) {
354  writeKey(key, std::string(value), comment);
355  }
356  template <typename T>
357  void writeKey(std::string const& key, T const& value);
358  void writeKey(std::string const& key, char const* value) { writeKey(key, std::string(value)); }
360 
362  template <typename T>
364  void updateColumnKey(std::string const& prefix, int n, T const& value, std::string const& comment);
365  void updateColumnKey(std::string const& prefix, int n, char const* value, std::string const& comment) {
366  updateColumnKey(prefix, n, std::string(value), comment);
367  }
368  template <typename T>
369  void updateColumnKey(std::string const& prefix, int n, T const& value);
370  void updateColumnKey(std::string const& prefix, int n, char const* value) {
371  updateColumnKey(prefix, n, std::string(value));
372  }
374 
376  template <typename T>
378  void writeColumnKey(std::string const& prefix, int n, T const& value, std::string const& comment);
379  void writeColumnKey(std::string const& prefix, int n, char const* value, std::string const& comment) {
380  writeColumnKey(prefix, n, std::string(value), comment);
381  }
382  template <typename T>
383  void writeColumnKey(std::string const& prefix, int n, T const& value);
384  void writeColumnKey(std::string const& prefix, int n, char const* value) {
385  writeColumnKey(prefix, n, std::string(value));
386  }
388 
398  void writeMetadata(daf::base::PropertySet const& metadata);
399 
409  void readMetadata(daf::base::PropertySet& metadata, bool strip = false);
410 
412  template <typename T>
413  void readKey(std::string const& key, T& value);
414 
423  void forEachKey(HeaderIterationFunctor& functor);
424 
431  void createEmpty();
432 
443  template <typename PixelT, int N>
444  void createImage(ndarray::Vector<ndarray::Size, N> const& shape) {
445  ndarray::Vector<long, N> nAxes(shape.reverse());
446  createImageImpl(detail::Bitpix<PixelT>::value, N, nAxes.elems);
447  }
448 
449  template <int N>
450  void createImage(int bitpix, ndarray::Vector<ndarray::Size, N> const& shape) {
451  ndarray::Vector<long, N> nAxes(shape.reverse());
452  createImageImpl(bitpix, N, nAxes.elems);
453  }
454 
461  template <typename PixelT>
462  void createImage(long x, long y) {
463  long naxes[2] = {x, y};
464  createImageImpl(detail::Bitpix<PixelT>::value, 2, naxes);
465  }
466 
476  template <typename T, int N, int C>
477  void writeImage(ndarray::Array<T const, N, C> const& array) {
478  writeImageImpl(makeContiguousArray(array).getData(), array.getNumElements());
479  }
480 
493  template <typename T>
494  void writeImage(
495  image::ImageBase<T> const& image, ImageWriteOptions const& options,
499 
501  int getImageDim();
502 
511  template <int N>
512  ndarray::Vector<ndarray::Size, N> getImageShape() {
513  ndarray::Vector<long, N> nAxes(1);
514  getImageShapeImpl(N, nAxes.elems);
515  ndarray::Vector<ndarray::Size, N> shape;
516  for (int i = 0; i < N; ++i) shape[i] = nAxes[N - i - 1];
517  return shape;
518  }
519 
526  template <typename T>
527  bool checkImageType();
528 
533 
540  template <typename T, int N>
541  void readImage(ndarray::Array<T, N, N> const& array, ndarray::Vector<int, N> const& offset) {
542  ndarray::Vector<long, N> begin(offset.reverse());
543  ndarray::Vector<long, N> end(begin);
544  end += array.getShape().reverse();
545  ndarray::Vector<long, N> increment(1);
546  begin += increment; // first FITS pixel is 1, not 0
547  readImageImpl(N, array.getData(), begin.elems, end.elems, increment.elems);
548  }
549 
551  void createTable();
552 
559  template <typename T>
560  int addColumn(std::string const& ttype, int size, std::string const& comment);
561 
568  template <typename T>
569  int addColumn(std::string const& ttype, int size);
570 
573 
576 
578  template <typename T>
579  void writeTableArray(std::size_t row, int col, int nElements, T const* value);
580 
582  template <typename T>
583  void writeTableScalar(std::size_t row, int col, T value) {
584  writeTableArray(row, col, 1, &value);
585  }
587  void writeTableScalar(std::size_t row, int col, std::string const& value);
588 
590  template <typename T>
591  void readTableArray(std::size_t row, int col, int nElements, T* value);
592 
594  template <typename T>
595  void readTableScalar(std::size_t row, int col, T& value) {
596  readTableArray(row, col, 1, &value);
597  }
598 
600  void readTableScalar(std::size_t row, int col, std::string& value, bool isVariableLength);
601 
603  long getTableArraySize(int col);
604 
607 
609  Fits() : fptr(nullptr), status(0), behavior(0) {}
610 
612  Fits(std::string const& filename, std::string const& mode, int behavior);
613 
615  Fits(MemFileManager& manager, std::string const& mode, int behavior);
616 
618  void closeFile();
619 
623  void setImageCompression(ImageCompressionOptions const& options);
624 
627 
636 
637  ~Fits() {
638  if ((fptr) && (behavior & AUTO_CLOSE)) closeFile();
639  }
640 
641  // No copying
642  Fits(const Fits&) = delete;
643  Fits& operator=(const Fits&) = delete;
644 
645  // No moving
646  Fits(Fits&&) = delete;
647  Fits& operator=(Fits&&) = delete;
648 
649  void* fptr; // the actual cfitsio fitsfile pointer; void to avoid including fitsio.h here.
650  int status; // the cfitsio status indicator that gets passed to every cfitsio call.
651  int behavior; // bitwise OR of BehaviorFlags
652 };
653 
674 
686  bool strip = false);
698  bool strip = false);
709 
710 void setAllowImageCompression(bool allow);
712 
713 
714 
725 public:
726 
727  HduMoveGuard() = delete;
728 
729  HduMoveGuard(HduMoveGuard const &) = delete;
731 
732  HduMoveGuard & operator=(HduMoveGuard const &) = delete;
734 
746  HduMoveGuard(Fits & fits, int hdu, bool relative=false);
747 
748  ~HduMoveGuard();
749 
751  void disable() { _enabled = false; }
752 
753 private:
754  Fits & _fits;
755  int _oldHdu;
756  bool _enabled;
757 };
758 
759 
760 } // namespace fits
761 } // namespace afw
762 } // namespace lsst
763 
764 #endif // !LSST_AFW_fits_h_INCLUDED
char * data
Definition: BaseRecord.cc:61
int end
double x
#define LSST_EXCEPTION_TYPE(t, b, c)
Macro used to define new types of exceptions without additional data.
Definition: Exception.h:69
Fits * fits
Definition: FitsWriter.cc:90
afw::table::Key< afw::table::Array< MaskPixelT > > mask
uint64_t * ptr
Definition: RangeSet.cc:88
std::string prefix
Definition: SchemaMapper.cc:72
int y
Definition: SpanSet.cc:48
Basic LSST definitions.
An exception thrown when problems are found when reading or writing FITS files.
Definition: fits.h:36
A simple struct that combines the two arguments that must be passed to most cfitsio routines and cont...
Definition: fits.h:297
void writeKey(std::string const &key, char const *value)
Definition: fits.h:358
void updateKey(std::string const &key, char const *value)
Definition: fits.h:340
void readImage(ndarray::Array< T, N, N > const &array, ndarray::Vector< int, N > const &offset)
Read an array from a FITS image.
Definition: fits.h:541
void writeKey(std::string const &key, T const &value, std::string const &comment)
Add a FITS header key to the bottom of the header.
Definition: fits.cc:667
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.
Definition: fits.cc:699
void closeFile()
Close a FITS file.
Definition: fits.cc:1623
void writeImage(ndarray::Array< T const, N, C > const &array)
Write an ndarray::Array to a FITS image HDU.
Definition: fits.h:477
void writeKey(std::string const &key, char const *value, std::string const &comment)
Definition: fits.h:353
int getImageDim()
Return the number of dimensions in the current HDU.
Definition: fits.cc:1422
void writeColumnKey(std::string const &prefix, int n, char const *value)
Definition: fits.h:384
void createImage(int bitpix, ndarray::Vector< ndarray::Size, N > const &shape)
Definition: fits.h:450
std::size_t countRows()
Return the number of row in a table.
Definition: fits.cc:1159
ImageCompressionOptions getImageCompression()
Return the current image compression settings.
Definition: fits.cc:1495
void createEmpty()
Create an empty image HDU with NAXIS=0 at the end of the file.
Definition: fits.cc:1240
void createImage(long x, long y)
Create a 2-d image with pixel type provided by the given explicit PixelT template parameter.
Definition: fits.h:462
void readTableArray(std::size_t row, int col, int nElements, T *value)
Read an array value from a binary table.
Definition: fits.cc:1192
void writeColumnKey(std::string const &prefix, int n, char const *value, std::string const &comment)
Definition: fits.h:379
Fits & operator=(const Fits &)=delete
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.
Definition: fits.cc:691
void setHdu(int hdu, bool relative=false)
Set the current HDU.
Definition: fits.cc:513
void createTable()
Create a new binary table extension.
Definition: fits.cc:1117
Fits()
Default constructor; set all data members to 0.
Definition: fits.h:609
void readTableScalar(std::size_t row, int col, T &value)
Read an array scalar from a binary table.
Definition: fits.h:595
void updateKey(std::string const &key, char const *value, std::string const &comment)
Definition: fits.h:335
bool checkCompressedImagePhu()
Go to the first image header in the FITS file.
Definition: fits.cc:1726
int countHdus()
Return the number of HDUs in the file.
Definition: fits.cc:534
void writeTableScalar(std::size_t row, int col, T value)
Write a scalar value to a binary table.
Definition: fits.h:583
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 de...
Definition: fits.h:444
ndarray::Vector< ndarray::Size, N > getImageShape()
Return the shape of the current (image) HDU.
Definition: fits.h:512
void forEachKey(HeaderIterationFunctor &functor)
Call a polymorphic functor for every key in the header.
Definition: fits.cc:781
std::string getFileName() const
Return the file name associated with the FITS object or "<unknown>" if there is none.
Definition: fits.cc:498
int addColumn(std::string const &ttype, int size, std::string const &comment)
Add a column to a table.
Definition: fits.cc:1140
void updateColumnKey(std::string const &prefix, int n, char const *value)
Definition: fits.h:370
Fits & operator=(Fits &&)=delete
Fits(const Fits &)=delete
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.
Definition: fits.cc:659
void setImageCompression(ImageCompressionOptions const &options)
Set compression options for writing FITS images.
Definition: fits.cc:1518
void readMetadata(daf::base::PropertySet &metadata, bool strip=false)
Read a FITS header into a PropertySet or PropertyList.
Definition: fits.cc:1087
void writeTableArray(std::size_t row, int col, int nElements, T const *value)
Write an array value to a binary table.
Definition: fits.cc:1169
void readKey(std::string const &key, T &value)
Read a FITS header key into the given reference.
Definition: fits.cc:774
std::string getImageDType()
Return the numpy dtype equivalent of the image pixel type (e.g.
Definition: fits.cc:1466
int getHdu()
Return the current HDU (0-indexed; 0 is the Primary HDU).
Definition: fits.cc:507
void updateColumnKey(std::string const &prefix, int n, char const *value, std::string const &comment)
Definition: fits.h:365
void writeMetadata(daf::base::PropertySet const &metadata)
Read a FITS header into a PropertySet or PropertyList.
Definition: fits.cc:1095
Fits(Fits &&)=delete
long getTableArraySize(int col)
Return the size of an array column.
Definition: fits.cc:1217
std::size_t addRows(std::size_t nRows)
Append rows to a table, and return the index of the first new row.
Definition: fits.cc:1149
bool checkImageType()
Return true if the current HDU is compatible with the given pixel type.
Definition: fits.cc:1435
An exception thrown when a FITS file has the wrong type.
Definition: fits.h:41
RAII scoped guard for moving the HDU in a Fits object.
Definition: fits.h:724
HduMoveGuard(HduMoveGuard &&)=delete
HduMoveGuard(HduMoveGuard const &)=delete
void disable()
Disable the guard, leaving the HDU at its current state at destruction.
Definition: fits.h:751
HduMoveGuard & operator=(HduMoveGuard &&)=delete
HduMoveGuard & operator=(HduMoveGuard const &)=delete
Base class for polymorphic functors used to iterator over FITS key headers.
Definition: fits.h:49
virtual void operator()(std::string const &key, std::string const &value, std::string const &comment)=0
Options for scaling image pixels.
Lifetime-management for memory that goes into FITS memory files.
Definition: fits.h:121
MemFileManager(MemFileManager &&)=delete
MemFileManager & operator=(MemFileManager &&)=delete
MemFileManager(void *ptr, std::size_t len)
Construct a MemFileManager that references and does not manage external memory.
Definition: fits.h:146
MemFileManager()
Construct a MemFileManager with no initial memory buffer.
Definition: fits.h:129
void reset(void *ptr, std::size_t len)
Set the internal memory buffer to an manually-managed external block.
Definition: fits.h:173
MemFileManager(std::size_t len)
Construct a MemFileManager with (len) bytes of initial memory.
Definition: fits.h:137
void * getData() const
Return the buffer.
Definition: fits.h:191
void reset()
Return the manager to the same state it would be if default-constructed.
Definition: fits.cc:475
MemFileManager & operator=(const MemFileManager &)=delete
MemFileManager(const MemFileManager &)=delete
std::size_t getLength() const
Return the buffer length.
Definition: fits.h:194
The base class for all image classed (Image, Mask, MaskedImage, ...)
Definition: ImageBase.h:102
A class to represent a 2-dimensional array of pixels.
Definition: Image.h:51
Represent a 2-dimensional array of bitmask pixels.
Definition: Mask.h:77
Class for storing generic metadata.
Definition: PropertySet.h:66
Reports errors in external input/output operations.
Definition: Runtime.h:160
bool strip
Definition: fits.cc:911
const int DEFAULT_HDU
Specify that the default HDU should be read.
Definition: fitsDefaults.h:18
ndarray::Array< T const, N, N > const makeContiguousArray(ndarray::Array< T, N, C > const &array)
Construct a contiguous ndarray.
Definition: fits.h:208
int getBitPix()
Return the cfitsio integer BITPIX code for the given data type.
Definition: fits.cc:490
std::shared_ptr< daf::base::PropertyList > combineMetadata(std::shared_ptr< const daf::base::PropertyList > first, std::shared_ptr< const daf::base::PropertyList > second)
Combine two sets of metadata in a FITS-appropriate fashion.
Definition: fits.cc:1628
std::shared_ptr< daf::base::PropertyList > readMetadata(std::string const &fileName, int hdu=DEFAULT_HDU, bool strip=false)
Read FITS header.
Definition: fits.cc:1657
void setAllowImageCompression(bool allow)
Definition: fits.cc:1546
std::string makeErrorMessage(std::string const &fileName="", int status=0, std::string const &msg="")
Return an error message reflecting FITS I/O errors.
Definition: fits.cc:426
bool getAllowImageCompression()
Definition: fits.cc:1548
std::string makeLimitedFitsHeader(lsst::daf::base::PropertySet const &metadata, std::set< std::string > const &excludeNames={})
Format a PropertySet into an FITS header string in a simplistic fashion.
Definition: fits.cc:457
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects.
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174
A base class for image defects.
int row
Definition: CR.cc:145
int col
Definition: CR.cc:144
Options for tile compression of image pixels.
Options for writing an image to FITS.
Definition: fits.h:219
ImageCompressionOptions compression
Options controlling compression.
Definition: fits.h:220
ImageScalingOptions scaling
Options controlling scaling.
Definition: fits.h:221
ImageWriteOptions(ImageScalingOptions const &scaling_)
Construct with specific scaling options.
Definition: fits.h:238
static std::shared_ptr< daf::base::PropertySet > validate(daf::base::PropertySet const &config)
Validate a PropertySet.
Definition: fits.cc:1781
ImageWriteOptions(image::Image< T > const &image)
Construct with default options for images.
Definition: fits.h:225
ImageWriteOptions(ImageCompressionOptions const &compression_=ImageCompressionOptions(ImageCompressionOptions::NONE), ImageScalingOptions const &scaling_=ImageScalingOptions())
Construct with specific compression and scaling options.
Definition: fits.h:232
ImageWriteOptions(image::Mask< T > const &mask)
Construct with default options for masks.
Definition: fits.h:229
FITS BITPIX header value by C++ type.