casacore
SubImage.h
Go to the documentation of this file.
1 //# SubImage.h: A (masked) subset of an ImageInterface object
2 //# Copyright (C) 1998,1999,2000,2001,2003
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_SUBIMAGE_H
29 #define IMAGES_SUBIMAGE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/ArrayFwd.h>
35 #include <casacore/images/Images/ImageInterface.h>
36 #include <casacore/casa/Arrays/AxesSpecifier.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class IPosition;
42 class LattRegionHolder;
43 class Slicer;
44 template <class T> class SubLattice;
45 class LatticeNavigator;
46 template <class T> class LatticeIterInterface;
47 class String;
48 
49 
50 // <summary>
51 // A (masked) subset of an ImageInterface object.
52 // </summary>
53 //
54 // <use visibility=export>
55 //
56 // <reviewed reviewer="" date="" tests="tSubImage.cc">
57 // </reviewed>
58 //
59 // <prerequisite>
60 // <li> <linkto class=ImageInterface>ImageInterface</linkto>
61 // <li> <linkto class=SubLattice>SubLattice</linkto>
62 // </prerequisite>
63 //
64 // <synopsis>
65 // Class SubImage has to be used to apply a region or mask to an image.
66 // Several functions are inherited from SubLattice and not declared
67 // in this class.
68 // <p>
69 // Using an <linkto class=AxesSpecifier>AxesSpecifier</linkto> object
70 // it is possible to remove some or all degenerate axes (i.e. axes
71 // with length 1) to get an image with a lower dimensionality.
72 // </synopsis>
73 //
74 // <example>
75 // <srcblock>
76 // </srcblock>
77 // </example>
78 //
79 // <motivation>
80 // </motivation>
81 //
82 // <todo asof="1998/02/09">
83 // </todo>
84 
85 
86 template <class T> class SubImage: public ImageInterface<T>
87 {
88 public:
89  // The default constructor
91 
92  // Create a SubImage from a Image.
93  // This results in a SubImage without a real mask.
94  // <br>The "const Image" version yields a non-writable SubImage,
95  // while for the non-const version one has to specify if the SubImage
96  // should be writable (if the original image is non-writable, the
97  // SubImage is always set to non-writable).
98  // <br>If preserveAxesOrder is True, the axes order will be preserved. This
99  // is only important in cases where pixel axes are to be dropped, if not
100  // the axes order will be preserved. If False and pixel axes are dropped,
101  // the order of the coordinates will be preserved, but not necessarily
102  // the axes.
103  // <group>
105  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
106  SubImage (ImageInterface<T>& image, Bool writableIfPossible,
107  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
108  // </group>
109 
110  // Create a SubImage from the given Image and region.
111  // <br>An exception is thrown if the image shape used in the region
112  // differs from the shape of the image.
113  // <group>
115  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
117  Bool writableIfPossible,
118  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
119  // </group>
120 
121  // Create a SubImage from the given Image and slicer.
122  // The slicer can be strided.
123  // <br>An exception is thrown if the slicer exceeds the image shape.
124  // <group>
125  SubImage (const ImageInterface<T>& image, const Slicer& slicer,
126  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
127  SubImage (ImageInterface<T>& image, const Slicer& slicer,
128  Bool writableIfPossible,
129  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
130  // </group>
131 
132  // Copy constructor (reference semantics).
133  SubImage (const SubImage<T>& other);
134 
135  virtual ~SubImage();
136 
137  // Assignment (reference semantics).
139 
140  // Make a copy of the object (reference semantics).
141  // <group>
142  virtual ImageInterface<T>* cloneII() const;
143  // </group>
144 
145  // Get the image type (returns name of derived class).
146  virtual String imageType() const;
147 
148  // Is the SubImage masked?
149  // It is if its parent image or its region is masked.
150  virtual Bool isMasked() const;
151 
152  // Does the image object have a pixelmask?
153  // It does if its parent has a pixelmask.
154  virtual Bool hasPixelMask() const;
155 
156  // Get access to the pixelmask in use (thus to the pixelmask of the parent).
157  // An exception is thrown if the parent does not have a pixelmask.
158  // <group>
159  virtual const Lattice<Bool>& pixelMask() const;
161  // </group>
162 
163  // A SubImage is persistent if no region is applied to the parent image.
164  // That is true if the region has the same shape as the parent image
165  // and the region has no mask.
166  virtual Bool isPersistent() const;
167 
168  // Is the SubImage paged to disk?
169  virtual Bool isPaged() const;
170 
171  // Can the lattice data be referenced as an array section?
172  virtual Bool canReferenceArray() const;
173 
174  // Is the SubImage writable?
175  virtual Bool isWritable() const;
176 
177  // Get the region/mask object describing this subImage.
178  virtual const LatticeRegion* getRegionPtr() const;
179 
180  // Returns the shape of the SubImage including all degenerate axes
181  // (i.e. axes with a length of one).
182  virtual IPosition shape() const;
183 
184  // Returns the number of axes in this SubImage. This includes all
185  // degenerate axes.
186  virtual uInt ndim() const;
187 
188  // Returns the total number of elements in this SubImage.
189  virtual size_t nelements() const;
190 
191  // returns a value of "True" if this instance of Lattice and 'other' have
192  // the same shape, otherwise returns a value of "False".
193  virtual Bool conform (const Lattice<T>& other) const;
194 
195  // This function returns the recommended maximum number of pixels to
196  // include in the cursor of an iterator.
197  virtual uInt advisedMaxPixels() const;
198 
199  // Get access to the attribute handler (of the parent image).
200  // If a handler keyword does not exist yet, it is created if
201  // <src>createHandler</src> is set.
202  // Otherwise the handler is empty and no groups can be created for it.
203  virtual ImageAttrHandler& attrHandler (Bool createHandler=False);
204 
205  // Get or put a single element in the lattice.
206  // <group>
207  virtual T getAt (const IPosition& where) const;
208  virtual void putAt (const T& value, const IPosition& where);
209  // </group>
210 
211  // Function which changes the shape of the SubImage.
212  // Throws an exception as resizing a SubImage is not possible.
213  virtual void resize(const TiledShape& newShape);
214 
215  // Return the name of the parent ImageInterface object.
216  virtual String name (Bool stripPath=False) const;
217 
218  // Check class invariants.
219  virtual Bool ok() const;
220 
221  // Do the actual getting of an array of values.
222  virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section);
223 
224  // Do the actual getting of an array of values.
225  virtual void doPutSlice (const Array<T>& sourceBuffer,
226  const IPosition& where,
227  const IPosition& stride);
228 
229  // Get a section of the mask.
230  virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
231 
232  // This function is used by the LatticeIterator class to generate an
233  // iterator of the correct type for this Lattice. Not recommended
234  // for general use.
236  (const LatticeNavigator& navigator,
237  Bool useRef) const;
238 
239  // Get the best cursor shape.
240  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
241 
242  // Handle the (un)locking and syncing, etc.
243  // <group>
244  virtual Bool lock (FileLocker::LockType, uInt nattempts);
245  virtual void unlock();
247  virtual void resync();
248  virtual void flush();
249  virtual void tempClose();
250  virtual void reopen();
251  // </group>
252 
253 private:
254  // Set the coordinates.
255  // It removes world axes if the subimage has axes removed.
256  // <br>If preserveAxesOrder is True and axes are dropped, it will preserve
257  // the order of the axes as well as the order of the coordinates.
258  void setCoords (const CoordinateSystem& coords, Bool preserveAxesOrder);
259  void setCoords (const CoordinateSystem& coords);
260 
261  // Set the other members to the one in itsImagePtr.
262  void setMembers();
263 
264  // Set the members to the subset (in particular, the beamset).
265  void setMembers (const Slicer& slicer);
266 
267  // Helper
268  void convertIPosition(Vector<Float>& x, const IPosition& pos) const;
269 
270 
271  //# itsImagePtr points to the parent image.
274 
275  //# Make members of parent class known.
276 public:
278 protected:
280 };
281 
282 //# Declare extern templates for often used types.
283  extern template class SubImage<Float>;
284  extern template class SubImage<Complex>;
285 
286 
287 } //# NAMESPACE CASACORE - END
288 
289 #ifndef CASACORE_NO_AUTO_TEMPLATES
290 #include <casacore/images/Images/SubImage.tcc>
291 #endif //# CASACORE_NO_AUTO_TEMPLATES
292 #endif
LockType
Define the possible lock types.
Definition: FileLocker.h:95
const LatticeRegion & region() const
Get the region used.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
SubImage(const ImageInterface< T > &image, const Slicer &slicer, AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False)
Create a SubImage from the given Image and slicer.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Get a section of the mask.
void setMembers()
Set the other members to the one in itsImagePtr.
virtual void unlock()
void convertIPosition(Vector< Float > &x, const IPosition &pos) const
Helper.
SubImage(ImageInterface< T > &image, const LattRegionHolder &region, Bool writableIfPossible, AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False)
SubImage(ImageInterface< T > &image, const Slicer &slicer, Bool writableIfPossible, AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False)
SubImage()
The default constructor.
virtual Lattice< Bool > & pixelMask()
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
SubImage(const ImageInterface< T > &image, const LattRegionHolder &region, AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False)
Create a SubImage from the given Image and region.
virtual const LatticeRegion * getRegionPtr() const
Get the region/mask object describing this subImage.
virtual Bool isPaged() const
Is the SubImage paged to disk?
virtual Bool isPersistent() const
A SubImage is persistent if no region is applied to the parent image.
SubImage< T > & operator=(const SubImage< T > &other)
Assignment (reference semantics).
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This function is used by the LatticeIterator class to generate an iterator of the correct type for th...
virtual Bool hasLock(FileLocker::LockType) const
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask in use (thus to the pixelmask of the parent).
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the SubImage.
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler (of the parent image).
virtual Bool hasPixelMask() const
Does the image object have a pixelmask? It does if its parent has a pixelmask.
virtual size_t nelements() const
Returns the total number of elements in this SubImage.
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
void setCoords(const CoordinateSystem &coords, Bool preserveAxesOrder)
Set the coordinates.
SubLattice< T > * itsSubLatPtr
Definition: SubImage.h:273
virtual uInt ndim() const
Returns the number of axes in this SubImage.
SubImage(const ImageInterface< T > &image, AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False)
Create a SubImage from a Image.
virtual void resync()
Resynchronize the Lattice object with the lattice file.
virtual String imageType() const
Get the image type (returns name of derived class).
virtual Bool isWritable() const
Is the SubImage writable?
SubImage(const SubImage< T > &other)
Copy constructor (reference semantics).
virtual void tempClose()
Temporarily close the lattice.
ImageInterface< T > * itsImagePtr
Definition: SubImage.h:272
virtual String name(Bool stripPath=False) const
Return the name of the parent ImageInterface object.
void setMembers(const Slicer &slicer)
Set the members to the subset (in particular, the beamset).
virtual T getAt(const IPosition &where) const
Get or put a single element in the lattice.
virtual Bool conform(const Lattice< T > &other) const
returns a value of "True" if this instance of Lattice and 'other' have the same shape,...
virtual Bool isMasked() const
Is the SubImage masked? It is if its parent image or its region is masked.
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle the (un)locking and syncing, etc.
void setCoords(const CoordinateSystem &coords)
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
SubImage(ImageInterface< T > &image, Bool writableIfPossible, AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False)
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
virtual void flush()
Flush the data (but do not unlock).
virtual IPosition shape() const
Returns the shape of the SubImage including all degenerate axes (i.e.
virtual uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
virtual Bool ok() const
Check class invariants.
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
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.