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