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 // for (uInt i=0; i<4; i++) {
142 // table.addRow();
143 // image.put (i, imageValues);
144 // ra.put (i, raValues);
145 // dec.put (i, decValues);
146 // velocity.put (i, velocityValues);
147 // }
148 // </srcblock>
149 // </example>
150 
151 //# <todo asof="$DATE:$">
152 //# A List of bugs, limitations, extensions or planned refinements.
153 //# </todo>
154 
155 
157 {
158 public:
159  // Create a TiledDataStMan storage manager for the hypercolumn
160  // with the given name. The columns used should have the FixedShape
161  // attribute set.
162  // The hypercolumn name is also the name of the storage manager.
163  // The given tile shape will be used as the default for the hypercube
164  // in each cell. Per cell it can be redefined via ArrayColumn::setShape.
165  // The given maximum cache size (default is unlimited) is persistent,
166  // thus will be reused when the table is read back. Note that the class
167  // <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
168  // allows one to overwrite the maximum cache size temporarily.
169  // Its description contains a discussion about the effects of
170  // setting a maximum cache.
171  // <br>The constructor taking a Record expects fields in the record with
172  // the name of the arguments in uppercase. If not defined, their
173  // default value is used.
174  // <group>
175  TiledCellStMan (const String& hypercolumnName,
178  TiledCellStMan (const String& hypercolumnName,
179  const Record& spec);
180  // </group>
181 
183 
184  // Clone this object.
185  // It does not clone TSMColumn objects possibly used.
186  DataManager* clone() const;
187 
188  // Get the type name of the data manager (i.e. TiledCellStMan).
190 
191  // This tiled storage manager can handle changing array shapes.
193 
194  // Set the shape and tile shape of the hypercube.
195  virtual void setShape (rownr_t rownr, TSMCube* hypercube,
196  const IPosition& shape,
197  const IPosition& tileShape);
198 
199  // Make the object from the type name string.
200  // This function gets registered in the DataManager "constructor" map.
202  const Record& spec);
203 
204 private:
205  // Create a TiledCellStMan.
206  // This constructor is private, because it should only be used
207  // by makeObject.
209 
210  // Forbid copy constructor.
212 
213  // Forbid assignment.
215 
216  // Get the default tile shape.
217  virtual IPosition defaultTileShape() const;
218 
219  // Add rows to the storage manager.
220  void addRow64 (rownr_t nrrow);
221 
222  // Get the hypercube in which the given row is stored.
223  virtual TSMCube* getHypercube (rownr_t rownr);
224 
225  // Get the hypercube in which the given row is stored.
226  // It also returns the position of the row in that hypercube.
227  virtual TSMCube* getHypercube (rownr_t rownr, IPosition& position);
228 
229  // Check if the hypercolumn definition fits this storage manager.
230  virtual void setupCheck (const TableDesc& tableDesc,
231  const Vector<String>& dataNames) const;
232 
233  // Flush and optionally fsync the data.
234  // It returns a True status if it had to flush (i.e. if data have changed).
235  virtual Bool flush (AipsIO&, Bool fsync);
236 
237  // Let the storage manager create files as needed for a new table.
238  // This allows a column with an indirect array to create its file.
239  virtual void create64 (rownr_t nrrow);
240 
241  // Read the header info.
242  virtual void readHeader (rownr_t nrrow, Bool firstTime);
243 
244 
245  //# Declare the data members.
247 };
248 
249 
250 
251 
252 } //# NAMESPACE CASACORE - END
253 
254 #endif
Abstract base class for a data manager.
Definition: DataManager.h:221
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual Bool flush(AipsIO &, Bool fsync)
Flush and optionally fsync the data.
virtual void setupCheck(const TableDesc &tableDesc, const Vector< String > &dataNames) const
Check if the hypercolumn definition fits this storage manager.
virtual void create64(rownr_t nrrow)
Let the storage manager create files as needed for a new table.
TiledCellStMan(const String &hypercolumnName, const Record &spec)
virtual IPosition defaultTileShape() const
Get the default tile shape.
TiledCellStMan()
Create a TiledCellStMan.
DataManager * clone() const
Clone this object.
virtual TSMCube * getHypercube(rownr_t rownr, IPosition &position)
Get the hypercube in which the given row is stored.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Make the object from the type name string.
virtual TSMCube * getHypercube(rownr_t rownr)
Get the hypercube in which the given row is stored.
void addRow64(rownr_t nrrow)
Add rows to the storage manager.
TiledCellStMan(const TiledCellStMan &)
Forbid copy constructor.
TiledCellStMan(const String &hypercolumnName, const IPosition &defaultTileShape, uInt64 maximumCacheSize=0)
Create a TiledDataStMan storage manager for the hypercolumn with the given name.
String dataManagerType() const
Get the type name of the data manager (i.e.
virtual void readHeader(rownr_t nrrow, Bool firstTime)
Read the header info.
Bool canChangeShape() const
This tiled storage manager can handle changing array shapes.
TiledCellStMan & operator=(const TiledCellStMan &)
Forbid assignment.
virtual void setShape(rownr_t rownr, TSMCube *hypercube, const IPosition &shape, const IPosition &tileShape)
Set the shape and tile shape of the hypercube.
uInt maximumCacheSize() const
Get the current maximum cache size (in MiB (MibiByte)).
Definition: TiledStMan.h:532
const IPosition & tileShape(rownr_t rownr) const
Get the tile shape of the data in the given row.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46
unsigned long long uInt64
Definition: aipsxtype.h:39