Loading...
Searching...
No Matches
ImageInterface.h
Go to the documentation of this file.
//# ImageInterface.h: a base class for astronomical images
//# Copyright (C) 1996,1997,1998,1999,2000,2001
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef IMAGES_IMAGEINTERFACE_H
#define IMAGES_IMAGEINTERFACE_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/ArrayFwd.h>
#include <casacore/images/Regions/RegionHandler.h>
#include <casacore/images/Images/MaskSpecifier.h>
#include <casacore/images/Images/ImageInfo.h>
#include <casacore/images/Images/ImageAttrHandler.h>
#include <casacore/lattices/Lattices/MaskedLattice.h>
#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
#include <casacore/tables/LogTables/LoggerHolder.h>
#include <casacore/tables/Tables/TableRecord.h>
#include <casacore/casa/Quanta/Unit.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
template <class T> class LatticeIterInterface;
template <class T> class COWPtr;
class ImageRegion;
class IPosition;
class TiledShape;
// <summary>
// A base class for astronomical images.
// </summary>
// <use visibility=export>
// <reviewed reviewer="" date="" tests="" demos="">
// </reviewed>
// <prerequisite>
// <li> <linkto class=Lattice>Lattices</linkto>
// <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
// </prerequisite>
// <etymology>
// The ImageInterface class name is derived from its role as the cookie cutter
// Interface base class for Images.
// </etymology>
// <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.
// </synopsis>
// <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.<br>
// eg 1. (used in dImageInterface.cc)
// <srcblock>
// 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;
// }
// </srcblock>
//
// The main purpose of this class is for programming objects, the following
// example is of how one would derive from ImageInterface: <br>
// eg 2.
// <srcblock>
// 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...
// };
// </srcblock>
// </example>
// <motivation>
// The use of abstract base classes to guide inheritance seemed appropriate
// for Images to ensure that CoordinateSystems and masking get handled
// uniformly.
// </motivation>
// <todo asof="1995/04/25">
// <li> replace ImageCoordinates
// </todo>
template <class T> class ImageInterface: public MaskedLattice<T>
{
//# Make members of parent class known.
public:
using MaskedLattice<T>::shape;
public:
ImageInterface();
// Construct for a specific region handler object.
ImageInterface (const RegionHandler& regionHandler);
// Copy constructor (copy semantics).
ImageInterface (const ImageInterface& other);
virtual ~ImageInterface();
// Make a copy of the derived object (reference semantics).
// <group>
virtual MaskedLattice<T>* cloneML() const;
virtual ImageInterface<T>* cloneII() const = 0;
// </group>
// Get the image type (returns name of derived class).
virtual String imageType() const = 0;
// Function which changes the shape of the image (N.B. the data is thrown
// away - the Image will be filled with nonsense afterwards)
virtual void resize (const TiledShape& newShape) = 0;
// Function which get and set the units associated with the image
// pixels (i.e. the "brightness" unit). <src>setUnits()</src> returns
// False if it cannot set the unit for some reason (e.g. the underlying
// file is not writable).
// <group>
virtual Bool setUnits (const Unit& newUnits);
virtual const Unit& units() const
{ return unit_p; }
// </group>
// 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.
virtual String name (Bool stripPath=False) const = 0;
// 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.
// <group>
virtual Bool setCoordinateInfo (const CoordinateSystem& coords);
const CoordinateSystem& coordinates() const
{ return coords_p; }
// </group>
// Function to get a LELCoordinate object containing the coordinates.
virtual LELCoordinates lelCoordinates() const;
// Get access to the LoggerHolder.
// <group>
LoggerHolder& logger()
{ return log_p; }
const LoggerHolder& logger() const
{ return log_p; }
// </group>
// Allow messages to be logged to this ImageInterface.
// <group>
LogIO& logSink()
{ return logger().logio(); }
const LogIO& logSink() const
{ return const_cast<ImageInterface<T>*>(this)->logSink(); }
// </group>
// Add the messages from the other image logger to this one.
void appendLog (const LoggerHolder& other)
{ log_p.append (other); }
// Often we have miscellaneous information we want to attach to an image.
// This is where it goes.
// <br>
// Note that setMiscInfo REPLACES the information with the new information.
// It can fail if, e.g., the underlying table is not writable.
// <group>
const TableRecord& miscInfo() const
{ return miscInfo_p; }
virtual Bool setMiscInfo (const RecordInterface& newInfo);
// </group>
// 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.
// <group>
const ImageInfo& imageInfo() const
{ return imageInfo_p; }
// Get non-const access to the ImageInfo.
ImageInfo& rwImageInfo()
{ return imageInfo_p; }
virtual Bool setImageInfo (const ImageInfo& info);
// </group>
// Get access to the attribute handler.
// By default an empty handler is returned where no groups can be added to.
// <group>
virtual ImageAttrHandler& attrHandler (Bool createHandler=False);
ImageAttrHandler& roAttrHandler() const
{ return const_cast<ImageInterface<T>*>(this)->attrHandler(False); }
// </group>
// Can the image handle region definition?
Bool canDefineRegion() const
{ return regHandPtr_p->canDefineRegion(); }
// 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).
// <br>Optionally the mask can be defined as an image region/mask
// and turned in the default mask for the image. By default it will.
virtual ImageRegion makeMask (const String& name,
Bool defineAsRegion = True,
Bool setAsDefaultMask = True,
Bool initialize = False,
Bool value = True);
// 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.
// <br>An exception is thrown if canDefineRegion is False.
virtual void defineRegion (const String& name, const ImageRegion& region,
RegionHandler::GroupType,
Bool overwrite = False);
// Does the image have a region with the given name?
virtual Bool hasRegion (const String& regionName,
RegionHandler::GroupType = RegionHandler::Any) const;
// Get a region/mask belonging to the image from the given group
// (which can be Any).
// <br>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 <src>ImageRegion</src> object created.
virtual ImageRegion* getImageRegionPtr
(const String& name,
RegionHandler::GroupType = RegionHandler::Any,
Bool throwIfUnknown = True) const;
// Rename a region.
// If a region with the new name already exists, it is deleted or
// an exception is thrown (depending on <src>overwrite</src>).
// The region name is looked up in the given group(s).
// <br>An exception is thrown if the old region name does not exist.
virtual void renameRegion (const String& newName,
const String& oldName,
RegionHandler::GroupType = RegionHandler::Any,
Bool overwrite = False);
// Remove a region/mask belonging to the image from the given group
// (which can be Any).
// <br>Optionally an exception is thrown if the region does not exist.
virtual void removeRegion (const String& name,
RegionHandler::GroupType = RegionHandler::Any,
Bool throwIfUnknown = True);
// Get the names of all regions/masks.
virtual Vector<String> regionNames
(RegionHandler::GroupType = RegionHandler::Any) const;
// Use the mask as specified.
// If a mask was already in use, it is replaced by the new one.
virtual void useMask (MaskSpecifier = MaskSpecifier());
// 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.
virtual void setDefaultMask (const String& regionName);
// Get the name of the default pixelmask.
// An empty string is returned if no default pixelmask.
virtual String getDefaultMask() const;
// Get a region belonging to the image.
// An exception is thrown if the region does not exist.
ImageRegion getRegion (const String& regionName,
RegionHandler::GroupType = RegionHandler::Any) 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.
String makeUniqueRegionName (const String& rootName,
uInt startNumber = 1) const;
// Check class invariants.
virtual Bool ok() const = 0;
// Save and restore an ImageInterface object to or from a state Record
Bool toRecord (String& error, RecordInterface& outRec);
Bool fromRecord (String& error, const RecordInterface& inRec);
protected:
// Assignment (copy semantics) is only useful for derived classes.
ImageInterface& operator= (const ImageInterface& other);
// Restore the image info from the record.
Bool restoreImageInfo (const RecordInterface& rec);
// Set the image logger variable.
void setLogMember (const LoggerHolder& logger)
{ log_p = logger; }
// Set the image info variable.
void setImageInfoMember (const ImageInfo& imageInfo);
// Set the coordinate system variable.
void setCoordsMember (const CoordinateSystem& coords)
{ coords_p = coords; }
// Set the unit variable.
void setUnitMember (const Unit& unit)
{ unit_p = unit; }
// Set the miscinfo variable.
void setMiscInfoMember (const RecordInterface& rec)
{ miscInfo_p.assign (rec); }
// Get access to the region handler.
RegionHandler* getRegionHandler()
{ return regHandPtr_p; }
private:
// It is the job of the derived class to make these variables valid.
CoordinateSystem coords_p;
LoggerHolder log_p;
ImageInfo imageInfo_p;
Unit unit_p;
TableRecord miscInfo_p;
// The region handling object.
RegionHandler* regHandPtr_p;
// The attribute handling object.
ImageAttrHandler itsBaseAttrHandler;
};
//# Declare extern templates for often used types.
extern template class ImageInterface<Float>;
extern template class ImageInterface<Complex>;
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/images/Images/ImageInterface.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::COWPtr
Definition COWPtr.h:183
casacore::CoordinateSystem
Definition CoordinateSystem.h:215
casacore::IPosition
Definition IPosition.h:117
casacore::ImageAttrHandler
Definition ImageAttrHandler.h:90
casacore::ImageInfo
Definition ImageInfo.h:90
casacore::ImageInterface
Definition ImageInterface.h:145
casacore::ImageInterface::removeRegion
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).
casacore::ImageInterface::logger
const LoggerHolder & logger() const
Definition ImageInterface.h:204
casacore::ImageInterface::logSink
LogIO & logSink()
Allow messages to be logged to this ImageInterface.
Definition ImageInterface.h:210
casacore::ImageInterface::appendLog
void appendLog(const LoggerHolder &other)
Add the messages from the other image logger to this one.
Definition ImageInterface.h:217
casacore::ImageInterface::miscInfo_p
TableRecord miscInfo_p
Definition ImageInterface.h:386
casacore::ImageInterface::setCoordsMember
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
Definition ImageInterface.h:365
casacore::ImageInterface::logger
LoggerHolder & logger()
Get access to the LoggerHolder.
Definition ImageInterface.h:202
casacore::ImageInterface::attrHandler
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
casacore::ImageInterface::unit_p
Unit unit_p
Definition ImageInterface.h:385
casacore::ImageInterface::setUnits
virtual Bool setUnits(const Unit &newUnits)
Function which get and set the units associated with the image pixels (i.e.
casacore::ImageInterface::~ImageInterface
virtual ~ImageInterface()
casacore::ImageInterface::rwImageInfo
ImageInfo & rwImageInfo()
Get non-const access to the ImageInfo.
Definition ImageInterface.h:241
casacore::ImageInterface::ImageInterface
ImageInterface(const RegionHandler &regionHandler)
Construct for a specific region handler object.
casacore::ImageInterface::setLogMember
void setLogMember(const LoggerHolder &logger)
Set the image logger variable.
Definition ImageInterface.h:358
casacore::ImageInterface::resize
virtual void resize(const TiledShape &newShape)=0
Function which changes the shape of the image (N.B.
casacore::ImageInterface::defineRegion
virtual void defineRegion(const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
Define a region/mask belonging to the image.
casacore::ImageInterface::cloneII
virtual ImageInterface< T > * cloneII() const =0
casacore::ImageInterface::setImageInfo
virtual Bool setImageInfo(const ImageInfo &info)
casacore::ImageInterface::logSink
const LogIO & logSink() const
Definition ImageInterface.h:212
casacore::ImageInterface::units
virtual const Unit & units() const
Definition ImageInterface.h:180
casacore::ImageInterface::imageType
virtual String imageType() const =0
Get the image type (returns name of derived class).
casacore::ImageInterface::makeMask
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.
casacore::ImageInterface::canDefineRegion
Bool canDefineRegion() const
Can the image handle region definition?
Definition ImageInterface.h:255
casacore::ImageInterface::imageInfo
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
Definition ImageInterface.h:238
casacore::ImageInterface::cloneML
virtual MaskedLattice< T > * cloneML() const
Make a copy of the derived object (reference semantics).
casacore::ImageInterface::roAttrHandler
ImageAttrHandler & roAttrHandler() const
Definition ImageInterface.h:250
casacore::ImageInterface::itsBaseAttrHandler
ImageAttrHandler itsBaseAttrHandler
The attribute handling object.
Definition ImageInterface.h:392
casacore::ImageInterface::name
virtual String name(Bool stripPath=False) const =0
Return the name of the current ImageInterface object.
casacore::ImageInterface::getRegionHandler
RegionHandler * getRegionHandler()
Get access to the region handler.
Definition ImageInterface.h:377
casacore::ImageInterface::getDefaultMask
virtual String getDefaultMask() const
Get the name of the default pixelmask.
casacore::ImageInterface::getRegion
ImageRegion getRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Get a region belonging to the image.
casacore::ImageInterface::getImageRegionPtr
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).
casacore::ImageInterface::ImageInterface
ImageInterface()
casacore::ImageInterface::regHandPtr_p
RegionHandler * regHandPtr_p
The region handling object.
Definition ImageInterface.h:389
casacore::ImageInterface::imageInfo_p
ImageInfo imageInfo_p
Definition ImageInterface.h:384
casacore::ImageInterface::setImageInfoMember
void setImageInfoMember(const ImageInfo &imageInfo)
Set the image info variable.
casacore::ImageInterface::useMask
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
casacore::ImageInterface::ok
virtual Bool ok() const =0
Check class invariants.
casacore::ImageInterface::log_p
LoggerHolder log_p
Definition ImageInterface.h:383
casacore::ImageInterface::operator=
ImageInterface & operator=(const ImageInterface &other)
Assignment (copy semantics) is only useful for derived classes.
casacore::ImageInterface::setMiscInfo
virtual Bool setMiscInfo(const RecordInterface &newInfo)
casacore::ImageInterface::hasRegion
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
casacore::ImageInterface::lelCoordinates
virtual LELCoordinates lelCoordinates() const
Function to get a LELCoordinate object containing the coordinates.
casacore::ImageInterface::setCoordinateInfo
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Functions to set or replace the coordinate information in the Image Returns False on failure,...
casacore::ImageInterface::setMiscInfoMember
void setMiscInfoMember(const RecordInterface &rec)
Set the miscinfo variable.
Definition ImageInterface.h:373
casacore::ImageInterface::ImageInterface
ImageInterface(const ImageInterface &other)
Copy constructor (copy semantics).
casacore::ImageInterface::coordinates
const CoordinateSystem & coordinates() const
Definition ImageInterface.h:193
casacore::ImageInterface::fromRecord
Bool fromRecord(String &error, const RecordInterface &inRec)
casacore::ImageInterface::makeUniqueRegionName
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...
casacore::ImageInterface::setDefaultMask
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).
casacore::ImageInterface::renameRegion
virtual void renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=RegionHandler::Any, Bool overwrite=False)
Rename a region.
casacore::ImageInterface::miscInfo
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
Definition ImageInterface.h:226
casacore::ImageInterface::regionNames
virtual Vector< String > regionNames(RegionHandler::GroupType=RegionHandler::Any) const
Get the names of all regions/masks.
casacore::ImageInterface::toRecord
Bool toRecord(String &error, RecordInterface &outRec)
Save and restore an ImageInterface object to or from a state Record.
casacore::ImageInterface::restoreImageInfo
Bool restoreImageInfo(const RecordInterface &rec)
Restore the image info from the record.
casacore::ImageInterface::setUnitMember
void setUnitMember(const Unit &unit)
Set the unit variable.
Definition ImageInterface.h:369
casacore::ImageInterface::coords_p
CoordinateSystem coords_p
It is the job of the derived class to make these variables valid.
Definition ImageInterface.h:382
casacore::ImageRegion
Definition ImageRegion.h:85
casacore::LELCoordinates
Definition LELCoordinates.h:122
casacore::LatticeIterInterface
Definition LatticeIterInterface.h:112
casacore::LogIO
Definition LogIO.h:165
casacore::LoggerHolder
Definition LoggerHolder.h:118
casacore::LoggerHolder::logio
LogIO & logio()
Get access to the logger.
Definition LoggerHolder.h:550
casacore::MaskSpecifier
Definition MaskSpecifier.h:68
casacore::MaskedLattice::MaskedLattice
MaskedLattice()
Default constructor.
Definition MaskedLattice.h:224
casacore::MaskedLattice::region
const LatticeRegion & region() const
Get the region used.
casacore::RegionHandler
Definition RegionHandler.h:92
casacore::RegionHandler::GroupType
GroupType
Define the possible group types (regions or masks).
Definition RegionHandler.h:97
casacore::RegionHandler::Any
@ Any
Definition RegionHandler.h:100
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::TableRecord
Definition TableRecord.h:183
casacore::TiledShape
Definition TiledShape.h:95
casacore::Unit
Definition Unit.h:187
casacore::Vector
Definition Vector.h:82
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::False
const Bool False
Definition aipstype.h:42
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::shape
IPosition shape(const RecordFieldId &) const
Get the actual shape of this field.
casacore::RecordInterface
RecordInterface()
The default constructor creates an empty record with a variable structure.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::True
const Bool True
Definition aipstype.h:41
casacore::value
NewDelAllocator< T > NewDelAllocator< T >::value
Definition Allocator.h:369