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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class IPosition;
42class LattRegionHolder;
43class Slicer;
44template <class T> class SubLattice;
45class LatticeNavigator;
46template <class T> class LatticeIterInterface;
47class 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
86template <class T> class SubImage: public ImageInterface<T>
87{
88public:
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
253private:
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.
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.
276public:
277 using ImageInterface<T>::logger;
278protected:
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
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
LoggerHolder & logger()
Get access to the LoggerHolder.
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.
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
void setMembers()
Set the other members to the one in itsImagePtr.
virtual Lattice< Bool > & pixelMask()
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 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 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.
virtual Bool hasLock(FileLocker::LockType) const
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 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 ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler (of the parent image).
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.
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 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)
SubImage< T > & operator=(const SubImage< T > &other)
Assignment (reference semantics).
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 const Lattice< Bool > & pixelMask() const
Get access to the pixelmask in use (thus to the pixelmask of the parent).
virtual Bool ok() const
Check class invariants.
virtual const LatticeRegion * getRegionPtr() const
Get the region/mask object describing this subImage.
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.