casacore
Loading...
Searching...
No Matches
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/ArrayFwd.h>
34#include <casacore/casa/Arrays/IPosition.h>
35
36namespace 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{
98public:
99 // Default constructor has empty shape and tile shape.
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.
106
107 // Use the given shape and tile shape.
108 // Both shapes must be conforming (i.e. have same number of elements).
110
111 // Copy constructor (copy semantics).
112 TiledShape (const TiledShape& that);
113
115
116 // Assignment (copy semantics).
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;
150 const Vector<Double>& tolerance,
151 const Vector<Double>& weight) const;
152 // </group>
153
154private:
158};
159
160
162{
163 return itsTileDefined;
164}
165inline const IPosition& TiledShape::shape() const
166{
167 return itsShape;
168}
169inline 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
TiledShape()
Default constructor has empty shape and tile shape.
IPosition tileShape(uInt nrPixelsPerTile=32768, Double tolerance=0.5) const
Return the tile shape.
Definition TiledShape.h:169
TiledShape(const IPosition &shape)
Use the given shape.
TiledShape(const TiledShape &that)
Copy constructor (copy semantics).
TiledShape & operator=(const TiledShape &that)
Assignment (copy semantics).
Bool isTileShapeDefined() const
Is the tile shape defined?
Definition TiledShape.h:161
IPosition defaultTileShape(uInt nrPixelsPerTile, Double tolerance) const
Derive the default tile shape from the shape for the given number of pixels per tile.
const IPosition & shape() const
Return the shape.
Definition TiledShape.h:165
TiledShape(const IPosition &shape, const IPosition &tileShape)
Use the given shape and tile shape.
IPosition defaultTileShape(uInt nrPixelsPerTile, const Vector< Double > &tolerance, const Vector< Double > &weight) const
this file contains all the compiler specific defines
Definition mainpage.dox:28
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
double Double
Definition aipstype.h:55