casacore
TiledCellStMan.h
Go to the documentation of this file.
1 //# TiledCellStMan.h: Tiled Cell Storage Manager
2 //# Copyright (C) 1995,1996,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 TABLES_TILEDCELLSTMAN_H
29 #define TABLES_TILEDCELLSTMAN_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/DataMan/TiledStMan.h>
35 #include <casacore/casa/Arrays/IPosition.h>
36 #include <casacore/casa/BasicSL/String.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 
42 
43 // <summary>
44 // Tiled Cell Storage Manager.
45 // </summary>
46 
47 // <use visibility=export>
48 
49 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
50 // </reviewed>
51 
52 // <prerequisite>
53 //# Classes you should understand before using this one.
54 // <li> <linkto class=TiledStMan>TiledStMan</linkto>
55 // <li> <linkto class=TSMCube>TSMCube</linkto>
56 // <li> <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
57 // for a discussion of the maximum cache size
58 // </prerequisite>
59 
60 // <etymology>
61 // TiledCellStMan is the Tiled Storage Manager storing
62 // each cell as a separate hypercube.
63 // </etymology>
64 
65 // <synopsis>
66 // TiledCellStMan is a derivation from TiledStMan, the abstract
67 // tiled storage manager class. A description of the basics
68 // of tiled storage managers is given in the
69 // <linkto module=Tables:TiledStMan>Tables module</linkto> description.
70 // <p>
71 // TiledCellStMan allows the user to create a tiled hypercube for
72 // each data cell in an automatic way. It is meant to be used for
73 // storing regularly shaped data like images (where the table contains
74 // a possibly differently shaped image in each row).
75 // <p>
76 // The TiledCellStMan has the following (extra) properties:
77 // <ul>
78 // <li> Addition of a row results in the addition of a hypercube in
79 // which the data cells in that row will be stored. Thus each row
80 // of the hypercolumn is stored in its own hypercube.
81 // Note that a hypercolumn has a given dimensionality, so each
82 // data cell in the hypercolumn has to match that dimensionality.
83 // <li> Although there are multiple hypercubes, an id value is not needed.
84 // The row number serves as the id value.
85 // <li> Coordinates for the hypercubes can be defined and (of course)
86 // their shapes have to match the hypercube shape.
87 // Their values have to be put explicitly (so it is not possible
88 // to define them via an addHypercube call like in
89 // <linkto class=TiledDataStMan>TiledDataStMan</linkto>).
90 // <li> It is possible to define a (default) tile shape in the
91 // TiledCellStMan constructor. When setting the shape of the
92 // array in a row (using <linkto class=ArrayColumn>
93 // ArrayColumn::setShape</linkto>), it is possible to override
94 // that default for the hypercube in this particular row.
95 // </ul>
96 // </synopsis>
97 
98 // <motivation>
99 // This tiled storage manager does not require any special action
100 // (like calling add/extendHypercube) when used with a column
101 // containing variable shaped arrays.
102 // </motivation>
103 
104 // <example>
105 // <srcblock>
106 // // Define the table description and the columns in it.
107 // TableDesc td ("", "1", TableDesc::Scratch);
108 // td.addColumn (ArrayColumnDesc<float> ("RA", 1));
109 // td.addColumn (ArrayColumnDesc<float> ("Dec", 1));
110 // td.addColumn (ArrayColumnDesc<float> ("Velocity", 1));
111 // td.addColumn (ArrayColumnDesc<float> ("Image", 3));
112 // // Define the 3-dim hypercolumn with its data and coordinate columns.
113 // // Note that its dimensionality must match the dimensionality
114 // // of the data cells.
115 // td.defineHypercolumn ("TSMExample",
116 // 3,
117 // stringToVector ("Image"),
118 // stringToVector ("RA,Dec,Velocity"));
119 // // Now create a new table from the description.
120 // SetupNewTable newtab("tTiledCellStMan_tmp.data", td, Table::New);
121 // // Create a TiledCellStMan storage manager for the hypercolumn
122 // // and bind the columns to it.
123 // TiledCellStMan sm1 ("TSMExample");
124 // newtab.bindAll (sm1);
125 // // Create the table.
126 // Table table(newtab);
127 // // Define the values for the coordinates of the hypercube.
128 // Vector<float> raValues(512);
129 // Vector<float> DecValues(512);
130 // Vector<float> VelocityValues(64);
131 // indgen (raValues);
132 // indgen (decValues, float(100));
133 // indgen (velocityValues, float(200));
134 // ArrayColumn<float> ra (table, "RA");
135 // ArrayColumn<float> dec (table, "Dec");
136 // ArrayColumn<float> velocity (table, "Velocity");
137 // ArrayColumn<float> image (table, "Image");
138 // Cube<float> imageValues(IPosition(3,512,512,64));
139 // indgen (imageValues);
140 // // Write some data into the data columns.
141 // uInt i;
142 // for (i=0; i<4; i++) {
143 // table.addRow();
144 // image.put (i, imageValues);
145 // ra.put (i, raValues);
146 // dec.put (i, decValues);
147 // velocity.put (i, velocityValues);
148 // }
149 // </srcblock>
150 // </example>
151 
152 //# <todo asof="$DATE:$">
153 //# A List of bugs, limitations, extensions or planned refinements.
154 //# </todo>
155 
156 
158 {
159 public:
160  // Create a TiledDataStMan storage manager for the hypercolumn
161  // with the given name. The columns used should have the FixedShape
162  // attribute set.
163  // The hypercolumn name is also the name of the storage manager.
164  // The given tile shape will be used as the default for the hypercube
165  // in each cell. Per cell it can be redefined via ArrayColumn::setShape.
166  // The given maximum cache size (default is unlimited) is persistent,
167  // thus will be reused when the table is read back. Note that the class
168  // <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
169  // allows one to overwrite the maximum cache size temporarily.
170  // Its description contains a discussion about the effects of
171  // setting a maximum cache.
172  // <br>The constructor taking a Record expects fields in the record with
173  // the name of the arguments in uppercase. If not defined, their
174  // default value is used.
175  // <group>
176  TiledCellStMan (const String& hypercolumnName,
178  uInt maximumCacheSize = 0);
179  TiledCellStMan (const String& hypercolumnName,
180  const Record& spec);
181  // </group>
182 
183  ~TiledCellStMan();
184 
185  // Clone this object.
186  // It does not clone TSMColumn objects possibly used.
187  DataManager* clone() const;
188 
189  // Get the type name of the data manager (i.e. TiledCellStMan).
190  String dataManagerType() const;
191 
192  // This tiled storage manager can handle changing array shapes.
193  Bool canChangeShape() const;
194 
195  // Set the shape and tile shape of the hypercube.
196  virtual void setShape (uInt rownr, TSMCube* hypercube,
197  const IPosition& shape,
198  const IPosition& tileShape);
199 
200  // Make the object from the type name string.
201  // This function gets registered in the DataManager "constructor" map.
202  static DataManager* makeObject (const String& dataManagerType,
203  const Record& spec);
204 
205 private:
206  // Create a TiledCellStMan.
207  // This constructor is private, because it should only be used
208  // by makeObject.
209  TiledCellStMan();
210 
211  // Forbid copy constructor.
213 
214  // Forbid assignment.
216 
217  // Get the default tile shape.
218  virtual IPosition defaultTileShape() const;
219 
220  // Add rows to the storage manager.
221  void addRow (uInt nrrow);
222 
223  // Get the hypercube in which the given row is stored.
224  virtual TSMCube* getHypercube (uInt rownr);
225 
226  // Get the hypercube in which the given row is stored.
227  // It also returns the position of the row in that hypercube.
228  virtual TSMCube* getHypercube (uInt rownr, IPosition& position);
229 
230  // Check if the hypercolumn definition fits this storage manager.
231  virtual void setupCheck (const TableDesc& tableDesc,
232  const Vector<String>& dataNames) const;
233 
234  // Flush and optionally fsync the data.
235  // It returns a True status if it had to flush (i.e. if data have changed).
236  virtual Bool flush (AipsIO&, Bool fsync);
237 
238  // Let the storage manager create files as needed for a new table.
239  // This allows a column with an indirect array to create its file.
240  virtual void create (uInt nrrow);
241 
242  // Read the header info.
243  virtual void readHeader (uInt nrrow, Bool firstTime);
244 
245 
246  //# Declare the data members.
248 };
249 
250 
251 
252 
253 } //# NAMESPACE CASACORE - END
254 
255 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
Tiled hypercube in a table.
Definition: TSMCube.h:105
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
virtual void setShape(uInt rownr, TSMCube *hypercube, const IPosition &shape, const IPosition &tileShape)
Set the shape and tile shape of the hypercube.
Base class for Tiled Storage Manager classes.
Definition: TiledStMan.h:107
TiledCellStMan()
Create a TiledCellStMan.
const IPosition & tileShape(uInt rownr) const
Get the tile shape of the data in the given row.
Tiled Cell Storage Manager.
virtual void create(uInt nrrow)
Let the storage manager create files as needed for a new table.
virtual Bool flush(AipsIO &, Bool fsync)
Flush and optionally fsync the data.
virtual void readHeader(uInt nrrow, Bool firstTime)
Read the header info.
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual TSMCube * getHypercube(uInt rownr)
Get the hypercube in which the given row is stored.
TiledCellStMan & operator=(const TiledCellStMan &)
Forbid assignment.
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1944
DataManager * clone() const
Clone this object.
Abstract base class for a data manager.
Definition: DataManager.h:224
virtual void setupCheck(const TableDesc &tableDesc, const Vector< String > &dataNames) const
Check if the hypercolumn definition fits this storage manager.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Make the object from the type name string.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Define the structure of a Casacore table.
Definition: TableDesc.h:187
Bool canChangeShape() const
This tiled storage manager can handle changing array shapes.
String dataManagerType() const
Get the type name of the data manager (i.e.
virtual IPosition defaultTileShape() const
Get the default tile shape.
void addRow(uInt nrrow)
Add rows to the storage manager.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
uInt maximumCacheSize() const
Get the current maximum cache size (in MiB (MibiByte)).
Definition: TiledStMan.h:533