LSSTApplications  11.0-24-g0a022a1,14.0+77,15.0,15.0+1
LSSTDataManagementBasePackage
Image/Mask/MaskedImage I/O

Image/Mask/MaskedImage I/O

Reading Images, Masks, and MaskedImages from FITS files is achieved via their constructors that take a string, e.g.

Image::Image(fileName, hdu=0, metadata=lsst::daf::base::PropertySet::Ptr(), bbox=BBox());

Writing to FITS files is done via a method, e.g. Image::writeFits (but once more, you should peruse Reading and writing MaskedImages).

Reading and writing MaskedImages

MaskedImages are a bit more complicated, as there are three pieces of data to read or write, the image, the mask, and the variance. What's more, LSST changed its mind about how to do this in the early summer of 2009.

The old convention was to write three separate FITS files, so a call to MaskedImage::writeFits("foo") would result in three files, foo_img.fits, foo_msk.fits, and foo_var.fits. The new convention is that, if the filename looks like a complete FITS file, the data should be written to a single Multi Extension Fits (MEF) file. I.e.

In both cases, the FITS HDUs are identified with the EXTTYPE keyword; the possible values are IMAGE, MASK, and VARIANCE. If the EXTTYPE keyword is present in the file, it must have the expected value or lsst::pex::exceptions::InvalidParameterException is thrown.

Deprecated:
Please do not use the three-separate-files APIs in new code.

The corresponding constructors obeyed and obey the same conventions, so

Note
If foo.fits doesn't exist, the code tries to read foo.fits_img.fits for backward compatibility, but there's no way to force the code to write this file.
An attempt to read a MaskedImage from a FITS file which does not have MASK and/or VARIANCE HDUs will succeed unless the requireAllHdus argument is true; the missing data will be replaced with 0s.
Reading a MaskedImage from a non-default HDU in a MEF will not read MASK or VARIANCE data; again, they will be replaced with 0s.

Appending to FITS files

If you specify the mode in e.g. Image::writeFits to a (or ab), the desired data will be appended to the file. For Images and Masks this adds a single HDU, while for a MaskedImage it adds 3.

You can read the HDU of your desires by passing an hdu to the constructor.

Note
Per the above, it is possible to append a MaskedImage to a FITS file, but not possible to read it back from a non-default HDU.