casacore
Static Public Member Functions | Static Public Attributes | Static Private Member Functions | List of all members
casacore::ImageFITSConverter Class Reference

Interconvert between Casacore Images and FITS files. More...

#include <ImageFITSConverter.h>

Static Public Member Functions

static Bool FITSToImage (ImageInterface< Float > *&newImage, String &error, const String &imageName, const String &fitsName, uInt whichRep=0, Int whichHDU=0, uInt memoryInMB=64, Bool allowOverwrite=False, Bool zeroBlanks=False)
 Convert a FITS file to a Casacore image. More...
 
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, Bool stokesLast=False, Bool preferWavelength=False, Bool airWavelength=False, const String &origin=String(), Bool history=True)
 Convert a Casacore image to a FITS file. More...
 
static Bool ImageHeaderToFITS (String &error, ImageFITSHeaderInfo &fhi, const ImageInterface< Float > &image, Bool preferVelocity=True, Bool opticalVelocity=True, Int BITPIX=-32, Float minPix=1.0, Float maxPix=-1.0, Bool degenerateLast=False, Bool verbose=True, Bool stokesLast=False, Bool preferWavelength=False, Bool airWavelength=False, Bool primHead=True, Bool allowAppend=True, const String &origin=String(), Bool history=True)
 
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. More...
 
static CoordinateSystem getCoordinateSystem (Int &imageType, RecordInterface &headerRec, const Vector< String > &header, LogIO &os, uInt whichRep, IPosition &shape, Bool dropStokes)
 Recover CoordinateSystem from header. More...
 
static ImageInfo getImageInfo (RecordInterface &header)
 Recover ImageInfo from header. More...
 
static Unit getBrightnessUnit (RecordInterface &header, LogIO &os)
 Recover brightness unit from header. More...
 
static void restoreHistory (LoggerHolder &logger, ConstFitsKeywordList &kw)
 Recover history from FITS file keyword list into logger. More...
 
static Bool extractMiscInfo (RecordInterface &miscInfo, const RecordInterface &header)
 Parse header record and set MiscInfo. More...
 
static void readBeamsTable (ImageInfo &info, const String &filename, const DataType type)
 Read the BEAMS table if present and add the restoring beams to info. More...
 

Static Public Attributes

static const String CASAMBM
 

Static Private Member Functions

static Bool ImageToFITSOut (String &error, LogIO &os, const ImageInterface< Float > &image, FitsOutput *output, uInt memoryInMB=64, Bool preferVelocity=True, Bool opticalVelocity=True, Int BITPIX=-32, Float minPix=1.0, Float maxPix=-1.0, Bool degenerateLast=False, Bool verbose=True, Bool stokesLast=False, Bool preferWavelength=False, Bool airWavelength=False, Bool primHead=True, Bool allowAppend=False, const String &origin=String(), Bool history=True)
 Put a CASA image to an opened FITS image Parameters as in "ImageToFITS". More...
 
static Bool QualImgToFITSOut (String &error, LogIO &os, ImageInterface< Float > &image, FitsOutput *outfile, uInt memoryInMB, Bool preferVelocity, Bool opticalVelocity, Int BITPIX, Float minPix, Float maxPix, Bool degenerateLast, Bool verbose, Bool stokesLast, Bool preferWavelength, Bool airWavelength, const String &origin, Bool history)
 Put a CASA image with quality coordinate to an opened FITS file Parameters as in "ImageToFITS". More...
 
static Bool removeFile (String &error, const File &outFile, const String &outName, Bool allowOverwrite)
 If existing, remove the file, symlink, or directory given by outFile. More...
 
static Bool openFitsOutput (String &error, FitsOutput *(&openFitsOutput), const String &fitsName, const Bool &allowOverwrite)
 Create an open FITS file with the name given. More...
 
static void _writeBeamsTable (FitsOutput *const &outfile, const ImageInfo &info)
 

Detailed Description

Interconvert between Casacore Images and FITS files.

Intended use:

Public interface

Review Status

Date Reviewed:
yyyy/mm/dd

Prerequisite

Synopsis

This class is a helper class that is used to interconvert between Casacore images and FITS files. This adds no functionality over the general abilities available in the underlying FITS classes, however it is a useful higher-level packaging.

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

We can read images from any HDU inside the FITS file (although this isn't well tested). Images with a quality axis (i.e. contain data and error values) are stored in the primary HDU (data) and an extension HDU (error). Other images are always written to the primary HDU.

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

A FITS to image conversion may be accomplished as follows:

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..\.
static Bool FITSToImage(ImageInterface< Float > *&newImage, String &error, const String &imageName, const String &fitsName, uInt whichRep=0, Int whichHDU=0, uInt memoryInMB=64, Bool allowOverwrite=False, Bool zeroBlanks=False)
Convert a FITS file to a Casacore image.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42

A couple of things to note:

Similarly, an image to FITS conversion may be accomplished as follows:

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);
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, Bool stokesLast=False, Bool preferWavelength=False, Bool airWavelength=False, const String &origin=String(), Bool history=True)
Convert a Casacore image to a FITS file.

A couple of similar remarks can be made about this example:

Motivation

FITS files are the fundamental transport format for images in Astronomy.

To Do

Definition at line 170 of file ImageFITSConverter.h.

Member Function Documentation

