ImageProxy.h

Go to the documentation of this file.
00001 //# ImageProxy.h:  Proxy interface to images
00002 //# Copyright (C) 1997-2007
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //#
00027 //# $Id$
00028 
00029 #ifndef IMAGES_IMAGEPROXY_H
00030 #define IMAGES_IMAGEPROXY_H
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/images/Images/MaskSpecifier.h>
00035 #include <casacore/lattices/Lattices/LatticeBase.h>
00036 #include <casacore/lattices/Lattices/TiledShape.h>
00037 #include <casacore/casa/Utilities/CountedPtr.h>
00038 #include <casacore/casa/Containers/ValueHolder.h>
00039 #include <casacore/casa/Containers/Record.h>
00040 
00041 namespace casacore {
00042 
00043   //# Forward Declarations.
00044   class ImageInfo;
00045   template<typename T> class ImageInterface;
00046   class LatticeExprNode;
00047   class CoordinateSystem;
00048   class ImageAttrHandler;
00049 
00050   // <synopsis>
00051   // ImageProxy is a proxy to an image having data type Float, Double,
00052   // Complex, or DComplex. Its primary purpose is to be bind the images
00053   // module to Python through pyrap.images. However, it can also be used
00054   // directly in C++.
00055   //
00056   // An ImageProxy object can be constructed for an image stored on disk in
00057   // Casacore, FITS, HDF5, or Miriad format. It can also be constructed given
00058   // a shape or an N-dim array with values.
00059   // Furthermore it can be constructed from a LEL expression (see class ImageExpr)
00060   // or a vector of images to be concatenated (see class ImageConcat).
00061   //
00062   // Many functions exist to operate on an ImageProxy object. For example:
00063   // <ul>
00064   //  <li> get meta info (shape, data type, coordinates, etc.)
00065   //  <li> save in Casacore, HDF5, or FITS format.
00066   //  <li> regrid.
00067   //  <li> get statistics.
00068   //  <li> form a subimage (which is done in a virtual way).
00069   // </ul>
00070   // Functions regrid and statistics can only be used for Float images.
00071   // They throw an exception for images with other data types.
00072   // Note that using a LEL expression it is possible to (virtually) convert an
00073   // image with another type to a Float image.
00074   // </synopsis>
00075 
00076   class ImageProxy
00077   {
00078   public:
00079     // Default constructor is needed for Boost-Python.
00080     ImageProxy();
00081 
00082     // Construct from the concatenation of the images along the axis.
00083     // The axis must be given as a Fortran-array axis.
00084     // All images must be of the same data type.
00085     ImageProxy (const Vector<String>& names, Int axis);
00086 
00087     // Construct from a string that contains an image name or image expression.
00088     // It is opened using ImageOpener.
00089     ImageProxy (const String& name, const String& mask,
00090                 const vector<ImageProxy>& images);
00091 
00092     // Construct from the concatenation of the image objects along the axis.
00093     // The axis must be given as a Fortran-array axis.
00094     // All images must be of the same data type.
00095     //# The dummy arguments are needed to let all constructors have a
00096     //# different number of arguments (for Boost-Python).
00097     ImageProxy (const vector<ImageProxy>& images, Int axis,
00098                 Int dummy1=0, Int dummy2=0);
00099 
00100     // Construct from a ValueHolder containing an Array of Float or Complex.
00101     // If the name is empty it is created as a temporary image, otherwise
00102     // as a PagedImage or HDF5Image.
00103     // If the coordinates record is empty, default coordinates are used.
00104     // A mask is created if the mask name or mask value is not empty.
00105     ImageProxy (const ValueHolder& values,
00106                 const ValueHolder& mask,
00107                 const Record& coordinates,
00108                 const String& imageName = String(),
00109                 Bool overwrite = True,
00110                 Bool asHDF5 = False,
00111                 const String& maskName = String(),
00112                 const IPosition& tileShape = IPosition());
00113 
00114     // Construct from a shape.
00115     // If the name is empty it is created as a temporary image, otherwise
00116     // as a PagedImage or HDF5Image.
00117     // If the coordinates record is empty, default coordinates are used.
00118     // A mask is created if the mask name is not empty.
00119     ImageProxy (const IPosition& shape,
00120                 const ValueHolder& value,
00121                 const Record& coordinates,
00122                 const String& imageName = String(),
00123                 Bool overwrite = True,
00124                 Bool asHDF5 = False,
00125                 const String& maskName = String(),
00126                 const IPosition& tileShape = IPosition(),
00127                 Int dummy=0);
00128 
00129     // Construct from an existing image object.
00130     ImageProxy (const CountedPtr<LatticeBase>&);
00131 
00132     // Copy constructor (reference semantics).
00133     ImageProxy (const ImageProxy&);
00134 
00135     // Assignment (reference semantics).
00136     ImageProxy& operator= (const ImageProxy&);
00137 
00138      ~ImageProxy();
00139 
00140     // Open the image (which can also be an expression).
00141     // It throws an exception if not succeeded.
00142     static LatticeBase* openImage (const String& name,
00143                                    const String& mask = String(),
00144                                    const vector<ImageProxy>& images = vector<ImageProxy>());
00145 
00146     // Open an image in the file/table with the given name.
00147     // The specified mask will be applied (default is default mask).
00148     // A null pointer is returned for an unknown image type.
00149     // Non-Casacore image types must have been registered to be known.
00150     // If not successful, try to open it as an image expression.
00151     static LatticeBase* openImageOrExpr (const String& str,
00152                                          const MaskSpecifier&,
00153                                          const Block<LatticeExprNode>& nodes);
00154 
00155     // Close the image by setting all pointers to 0.
00156     void close();
00157 
00158     // Turn the ImageProxy into a LatticeExprNode.
00159     LatticeExprNode makeNode() const;
00160 
00161     // Is the image persistent or temporary.
00162     Bool isPersistent() const;
00163 
00164     // Get the name of the image.
00165     String name (Bool stripPath=False) const;
00166 
00167     // Get the shape of the image.
00168     IPosition shape() const;
00169 
00170     // Get the dimensionality of the image.
00171     uInt ndim() const;
00172 
00173     // Get the size of the image (nr of pixels).
00174     uInt size() const;
00175 
00176     // Get the data type of the image.
00177     String dataType() const;
00178 
00179     DataType type() const;
00180 
00181     // Get the image type (PagedImage, HDF5Image, etc.)
00182     String imageType() const;
00183 
00184     // Get a chunk of data.
00185     ValueHolder getData (const IPosition& blc,
00186                          const IPosition& trc, 
00187                          const IPosition& inc);
00188 
00189     // Get a chunk of the mask.
00190     ValueHolder getMask (const IPosition& blc,
00191                          const IPosition& trc, 
00192                          const IPosition& inc);
00193 
00194     // Put a chunk of data.
00195     void putData (const ValueHolder&,
00196                   const IPosition& blc,
00197                   const IPosition& inc);
00198 
00199     // Put a chunk of the mask.
00200     // The mask will be created if not present yet.
00201     // That will not be done if the entire mask is True.
00202     void putMask (const ValueHolder& value,
00203                   const IPosition& blc,
00204                   const IPosition& inc);
00205 
00206     // Does the image have a read or write lock?
00207     Bool hasLock (Bool writeLock = False);
00208 
00209     // Try to acquire a read or write lock.
00210     // nattempts=0 means wait until acquired. Otherwise every second an
00211     // attempt is done.
00212     void lock (Bool writeLock=False, Int nattempts=0);
00213 
00214     // Release the lock acquired by lock().
00215     void unlock();
00216 
00217     // Get the names of the attribute groups.
00218     Vector<String> attrGroupNames() const;
00219 
00220     // Create a new attribute group.
00221     void createAttrGroup (const String& groupName);
00222 
00223     // Get the names of all attributes in a group.
00224     Vector<String> attrNames (const String& groupName) const;
00225 
00226     // Get the number of rows in an attribute group.
00227     uInt attrNrows (const String& groupName) const;
00228 
00229     // Get the value of an attribute in a group row.
00230     ValueHolder getAttr (const String& groupName,
00231                          const String& attrName,
00232                          uInt rownr) const;
00233 
00234     // Get all attributes in a group row.
00235     Record getAttrRow (const String& groupName,
00236                        uInt rownr) const;
00237 
00238     // Get the unit(s) of an attribute in a group.
00239     Vector<String> getAttrUnit(const String& groupName,
00240                                const String& attrName) const;
00241 
00242     // Get the measinfo of an attribute in a group.
00243     Vector<String> getAttrMeas(const String& groupName,
00244                                const String& attrName) const;
00245 
00246     // Put the value, unit, and measinfo of an attribute in a group row.
00247     // The attribute or row is added if new.
00248     void putAttr (const String& groupName, const String& attrName, uInt rownr,
00249                   const ValueHolder& value,
00250                   const Vector<String>& units,
00251                   const Vector<String>& measInfo);
00252 
00253     // Form a new (virtual) image being a subset of the image.
00254     // It uses preserveAxesOrder=False.
00255     ImageProxy subImage (const IPosition& blc,
00256                          const IPosition& trc, 
00257                          const IPosition& inc,
00258                          Bool dropDegenerate=True);
00259     // Same with a new function name for backward compatibility with old pyrap.
00260     ImageProxy subImage2 (const IPosition& blc,
00261                           const IPosition& trc, 
00262                           const IPosition& inc,
00263                           Bool dropDegenerate,
00264                           Bool preserveAxesOrder);
00265 
00266     // Get the brightness unit.
00267     String unit() const;
00268 
00269     // Get the coordinate system.
00270     Record coordSys() const;
00271 
00272     const CoordinateSystem& coordSysObject() const;
00273 
00274     // Convert a pixel coordinate to world coordinate.
00275     // if <src>reverseAxes=True</src> the input and output vector will be
00276     // reversed (as needed for pyrap).
00277     Vector<Double> toWorld (const Vector<Double>& pixel,
00278                             Bool reverseAxes);
00279 
00280     // Convert a world coordinate to pixel coordinate.
00281     // if <src>reverseAxes=True</src> the input and output vector will be
00282     // reversed (as needed for pyrap).
00283     Vector<Double> toPixel (const Vector<Double>& world,
00284                             Bool reverseAxes);
00285 
00286     // Get the image info.
00287     Record imageInfo() const;
00288 
00289     const ImageInfo& imageInfoObject() const;
00290 
00291     // Get the miscellaneous info.
00292     Record miscInfo() const;
00293 
00294     // Get the history.
00295     Vector<String> history() const;
00296 
00297     // Write the image in FITS format.
00298     // See class ImageFITSConverter for a description of the arguments.
00299     // Currently only a float image can be written to FITS.
00300     void toFits (const String& fitsfile, Bool overwrite=True,
00301                  Bool velocity=True, Bool optical=True, Int bitpix=-32,
00302                  Double minpix=1, Double maxpix=-1) const;
00303 
00304     // Write the image to an image file with the given name.
00305     // An exception is thrown if the name is the name of an already open image.
00306     void saveAs (const String& fileName, Bool overwrite=True,
00307                  Bool hdf5=False,
00308                  Bool copyMask=True, const String& newMaskName=String(),
00309                  const IPosition& newTileShape=IPosition()) const;
00310 
00311     // Return the statistics for the given axes.
00312     // E.g., if axes 0,1 is given in a 3-dim image, the statistics are
00313     // calculated for each plane along the 3rd axis.
00314     // MinMaxValues can be given to include or exclude (4th argument) pixels
00315     // with values in the given range. If only one value is given, min=-abs(val)
00316     // and max=abs(val).
00317     // Robust statistics (Median, MedAbsDevMed, and Quartile) can be returned
00318     // too.
00319     Record statistics (const Vector<Int>& axes,
00320                        const String& mask,
00321                        const ValueHolder& minMaxValues,
00322                        Bool exclude = False,
00323                        Bool robust = False) const;
00324 
00325     // Regrid the image on the given axes to the given coordinate system.
00326     // The output is stored in the given file; it no file name is given a
00327     // temporary image is made.
00328     // If the output shape is empty, the old shape is used.
00329     // <src>replicate=True</src> means replication rather than regridding.
00330     ImageProxy regrid (const Vector<Int>& axes = Vector<Int>(),
00331                        const String& outfile = String(),
00332                        Bool overwriteOutFile = True,
00333                        const IPosition& outShape = IPosition(),
00334                        const Record& coordSys = Record(),
00335                        const String& method = "linear",
00336                        Int decimate = 10,
00337                        Bool replicate = False,
00338                        Bool doRefChange = True,
00339                        Bool forceRegrid = False);
00340 
00341     // Check and adjust blc, trc, or inc using the shape.
00342     // <group>
00343     static IPosition adjustBlc (const IPosition& blc, const IPosition& shp);
00344     static IPosition adjustTrc (const IPosition& trc, const IPosition& shp);
00345     static IPosition adjustInc (const IPosition& inc, const IPosition& shp);
00346     // </group>
00347 
00348 
00349     /*
00350 
00351     ImageProxy rotate(const String& outfile, 
00352                       const IPosition& shape, 
00353                       const Quantity& pa, Record& region, 
00354                       const String& mask, 
00355                       const String& method = "cubic", 
00356                       Int decimate = 0, 
00357                       Bool replicate = False, 
00358                       Bool dropdeg = False,
00359                       Bool overwrite = False);
00360 
00361 
00362     Bool setbrightnessunit (const String& unit);
00363 
00364     Bool setcoordsys (const Record& csys);
00365 
00366     Bool sethistory (const String& origin, const Vector<String>& history);
00367 
00368     Bool setmiscinfo (const Record& info);
00369 
00370     ImageProxy subimage(const String& outfile, Record& region, 
00371                         const String& mask, 
00372                         Bool dropdeg = False, 
00373                         Bool overwrite = False, 
00374                         Bool list = True);
00375 
00376     Vector<Double> topixel(Record& value);
00377 
00378     */
00379 
00380     LatticeBase* getLattice() const
00381       { return itsLattice.operator->(); }
00382 
00383  private:
00384     // Form an ImageProxy object from an existing image object.
00385     explicit ImageProxy (LatticeBase*);
00386 
00387     // Throw an exception if the object is null.
00388     void checkNull() const;
00389 
00390     // Make an image from an array or shape.
00391     template<typename T>
00392     void makeImage (const Array<T>& array, const Array<Bool>& mask,
00393                     const IPosition& shape, const Record& coordinates,
00394                     const String& fileName, Bool asHDF5,
00395                     const String& maskName,
00396                     const IPosition& tileShape);
00397 
00398     // Form a concatenated image.
00399     // <group>
00400     void concatImages         (const std::vector<ImageProxy>& images, Int axis);
00401     void concatImagesFloat    (const std::vector<ImageProxy>& images, Int axis);
00402     void concatImagesDouble   (const std::vector<ImageProxy>& images, Int axis);
00403     void concatImagesComplex  (const std::vector<ImageProxy>& images, Int axis);
00404     void concatImagesDComplex (const std::vector<ImageProxy>& images, Int axis);
00405     // </group>
00406 
00407     // Setup the pointers for the various image data types.
00408     void setup();
00409 
00410     // Setup the pointers for the various image data types.
00411     // It takes over the lattice pointer.
00412     void setup (LatticeBase* lattice);
00413 
00414     // Centre all axes except the Stokes one.
00415     void centreRefPix (CoordinateSystem& cSys, 
00416                        const IPosition& shape) const;
00417 
00418     // Put the mask and create it if needed.
00419     template<typename T>
00420     void doPutMask (ImageInterface<T>& image,
00421                     const ValueHolder& value,
00422                     const IPosition& blc,
00423                     const IPosition& inc);
00424 
00425     // Copy the image to an image (PagedImage or HDF5Image) with the given name.
00426     // A new tile shape can be given.
00427     // If the image is masked, the mask can be copied as well.
00428     template <typename T>
00429     void saveImage (const String& fileName,
00430                     Bool hdf5, Bool copyMask,
00431                     const String& newMaskName, 
00432                     const IPosition& newTileShape,
00433                     const ImageInterface<T>& image) const;
00434 
00435     // Form a tiled shape from the current shape and a possible new tile shape.
00436     TiledShape makeTiledShape (const IPosition& newTileShape,
00437                                const IPosition& shape,
00438                                const IPosition& oldTileShape=IPosition()) const;
00439 
00440     // Calculate the statistics.
00441     template<typename T>
00442     Record makeStatistics (const ImageInterface<T>& image,
00443                            const Vector<Int>& axes,
00444                            const String& mask,
00445                            const ValueHolder& minMaxValues,
00446                            Bool exclude,
00447                            Bool robust) const;
00448 
00449     // Do the actual regridding.
00450     template<typename T>
00451     ImageProxy doRegrid (const ImageInterface<T>& image,
00452                          const Vector<Int>& axes,
00453                          const String& outfile,
00454                          const IPosition& shape,
00455                          const Record& coordSys,
00456                          const String& method,
00457                          Int decimate,
00458                          Bool replicate, 
00459                          Bool doRefChange,
00460                          Bool force);
00461 
00462     // Make a coordinate system from the Record.
00463     // The cylindrical fix is applied if needed.
00464     CoordinateSystem makeCoordinateSystem (const Record& coordinates,
00465                                            const IPosition& shape) const;
00466 
00467 
00468     //# Data members.
00469     //# itsLattice is the real data; the pointers are for type convenience only.
00470     CountedPtr<LatticeBase>   itsLattice;
00471     ImageInterface<Float>*    itsImageFloat;
00472     ImageInterface<Double>*   itsImageDouble;
00473     ImageInterface<Complex>*  itsImageComplex;
00474     ImageInterface<DComplex>* itsImageDComplex;
00475     const CoordinateSystem*   itsCoordSys;
00476     ImageAttrHandler*         itsAttrHandler;
00477   };
00478 
00479 } // end namespace casacore
00480 
00481 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1