ImageFITSConverter.h

Classes

ImageFITSConverter -- Interconvert between AIPS++ Images and FITS files. (full description)

ImageFITSConverterImpl -- This class is an internal class for ImageFITSConverter. (full description)

class ImageFITSConverter

Interface

Public Members

static Bool FITSToImage(ImageInterface<Float>*& newImage, String &error, const String &imageName, const String &fitsName, uInt whichRep = 0, uInt whichHDU = 0, uInt memoryInMB = 64, Bool allowOverwrite=False, Bool zeroBlanks=False)

static Bool FITSToImageOld(ImageInterface<Float>*& newImage, String &error, const String &imageName, const String &fitsName, uInt whichHDU = 0, uInt memoryInMB = 64, Bool allowOverwrite=False, Bool zeroBlanks=False)

static Bool ImageToFITS(String &error, ImageInterface<Float> &image, const String &fitsName, uInt memoryInMB = 64, Bool preferVelocity = True, Bool opticalVelocity = True, Int BITPIX=-32, Float minPix = 1.0, Float maxPix = -1.0, Bool allowOverwrite=False, Bool degenerateLast=False, Bool verbose=True)

static IPosition copyCursorShape(String &report, const IPosition &shape, uInt imagePixelSize, uInt fitsPixelSize, uInt memoryInMB)

static CoordinateSystem getCoordinateSystem (Int& imageType, RecordInterface& headerRec, const Vector<Vector>& header, String& os, uInt whichRep, LogIO& shape, Bool dropStokes)

static CoordinateSystem getCoordinateSystemOld (Int& imageType, RecordInterface& header, LogIO& os, LogIO& shape, Bool dropStokes)

static ImageInfo getImageInfo (RecordInterface& header)

static ImageInfo getImageInfoOld (RecordInterface& header)

static Unit getBrightnessUnit (RecordInterface& header, LogIO& os)

static Unit getBrightnessUnitOld (RecordInterface& header, LogIO& os)

static void restoreHistory (LoggerHolder& logger, ConstFitsKeywordList& kw)

static Bool extractMiscInfo (RecordInterface& miscInfo, const RecordInterface& header)

Private Members

static Bool removeFile (String& error, const File& outFile, const String& outName, Bool allowOverwrite)

Description

Review Status

Date Reviewed:

yyyy/mm/dd

Prerequisite

• PagedImage
• PrimaryArray (and FITS concepts in general).

Synopsis

There are two fundamental member functions in this class. FITSToImage which turns a FITS file into an AIPS++ image, and ImageToFITS which does the opposite.

