casacore
Loading...
Searching...
No Matches
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.
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?
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.
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.
const LatticeRegion & region() const
Get the region used.
GroupType
Define the possible group types (regions or masks).
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