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:
153  ImageInterface();
154 
155  // Construct for a specific region handler object.
156  ImageInterface (const RegionHandler& regionHandler);
157 
158  // Copy constructor (copy semantics).
159  ImageInterface (const ImageInterface& other);
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.
200  virtual LELCoordinates lelCoordinates() const;
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  virtual Bool setImageInfo (const ImageInfo& info);
243  // </group>
244 
245  // Get access to the attribute handler.
246  // By default an empty handler is returned where no groups can be added to.
247  // <group>
248  virtual ImageAttrHandler& attrHandler (Bool createHandler=False);
250  { return const_cast<ImageInterface<T>*>(this)->attrHandler(False); }
251  // </group>
252 
253  // Can the image handle region definition?
255  { return regHandPtr_p->canDefineRegion(); }
256 
257  // Make a mask which is suitable for the type of image.
258  // Optionally the mask can be initialized with the given value
259  // (by default it will not).
260  // <br>Optionally the mask can be defined as an image region/mask
261  // and turned in the default mask for the image. By default it will.
262  virtual ImageRegion makeMask (const String& name,
263  Bool defineAsRegion = True,
264  Bool setAsDefaultMask = True,
265  Bool initialize = False,
266  Bool value = True);
267 
268  // Define a region/mask belonging to the image.
269  // The group type determines if it stored as a region or mask.
270  // If overwrite=False, an exception will be thrown if the region
271  // already exists.
272  // <br>An exception is thrown if canDefineRegion is False.
273  virtual void defineRegion (const String& name, const ImageRegion& region,
275  Bool overwrite = False);
276 
277  // Does the image have a region with the given name?
278  virtual Bool hasRegion (const String& regionName,
280 
281  // Get a region/mask belonging to the image from the given group
282  // (which can be Any).
283  // <br>Optionally an exception is thrown if the region does not exist.
284  // A zero pointer is returned if the region does not exist.
285  // The caller has to delete the <src>ImageRegion</src> object created.
287  (const String& name,
289  Bool throwIfUnknown = True) const;
290 
291  // Rename a region.
292  // If a region with the new name already exists, it is deleted or
293  // an exception is thrown (depending on <src>overwrite</src>).
294  // The region name is looked up in the given group(s).
295  // <br>An exception is thrown if the old region name does not exist.
296  virtual void renameRegion (const String& newName,
297  const String& oldName,
299  Bool overwrite = False);
300 
301  // Remove a region/mask belonging to the image from the given group
302  // (which can be Any).
303  // <br>Optionally an exception is thrown if the region does not exist.
304  virtual void removeRegion (const String& name,
306  Bool throwIfUnknown = True);
307 
308  // Get the names of all regions/masks.
311 
312  // Use the mask as specified.
313  // If a mask was already in use, it is replaced by the new one.
314  virtual void useMask (MaskSpecifier = MaskSpecifier());
315 
316  // Set the default pixelmask to the mask with the given name
317  // (which has to exist in the "masks" group).
318  // If the image table is writable, the setting is persistent by writing
319  // the name as a keyword.
320  // If the given regionName is the empty string,
321  // the default pixelmask is unset.
322  virtual void setDefaultMask (const String& regionName);
323 
324  // Get the name of the default pixelmask.
325  // An empty string is returned if no default pixelmask.
326  virtual String getDefaultMask() const;
327 
328  // Get a region belonging to the image.
329  // An exception is thrown if the region does not exist.
330  ImageRegion getRegion (const String& regionName,
332 
333  // Make a unique region name from the given root name, thus make it such
334  // that the name is not already in use for a region or mask.
335  // The root name is returned if it is already unique.
336  // Otherwise a number is appended to the root name to make it unique.
337  // The number starts at the given number and is incremented until the name
338  // is unique.
339  String makeUniqueRegionName (const String& rootName,
340  uInt startNumber = 1) const;
341 
342  // Check class invariants.
343  virtual Bool ok() const = 0;
344 
345  // Save and restore an ImageInterface object to or from a state Record
346  Bool toRecord (String& error, RecordInterface& outRec);
347  Bool fromRecord (String& error, const RecordInterface& inRec);
348 
349 protected:
350  // Assignment (copy semantics) is only useful for derived classes.
352 
353  // Restore the image info from the record.
355 
356  // Set the image logger variable.
358  { log_p = logger; }
359 
360  // Set the image info variable.
361  void setImageInfoMember (const ImageInfo& imageInfo);
362 
363  // Set the coordinate system variable.
364  void setCoordsMember (const CoordinateSystem& coords)
365  { coords_p = coords; }
366 
367  // Set the unit variable.
368  void setUnitMember (const Unit& unit)
369  { unit_p = unit; }
370 
371  // Set the miscinfo variable.
373  { miscInfo_p.assign (rec); }
374 
375  // Get access to the region handler.
377  { return regHandPtr_p; }
378 
379  // Get non-const access to the ImageInfo.
381  { return imageInfo_p; }
382 
383 private:
384  // It is the job of the derived class to make these variables valid.
390 
391  // The region handling object.
393 
394  // The attribute handling object.
396 };
397 
398 
399 
400 } //# NAMESPACE CASACORE - END
401 
402 #ifndef CASACORE_NO_AUTO_TEMPLATES
403 #include <casacore/images/Images/ImageInterface.tcc>
404 #endif //# CASACORE_NO_AUTO_TEMPLATES
405 #endif
virtual Bool setUnits(const Unit &newUnits)
Function which get and set the units associated with the image pixels (i.e.
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
void append(const LoggerHolder &other)
Append the entries of the other logger to this one.
RegionHandler * getRegionHandler()
Get access to the region handler.
virtual const Unit & units() const
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
Bool toRecord(String &error, RecordInterface &outRec)
Save and restore an ImageInterface object to or from a state Record.
ImageInterface & operator=(const ImageInterface &other)
Assignment (copy semantics) is only useful for derived classes.
Envelope class to handle Lattice Coordinates in LEL.
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...
void appendLog(const LoggerHolder &other)
Add the messages from the other image logger to this one.
LoggerHolder & logger()
Get access to the LoggerHolder.
Bool restoreImageInfo(const RecordInterface &rec)
Restore the image info from the record.
ImageAttrHandler itsBaseAttrHandler
The attribute handling object.
ostream-like interface to creating log messages.
Definition: LogIO.h:167
virtual MaskedLattice< T > * cloneML() const
Make a copy of the derived object (reference semantics).
virtual Vector< String > regionNames(RegionHandler::GroupType=RegionHandler::Any) const
Get the names of all regions/masks.
Base class for handling regions in images.
Definition: RegionHandler.h:93
Abstract base class for an image attributes handler.
Bool fromRecord(String &error, const RecordInterface &inRec)
void setUnitMember(const Unit &unit)
Set the unit variable.
defines physical units
Definition: Unit.h:189
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.
void setImageInfoMember(const ImageInfo &imageInfo)
Set the image info variable.
virtual Bool setMiscInfo(const RecordInterface &newInfo)
void setLogMember(const LoggerHolder &logger)
Set the image logger variable.
virtual String getDefaultMask() const
Get the name of the default pixelmask.
virtual void defineRegion(const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
Define a region/mask belonging to the image.
A base class for astronomical images.
virtual IPosition shape() const =0
Return the shape of the Lattice including all degenerate axes (ie.
Class to specify which mask to use in an image.
Definition: MaskSpecifier.h:69
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)...
ImageInfo & rwImageInfo()
Get non-const access to the ImageInfo.
virtual Bool ok() const =0
Check class invariants.
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
const LoggerHolder & logger() const
virtual String name(Bool stripPath=False) const =0
Return the name of the current ImageInterface object.
virtual ImageInterface< T > * cloneII() const =0
virtual LELCoordinates lelCoordinates() const
Function to get a LELCoordinate object containing the coordinates.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
virtual String imageType() const =0
Get the image type (returns name of derived class).
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Functions to set or replace the coordinate information in the Image Returns False on failure...
virtual Bool canDefineRegion() const
Can the class indeed define and handle regions? The default implementation returns False...
virtual void renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=RegionHandler::Any, Bool overwrite=False)
Rename a region.
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
const Bool False
Definition: aipstype.h:41
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
Class to hold a region of interest in an image.
Definition: ImageRegion.h:86
ImageAttrHandler & roAttrHandler() const
virtual void assign(const RecordInterface &that)
Assign that RecordInterface object to this one.
const CoordinateSystem & coordinates() const
LogIO & logSink()
Allow messages to be logged to this ImageInterface.
virtual void resize(const TiledShape &newShape)=0
Function which changes the shape of the image (N.B.
LogIO & logio()
Get access to the logger.
Definition: LoggerHolder.h:554
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
const LatticeRegion & region() const
Get the region used.
const LogIO & logSink() const
String: the storage and methods of handling collections of characters.
Definition: String.h:223
CoordinateSystem coords_p
It is the job of the derived class to make these variables valid.
void setMiscInfoMember(const RecordInterface &rec)
Set the miscinfo variable.
Abstract base class for Record classes.
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
Class holding a hierarchy of loggers.
Definition: LoggerHolder.h:120
Miscellaneous information related to an image.
Definition: ImageInfo.h:92
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 Bool True
Definition: aipstype.h:40
virtual Bool setImageInfo(const ImageInfo &info)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
Interconvert pixel and world coordinates.
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). ...
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
ImageRegion getRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Get a region belonging to the image.
RegionHandler * regHandPtr_p
The region handling object.
unsigned int uInt
Definition: aipstype.h:48