TiledShape.h

Go to the documentation of this file.

// # TiledShape.h: Define the shape and tile shape
// # Copyright (C) 1997,1998,1999,2001
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef LATTICES_TILEDSHAPE_H
#define LATTICES_TILEDSHAPE_H
 
// # Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/ArrayFwd.h>
#include <casacore/casa/Arrays/IPosition.h>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// <summary>
// Define the shape and tile shape
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTiledShape.cc">
// </reviewed>
 
// <prerequisite>
//  <li> <linkto class=IPosition>IPosition</linkto>
// </prerequisite>
 
// <etymology>
// TiledShape defines the shape and tile shape of a tiled array.
// </etymology>
 
// <synopsis>
// TiledShape is a class defining the shape and optionally the tile
// shape of a lattice. It is used in the constructors of
// <linkto class=PagedArray>PagedArray</linkto> and
// <linkto class=PagedImage>PagedImage</linkto>.
// <p>
// In principle it serves as a place holder for the lattice shape and
// tile shape. The functions <src>shape</src> and <src>tileShape</src>
// can be used to retrieve the shapes.
// However, when the tile shape is not given, the function
// <src>tileShape</src> calculates a default tile shape using the
// given maximum tile size in pixel elements. The default tile shape
// is calculated in such a way that the sizes of its axes
// are proportional to the sizes of the lattice axes. Per axis it is
// tried as much as possible to fit an integral number of tiles
// in the lattice.
// <br>In this way getting the tile shape is completely transparent.
// </synopsis>
 
// <example>
// <srcblock>
// // Do not explicitly define a tile shape.
// // This results in a default tile shape (of 32,32,32).
// TiledShape shape(IPosition(3,128,128,128));
// cout << shape.shape() << ' ' << shape.tileShape() << endl;
//
// // Use with an explicitly given tile shape.
// TiledShape shape(IPosition(3,128,128,128), IPosition(3,64,32,8));
// cout << shape.shape() << ' ' << shape.tileShape() << endl;
// </srcblock>
// </example>
 
// <motivation>
// Classes <src>PagedArray</src> and <src>PagedImage</src> contained
// several duplicated constructors to be able to pass a tile shape.
// This class makes it possible to have only one constructor
// instead of two. Furthermore it contains the logic to check if the
// shapes are conforming and the logic to calculate a default tile shape.
// </motivation>
 
class TiledShape {
 public:
  // Default constructor has empty shape and tile shape.
  TiledShape();
 
  // Use the given shape.
  // No tile shape is given, so function <src>tileShape</src>
  // will calculate it using the size of a tile.
  TiledShape(const IPosition& shape);
 
  // Use the given shape and tile shape.
  // Both shapes must be conforming (i.e. have same number of elements).
  TiledShape(const IPosition& shape, const IPosition& tileShape);
 
  // Copy constructor (copy semantics).
  TiledShape(const TiledShape& that);
 
  ~TiledShape();
 
  // Assignment (copy semantics).
  TiledShape& operator=(const TiledShape& that);
 
  // Is the tile shape defined?
  Bool isTileShapeDefined() const;
 
  // Return the shape.
  const IPosition& shape() const;
 
  // Return the tile shape.
  // When the tile shape is undefined, the default tile shape will be
  // calculated using the given tile size and tolerance.
  // <br> The tolerance is used to determine the boundaries where
  // it is tried to fit an integral number of tiles.
  IPosition tileShape(uInt nrPixelsPerTile = 32768, Double tolerance = 0.5) const;
 
  // Derive the default tile shape from the shape for the given
  // number of pixels per tile. It is tried to get the same number
  // of tiles for each dimension.
  // When a weight vector is given, the number of tiles for a dimension
  // is proportional to the weight.
  // <br>After the initial guess it tries to optimize it by trying to
  // waste as little space as possible, while trying to keep as close as
  // possible to the initial guess. The given tolerance (possibly per axis)
  // gives the minimum and maximum possible length of a tile axis
  // (minimum = initial_guess*tolerance; maximum = initial_guess/tolerance).
  // The heuristic is such that a tile axis length dividing the cube length
  // exactly is always favoured.
  // The test program <src>tTiledShape</src> can be used to see how
  // the algorithm works out for a given shape and tile size.
  // <group>
  IPosition defaultTileShape(uInt nrPixelsPerTile, Double tolerance) const;
  IPosition defaultTileShape(uInt nrPixelsPerTile, const Vector<Double>& tolerance,
                             const Vector<Double>& weight) const;
  // </group>
 
 private:
  IPosition itsShape;
  IPosition itsTileShape;
  Bool itsTileDefined;
};
 
inline Bool TiledShape::isTileShapeDefined() const { return itsTileDefined; }
inline const IPosition& TiledShape::shape() const { return itsShape; }
inline IPosition TiledShape::tileShape(uInt nrPixelsPerTile, Double tolerance) const {
  return (itsTileDefined ? itsTileShape : defaultTileShape(nrPixelsPerTile, tolerance));
}
 
}  // namespace casacore
 
#endif