TiledShape.h

Go to the documentation of this file.
00001 //# TiledShape.h: Define the shape and tile shape
00002 //# Copyright (C) 1997,1998,1999,2001
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 //# $Id$
00027 
00028 #ifndef LATTICES_TILEDSHAPE_H
00029 #define LATTICES_TILEDSHAPE_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/casa/Arrays/IPosition.h>
00034 
00035 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00036 
00037 //# Forward Declarations
00038 template<class T> class Vector;
00039 
00040 
00041 // <summary>
00042 // Define the shape and tile shape
00043 // </summary>
00044 
00045 // <use visibility=export>
00046 
00047 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTiledShape.cc">
00048 // </reviewed>
00049 
00050 // <prerequisite>
00051 //  <li> <linkto class=IPosition>IPosition</linkto>
00052 // </prerequisite>
00053 
00054 // <etymology>
00055 // TiledShape defines the shape and tile shape of a tiled array.
00056 // </etymology>
00057 
00058 // <synopsis> 
00059 // TiledShape is a class defining the shape and optionally the tile
00060 // shape of a lattice. It is used in the constructors of
00061 // <linkto class=PagedArray>PagedArray</linkto> and
00062 // <linkto class=PagedImage>PagedImage</linkto>.
00063 // <p>
00064 // In principle it serves as a place holder for the lattice shape and
00065 // tile shape. The functions <src>shape</src> and <src>tileShape</src>
00066 // can be used to retrieve the shapes.
00067 // However, when the tile shape is not given, the function
00068 // <src>tileShape</src> calculates a default tile shape using the
00069 // given maximum tile size in pixel elements. The default tile shape
00070 // is calculated in such a way that the sizes of its axes
00071 // are proportional to the sizes of the lattice axes. Per axis it is
00072 // tried as much as possible to fit an integral number of tiles
00073 // in the lattice.
00074 // <br>In this way getting the tile shape is completely transparent.
00075 // </synopsis>
00076 
00077 // <example>
00078 // <srcblock>
00079 // // Do not explicitly define a tile shape.
00080 // // This results in a default tile shape (of 32,32,32).
00081 // TiledShape shape(IPosition(3,128,128,128));
00082 // cout << shape.shape() << ' ' << shape.tileShape() << endl;
00083 //
00084 // // Use with an explicitly given tile shape.
00085 // TiledShape shape(IPosition(3,128,128,128), IPosition(3,64,32,8));
00086 // cout << shape.shape() << ' ' << shape.tileShape() << endl;
00087 // </srcblock>
00088 // </example>
00089 
00090 // <motivation>
00091 // Classes <src>PagedArray</src> and <src>PagedImage</src> contained
00092 // several duplicated constructors to be able to pass a tile shape.
00093 // This class makes it possible to have only one constructor
00094 // instead of two. Furthermore it contains the logic to check if the
00095 // shapes are conforming and the logic to calculate a default tile shape.
00096 // </motivation>
00097 
00098 
00099 class TiledShape
00100 {
00101 public:
00102     // Default constructor has empty shape and tile shape.
00103     TiledShape();
00104 
00105     // Use the given shape.
00106     // No tile shape is given, so function <src>tileShape</src>
00107     // will calculate it using the size of a tile.
00108     TiledShape (const IPosition& shape);
00109 
00110     // Use the given shape and tile shape.
00111     // Both shapes must be conforming (i.e. have same number of elements).
00112     TiledShape (const IPosition& shape, const IPosition& tileShape);
00113 
00114     // Copy constructor (copy semantics).
00115     TiledShape (const TiledShape& that);
00116 
00117     ~TiledShape();
00118 
00119     // Assignment (copy semantics).
00120     TiledShape& operator= (const TiledShape& that);
00121 
00122     // Is the tile shape defined?
00123     Bool isTileShapeDefined() const;
00124 
00125     // Return the shape.
00126     const IPosition& shape() const;
00127 
00128     // Return the tile shape.
00129     // When the tile shape is undefined, the default tile shape will be
00130     // calculated using the given tile size and tolerance.
00131     // <br> The tolerance is used to determine the boundaries where
00132     // it is tried to fit an integral number of tiles.
00133     IPosition tileShape (uInt nrPixelsPerTile = 32768,
00134                          Double tolerance = 0.5) const;
00135 
00136     // Derive the default tile shape from the shape for the given
00137     // number of pixels per tile. It is tried to get the same number
00138     // of tiles for each dimension.
00139     // When a weight vector is given, the number of tiles for a dimension
00140     // is proportional to the weight.
00141     // <br>After the initial guess it tries to optimize it by trying to
00142     // waste as little space as possible, while trying to keep as close as
00143     // possible to the initial guess. The given tolerance (possibly per axis)
00144     // gives the minimum and maximum possible length of a tile axis
00145     // (minimum = initial_guess*tolerance; maximum = initial_guess/tolerance).
00146     // The heuristic is such that a tile axis length dividing the cube length
00147     // exactly is always favoured.
00148     // The test program <src>tTiledShape</src> can be used to see how
00149     // the algorithm works out for a given shape and tile size.
00150     // <group>
00151     IPosition defaultTileShape (uInt nrPixelsPerTile, Double tolerance) const;
00152     IPosition defaultTileShape (uInt nrPixelsPerTile,
00153                                 const Vector<Double>& tolerance,
00154                                 const Vector<Double>& weight) const;
00155     // </group>
00156 
00157 private:
00158     IPosition itsShape;
00159     IPosition itsTileShape;
00160     Bool      itsTileDefined;
00161 };
00162 
00163 
00164 inline Bool TiledShape::isTileShapeDefined() const
00165 {
00166     return itsTileDefined;
00167 }
00168 inline const IPosition& TiledShape::shape() const
00169 {
00170     return itsShape;
00171 }
00172 inline IPosition TiledShape::tileShape (uInt nrPixelsPerTile,
00173                                         Double tolerance) const
00174 {
00175     return (itsTileDefined  ?  itsTileShape :
00176                                defaultTileShape (nrPixelsPerTile, tolerance));
00177 }
00178 
00179 
00180 
00181 } //# NAMESPACE CASACORE - END
00182 
00183 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1