We can read images from any HDU inside the FITS file (although this isn't well tested). However at the moment we always write to the first HDU, i.e. to the primary array, not an image extension.

Pixels in the FITS file which are blanked are masked out (the mask is set to False) in the output image. On conversion to FITS, masked values are blanked. The mask which is read is the current default mask.

Example

    PagedImage<Float> *image = 0;
    String fitsName = "exists.fits";
    String imageName = "new.image";
    String error;
    Bool ok = ImageFITSConverter::FITSToImage(image, error, imageName, fitsName);
    if (!image) ... error ...

• If ok is False, the conversion failed and error will be set.
• The pointer "image" is set if the conversion succeeds. If it is zero the conversion failed and error will contain an error message.
• The caller is responsible for deleting the pointer image when the conversion is successful.

    String imageName = argv[1];
    PagedImage<Float> image = ...; // An existing image from somewhere
    String fitsName = "new.fits";
    String error;
    Bool ok = ImageFITSConverter::ImageToFITS(error, image, fitsName);

• If ok is False, the conversion failed and error will be set.

Motivation

To Do

• It might be useful to have functions that convert between FITS and general lattices.
• Add support for PagedImage
• Convert multiple images at once?
• Allow writing FITS files to an image extension in an existing FITS file.

Member Description

static Bool FITSToImage(ImageInterface<Float>*& newImage, String &error, const String &imageName, const String &fitsName, uInt whichRep = 0, uInt whichHDU = 0, uInt memoryInMB = 64, Bool allowOverwrite=False, Bool zeroBlanks=False)

• newImage will be zero if the conversion fail. If the conversion succeeds, the caller is responsible for deleting this pointer.
• error will be set if the conversion fails.
• If imageName is empty, a TempImage will be created, otherwise a PagedImage on disk.
• fitsName must already exist (and have an image at the indicated HDU).
• whichRep Zero-relative coordinate representation (Starting with wcs FITS multiple coordinate representations can be stored in a FITS file)
• whichHDU Zero-relative hdu. The default is correct for a primary array, set it for an image extension. Only zero has been tested.
• memoryInMB. Setting this to zero will result in row-by-row copying, otherwise it will attempt to with as large a chunk-size as possible, while fitting in the desired memory.
• allowOverwrite If True, allow imageName to be overwritten if it already exists.
• zeroBlanks If True, allow any blanked pixels are set to zero rather than NaN

static Bool FITSToImageOld(ImageInterface<Float>*& newImage, String &error, const String &imageName, const String &fitsName, uInt whichHDU = 0, uInt memoryInMB = 64, Bool allowOverwrite=False, Bool zeroBlanks=False)

Old version

static Bool ImageToFITS(String &error, ImageInterface<Float> &image, const String &fitsName, uInt memoryInMB = 64, Bool preferVelocity = True, Bool opticalVelocity = True, Int BITPIX=-32, Float minPix = 1.0, Float maxPix = -1.0, Bool allowOverwrite=False, Bool degenerateLast=False, Bool verbose=True)

Convert an AIPS++ image to a FITS file.

• return True if the conversion succeeds, False otherwise.
• error will be set if the conversion fails.
• image The image to convert.
• fitsName If the name is "-" (the minus character), then write to stdout Always writes to the primary array.
• memoryInMB. Setting this to zero will result in row-by-row copying, otherwise it will attempt to with as large a chunk-size as possible, while fitting in the desired memory.
• preferVelocityWrite a velocity primary spectral axis if possible.
• opticalVelocityIf writing a velocity, use the optical definition (otherwise use radio).
• BITPIX, minPix, maxPix BITPIX can presently be set to -32 or 16 only. When BITPIX is 16 it will write BSCALE and BZERO into the FITS file. If minPix is greater than maxPix the minimum and maximum pixel values will be determined from the array, otherwise the supplied values will be used and pixels outside that range will be truncated to the minimum and maximum pixel values (note that this truncation does not occur for BITPIX=-32).
• allowOverwrite If True, allow fitsName to be overwritten if it already exists.
• degenerateLast If True, axes of length 1 will be written last to the header.

static IPosition copyCursorShape(String &report, const IPosition &shape, uInt imagePixelSize, uInt fitsPixelSize, uInt memoryInMB)

Helper function - used to calculate a cursor appropriate for the desired memory use. It's not intended that application programmers call this, but you may if it's useful to you.

static CoordinateSystem getCoordinateSystem (Int& imageType, RecordInterface& headerRec, const Vector<Vector>& header, String& os, uInt whichRep, LogIO& shape, Bool dropStokes)

Recover CoordinateSystem from header. Used keywords are removed from header and the unused one returned in a Record for ease of use. Degenerate axes may be added to shape if needed

static CoordinateSystem getCoordinateSystemOld (Int& imageType, RecordInterface& header, LogIO& os, LogIO& shape, Bool dropStokes)

Old version

static ImageInfo getImageInfo (RecordInterface& header)

Recover ImageInfo from header. Used keywords are removed from header

static ImageInfo getImageInfoOld (RecordInterface& header)

Old version

static Unit getBrightnessUnit (RecordInterface& header, LogIO& os)

Recover brightness unit from header. Used keywords are removed from header

static Unit getBrightnessUnitOld (RecordInterface& header, LogIO& os)

static void restoreHistory (LoggerHolder& logger, ConstFitsKeywordList& kw)

Recover history from FITS file keywrod list into logger

static Bool extractMiscInfo (RecordInterface& miscInfo, const RecordInterface& header)

Parse header record and set MiscInfo

static Bool removeFile (String& error, const File& outFile, const String& outName, Bool allowOverwrite)

template<class HDUType> class ImageFITSConverterImpl

Interface