A base class for astronomical images. More...

#include <ImageInterface.h>

Inheritance diagram for casa::ImageInterface< T >:

Public Member Functions
	ImageInterface ()
	ImageInterface (const RegionHandler &regionHandler)
	Construct for a specific region handler object.
	ImageInterface (const ImageInterface &other)
	Copy constructor (copy semantics).
virtual	~ImageInterface ()
virtual MaskedLattice< T > *	cloneML () const
	Make a copy of the derived object (reference semantics).
virtual ImageInterface< T > *	cloneII () const =0
virtual String	imageType () const =0
	Get the image type (returns name of derived class).
virtual void	resize (const TiledShape &newShape)=0
	Function which changes the shape of the image (N.B.
virtual Bool	setUnits (const Unit &newUnits)
	Function which get and set the units associated with the image pixels (i.e.
virtual const Unit &	units () const
virtual String	name (Bool stripPath=False) const =0
	Return the name of the current ImageInterface object.
virtual Bool	setCoordinateInfo (const CoordinateSystem &coords)
	Functions to set or replace the coordinate information in the Image Returns False on failure, e.g.
const CoordinateSystem &	coordinates () const
virtual LELCoordinates	lelCoordinates () const
	Function to get a LELCoordinate object containing the coordinates.
LoggerHolder &	logger ()
	Get access to the LoggerHolder.
const LoggerHolder &	logger () const
LogIO &	logSink ()
	Allow messages to be logged to this ImageInterface.
const LogIO &	logSink () const
void	appendLog (const LoggerHolder &other)
	Add the messages from the other image logger to this one.
const TableRecord &	miscInfo () const
	Often we have miscellaneous information we want to attach to an image.
virtual Bool	setMiscInfo (const RecordInterface &newInfo)
const ImageInfo &	imageInfo () const
	The ImageInfo object contains some miscellaneous information about the image which unlike that stored in MiscInfo, has a standard list of things, such as the restoring beam.
virtual Bool	setImageInfo (const ImageInfo &info)
Bool	canDefineRegion () const
	Can the image handle region definition?
virtual ImageRegion	makeMask (const String &name, Bool defineAsRegion=True, Bool setAsDefaultMask=True, Bool initialize=False, Bool value=True)
	Make a mask which is suitable for the type of image.
virtual void	defineRegion (const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
	Define a region/mask belonging to the image.
virtual Bool	hasRegion (const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
	Does the image have a region with the given name?
virtual ImageRegion *	getImageRegionPtr (const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True) const
	Get a region/mask belonging to the image from the given group (which can be Any).
virtual void	renameRegion (const String &newName, const String &oldName, RegionHandler::GroupType=RegionHandler::Any, Bool overwrite=False)
	Rename a region.
virtual void	removeRegion (const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True)
	Remove a region/mask belonging to the image from the given group (which can be Any).
virtual Vector< String >	regionNames (RegionHandler::GroupType=RegionHandler::Any) const
	Get the names of all regions/masks.
virtual void	useMask (MaskSpecifier=MaskSpecifier())
	Use the mask as specified.
virtual void	setDefaultMask (const String &regionName)
	Set the default pixelmask to the mask with the given name (which has to exist in the "masks" group).
virtual String	getDefaultMask () const
	Get the name of the default pixelmask.
ImageRegion	getRegion (const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
	Get a region belonging to the image.
String	makeUniqueRegionName (const String &rootName, uInt startNumber=1) const
	Make a unique region name from the given root name, thus make it such that the name is not already in use for a region or mask.
virtual Bool	ok () const =0
	Check class invariants.
Bool	toRecord (String &error, RecordInterface &outRec)
	Save and restore an ImageInterface object to or from a state Record.
Bool	fromRecord (String &error, const RecordInterface &inRec)
Protected Member Functions
ImageInterface &	operator= (const ImageInterface &other)
	Assignment (copy semantics) is only useful for derived classes.
Bool	restoreImageInfo (const RecordInterface &rec)
	Restore the image info from the record.
void	setLogMember (const LoggerHolder &logger)
	Set the image logger variable.
void	setImageInfoMember (const ImageInfo &imageInfo)
*void	setCoordsMember (const CoordinateSystem &coords)
	Set the coordinate system variable.
void	setUnitMember (const Unit &unit)
	Set the unit variable.
void	setMiscInfoMember (const RecordInterface &rec)
	Set the miscinfo variable.
RegionHandler *	getRegionHandler ()
	Get access to the region handler.
Private Attributes
CoordinateSystem	coords_p
	It is the job of the derived class to make these variables valid.
LoggerHolder	log_p
ImageInfo	imageInfo_p
Unit	unit_p
TableRecord	miscInfo_p
RegionHandler *	regHandPtr_p
	The region handling object.

Detailed Description

template<class T>
class casa::ImageInterface< T >

A base class for astronomical images.

Intended use:

Public interface

Prerequisite

Etymology

The ImageInterface class name is derived from its role as the cookie cutter Interface base class for Images.

Synopsis

The ImageInterface class is an abstract base class. All Image classes should derive from this class to ensure functions which operate on Images will work for all Image derivations.

An Image is currently defined as an Array of pixels, a Boolean mask, defining which pixels are valid and coordinates to define the reference frame. The only concrete class currently derived from this Interface is PagedImage, which allows the image to be stored on disk, and only reads specified portions of the image into memory.

Example

As this is an abstract base class it is not possible to construct an instance of this object. It can however be used as a function argument.
eg 1. (used in dImageInterface.cc)

    Float sumPixels(const ImageInterface<Float>& image){
      uInt rowLength = image.shape()(0);
      IPosition rowShape(image.ndim());
      rowShape = 1; rowShape(0) = rowLength;
      Float sumPix = 0;
      RO_LatticeIterator<Float> iter(image, rowShape);
      while(!iter.atEnd()){
        sumPix += sum(iter.vectorCursor());
        iter++;
      }
      return sumPix;
    }

The main purpose of this class is for programming objects, the following example is of how one would derive from ImageInterface:
eg 2.

    template <class T> class myNewImage : public ImageInterface<T>
    {
    public:
      // default constructor
      myNewImage();
   
      // argumented constructor
      myNewImage(...);
   
      // destructor
      ~myNewImage
      
      // the shape function is forced upon us by the Lattice base class
      IPosition shape() const;
      
      // doGetSlice is another function required of all Lattice objects.
      Bool doGetSlice(<Array<T>& buffer, const Slicer& section);
   
     // etc..\.
    private:
     // put the actual map data down here.
     // etc..\.
    };

Motivation

The use of abstract base classes to guide inheritance seemed appropriate for Images to ensure that CoordinateSystems and masking get handled uniformly.

To Do

replace ImageCoordinates

Definition at line 145 of file ImageInterface.h.

Constructor & Destructor Documentation

template<class T>

casa::ImageInterface< T >::ImageInterface ( )

template<class T>

casa::ImageInterface< T >::ImageInterface ( const RegionHandler & regionHandler )

Construct for a specific region handler object.

template<class T>

casa::ImageInterface< T >::ImageInterface ( const ImageInterface< T > & other )

Copy constructor (copy semantics).

template<class T>

virtual casa::ImageInterface< T >::~ImageInterface ( ) [virtual]

Member Function Documentation

template<class T>

void casa::ImageInterface< T >::appendLog ( const LoggerHolder & other ) [inline]

Add the messages from the other image logger to this one.

Definition at line 220 of file ImageInterface.h.

template<class T>

Bool casa::ImageInterface< T >::canDefineRegion ( ) const [inline]

Can the image handle region definition?

Definition at line 247 of file ImageInterface.h.

template<class T>

virtual ImageInterface<T>* casa::ImageInterface< T >::cloneII ( ) const [pure virtual]

Implemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::CurvedImage2D< T >, casa::ImageConcat< T >, casa::HDF5Image< T >, casa::FITSImage, casa::SubImage< T >, casa::SubImage< Float >, casa::ImageExpr< T >, casa::ImageExpr< Bool >, casa::MIRIADImage, casa::TempImage< T >, casa::TempImage< Float >, casa::TempImage< Complex >, casa::FITSQualityImage, casa::FITSErrorImage, casa::RebinImage< T >, and casa::ExtendImage< T >.

template<class T>

virtual MaskedLattice<T>* casa::ImageInterface< T >::cloneML ( ) const [virtual]

Make a copy of the derived object (reference semantics).

Implements casa::MaskedLattice< T >.

template<class T>

const CoordinateSystem& casa::ImageInterface< T >::coordinates ( ) const [inline]

Definition at line 196 of file ImageInterface.h.

Referenced by casa::ImagePolarimetry::coordinates().

template<class T>

virtual void casa::ImageInterface< T >::defineRegion	(	const String &	name,
		const ImageRegion &	region,
		RegionHandler::GroupType	,
		Bool	overwrite = `False`
	)		`[virtual]`

Define a region/mask belonging to the image.

The group type determines if it stored as a region or mask. If overwrite=False, an exception will be thrown if the region already exists.
An exception is thrown if canDefineRegion is False.

template<class T>

Bool casa::ImageInterface< T >::fromRecord	(	String &	error,
		const RecordInterface &	inRec
	)

template<class T>

virtual String casa::ImageInterface< T >::getDefaultMask ( ) const [virtual]

Get the name of the default pixelmask.

An empty string is returned if no default pixelmask.

template<class T>

virtual ImageRegion* casa::ImageInterface< T >::getImageRegionPtr	(	const String &	name,
		RegionHandler::GroupType	= `RegionHandler::Any`,
		Bool	throwIfUnknown = `True`
	)		const `[virtual]`

Get a region/mask belonging to the image from the given group (which can be Any).

Optionally an exception is thrown if the region does not exist. A zero pointer is returned if the region does not exist. The caller has to delete the ImageRegion object created.

template<class T>

ImageRegion casa::ImageInterface< T >::getRegion	(	const String &	regionName,
		RegionHandler::GroupType	= `RegionHandler::Any`
	)		const

Get a region belonging to the image.

An exception is thrown if the region does not exist.

template<class T>

RegionHandler* casa::ImageInterface< T >::getRegionHandler ( ) [inline, protected]

Get access to the region handler.

Definition at line 372 of file ImageInterface.h.

template<class T>

virtual Bool casa::ImageInterface< T >::hasRegion	(	const String &	regionName,
		RegionHandler::GroupType	= `RegionHandler::Any`
	)		const `[virtual]`

Does the image have a region with the given name?

template<class T>

const ImageInfo& casa::ImageInterface< T >::imageInfo ( ) const [inline]

The ImageInfo object contains some miscellaneous information about the image which unlike that stored in MiscInfo, has a standard list of things, such as the restoring beam.

Note that setImageInfo REPLACES the information with the new information. It is up to the derived class to make the ImageInfo permanent.

Definition at line 241 of file ImageInterface.h.

template<class T>

virtual String casa::ImageInterface< T >::imageType ( ) const [pure virtual]

Get the image type (returns name of derived class).

Implemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::CurvedImage2D< T >, casa::ImageConcat< T >, casa::HDF5Image< T >, casa::FITSImage, casa::SubImage< T >, casa::SubImage< Float >, casa::ImageExpr< T >, casa::ImageExpr< Bool >, casa::MIRIADImage, casa::TempImage< T >, casa::TempImage< Float >, casa::TempImage< Complex >, casa::FITSQualityImage, casa::FITSErrorImage, casa::RebinImage< T >, and casa::ExtendImage< T >.

template<class T>

virtual LELCoordinates casa::ImageInterface< T >::lelCoordinates ( ) const [virtual]

Function to get a LELCoordinate object containing the coordinates.

Reimplemented from casa::LatticeBase.

template<class T>

LoggerHolder& casa::ImageInterface< T >::logger ( ) [inline]

Get access to the LoggerHolder.

Definition at line 205 of file ImageInterface.h.

Referenced by casa::ImageInterface< Complex >::logSink(), and casa::ImageInterface< Complex >::setLogMember().

template<class T>

const LoggerHolder& casa::ImageInterface< T >::logger ( ) const [inline]

Definition at line 207 of file ImageInterface.h.

template<class T>

LogIO& casa::ImageInterface< T >::logSink ( ) [inline]

Allow messages to be logged to this ImageInterface.

Definition at line 213 of file ImageInterface.h.

template<class T>

const LogIO& casa::ImageInterface< T >::logSink ( ) const [inline]

Definition at line 215 of file ImageInterface.h.

Referenced by casa::ImageInterface< Complex >::logSink().

template<class T>

virtual ImageRegion casa::ImageInterface< T >::makeMask	(	const String &	name,
		Bool	defineAsRegion = `True`,
		Bool	setAsDefaultMask = `True`,
		Bool	initialize = `False`,
		Bool	value = `True`
	)		`[virtual]`

Make a mask which is suitable for the type of image.

Optionally the mask can be initialized with the given value (by default it will not).
Optionally the mask can be defined as an image region/mask and turned in the default mask for the image. By default it will.

template<class T>

String casa::ImageInterface< T >::makeUniqueRegionName	(	const String &	rootName,
		uInt	startNumber = `1`
	)		const

Make a unique region name from the given root name, thus make it such that the name is not already in use for a region or mask.

The root name is returned if it is already unique. Otherwise a number is appended to the root name to make it unique. The number starts at the given number and is incremented until the name is unique.

template<class T>

const TableRecord& casa::ImageInterface< T >::miscInfo ( ) const [inline]

Often we have miscellaneous information we want to attach to an image.

This is where it goes.
Note that setMiscInfo REPLACES the information with the new information. It can fail if, e.g., the underlying table is not writable.

Reimplemented in casa::MIRIADImage.

Definition at line 229 of file ImageInterface.h.

template<class T>

virtual String casa::ImageInterface< T >::name ( Bool stripPath = False ) const [pure virtual]

Return the name of the current ImageInterface object.

This will generally be a file name for images that have a persistent form. Any path before the actual file name can be optionally stripped off.

Reimplemented from casa::LatticeBase.

Implemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::SubImage< T >, casa::SubImage< Float >, casa::TempImage< T >, casa::TempImage< Float >, casa::TempImage< Complex >, casa::MIRIADImage, casa::FITSImage, casa::CurvedImage2D< T >, casa::ImageConcat< T >, casa::FITSQualityImage, casa::ImageExpr< T >, casa::ImageExpr< Bool >, casa::HDF5Image< T >, casa::RebinImage< T >, and casa::ExtendImage< T >.

template<class T>

virtual Bool casa::ImageInterface< T >::ok ( ) const [pure virtual]

Check class invariants.

Reimplemented from casa::LatticeBase.

Implemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::TempImage< T >, casa::TempImage< Float >, casa::TempImage< Complex >, casa::ImageConcat< T >, casa::MIRIADImage, casa::FITSImage, casa::SubImage< T >, casa::SubImage< Float >, casa::CurvedImage2D< T >, casa::FITSQualityImage, casa::ImageExpr< T >, casa::ImageExpr< Bool >, casa::HDF5Image< T >, casa::RebinImage< T >, and casa::ExtendImage< T >.

template<class T>

ImageInterface& casa::ImageInterface< T >::operator= ( const ImageInterface< T > & other ) [protected]

Assignment (copy semantics) is only useful for derived classes.

template<class T>

virtual Vector<String> casa::ImageInterface< T >::regionNames ( RegionHandler::GroupType = RegionHandler::Any ) const [virtual]

Get the names of all regions/masks.

template<class T>

virtual void casa::ImageInterface< T >::removeRegion	(	const String &	name,
		RegionHandler::GroupType	= `RegionHandler::Any`,
		Bool	throwIfUnknown = `True`
	)		`[virtual]`

Remove a region/mask belonging to the image from the given group (which can be Any).

Optionally an exception is thrown if the region does not exist.

Reimplemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::HDF5Image< T >, casa::TempImage< T >, casa::TempImage< Float >, and casa::TempImage< Complex >.

template<class T>

virtual void casa::ImageInterface< T >::renameRegion	(	const String &	newName,
		const String &	oldName,
		RegionHandler::GroupType	= `RegionHandler::Any`,
		Bool	overwrite = `False`
	)		`[virtual]`

Rename a region.

If a region with the new name already exists, it is deleted or an exception is thrown (depending on overwrite). The region name is looked up in the given group(s).
An exception is thrown if the old region name does not exist.

template<class T>

virtual void casa::ImageInterface< T >::resize ( const TiledShape & newShape ) [pure virtual]

Function which changes the shape of the image (N.B.

the data is thrown away - the Image will be filled with nonsense afterwards)

Implemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::ImageConcat< T >, casa::SubImage< T >, casa::SubImage< Float >, casa::TempImage< T >, casa::TempImage< Float >, casa::TempImage< Complex >, casa::CurvedImage2D< T >, casa::HDF5Image< T >, casa::FITSImage, casa::ImageExpr< T >, casa::ImageExpr< Bool >, casa::RebinImage< T >, casa::ExtendImage< T >, casa::MIRIADImage, and casa::FITSQualityImage.

template<class T>

Bool casa::ImageInterface< T >::restoreImageInfo ( const RecordInterface & rec ) [protected]

Restore the image info from the record.

Reimplemented in casa::HDF5Image< T >.

template<class T>

virtual Bool casa::ImageInterface< T >::setCoordinateInfo ( const CoordinateSystem & coords ) [virtual]

Functions to set or replace the coordinate information in the Image Returns False on failure, e.g.

if the number of axes do not match.

Reimplemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, and casa::HDF5Image< T >.

template<class T>

* void casa::ImageInterface< T >::setCoordsMember ( const CoordinateSystem & coords ) [inline, protected]

Set the coordinate system variable.

Definition at line 360 of file ImageInterface.h.

template<class T>

virtual void casa::ImageInterface< T >::setDefaultMask ( const String & regionName ) [virtual]

Set the default pixelmask to the mask with the given name (which has to exist in the "masks" group).

If the image table is writable, the setting is persistent by writing the name as a keyword. If the given regionName is the empty string, the default pixelmask is unset.

Reimplemented in casa::PagedImage< T >, casa::PagedImage< Float >, casa::PagedImage< Complex >, casa::HDF5Image< T >, casa::TempImage< T >, casa::TempImage< Float >, and casa::TempImage< Complex >.

template<class T>

virtual Bool casa::ImageInterface< T >::setImageInfo ( const ImageInfo & info ) [virtual]