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