Image 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());

fileName gives the name of the file to be written (but see Reading and writing MaskedImages).
The hdu is FITS jargon for the Header Data Unit; the 1-indexed offset of the desired block of data in the file. As a special favour, "0" is intepreted as the first HDU, and if it's empty, the next is read instead.
The metadata is basically the contents of the FITS header (n.b. it's read automatically if you call Exposure::Exposure(fileName)).
If the bounding box bbox is supplied, only that part of the file is read (n.b. in this case the image's origin is set correctly, cf. Image::getXY0).

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.

MaskedImage::writeFits("foo.fits") writes the single MEF file, foo.fits
MaskedImage::writeFits("foo") still writes three files, foo_{img,msk,var}.fits, unless you explictly set writeMef in which case a single file, foo, will be written.

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

MaskedImage::MaskedImage("foo") reads foo_{img,msk,var}.fits if foo_img.fits exists, otherwise it reads foo
MaskedImage::MaskedImage("foo.fits") reads foo.fits

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.