casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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  // 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.
342  String makeUniqueRegionName (const String& rootName,
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.
364  void setImageInfoMember (const ImageInfo& imageInfo);
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
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.
void append(const LoggerHolder &other)
Append the entries of the other logger to this one.
RegionHandler * getRegionHandler()
Get access to the region handler.
std::vector< double > Vector
Definition: ds9context.h:24
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.
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 &quot;masks&quot; 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:42
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:44
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1944
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:43
virtual Bool setImageInfo(const ImageInfo &info)
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:51
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42