◆ _writeBeamsTable()

static void casacore::ImageFITSConverter::_writeBeamsTable ( FitsOutput *const &  outfile,
const ImageInfo info 
)
staticprivate

◆ copyCursorShape()

static IPosition casacore::ImageFITSConverter::copyCursorShape ( String report,
const IPosition shape,
uInt  imagePixelSize,
uInt  fitsPixelSize,
uInt  memoryInMB 
)
static

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.

◆ extractMiscInfo()

static Bool casacore::ImageFITSConverter::extractMiscInfo ( RecordInterface miscInfo,
const RecordInterface header 
)
static

Parse header record and set MiscInfo.

◆ FITSToImage()

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

Convert a FITS file to a Casacore image.

  • 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. A value of -1 makes the code look for the first readable HDU.
  • 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

◆ getBrightnessUnit()

static Unit casacore::ImageFITSConverter::getBrightnessUnit ( RecordInterface header,
LogIO os 
)
static

Recover brightness unit from header.

Used keywords are removed from header.

◆ getCoordinateSystem()

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

Recover CoordinateSystem from header.

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

◆ getImageInfo()

static ImageInfo casacore::ImageFITSConverter::getImageInfo ( RecordInterface header)
static

Recover ImageInfo from header.

Used keywords are removed from header

◆ ImageHeaderToFITS()

static Bool casacore::ImageFITSConverter::ImageHeaderToFITS ( String error,
ImageFITSHeaderInfo fhi,
const ImageInterface< Float > &  image,
Bool  preferVelocity = True,
Bool  opticalVelocity = True,
Int  BITPIX = -32,
Float  minPix = 1.0,
Float  maxPix = -1.0,
Bool  degenerateLast = False,
Bool  verbose = True,
Bool  stokesLast = False,
Bool  preferWavelength = False,
Bool  airWavelength = False,
Bool  primHead = True,
Bool  allowAppend = True,
const String origin = String(),
Bool  history = True 
)
static

◆ ImageToFITS()

static Bool casacore::ImageFITSConverter::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,
Bool  stokesLast = False,
Bool  preferWavelength = False,
Bool  airWavelength = False,
const String origin = String(),
Bool  history = True 
)
static

Convert a Casacore 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.
  • preferWavelength If True, write a wavelength primary axis.
  • airWavelength If True and preferWavelength is True write an air wavelength primary axis.
  • origin gives the origin, i.e., the name of the package. If empty, it defaults to "casacore-"getVersion().

◆ ImageToFITSOut()

static Bool casacore::ImageFITSConverter::ImageToFITSOut ( String error,
LogIO os,
const ImageInterface< Float > &  image,
FitsOutput output,
uInt  memoryInMB = 64,
Bool  preferVelocity = True,
Bool  opticalVelocity = True,
Int  BITPIX = -32,
Float  minPix = 1.0,
Float  maxPix = -1.0,
Bool  degenerateLast = False,
Bool  verbose = True,
Bool  stokesLast = False,
Bool  preferWavelength = False,
Bool  airWavelength = False,
Bool  primHead = True,
Bool  allowAppend = False,
const String origin = String(),
Bool  history = True 
)
staticprivate

Put a CASA image to an opened FITS image Parameters as in "ImageToFITS".

In addition:

  • output The FITS output to write to.
  • primHead Write to a primary HDU.
  • allowAppend Allow to append extension HDU's.

◆ openFitsOutput()

static Bool casacore::ImageFITSConverter::openFitsOutput ( String error,
FitsOutput *&  openFitsOutput,
const String fitsName,
const Bool allowOverwrite 
)
staticprivate

Create an open FITS file with the name given.

◆ QualImgToFITSOut()

static Bool casacore::ImageFITSConverter::QualImgToFITSOut ( String error,
LogIO os,
ImageInterface< Float > &  image,
FitsOutput outfile,
uInt  memoryInMB,
Bool  preferVelocity,
Bool  opticalVelocity,
Int  BITPIX,
Float  minPix,
Float  maxPix,
Bool  degenerateLast,
Bool  verbose,
Bool  stokesLast,
Bool  preferWavelength,
Bool  airWavelength,
const String origin,
Bool  history 
)
staticprivate

Put a CASA image with quality coordinate to an opened FITS file Parameters as in "ImageToFITS".

In addition:

  • output The FITS output to write to.

◆ readBeamsTable()

static void casacore::ImageFITSConverter::readBeamsTable ( ImageInfo info,
const String filename,
const DataType  type 
)
static

Read the BEAMS table if present and add the restoring beams to info.

◆ removeFile()

static Bool casacore::ImageFITSConverter::removeFile ( String error,
const File outFile,
const String outName,
Bool  allowOverwrite 
)
staticprivate

If existing, remove the file, symlink, or directory given by outFile.

It is only removed if allowOverwrite=True. An exception (using argument outName) is thrown if the file could not be removed.

◆ restoreHistory()

static void casacore::ImageFITSConverter::restoreHistory ( LoggerHolder logger,
ConstFitsKeywordList kw 
)
static

Recover history from FITS file keyword list into logger.

Member Data Documentation

◆ CASAMBM

const String casacore::ImageFITSConverter::CASAMBM
static

Definition at line 173 of file ImageFITSConverter.h.


The documentation for this class was generated from the following file: