casacore
ImageInterface.h
Go to the documentation of this file.
1 //# ImageInterface.h: a base class for astronomical images
2 //# Copyright (C) 1996,1997,1998,1999,2000,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef IMAGES_IMAGEINTERFACE_H
29 #define IMAGES_IMAGEINTERFACE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/images/Regions/RegionHandler.h>
35 #include <casacore/images/Images/MaskSpecifier.h>
36 #include <casacore/images/Images/ImageInfo.h>
37 #include <casacore/images/Images/ImageAttrHandler.h>
38 #include <casacore/lattices/Lattices/MaskedLattice.h>
39 #include <casacore/coordinates/Coordinates/CoordinateSystem.h>
40 #include <casacore/tables/LogTables/LoggerHolder.h>
41 #include <casacore/tables/Tables/TableRecord.h>
42 #include <casacore/casa/Quanta/Unit.h>
43 
44 namespace casacore { //# NAMESPACE CASACORE - BEGIN
45 
46 //# Forward Declarations
47 template <class T> class LatticeIterInterface;
48 template <class T> class Vector;
49 template <class T> class COWPtr;
50 class ImageRegion;
51 class IPosition;
52 class TiledShape;
53 
54 
55 // <summary>
56 // A base class for astronomical images.
57 // </summary>
58 
59 // <use visibility=export>
60 
61 // <reviewed reviewer="" date="" tests="" demos="">
62 // </reviewed>
63 
64 // <prerequisite>
65 // <li> <linkto class=Lattice>Lattices</linkto>
66 // <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
67 // </prerequisite>
68 
69 // <etymology>
70 // The ImageInterface class name is derived from its role as the cookie cutter
71 // Interface base class for Images.
72 // </etymology>
73 
74 // <synopsis>
75 // The ImageInterface class is an abstract base class. All Image classes
76 // should derive from this class to ensure functions which operate on Images
77 // will work for all Image derivations.
78 //
79 // An Image is currently defined as an Array of pixels, a Boolean mask,
80 // defining which pixels are valid and coordinates to define the reference
81 // frame. The only concrete class currently derived from this Interface is
82 // PagedImage, which allows the image to be stored on disk, and only reads
83 // specified portions of the image into memory.
84 // </synopsis>
85 
86 // <example>
87 // As this is an abstract base class it is not possible to construct an
88 // instance of this object. It can however be used as a function argument.<br>
89 // eg 1. (used in dImageInterface.cc)
90 // <srcblock>
91 // Float sumPixels(const ImageInterface<Float>& image){
92 // uInt rowLength = image.shape()(0);
93 // IPosition rowShape(image.ndim());
94 // rowShape = 1; rowShape(0) = rowLength;
95 // Float sumPix = 0;
96 // RO_LatticeIterator<Float> iter(image, rowShape);
97 // while(!iter.atEnd()){
98 // sumPix += sum(iter.vectorCursor());
99 // iter++;
100 // }
101 // return sumPix;
102 // }
103 // </srcblock>
104 //
105 // The main purpose of this class is for programming objects, the following
106 // example is of how one would derive from ImageInterface: <br>
107 // eg 2.
108 // <srcblock>
109 // template <class T> class myNewImage : public ImageInterface<T>
110 // {
111 // public:
112 // // default constructor
113 // myNewImage();
114 //
115 // // argumented constructor
116 // myNewImage(...);
117 //
118 // // destructor
119 // ~myNewImage
120 //
121 // // the shape function is forced upon us by the Lattice base class
122 // IPosition shape() const;
123 //
124 // // doGetSlice is another function required of all Lattice objects.
125 // Bool doGetSlice(<Array<T>& buffer, const Slicer& section);
126 //
127 // // etc...
128 // private:
129 // // put the actual map data down here.
130 // // etc...
131 // };
132 // </srcblock>
133 // </example>
134 
135 // <motivation>
136 // The use of abstract base classes to guide inheritance seemed appropriate
137 // for Images to ensure that CoordinateSystems and masking get handled
138 // uniformly.
139 // </motivation>
140 
141 // <todo asof="1995/04/25">
142 // <li> replace ImageCoordinates
143 // </todo>
144 
145 
146 template <class T> class ImageInterface: public MaskedLattice<T>
147 {
148  //# Make members of parent class known.
149 public:
151 
152 public:
154 
155  // Construct for a specific region handler object.
156  ImageInterface (const RegionHandler& regionHandler);
157 
158  // Copy constructor (copy semantics).
160 
161  virtual ~ImageInterface();
162 
163  // Make a copy of the derived object (reference semantics).
164  // <group>
165  virtual MaskedLattice<T>* cloneML() const;
166  virtual ImageInterface<T>* cloneII() const = 0;
167  // </group>
168 
169  // Get the image type (returns name of derived class).
170  virtual String imageType() const = 0;
171 
172  // Function which changes the shape of the image (N.B. the data is thrown
173  // away - the Image will be filled with nonsense afterwards)
174  virtual void resize (const TiledShape& newShape) = 0;
175 
176  // Function which get and set the units associated with the image
177  // pixels (i.e. the "brightness" unit). <src>setUnits()</src> returns
178  // False if it cannot set the unit for some reason (e.g. the underlying
179  // file is not writable).
180  // <group>
181  virtual Bool setUnits (const Unit& newUnits);
182  virtual const Unit& units() const
183  { return unit_p; }
184  // </group>
185 
186  // Return the name of the current ImageInterface object. This will generally
187  // be a file name for images that have a persistent form. Any path
188  // before the actual file name can be optionally stripped off.
189  virtual String name (Bool stripPath=False) const = 0;
190 
191  // Functions to set or replace the coordinate information in the Image
192  // Returns False on failure, e.g. if the number of axes do not match.
193  // <group>
194  virtual Bool setCoordinateInfo (const CoordinateSystem& coords);
196  { return coords_p; }
197  // </group>
198 
199  // Function to get a LELCoordinate object containing the coordinates.
201 
202  // Get access to the LoggerHolder.
203  // <group>
205  { return log_p; }
206  const LoggerHolder& logger() const
207  { return log_p; }
208  // </group>
209 
210  // Allow messages to be logged to this ImageInterface.
211  // <group>
213  { return logger().logio(); }
214  const LogIO& logSink() const
215  { return const_cast<ImageInterface<T>*>(this)->logSink(); }
216  // </group>
217 
218  // Add the messages from the other image logger to this one.
219  void appendLog (const LoggerHolder& other)
220  { log_p.append (other); }
221 
222  // Often we have miscellaneous information we want to attach to an image.
223  // This is where it goes.
224  // <br>
225  // Note that setMiscInfo REPLACES the information with the new information.
226  // It can fail if, e.g., the underlying table is not writable.
227  // <group>
228  const TableRecord& miscInfo() const
229  { return miscInfo_p; }
230  virtual Bool setMiscInfo (const RecordInterface& newInfo);
231  // </group>
232 
233  // The ImageInfo object contains some miscellaneous information about the image
234  // which unlike that stored in MiscInfo, has a standard list of things,
235  // such as the restoring beam.
236  //
237  // Note that setImageInfo REPLACES the information with the new information.
238  // It is up to the derived class to make the ImageInfo permanent.
239  // <group>
240  const ImageInfo& imageInfo() const
241  { return imageInfo_p; }
242  // Get non-const access to the ImageInfo.
244  { return imageInfo_p; }
245  virtual Bool setImageInfo (const ImageInfo& info);
246  // </group>
247 
248  // Get access to the attribute handler.
249  // By default an empty handler is returned where no groups can be added to.
250  // <group>
251  virtual ImageAttrHandler& attrHandler (Bool createHandler=False);
253  { return const_cast<ImageInterface<T>*>(this)->attrHandler(False); }
254  // </group>
255 
256  // Can the image handle region definition?
258  { return regHandPtr_p->canDefineRegion(); }
259 
260  // Make a mask which is suitable for the type of image.
261  // Optionally the mask can be initialized with the given value
262  // (by default it will not).
263  // <br>Optionally the mask can be defined as an image region/mask
264  // and turned in the default mask for the image. By default it will.
265  virtual ImageRegion makeMask (const String& name,
266  Bool defineAsRegion = True,
267  Bool setAsDefaultMask = True,
268  Bool initialize = False,
269  Bool value = True);
270 
271  // Define a region/mask belonging to the image.
272  // The group type determines if it stored as a region or mask.
273  // If overwrite=False, an exception will be thrown if the region
274  // already exists.
275  // <br>An exception is thrown if canDefineRegion is False.
276  virtual void defineRegion (const String& name, const ImageRegion& region,
278  Bool overwrite = False);
279 
280  // Does the image have a region with the given name?
281  virtual Bool hasRegion (const String& regionName,
283 
284  // Get a region/mask belonging to the image from the given group
285  // (which can be Any).
286  // <br>Optionally an exception is thrown if the region does not exist.
287  // A zero pointer is returned if the region does not exist.
288  // The caller has to delete the <src>ImageRegion</src> object created.
290  (const String& name,
292  Bool throwIfUnknown = True) const;
293 
294  // Rename a region.
295  // If a region with the new name already exists, it is deleted or
296  // an exception is thrown (depending on <src>overwrite</src>).
297  // The region name is looked up in the given group(s).
298  // <br>An exception is thrown if the old region name does not exist.
299  virtual void renameRegion (const String& newName,
300  const String& oldName,
302  Bool overwrite = False);
303 
304  // Remove a region/mask belonging to the image from the given group
305  // (which can be Any).
306  // <br>Optionally an exception is thrown if the region does not exist.
307  virtual void removeRegion (const String& name,
309  Bool throwIfUnknown = True);
310 
311  // Get the names of all regions/masks.
314 
315  // Use the mask as specified.
316  // If a mask was already in use, it is replaced by the new one.
317  virtual void useMask (MaskSpecifier = MaskSpecifier());
318 
319  // Set the default pixelmask to the mask with the given name
320  // (which has to exist in the "masks" group).
321  // If the image table is writable, the setting is persistent by writing
322  // the name as a keyword.
323  // If the given regionName is the empty string,
324  // the default pixelmask is unset.
325  virtual void setDefaultMask (const String& regionName);
326 
327  // Get the name of the default pixelmask.
328  // An empty string is returned if no default pixelmask.
329  virtual String getDefaultMask() const;
330 
331  // Get a region belonging to the image.
332  // An exception is thrown if the region does not exist.
333  ImageRegion getRegion (const String& regionName,
335 
336  // Make a unique region name from the given root name, thus make it such
337  // that the name is not already in use for a region or mask.
338  // The root name is returned if it is already unique.
339  // Otherwise a number is appended to the root name to make it unique.
340  // The number starts at the given number and is incremented until the name
341  // is unique.
343  uInt startNumber = 1) const;
344 
345  // Check class invariants.
346  virtual Bool ok() const = 0;
347 
348  // Save and restore an ImageInterface object to or from a state Record
349  Bool toRecord (String& error, RecordInterface& outRec);
350  Bool fromRecord (String& error, const RecordInterface& inRec);
351 
352 protected:
353  // Assignment (copy semantics) is only useful for derived classes.
355 
356  // Restore the image info from the record.
358 
359  // Set the image logger variable.
361  { log_p = logger; }
362 
363  // Set the image info variable.
365 
366  // Set the coordinate system variable.
367  void setCoordsMember (const CoordinateSystem& coords)
368  { coords_p = coords; }
369 
370  // Set the unit variable.
371  void setUnitMember (const Unit& unit)
372  { unit_p = unit; }
373 
374  // Set the miscinfo variable.
376  { miscInfo_p.assign (rec); }
377 
378  // Get access to the region handler.
380  { return regHandPtr_p; }
381 
382 private:
383  // It is the job of the derived class to make these variables valid.
389 
390  // The region handling object.
392 
393  // The attribute handling object.
395 };
396 
397 
398 //# Declare extern templates for often used types.
399  extern template class ImageInterface<Float>;
400  extern template class ImageInterface<Complex>;
401 
402 
403 } //# NAMESPACE CASACORE - END
404 
405 #ifndef CASACORE_NO_AUTO_TEMPLATES
406 #include <casacore/images/Images/ImageInterface.tcc>
407 #endif //# CASACORE_NO_AUTO_TEMPLATES
408 #endif
casacore::CoordinateSystem
Interconvert pixel and world coordinates.
Definition: CoordinateSystem.h:218
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
A base class for astronomical images.
Definition: ImageFITSConverter.h:48
casacore::ImageInterface::canDefineRegion
Bool canDefineRegion() const
Can the image handle region definition?
Definition: ImageInterface.h:257
casacore::ImageInterface::ok
virtual Bool ok() const =0
Check class invariants.
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::fromRecord
Bool fromRecord(String &error, const RecordInterface &inRec)
casacore::ImageInterface::setUnitMember
void setUnitMember(const Unit &unit)
Set the unit variable.
Definition: ImageInterface.h:371
casacore::RegionHandler::GroupType
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
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::ImageInterface
ImageInterface()
casacore::ImageInterface::roAttrHandler
ImageAttrHandler & roAttrHandler() const
Definition: ImageInterface.h:252
casacore::RegionHandler::Any
@ Any
Definition: RegionHandler.h:102
casacore::ImageInterface::miscInfo
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
Definition: ImageInterface.h:228
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::hasRegion
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
casacore::MaskedLattice
A templated, abstract base class for array-like objects with masks.
Definition: ImageConcat.h:46
casacore::ImageInterface::name
virtual String name(Bool stripPath=False) const =0
Return the name of the current ImageInterface object.
casacore::ImageInterface::setMiscInfoMember
void setMiscInfoMember(const RecordInterface &rec)
Set the miscinfo variable.
Definition: ImageInterface.h:375
casacore::TableRecord
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:183
casacore::RegionHandler::canDefineRegion
virtual Bool canDefineRegion() const
Can the class indeed define and handle regions? The default implementation returns False.
casacore::ImageInterface::useMask
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
casacore::ImageInterface::resize
virtual void resize(const TiledShape &newShape)=0
Function which changes the shape of the image (N.B.
casacore::ImageInterface::ImageInterface
ImageInterface(const RegionHandler &regionHandler)
Construct for a specific region handler object.
casacore::ImageInterface::ImageInterface
ImageInterface(const ImageInterface &other)
Copy constructor (copy semantics).
casacore::ImageInterface::appendLog
void appendLog(const LoggerHolder &other)
Add the messages from the other image logger to this one.
Definition: ImageInterface.h:219
casacore::ImageInterface::regionNames
virtual Vector< String > regionNames(RegionHandler::GroupType=RegionHandler::Any) const
Get the names of all regions/masks.
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::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::logger
const LoggerHolder & logger() const
Definition: ImageInterface.h:206
casacore::ImageInterface::log_p
LoggerHolder log_p
Definition: ImageInterface.h:385
casacore::LogIO
ostream-like interface to creating log messages.
Definition: LogIO.h:168
casacore::ImageInterface::imageInfo_p
ImageInfo imageInfo_p
Definition: ImageInterface.h:386
casacore::LoggerHolder::append
void append(const LoggerHolder &other)
Append the entries of the other logger to this one.
casacore::ImageInterface::logSink
LogIO & logSink()
Allow messages to be logged to this ImageInterface.
Definition: ImageInterface.h:212
casacore::LoggerHolder::logio
LogIO & logio()
Get access to the logger.
Definition: LoggerHolder.h:554
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::ImageInterface::regHandPtr_p
RegionHandler * regHandPtr_p
The region handling object.
Definition: ImageInterface.h:391
casacore::ImageInterface::~ImageInterface
virtual ~ImageInterface()
casacore::ImageInterface::logger
LoggerHolder & logger()
Get access to the LoggerHolder.
Definition: ImageInterface.h:204
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::ImageInterface::setImageInfoMember
void setImageInfoMember(const ImageInfo &imageInfo)
Set the image info variable.
casacore::ImageInterface::miscInfo_p
TableRecord miscInfo_p
Definition: ImageInterface.h:388
casacore::shape
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1944
casacore::ImageInterface::lelCoordinates
virtual LELCoordinates lelCoordinates() const
Function to get a LELCoordinate object containing the coordinates.
casacore::ImageInterface::attrHandler
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
casacore::MaskSpecifier
Class to specify which mask to use in an image.
Definition: MaskSpecifier.h:70
casacore::TableRecord::assign
virtual void assign(const RecordInterface &that)
Assign that RecordInterface object to this one.
casacore::ImageInterface::setCoordsMember
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
Definition: ImageInterface.h:367
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::ImageInterface::setImageInfo
virtual Bool setImageInfo(const ImageInfo &info)
casacore::ImageInterface::operator=
ImageInterface & operator=(const ImageInterface &other)
Assignment (copy semantics) is only useful for derived classes.
casacore::LELCoordinates
Envelope class to handle Lattice Coordinates in LEL.
Definition: LELCoordinates.h:124
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::ImageInterface::itsBaseAttrHandler
ImageAttrHandler itsBaseAttrHandler
The attribute handling object.
Definition: ImageInterface.h:394
casacore::ImageInterface::coords_p
CoordinateSystem coords_p
It is the job of the derived class to make these variables valid.
Definition: ImageInterface.h:384
casacore::ImageInterface::coordinates
const CoordinateSystem & coordinates() const
Definition: ImageInterface.h:195
casacore::ImageInterface::units
virtual const Unit & units() const
Definition: ImageInterface.h:182
casacore::RecordInterface
Abstract base class for Record classes.
Definition: RecordInterface.h:145
casacore::ImageInterface::rwImageInfo
ImageInfo & rwImageInfo()
Get non-const access to the ImageInfo.
Definition: ImageInterface.h:243
casacore::ImageInterface::imageInfo
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
Definition: ImageInterface.h:240
casacore::ImageInterface::unit_p
Unit unit_p
Definition: ImageInterface.h:387
casacore::ImageInterface::getDefaultMask
virtual String getDefaultMask() const
Get the name of the default pixelmask.
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::cloneII
virtual ImageInterface< T > * cloneII() const =0
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::RegionHandler
Base class for handling regions in images.
Definition: RegionHandler.h:94
casacore::ImageInterface::renameRegion
virtual void renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=RegionHandler::Any, Bool overwrite=False)
Rename a region.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::LoggerHolder
Class holding a hierarchy of loggers.
Definition: LoggerHolder.h:121
casacore::ImageRegion
Class to hold a region of interest in an image.
Definition: ImageRegion.h:87
casacore::ImageInterface::setLogMember
void setLogMember(const LoggerHolder &logger)
Set the image logger variable.
Definition: ImageInterface.h:360
casacore::ImageInterface::cloneML
virtual MaskedLattice< T > * cloneML() const
Make a copy of the derived object (reference semantics).
casacore::ImageInterface::getRegionHandler
RegionHandler * getRegionHandler()
Get access to the region handler.
Definition: ImageInterface.h:379
casacore::ImageAttrHandler
Abstract base class for an image attributes handler.
Definition: ImageAttrHandler.h:92
casacore::Unit
defines physical units
Definition: Unit.h:189
casacore::ImageInterface::restoreImageInfo
Bool restoreImageInfo(const RecordInterface &rec)
Restore the image info from the record.
casacore::Vector
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
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::TiledShape
Define the shape and tile shape.
Definition: TiledShape.h:100
casacore::ImageInterface::setMiscInfo
virtual Bool setMiscInfo(const RecordInterface &newInfo)
casacore::ImageInfo
Miscellaneous information related to an image.
Definition: ImageInfo.h:93
casacore::ImageInterface::logSink
const LogIO & logSink() const
Definition: ImageInterface.h:214
casacore::ImageInterface::toRecord
Bool toRecord(String &error, RecordInterface &outRec)
Save and restore an ImageInterface object to or from a state Record.
casacore::ImageInterface::imageType
virtual String imageType() const =0
Get the image type (returns name of derived class).
casacore::ImageInterface::getRegion
ImageRegion getRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Get a region belonging to the image.