casacore
TiledShape.h
Go to the documentation of this file.
1 //# TiledShape.h: Define the shape and tile shape
2 //# Copyright (C) 1997,1998,1999,2001
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 LATTICES_TILEDSHAPE_H
29 #define LATTICES_TILEDSHAPE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/IPosition.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 template<class T> class Vector;
39 
40 
41 // <summary>
42 // Define the shape and tile shape
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTiledShape.cc">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> <linkto class=IPosition>IPosition</linkto>
52 // </prerequisite>
53 
54 // <etymology>
55 // TiledShape defines the shape and tile shape of a tiled array.
56 // </etymology>
57 
58 // <synopsis>
59 // TiledShape is a class defining the shape and optionally the tile
60 // shape of a lattice. It is used in the constructors of
61 // <linkto class=PagedArray>PagedArray</linkto> and
62 // <linkto class=PagedImage>PagedImage</linkto>.
63 // <p>
64 // In principle it serves as a place holder for the lattice shape and
65 // tile shape. The functions <src>shape</src> and <src>tileShape</src>
66 // can be used to retrieve the shapes.
67 // However, when the tile shape is not given, the function
68 // <src>tileShape</src> calculates a default tile shape using the
69 // given maximum tile size in pixel elements. The default tile shape
70 // is calculated in such a way that the sizes of its axes
71 // are proportional to the sizes of the lattice axes. Per axis it is
72 // tried as much as possible to fit an integral number of tiles
73 // in the lattice.
74 // <br>In this way getting the tile shape is completely transparent.
75 // </synopsis>
76 
77 // <example>
78 // <srcblock>
79 // // Do not explicitly define a tile shape.
80 // // This results in a default tile shape (of 32,32,32).
81 // TiledShape shape(IPosition(3,128,128,128));
82 // cout << shape.shape() << ' ' << shape.tileShape() << endl;
83 //
84 // // Use with an explicitly given tile shape.
85 // TiledShape shape(IPosition(3,128,128,128), IPosition(3,64,32,8));
86 // cout << shape.shape() << ' ' << shape.tileShape() << endl;
87 // </srcblock>
88 // </example>
89 
90 // <motivation>
91 // Classes <src>PagedArray</src> and <src>PagedImage</src> contained
92 // several duplicated constructors to be able to pass a tile shape.
93 // This class makes it possible to have only one constructor
94 // instead of two. Furthermore it contains the logic to check if the
95 // shapes are conforming and the logic to calculate a default tile shape.
96 // </motivation>
97 
98 
100 {
101 public:
102  // Default constructor has empty shape and tile shape.
103  TiledShape();
104 
105  // Use the given shape.
106  // No tile shape is given, so function <src>tileShape</src>
107  // will calculate it using the size of a tile.
108  TiledShape (const IPosition& shape);
109 
110  // Use the given shape and tile shape.
111  // Both shapes must be conforming (i.e. have same number of elements).
112  TiledShape (const IPosition& shape, const IPosition& tileShape);
113 
114  // Copy constructor (copy semantics).
115  TiledShape (const TiledShape& that);
116 
117  ~TiledShape();
118 
119  // Assignment (copy semantics).
120  TiledShape& operator= (const TiledShape& that);
121 
122  // Is the tile shape defined?
123  Bool isTileShapeDefined() const;
124 
125  // Return the shape.
126  const IPosition& shape() const;
127 
128  // Return the tile shape.
129  // When the tile shape is undefined, the default tile shape will be
130  // calculated using the given tile size and tolerance.
131  // <br> The tolerance is used to determine the boundaries where
132  // it is tried to fit an integral number of tiles.
133  IPosition tileShape (uInt nrPixelsPerTile = 32768,
134  Double tolerance = 0.5) const;
135 
136  // Derive the default tile shape from the shape for the given
137  // number of pixels per tile. It is tried to get the same number
138  // of tiles for each dimension.
139  // When a weight vector is given, the number of tiles for a dimension
140  // is proportional to the weight.
141  // <br>After the initial guess it tries to optimize it by trying to
142  // waste as little space as possible, while trying to keep as close as
143  // possible to the initial guess. The given tolerance (possibly per axis)
144  // gives the minimum and maximum possible length of a tile axis
145  // (minimum = initial_guess*tolerance; maximum = initial_guess/tolerance).
146  // The heuristic is such that a tile axis length dividing the cube length
147  // exactly is always favoured.
148  // The test program <src>tTiledShape</src> can be used to see how
149  // the algorithm works out for a given shape and tile size.
150  // <group>
151  IPosition defaultTileShape (uInt nrPixelsPerTile, Double tolerance) const;
152  IPosition defaultTileShape (uInt nrPixelsPerTile,
153  const Vector<Double>& tolerance,
154  const Vector<Double>& weight) const;
155  // </group>
156 
157 private:
161 };
162 
163 
165 {
166  return itsTileDefined;
167 }
168 inline const IPosition& TiledShape::shape() const
169 {
170  return itsShape;
171 }
172 inline IPosition TiledShape::tileShape (uInt nrPixelsPerTile,
173  Double tolerance) const
174 {
175  return (itsTileDefined ? itsTileShape :
176  defaultTileShape (nrPixelsPerTile, tolerance));
177 }
178 
179 
180 
181 } //# NAMESPACE CASACORE - END
182 
183 #endif
IPosition defaultTileShape(uInt nrPixelsPerTile, Double tolerance) const
Derive the default tile shape from the shape for the given number of pixels per tile.
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
IPosition tileShape(uInt nrPixelsPerTile=32768, Double tolerance=0.5) const
Return the tile shape.
Definition: TiledShape.h:172
const IPosition & shape() const
Return the shape.
Definition: TiledShape.h:168
Define the shape and tile shape.
Definition: TiledShape.h:99
TiledShape()
Default constructor has empty shape and tile shape.
double Double
Definition: aipstype.h:55
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
IPosition itsTileShape
Definition: TiledShape.h:159
TiledShape & operator=(const TiledShape &that)
Assignment (copy semantics).
Bool isTileShapeDefined() const
Is the tile shape defined?
Definition: TiledShape.h:164
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51