lsst.afw g190dffac4e+f394777a51
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"
28
29namespace lsst {
30namespace afw {
31namespace fits {
32
37
38
41LSST_EXCEPTION_TYPE(FitsTypeError, lsst::afw::fits::FitsError, lsst::afw::fits::FitsTypeError)
42
50public:
51 virtual void operator()(std::string const& key, std::string const& value, std::string const& comment) = 0;
52
54};
55
64std::string makeErrorMessage(std::string const& fileName = "", int status = 0, std::string const& msg = "");
65inline std::string makeErrorMessage(std::string const& fileName, int status, boost::format const& msg) {
66 return makeErrorMessage(fileName, status, msg.str());
67}
68
78std::string makeErrorMessage(void* fptr, int status = 0, std::string const& msg = "");
79inline 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) { \
113 auto except = LSST_FITS_EXCEPT(lsst::afw::fits::FitsError, fitsObj, __VA_ARGS__); \
114 (fitsObj).status = 0; \
115 throw except; \
116 }
117
119template <typename T>
120int getBitPix();
121
126public:
133 MemFileManager() : _ptr(nullptr), _len(0), _managed(true) {}
134
141 explicit MemFileManager(std::size_t len) : _ptr(nullptr), _len(0), _managed(true) { reset(len); }
142
150 MemFileManager(void* ptr, std::size_t len) : _ptr(ptr), _len(len), _managed(false) {}
151
157 void reset();
158
167 void reset(std::size_t len);
168
177 void reset(void* ptr, std::size_t len) {
178 reset();
179 _ptr = ptr;
180 _len = len;
181 _managed = false;
182 }
183
185
186 // No copying
189
190 // No moving
193
195 void* getData() const { return _ptr; }
196
198 std::size_t getLength() const { return _len; }
199
200private:
201 friend class Fits;
202
203 void* _ptr;
204 std::size_t _len;
205 bool _managed;
206};
207
211template <typename T, int N, int C>
212ndarray::Array<T const, N, N> const makeContiguousArray(ndarray::Array<T, N, C> const& array) {
213 ndarray::Array<T const, N, N> contiguous = ndarray::dynamic_dimension_cast<N>(array);
214 if (contiguous.empty()) contiguous = ndarray::copy(array);
215 return contiguous;
216}
217
226
228 template <typename T>
230
232 template <typename T>
234
236 explicit ImageWriteOptions(ImageCompressionOptions const& compression_ =
238 ImageScalingOptions const& scaling_ = ImageScalingOptions())
239 : compression(compression_), scaling(scaling_) {}
240
242 explicit ImageWriteOptions(ImageScalingOptions const& scaling_)
243 : compression(ImageCompressionOptions::NONE), scaling(scaling_) {}
244
270
283};
284
301class Fits {
302 void createImageImpl(int bitpix, int nAxis, long const* nAxes);
303 template <typename T>
304 void writeImageImpl(T const* data, int nElements);
305 template <typename T>
306 void readImageImpl(int nAxis, T* data, long* begin, long* end, long* increment);
307 void getImageShapeImpl(int maxDim, long* nAxes);
308
309public:
311 AUTO_CLOSE = 0x01, // Close files when the Fits object goes out of scope if fptr != NULL
312 AUTO_CHECK = 0x02 // Call LSST_FITS_CHECK_STATUS after every cfitsio call
313 };
314
316 std::string getFileName() const;
317
319 int getHdu();
320
330 void setHdu(int hdu, bool relative = false);
331
333 int countHdus();
334
336
337 template <typename T>
338 void updateKey(std::string const& key, T const& value, std::string const& comment);
339 void updateKey(std::string const& key, char const* value, std::string const& comment) {
340 updateKey(key, std::string(value), comment);
341 }
342 template <typename T>
343 void updateKey(std::string const& key, T const& value);
344 void updateKey(std::string const& key, char const* value) { updateKey(key, std::string(value)); }
346
348
355 template <typename T>
356 void writeKey(std::string const& key, T const& value, std::string const& comment);
357 void writeKey(std::string const& key, char const* value, std::string const& comment) {
358 writeKey(key, std::string(value), comment);
359 }
360 template <typename T>
361 void writeKey(std::string const& key, T const& value);
362 void writeKey(std::string const& key, char const* value) { writeKey(key, std::string(value)); }
364
366
367 template <typename T>
368 void updateColumnKey(std::string const& prefix, int n, T const& value, std::string const& comment);
369 void updateColumnKey(std::string const& prefix, int n, char const* value, std::string const& comment) {
370 updateColumnKey(prefix, n, std::string(value), comment);
371 }
372 template <typename T>
373 void updateColumnKey(std::string const& prefix, int n, T const& value);
374 void updateColumnKey(std::string const& prefix, int n, char const* value) {
376 }
378
380
381 template <typename T>
382 void writeColumnKey(std::string const& prefix, int n, T const& value, std::string const& comment);
383 void writeColumnKey(std::string const& prefix, int n, char const* value, std::string const& comment) {
384 writeColumnKey(prefix, n, std::string(value), comment);
385 }
386 template <typename T>
387 void writeColumnKey(std::string const& prefix, int n, T const& value);
388 void writeColumnKey(std::string const& prefix, int n, char const* value) {
390 }
392
402 void writeMetadata(daf::base::PropertySet const& metadata);
403
413 void readMetadata(daf::base::PropertySet& metadata, bool strip = false);
414
416 template <typename T>
417 void readKey(std::string const& key, T& value);
418
427 void forEachKey(HeaderIterationFunctor& functor);
428
435 void createEmpty();
436
447 template <typename PixelT, int N>
448 void createImage(ndarray::Vector<ndarray::Size, N> const& shape) {
449 ndarray::Vector<long, N> nAxes(shape.reverse());
450 createImageImpl(detail::Bitpix<PixelT>::value, N, nAxes.elems);
451 }
452
453 template <int N>
454 void createImage(int bitpix, ndarray::Vector<ndarray::Size, N> const& shape) {
455 ndarray::Vector<long, N> nAxes(shape.reverse());
456 createImageImpl(bitpix, N, nAxes.elems);
457 }
458
465 template <typename PixelT>
466 void createImage(long x, long y) {
467 long naxes[2] = {x, y};
468 createImageImpl(detail::Bitpix<PixelT>::value, 2, naxes);
469 }
470
480 template <typename T, int N, int C>
481 void writeImage(ndarray::Array<T const, N, C> const& array) {
482 writeImageImpl(makeContiguousArray(array).getData(), array.getNumElements());
483 }
484
486
498 template <typename T>
499 void writeImage(
500 image::ImageBase<T> const& image, ImageWriteOptions const& options,
501 daf::base::PropertySet const * header = nullptr,
502 image::Mask<image::MaskPixel> const * mask = nullptr);
503 template <typename T>
504 [[deprecated("Replaced by a non-shared_ptr overload. Will be removed after v25.")]]
505 void writeImage(
506 image::ImageBase<T> const& image, ImageWriteOptions const& options,
510
512 int getImageDim();
513
522 template <int N>
523 ndarray::Vector<ndarray::Size, N> getImageShape() {
524 ndarray::Vector<long, N> nAxes(1);
525 getImageShapeImpl(N, nAxes.elems);
526 ndarray::Vector<ndarray::Size, N> shape;
527 for (int i = 0; i < N; ++i) shape[i] = nAxes[N - i - 1];
528 return shape;
529 }
530
537 template <typename T>
538 bool checkImageType();
539
544
551 template <typename T, int N>
552 void readImage(ndarray::Array<T, N, N> const& array, ndarray::Vector<int, N> const& offset) {
553 ndarray::Vector<long, N> begin(offset.reverse());
554 ndarray::Vector<long, N> end(begin);
555 end += array.getShape().reverse();
556 ndarray::Vector<long, N> increment(1);
557 begin += increment; // first FITS pixel is 1, not 0
558 readImageImpl(N, array.getData(), begin.elems, end.elems, increment.elems);
559 }
560
562 void createTable();
563
570 template <typename T>
571 int addColumn(std::string const& ttype, int size, std::string const& comment);
572
579 template <typename T>
580 int addColumn(std::string const& ttype, int size);
581
584
587
589 template <typename T>
590 void writeTableArray(std::size_t row, int col, int nElements, T const* value);
591
593 template <typename T>
594 void writeTableScalar(std::size_t row, int col, T value) {
595 writeTableArray(row, col, 1, &value);
596 }
598 void writeTableScalar(std::size_t row, int col, std::string const& value);
599
601 template <typename T>
602 void readTableArray(std::size_t row, int col, int nElements, T* value);
603
605 template <typename T>
606 void readTableScalar(std::size_t row, int col, T& value) {
607 readTableArray(row, col, 1, &value);
608 }
609
611 void readTableScalar(std::size_t row, int col, std::string& value, bool isVariableLength);
612
614 long getTableArraySize(int col);
615
617 long getTableArraySize(std::size_t row, int col);
618
620 Fits() : fptr(nullptr), status(0), behavior(0) {}
621
623 Fits(std::string const& filename, std::string const& mode, int behavior);
624
626 Fits(MemFileManager& manager, std::string const& mode, int behavior);
627
629 void closeFile();
630
634 void setImageCompression(ImageCompressionOptions const& options);
635
638
647
649 if ((fptr) && (behavior & AUTO_CLOSE)) closeFile();
650 }
651
652 // No copying
653 Fits(const Fits&) = delete;
654 Fits& operator=(const Fits&) = delete;
655
656 // No moving
657 Fits(Fits&&) = delete;
658 Fits& operator=(Fits&&) = delete;
659
660 void* fptr; // the actual cfitsio fitsfile pointer; void to avoid including fitsio.h here.
661 int status; // the cfitsio status indicator that gets passed to every cfitsio call.
662 int behavior; // bitwise OR of BehaviorFlags
663};
664
666
686[[deprecated("Replaced by a non-shared_ptr overload. Will be removed after v25.")]]
691
703 bool strip = false);
715 bool strip = false);
726
727void setAllowImageCompression(bool allow);
729
730
731
742public:
743
744 HduMoveGuard() = delete;
745
746 HduMoveGuard(HduMoveGuard const &) = delete;
748
751
763 HduMoveGuard(Fits & fits, int hdu, bool relative=false);
764
766
768 void disable() { _enabled = false; }
769
770private:
771 Fits & _fits;
772 int _oldHdu;
773 bool _enabled;
774};
775
776
777} // namespace fits
778} // namespace afw
779} // namespace lsst
780
781#endif // !LSST_AFW_fits_h_INCLUDED
char * data
Definition: BaseRecord.cc:61
int end
double x
#define LSST_EXCEPTION_TYPE(t, b, c)
Fits * fits
Definition: FitsWriter.cc:90
afw::table::Key< afw::table::Array< MaskPixelT > > mask
std::string prefix
Definition: SchemaMapper.cc:72
int y
Definition: SpanSet.cc:48
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:301
void writeKey(std::string const &key, char const *value)
Definition: fits.h:362
void updateKey(std::string const &key, char const *value)
Definition: fits.h:344
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:552
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:674
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:706
void closeFile()
Close a FITS file.
Definition: fits.cc:1637
void writeImage(ndarray::Array< T const, N, C > const &array)
Write an ndarray::Array to a FITS image HDU.
Definition: fits.h:481
void writeKey(std::string const &key, char const *value, std::string const &comment)
Definition: fits.h:357
int getImageDim()
Return the number of dimensions in the current HDU.
Definition: fits.cc:1436
void writeColumnKey(std::string const &prefix, int n, char const *value)
Definition: fits.h:388
void createImage(int bitpix, ndarray::Vector< ndarray::Size, N > const &shape)
Definition: fits.h:454
std::size_t countRows()
Return the number of row in a table.
Definition: fits.cc:1166
ImageCompressionOptions getImageCompression()
Return the current image compression settings.
Definition: fits.cc:1509
void createEmpty()
Create an empty image HDU with NAXIS=0 at the end of the file.
Definition: fits.cc:1247
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:466
void readTableArray(std::size_t row, int col, int nElements, T *value)
Read an array value from a binary table.
Definition: fits.cc:1199
Fits & operator=(const Fits &)=delete
void writeColumnKey(std::string const &prefix, int n, char const *value, std::string const &comment)
Definition: fits.h:383
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:698
void setHdu(int hdu, bool relative=false)
Set the current HDU.
Definition: fits.cc:520
void createTable()
Create a new binary table extension.
Definition: fits.cc:1124
Fits()
Default constructor; set all data members to 0.
Definition: fits.h:620
void readTableScalar(std::size_t row, int col, T &value)
Read an array scalar from a binary table.
Definition: fits.h:606
void updateKey(std::string const &key, char const *value, std::string const &comment)
Definition: fits.h:339
bool checkCompressedImagePhu()
Go to the first image header in the FITS file.
Definition: fits.cc:1752
int countHdus()
Return the number of HDUs in the file.
Definition: fits.cc:541
void writeTableScalar(std::size_t row, int col, T value)
Write a scalar value to a binary table.
Definition: fits.h:594
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:448
void forEachKey(HeaderIterationFunctor &functor)
Call a polymorphic functor for every key in the header.
Definition: fits.cc:788
std::string getFileName() const
Return the file name associated with the FITS object or "<unknown>" if there is none.
Definition: fits.cc:505
int addColumn(std::string const &ttype, int size, std::string const &comment)
Add a column to a table.
Definition: fits.cc:1147
void updateColumnKey(std::string const &prefix, int n, char const *value)
Definition: fits.h:374
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:666
void setImageCompression(ImageCompressionOptions const &options)
Set compression options for writing FITS images.
Definition: fits.cc:1532
void readMetadata(daf::base::PropertySet &metadata, bool strip=false)
Read a FITS header into a PropertySet or PropertyList.
Definition: fits.cc:1094
void writeTableArray(std::size_t row, int col, int nElements, T const *value)
Write an array value to a binary table.
Definition: fits.cc:1176
void readKey(std::string const &key, T &value)
Read a FITS header key into the given reference.
Definition: fits.cc:781
std::string getImageDType()
Return the numpy dtype equivalent of the image pixel type (e.g.
Definition: fits.cc:1480
ndarray::Vector< ndarray::Size, N > getImageShape()
Return the shape of the current (image) HDU.
Definition: fits.h:523
int getHdu()
Return the current HDU (0-indexed; 0 is the Primary HDU).
Definition: fits.cc:514
void updateColumnKey(std::string const &prefix, int n, char const *value, std::string const &comment)
Definition: fits.h:369
Fits & operator=(Fits &&)=delete
void writeMetadata(daf::base::PropertySet const &metadata)
Read a FITS header into a PropertySet or PropertyList.
Definition: fits.cc:1102
Fits(Fits &&)=delete
long getTableArraySize(int col)
Return the size of an array column.
Definition: fits.cc:1224
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:1156
bool checkImageType()
Return true if the current HDU is compatible with the given pixel type.
Definition: fits.cc:1449
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:741
HduMoveGuard(HduMoveGuard &&)=delete
HduMoveGuard(HduMoveGuard const &)=delete
void disable()
Disable the guard, leaving the HDU at its current state at destruction.
Definition: fits.h:768
HduMoveGuard & operator=(HduMoveGuard const &)=delete
HduMoveGuard & operator=(HduMoveGuard &&)=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:125
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:150
MemFileManager()
Construct a MemFileManager with no initial memory buffer.
Definition: fits.h:133
void reset(void *ptr, std::size_t len)
Set the internal memory buffer to an manually-managed external block.
Definition: fits.h:177
MemFileManager(std::size_t len)
Construct a MemFileManager with (len) bytes of initial memory.
Definition: fits.h:141
void * getData() const
Return the buffer.
Definition: fits.h:195
MemFileManager & operator=(const MemFileManager &)=delete
void reset()
Return the manager to the same state it would be if default-constructed.
Definition: fits.cc:482
MemFileManager(const MemFileManager &)=delete
std::size_t getLength() const
Return the buffer length.
Definition: fits.h:198
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
bool strip
Definition: fits.cc:918
std::shared_ptr< daf::base::PropertyList > combineMetadata(daf::base::PropertyList const &first, daf::base::PropertyList const &second)
Combine two sets of metadata in a FITS-appropriate fashion.
Definition: fits.cc:1642
const int DEFAULT_HDU
Specify that the default HDU should be read.
Definition: fitsDefaults.h:18
int getBitPix()
Return the cfitsio integer BITPIX code for the given data type.
Definition: fits.cc:497
std::shared_ptr< daf::base::PropertyList > readMetadata(std::string const &fileName, int hdu=DEFAULT_HDU, bool strip=false)
Read FITS header.
Definition: fits.cc:1683
void setAllowImageCompression(bool allow)
Definition: fits.cc:1560
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:427
bool getAllowImageCompression()
Definition: fits.cc:1562
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:464
ndarray::Array< T const, N, N > const makeContiguousArray(ndarray::Array< T, N, C > const &array)
Construct a contiguous ndarray.
Definition: fits.h:212
Options for tile compression of image pixels.
Options for writing an image to FITS.
Definition: fits.h:223
ImageCompressionOptions compression
Options controlling compression.
Definition: fits.h:224
ImageScalingOptions scaling
Options controlling scaling.
Definition: fits.h:225
ImageWriteOptions(ImageScalingOptions const &scaling_)
Construct with specific scaling options.
Definition: fits.h:242
static std::shared_ptr< daf::base::PropertySet > validate(daf::base::PropertySet const &config)
Validate a PropertySet.
Definition: fits.cc:1807
ImageWriteOptions(image::Image< T > const &image)
Construct with default options for images.
Definition: fits.h:229
ImageWriteOptions(ImageCompressionOptions const &compression_=ImageCompressionOptions(ImageCompressionOptions::NONE), ImageScalingOptions const &scaling_=ImageScalingOptions())
Construct with specific compression and scaling options.
Definition: fits.h:236
ImageWriteOptions(image::Mask< T > const &mask)
Construct with default options for masks.
Definition: fits.h:233
FITS BITPIX header value by C++ type.