casacore
Loading...
Searching...
No Matches
ImageProxy.h
Go to the documentation of this file.
1//# ImageProxy.h: Proxy interface to images
2//# Copyright (C) 1997-2007
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//#
27//# $Id$
28
29#ifndef IMAGES_IMAGEPROXY_H
30#define IMAGES_IMAGEPROXY_H
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/images/Images/MaskSpecifier.h>
35#include <casacore/lattices/Lattices/LatticeBase.h>
36#include <casacore/lattices/Lattices/TiledShape.h>
37#include <casacore/casa/Utilities/CountedPtr.h>
38#include <casacore/casa/Containers/ValueHolder.h>
39#include <casacore/casa/Containers/Record.h>
40
41namespace casacore {
42
43 //# Forward Declarations.
44 class ImageInfo;
45 template<typename T> class ImageInterface;
46 class LatticeExprNode;
47 class CoordinateSystem;
48 class ImageAttrHandler;
49
50 // <synopsis>
51 // ImageProxy is a proxy to an image having data type Float, Double,
52 // Complex, or DComplex. Its primary purpose is to be bind the images
53 // module to Python through pyrap.images. However, it can also be used
54 // directly in C++.
55 //
56 // An ImageProxy object can be constructed for an image stored on disk in
57 // Casacore, FITS, HDF5, or Miriad format. It can also be constructed given
58 // a shape or an N-dim array with values.
59 // Furthermore it can be constructed from a LEL expression (see class ImageExpr)
60 // or a vector of images to be concatenated (see class ImageConcat).
61 //
62 // Many functions exist to operate on an ImageProxy object. For example:
63 // <ul>
64 // <li> get meta info (shape, data type, coordinates, etc.)
65 // <li> save in Casacore, HDF5, or FITS format.
66 // <li> regrid.
67 // <li> get statistics.
68 // <li> form a subimage (which is done in a virtual way).
69 // </ul>
70 // Functions regrid and statistics can only be used for Float images.
71 // They throw an exception for images with other data types.
72 // Note that using a LEL expression it is possible to (virtually) convert an
73 // image with another type to a Float image.
74 // </synopsis>
75
77 {
78 public:
79 // Default constructor is needed for Boost-Python.
81
82 // Construct from the concatenation of the images along the axis.
83 // The axis must be given as a Fortran-array axis.
84 // All images must be of the same data type.
85 ImageProxy (const Vector<String>& names, Int axis);
86
87 // Construct from a string that contains an image name or image expression.
88 // It is opened using ImageOpener.
89 ImageProxy (const String& name, const String& mask,
90 const std::vector<ImageProxy>& images);
91
92 // Construct from the concatenation of the image objects along the axis.
93 // The axis must be given as a Fortran-array axis.
94 // All images must be of the same data type.
95 //# The dummy arguments are needed to let all constructors have a
96 //# different number of arguments (for Boost-Python).
97 ImageProxy (const std::vector<ImageProxy>& images, Int axis,
98 Int dummy1=0, Int dummy2=0);
99
100 // Construct from a ValueHolder containing an Array of Float or Complex.
101 // If the name is empty it is created as a temporary image, otherwise
102 // as a PagedImage or HDF5Image.
103 // If the coordinates record is empty, default coordinates are used.
104 // A mask is created if the mask name or mask value is not empty.
105 ImageProxy (const ValueHolder& values,
106 const ValueHolder& mask,
107 const Record& coordinates,
108 const String& imageName = String(),
109 Bool overwrite = True,
110 Bool asHDF5 = False,
111 const String& maskName = String(),
112 const IPosition& tileShape = IPosition());
113
114 // Construct from a shape.
115 // If the name is empty it is created as a temporary image, otherwise
116 // as a PagedImage or HDF5Image.
117 // If the coordinates record is empty, default coordinates are used.
118 // A mask is created if the mask name is not empty.
120 const ValueHolder& value,
121 const Record& coordinates,
122 const String& imageName = String(),
123 Bool overwrite = True,
124 Bool asHDF5 = False,
125 const String& maskName = String(),
126 const IPosition& tileShape = IPosition(),
127 Int dummy=0);
128
129 // Construct from an existing image object.
131
132 // Copy constructor (reference semantics).
134
135 // Assignment (reference semantics).
137
139
140 // Open the image (which can also be an expression).
141 // It throws an exception if not succeeded.
143 const String& mask = String(),
144 const std::vector<ImageProxy>& images = std::vector<ImageProxy>());
145
146 // Open an image in the file/table with the given name.
147 // The specified mask will be applied (default is default mask).
148 // A null pointer is returned for an unknown image type.
149 // Non-Casacore image types must have been registered to be known.
150 // If not successful, try to open it as an image expression.
151 static LatticeBase* openImageOrExpr (const String& str,
152 const MaskSpecifier&,
153 const Block<LatticeExprNode>& nodes);
154
155 // Close the image by setting all pointers to 0.
156 void close();
157
158 // Turn the ImageProxy into a LatticeExprNode.
160
161 // Is the image persistent or temporary.
163
164 // Get the name of the image.
165 String name (Bool stripPath=False) const;
166
167 // Get the shape of the image.
169
170 // Get the dimensionality of the image.
171 uInt ndim() const;
172
173 // Get the size of the image (nr of pixels).
174 uInt size() const;
175
176 // Get the data type of the image.
178
179 DataType type() const;
180
181 // Get the image type (PagedImage, HDF5Image, etc.)
183
184 // Get a chunk of data.
186 const IPosition& trc,
187 const IPosition& inc);
188
189 // Get a chunk of the mask.
191 const IPosition& trc,
192 const IPosition& inc);
193
194 // Put a chunk of data.
195 void putData (const ValueHolder&,
196 const IPosition& blc,
197 const IPosition& inc);
198
199 // Put a chunk of the mask.
200 // The mask will be created if not present yet.
201 // That will not be done if the entire mask is True.
203 const IPosition& blc,
204 const IPosition& inc);
205
206 // Does the image have a read or write lock?
207 Bool hasLock (Bool writeLock = False);
208
209 // Try to acquire a read or write lock.
210 // nattempts=0 means wait until acquired. Otherwise every second an
211 // attempt is done.
212 void lock (Bool writeLock=False, Int nattempts=0);
213
214 // Release the lock acquired by lock().
215 void unlock();
216
217 // Get the names of the attribute groups.
219
220 // Create a new attribute group.
221 void createAttrGroup (const String& groupName);
222
223 // Get the names of all attributes in a group.
224 Vector<String> attrNames (const String& groupName) const;
225
226 // Get the number of rows in an attribute group.
227 uInt attrNrows (const String& groupName) const;
228
229 // Get the value of an attribute in a group row.
230 ValueHolder getAttr (const String& groupName,
231 const String& attrName,
232 uInt rownr) const;
233
234 // Get all attributes in a group row.
235 Record getAttrRow (const String& groupName,
236 uInt rownr) const;
237
238 // Get the unit(s) of an attribute in a group.
240 const String& attrName) const;
241
242 // Get the measinfo of an attribute in a group.
244 const String& attrName) const;
245
246 // Put the value, unit, and measinfo of an attribute in a group row.
247 // The attribute or row is added if new.
248 void putAttr (const String& groupName, const String& attrName, uInt rownr,
249 const ValueHolder& value,
250 const Vector<String>& units,
251 const Vector<String>& measInfo);
252
253 // Form a new (virtual) image being a subset of the image.
254 // It uses preserveAxesOrder=False.
256 const IPosition& trc,
257 const IPosition& inc,
258 Bool dropDegenerate=True);
259 // Same with a new function name for backward compatibility with old pyrap.
261 const IPosition& trc,
262 const IPosition& inc,
263 Bool dropDegenerate,
264 Bool preserveAxesOrder);
265
266 // Get the brightness unit.
267 String unit() const;
268
269 // Get the coordinate system.
271
273
274 // Convert a pixel coordinate to world coordinate.
275 // if <src>reverseAxes=True</src> the input and output vector will be
276 // reversed (as needed for pyrap).
278 Bool reverseAxes);
279
280 // Convert a world coordinate to pixel coordinate.
281 // if <src>reverseAxes=True</src> the input and output vector will be
282 // reversed (as needed for pyrap).
284 Bool reverseAxes);
285
286 // Get the image info.
288
290
291 // Get the miscellaneous info.
293
294 // Get the history.
296
297 // Write the image in FITS format.
298 // See class ImageFITSConverter for a description of the arguments.
299 // Currently only a float image can be written to FITS.
300 void toFits (const String& fitsfile, Bool overwrite=True,
301 Bool velocity=True, Bool optical=True, Int bitpix=-32,
302 Double minpix=1, Double maxpix=-1) const;
303
304 // Write the image to an image file with the given name.
305 // An exception is thrown if the name is the name of an already open image.
306 void saveAs (const String& fileName, Bool overwrite=True,
307 Bool hdf5=False,
308 Bool copyMask=True, const String& newMaskName=String(),
309 const IPosition& newTileShape=IPosition()) const;
310
311 // Return the statistics for the given axes.
312 // E.g., if axes 0,1 is given in a 3-dim image, the statistics are
313 // calculated for each plane along the 3rd axis.
314 // MinMaxValues can be given to include or exclude (4th argument) pixels
315 // with values in the given range. If only one value is given, min=-abs(val)
316 // and max=abs(val).
317 // Robust statistics (Median, MedAbsDevMed, and Quartile) can be returned
318 // too.
320 const String& mask,
321 const ValueHolder& minMaxValues,
322 Bool exclude = False,
323 Bool robust = False) const;
324
325 // Regrid the image on the given axes to the given coordinate system.
326 // The output is stored in the given file; it no file name is given a
327 // temporary image is made.
328 // If the output shape is empty, the old shape is used.
329 // <src>replicate=True</src> means replication rather than regridding.
331 const String& outfile = String(),
332 Bool overwriteOutFile = True,
333 const IPosition& outShape = IPosition(),
334 const Record& coordSys = Record(),
335 const String& method = "linear",
336 Int decimate = 10,
337 Bool replicate = False,
338 Bool doRefChange = True,
339 Bool forceRegrid = False);
340
341 // Check and adjust blc, trc, or inc using the shape.
342 // <group>
343 static IPosition adjustBlc (const IPosition& blc, const IPosition& shp);
344 static IPosition adjustTrc (const IPosition& trc, const IPosition& shp);
345 static IPosition adjustInc (const IPosition& inc, const IPosition& shp);
346 // </group>
347
348
349 /*
350
351 ImageProxy rotate(const String& outfile,
352 const IPosition& shape,
353 const Quantity& pa, Record& region,
354 const String& mask,
355 const String& method = "cubic",
356 Int decimate = 0,
357 Bool replicate = False,
358 Bool dropdeg = False,
359 Bool overwrite = False);
360
361
362 Bool setbrightnessunit (const String& unit);
363
364 Bool setcoordsys (const Record& csys);
365
366 Bool sethistory (const String& origin, const Vector<String>& history);
367
368 Bool setmiscinfo (const Record& info);
369
370 ImageProxy subimage(const String& outfile, Record& region,
371 const String& mask,
372 Bool dropdeg = False,
373 Bool overwrite = False,
374 Bool list = True);
375
376 Vector<Double> topixel(Record& value);
377
378 */
379
381 { return itsLattice.operator->(); }
382
383 private:
384 // Form an ImageProxy object from an existing image object.
386
387 // Throw an exception if the object is null.
388 void checkNull() const;
389
390 // Make an image from an array or shape.
391 template<typename T>
393 const IPosition& shape, const Record& coordinates,
394 const String& fileName, Bool asHDF5,
395 const String& maskName,
396 const IPosition& tileShape);
397
398 // Form a concatenated image.
399 // <group>
400 void concatImages (const std::vector<ImageProxy>& images, Int axis);
401 void concatImagesFloat (const std::vector<ImageProxy>& images, Int axis);
402 void concatImagesDouble (const std::vector<ImageProxy>& images, Int axis);
403 void concatImagesComplex (const std::vector<ImageProxy>& images, Int axis);
404 void concatImagesDComplex (const std::vector<ImageProxy>& images, Int axis);
405 // </group>
406
407 // Setup the pointers for the various image data types.
408 void setup();
409
410 // Setup the pointers for the various image data types.
411 // It takes over the lattice pointer.
412 void setup (LatticeBase* lattice);
413
414 // Centre all axes except the Stokes one.
416 const IPosition& shape) const;
417
418 // Put the mask and create it if needed.
419 template<typename T>
421 const ValueHolder& value,
422 const IPosition& blc,
423 const IPosition& inc);
424
425 // Copy the image to an image (PagedImage or HDF5Image) with the given name.
426 // A new tile shape can be given.
427 // If the image is masked, the mask can be copied as well.
428 template <typename T>
429 void saveImage (const String& fileName,
430 Bool hdf5, Bool copyMask,
431 const String& newMaskName,
432 const IPosition& newTileShape,
433 const ImageInterface<T>& image) const;
434
435 // Form a tiled shape from the current shape and a possible new tile shape.
436 TiledShape makeTiledShape (const IPosition& newTileShape,
437 const IPosition& shape,
438 const IPosition& oldTileShape=IPosition()) const;
439
440 // Calculate the statistics.
441 template<typename T>
443 const Vector<Int>& axes,
444 const String& mask,
445 const ValueHolder& minMaxValues,
446 Bool exclude,
447 Bool robust) const;
448
449 // Do the actual regridding.
450 template<typename T>
452 const Vector<Int>& axes,
453 const String& outfile,
454 const IPosition& shape,
455 const Record& coordSys,
456 const String& method,
457 Int decimate,
458 Bool replicate,
459 Bool doRefChange,
460 Bool force);
461
462 // Make a coordinate system from the Record.
463 // The cylindrical fix is applied if needed.
465 const IPosition& shape) const;
466
467
468 //# Data members.
469 //# itsLattice is the real data; the pointers are for type convenience only.
477 };
478
479} // end namespace casacore
480
481#endif
simple 1-D array
Definition Block.h:200
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
void makeImage(const Array< T > &array, const Array< Bool > &mask, const IPosition &shape, const Record &coordinates, const String &fileName, Bool asHDF5, const String &maskName, const IPosition &tileShape)
Make an image from an array or shape.
const CoordinateSystem * itsCoordSys
Definition ImageProxy.h:475
static LatticeBase * openImage(const String &name, const String &mask=String(), const std::vector< ImageProxy > &images=std::vector< ImageProxy >())
Open the image (which can also be an expression).
Record coordSys() const
Get the coordinate system.
CoordinateSystem makeCoordinateSystem(const Record &coordinates, const IPosition &shape) const
Make a coordinate system from the Record.
ImageProxy & operator=(const ImageProxy &)
Assignment (reference semantics).
ImageProxy(const String &name, const String &mask, const std::vector< ImageProxy > &images)
Construct from a string that contains an image name or image expression.
void putAttr(const String &groupName, const String &attrName, uInt rownr, const ValueHolder &value, const Vector< String > &units, const Vector< String > &measInfo)
Put the value, unit, and measinfo of an attribute in a group row.
ImageProxy(const ValueHolder &values, const ValueHolder &mask, const Record &coordinates, const String &imageName=String(), Bool overwrite=True, Bool asHDF5=False, const String &maskName=String(), const IPosition &tileShape=IPosition())
Construct from a ValueHolder containing an Array of Float or Complex.
void saveAs(const String &fileName, Bool overwrite=True, Bool hdf5=False, Bool copyMask=True, const String &newMaskName=String(), const IPosition &newTileShape=IPosition()) const
Write the image to an image file with the given name.
void putData(const ValueHolder &, const IPosition &blc, const IPosition &inc)
Put a chunk of data.
ImageInterface< DComplex > * itsImageDComplex
Definition ImageProxy.h:474
const CoordinateSystem & coordSysObject() const
uInt size() const
Get the size of the image (nr of pixels).
static LatticeBase * openImageOrExpr(const String &str, const MaskSpecifier &, const Block< LatticeExprNode > &nodes)
Open an image in the file/table with the given name.
Record statistics(const Vector< Int > &axes, const String &mask, const ValueHolder &minMaxValues, Bool exclude=False, Bool robust=False) const
Return the statistics for the given axes.
void concatImagesFloat(const std::vector< ImageProxy > &images, Int axis)
ImageProxy()
Default constructor is needed for Boost-Python.
ImageProxy(LatticeBase *)
Form an ImageProxy object from an existing image object.
uInt attrNrows(const String &groupName) const
Get the number of rows in an attribute group.
void concatImagesComplex(const std::vector< ImageProxy > &images, Int axis)
ImageProxy subImage2(const IPosition &blc, const IPosition &trc, const IPosition &inc, Bool dropDegenerate, Bool preserveAxesOrder)
Same with a new function name for backward compatibility with old pyrap.
void concatImagesDComplex(const std::vector< ImageProxy > &images, Int axis)
ValueHolder getAttr(const String &groupName, const String &attrName, uInt rownr) const
Get the value of an attribute in a group row.
void lock(Bool writeLock=False, Int nattempts=0)
Try to acquire a read or write lock.
Record miscInfo() const
Get the miscellaneous info.
void centreRefPix(CoordinateSystem &cSys, const IPosition &shape) const
Centre all axes except the Stokes one.
ValueHolder getMask(const IPosition &blc, const IPosition &trc, const IPosition &inc)
Get a chunk of the mask.
ImageInterface< Complex > * itsImageComplex
Definition ImageProxy.h:473
void putMask(const ValueHolder &value, const IPosition &blc, const IPosition &inc)
Put a chunk of the mask.
Bool hasLock(Bool writeLock=False)
Does the image have a read or write lock?
DataType type() const
LatticeExprNode makeNode() const
Turn the ImageProxy into a LatticeExprNode.
IPosition shape() const
Get the shape of the image.
ImageInterface< Float > * itsImageFloat
Definition ImageProxy.h:471
Vector< String > attrNames(const String &groupName) const
Get the names of all attributes in a group.
Record imageInfo() const
Get the image info.
ImageProxy(const IPosition &shape, const ValueHolder &value, const Record &coordinates, const String &imageName=String(), Bool overwrite=True, Bool asHDF5=False, const String &maskName=String(), const IPosition &tileShape=IPosition(), Int dummy=0)
Construct from a shape.
void unlock()
Release the lock acquired by lock().
Bool isPersistent() const
Is the image persistent or temporary.
ImageProxy(const ImageProxy &)
Copy constructor (reference semantics).
void concatImagesDouble(const std::vector< ImageProxy > &images, Int axis)
ImageAttrHandler * itsAttrHandler
Definition ImageProxy.h:476
Vector< String > getAttrUnit(const String &groupName, const String &attrName) const
Get the unit(s) of an attribute in a group.
CountedPtr< LatticeBase > itsLattice
Definition ImageProxy.h:470
Vector< Double > toWorld(const Vector< Double > &pixel, Bool reverseAxes)
Convert a pixel coordinate to world coordinate.
void concatImages(const std::vector< ImageProxy > &images, Int axis)
Form a concatenated image.
TiledShape makeTiledShape(const IPosition &newTileShape, const IPosition &shape, const IPosition &oldTileShape=IPosition()) const
Form a tiled shape from the current shape and a possible new tile shape.
Vector< Double > toPixel(const Vector< Double > &world, Bool reverseAxes)
Convert a world coordinate to pixel coordinate.
const ImageInfo & imageInfoObject() const
void saveImage(const String &fileName, Bool hdf5, Bool copyMask, const String &newMaskName, const IPosition &newTileShape, const ImageInterface< T > &image) const
Copy the image to an image (PagedImage or HDF5Image) with the given name.
ImageProxy regrid(const Vector< Int > &axes=Vector< Int >(), const String &outfile=String(), Bool overwriteOutFile=True, const IPosition &outShape=IPosition(), const Record &coordSys=Record(), const String &method="linear", Int decimate=10, Bool replicate=False, Bool doRefChange=True, Bool forceRegrid=False)
Regrid the image on the given axes to the given coordinate system.
ImageProxy subImage(const IPosition &blc, const IPosition &trc, const IPosition &inc, Bool dropDegenerate=True)
Form a new (virtual) image being a subset of the image.
static IPosition adjustBlc(const IPosition &blc, const IPosition &shp)
Check and adjust blc, trc, or inc using the shape.
String imageType() const
Get the image type (PagedImage, HDF5Image, etc.)
Vector< String > attrGroupNames() const
Get the names of the attribute groups.
Vector< String > history() const
Get the history.
ImageInterface< Double > * itsImageDouble
Definition ImageProxy.h:472
uInt ndim() const
Get the dimensionality of the image.
ImageProxy(const std::vector< ImageProxy > &images, Int axis, Int dummy1=0, Int dummy2=0)
Construct from the concatenation of the image objects along the axis.
String unit() const
Get the brightness unit.
void checkNull() const
Throw an exception if the object is null.
Vector< String > getAttrMeas(const String &groupName, const String &attrName) const
Get the measinfo of an attribute in a group.
ImageProxy(const Vector< String > &names, Int axis)
Construct from the concatenation of the images along the axis.
String dataType() const
Get the data type of the image.
String name(Bool stripPath=False) const
Get the name of the image.
static IPosition adjustTrc(const IPosition &trc, const IPosition &shp)
void setup()
Setup the pointers for the various image data types.
LatticeBase * getLattice() const
Definition ImageProxy.h:380
void setup(LatticeBase *lattice)
Setup the pointers for the various image data types.
void createAttrGroup(const String &groupName)
Create a new attribute group.
ImageProxy(const CountedPtr< LatticeBase > &)
Construct from an existing image object.
ValueHolder getData(const IPosition &blc, const IPosition &trc, const IPosition &inc)
Get a chunk of data.
static IPosition adjustInc(const IPosition &inc, const IPosition &shp)
void toFits(const String &fitsfile, Bool overwrite=True, Bool velocity=True, Bool optical=True, Int bitpix=-32, Double minpix=1, Double maxpix=-1) const
Write the image in FITS format.
void close()
Close the image by setting all pointers to 0.
void doPutMask(ImageInterface< T > &image, const ValueHolder &value, const IPosition &blc, const IPosition &inc)
Put the mask and create it if needed.
ImageProxy doRegrid(const ImageInterface< T > &image, const Vector< Int > &axes, const String &outfile, const IPosition &shape, const Record &coordSys, const String &method, Int decimate, Bool replicate, Bool doRefChange, Bool force)
Do the actual regridding.
Record makeStatistics(const ImageInterface< T > &image, const Vector< Int > &axes, const String &mask, const ValueHolder &minMaxValues, Bool exclude, Bool robust) const
Calculate the statistics.
Record getAttrRow(const String &groupName, uInt rownr) const
Get all attributes in a group row.
String: the storage and methods of handling collections of characters.
Definition String.h:225
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
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition ExprNode.h:1929
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
int Int
Definition aipstype.h:50
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.
const Bool True
Definition aipstype.h:43
double Double
Definition aipstype.h:55