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/casa/Arrays/ArrayFwd.h>
35#include <casacore/images/Regions/RegionHandler.h>
36#include <casacore/images/Images/MaskSpecifier.h>
37#include <casacore/images/Images/ImageInfo.h>
38#include <casacore/images/Images/ImageAttrHandler.h>
39#include <casacore/lattices/Lattices/MaskedLattice.h>
40#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
41#include <casacore/tables/LogTables/LoggerHolder.h>
42#include <casacore/tables/Tables/TableRecord.h>
43#include <casacore/casa/Quanta/Unit.h>
44
45namespace casacore { //# NAMESPACE CASACORE - BEGIN
46
47//# Forward Declarations
48template <class T> class LatticeIterInterface;
49template <class T> class COWPtr;
50class ImageRegion;
51class IPosition;
52class 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
146template <class T> class ImageInterface: public MaskedLattice<T>
147{
148 //# Make members of parent class known.
149public:
150 using MaskedLattice<T>::shape;
151
152public:
154
155 // Construct for a specific region handler object.
156 ImageInterface (const RegionHandler& regionHandler);
157
158 // Copy constructor (copy semantics).
160
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.
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.
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
350 Bool fromRecord (String& error, const RecordInterface& inRec);
351
352protected:
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.
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
382private:
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
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).
const LoggerHolder & logger() const
LogIO & logSink()
Allow messages to be logged to this ImageInterface.
void appendLog(const LoggerHolder &other)
Add the messages from the other image logger to this one.
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
LoggerHolder & logger()
Get access to the LoggerHolder.
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
virtual Bool setUnits(const Unit &newUnits)
Function which get and set the units associated with the image pixels (i.e.
ImageInfo & rwImageInfo()
Get non-const access to the ImageInfo.
ImageInterface(const RegionHandler &regionHandler)
Construct for a specific region handler object.
void setLogMember(const LoggerHolder &logger)
Set the image logger variable.
virtual void resize(const TiledShape &newShape)=0
Function which changes the shape of the image (N.B.
virtual void defineRegion(const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
Define a region/mask belonging to the image.
virtual ImageInterface< T > * cloneII() const =0
virtual Bool setImageInfo(const ImageInfo &info)
const LogIO & logSink() const
virtual const Unit & units() const
virtual String imageType() const =0
Get the image type (returns name of derived class).
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.
Bool canDefineRegion() const
Can the image handle region definition?
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
virtual MaskedLattice< T > * cloneML() const
Make a copy of the derived object (reference semantics).
ImageAttrHandler & roAttrHandler() const
ImageAttrHandler itsBaseAttrHandler
The attribute handling object.
virtual String name(Bool stripPath=False) const =0
Return the name of the current ImageInterface object.
RegionHandler * getRegionHandler()
Get access to the region handler.
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.
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).
RegionHandler * regHandPtr_p
The region handling object.
void setImageInfoMember(const ImageInfo &imageInfo)
Set the image info variable.
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
virtual Bool ok() const =0
Check class invariants.
ImageInterface & operator=(const ImageInterface &other)
Assignment (copy semantics) is only useful for derived classes.
virtual Bool setMiscInfo(const RecordInterface &newInfo)
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
virtual LELCoordinates lelCoordinates() const
Function to get a LELCoordinate object containing the coordinates.
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Functions to set or replace the coordinate information in the Image Returns False on failure,...
void setMiscInfoMember(const RecordInterface &rec)
Set the miscinfo variable.
ImageInterface(const ImageInterface &other)
Copy constructor (copy semantics).
const CoordinateSystem & coordinates() const
Bool fromRecord(String &error, const RecordInterface &inRec)
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...
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 void renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=RegionHandler::Any, Bool overwrite=False)
Rename a region.
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
virtual Vector< String > regionNames(RegionHandler::GroupType=RegionHandler::Any) const
Get the names of all regions/masks.
Bool toRecord(String &error, RecordInterface &outRec)
Save and restore an ImageInterface object to or from a state Record.
Bool restoreImageInfo(const RecordInterface &rec)
Restore the image info from the record.
void setUnitMember(const Unit &unit)
Set the unit variable.
CoordinateSystem coords_p
It is the job of the derived class to make these variables valid.
virtual IPosition shape() const =0
Return the shape of the Lattice including all degenerate axes (ie.
void append(const LoggerHolder &other)
Append the entries of the other logger to this one.
LogIO & logio()
Get access to the logger.
Definition: LoggerHolder.h:554
const LatticeRegion & region() const
Get the region used.
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
virtual Bool canDefineRegion() const
Can the class indeed define and handle regions? The default implementation returns False.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual void assign(const RecordInterface &that)
Assign that RecordInterface object to this one.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43