casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class IPosition;
41 class LattRegionHolder;
42 class Slicer;
43 template <class T> class SubLattice;
44 template <class T> class Array;
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
90  SubImage();
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>
104  SubImage (const ImageInterface<T>& image,
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>
114  SubImage (const ImageInterface<T>& image, const LattRegionHolder& region,
115  AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False);
116  SubImage (ImageInterface<T>& image, const LattRegionHolder& region,
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).
138  SubImage<T>& operator= (const SubImage<T>& other);
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;
160  virtual Lattice<Bool>& pixelMask();
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();
246  virtual Bool hasLock (FileLocker::LockType) const;
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
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:119
A subset of a Lattice or MaskedLattice.
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the SubImage.
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle the (un)locking and syncing, etc.
virtual size_t nelements() const
Returns the total number of elements in this SubImage.
virtual Bool hasLock(FileLocker::LockType) const
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual Bool isPaged() const
Is the SubImage paged to disk?
virtual void flush()
Flush the data (but do not unlock).
virtual uInt ndim() const
Returns the number of axes in this SubImage.
SubLattice< T > * itsSubLatPtr
Definition: SubImage.h:273
virtual IPosition shape() const
Returns the shape of the SubImage including all degenerate axes (i.e.
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
virtual Bool isPersistent() const
A SubImage is persistent if no region is applied to the parent image.
virtual const LatticeRegion * getRegionPtr() const
Get the region/mask object describing this subImage.
virtual T getAt(const IPosition &where) const
Get or put a single element in the lattice.
virtual uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
SubImage< T > & operator=(const SubImage< T > &other)
Assignment (reference semantics).
Abstract base class for an image attributes handler.
Specification of axes to keep or remove.
virtual Bool hasPixelMask() const
Does the image object have a pixelmask? It does if its parent has a pixelmask.
A base class for Lattice iterators.
Definition: SubImage.h:46
Define the shape and tile shape.
Definition: TiledShape.h:99
virtual Bool isWritable() const
Is the SubImage writable?
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
A base class for astronomical images.
virtual String imageType() const
Get the image type (returns name of derived class).
virtual Bool isMasked() const
Is the SubImage masked? It is if its parent image or its region is masked.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Get a section of the mask.
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...
void convertIPosition(Vector< Float > &x, const IPosition &pos) const
Helper.
Class to hold a region of interest in an image.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
const Bool False
Definition: aipstype.h:44
A (masked) subset of an ImageInterface object.
template &lt;class T, class U&gt; class vector;
Definition: MSFlagger.h:37
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
virtual void unlock()
virtual Bool ok() const
Check class invariants.
SubImage()
The default constructor.
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler (of the parent image).
void setMembers()
Set the other members to the one in itsImagePtr.
const LatticeRegion & region() const
Get the region used.
virtual void resync()
Resynchronize the Lattice object with the lattice file.
virtual void tempClose()
Temporarily close the lattice.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:74
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
void setCoords(const CoordinateSystem &coords, Bool preserveAxesOrder)
Set the coordinates.
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask in use (thus to the pixelmask of the parent).
ImageInterface< T > * itsImagePtr
Definition: SubImage.h:272
Interconvert pixel and world coordinates.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
virtual Bool conform(const Lattice< T > &other) const
returns a value of &quot;True&quot; if this instance of Lattice and &#39;other&#39; have the same shape...
virtual String name(Bool stripPath=False) const
Return the name of the parent ImageInterface object.
unsigned int uInt
Definition: aipstype.h:51
Abstract base class to steer lattice iterators.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42