casacore
ScaledArrayEngine.h
Go to the documentation of this file.
1 //# ScaledArrayEngine.h: Templated virtual column engine to scale a table array
2 //# Copyright (C) 1994,1995,1996,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_SCALEDARRAYENGINE_H
29 #define TABLES_SCALEDARRAYENGINE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/DataMan/BaseMappedArrayEngine.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 template<class T> class ScalarColumn;
39 
40 
41 
42 // <summary>
43 // Templated virtual column engine to scale a table array
44 // </summary>
45 
46 // <use visibility=export>
47 
48 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
49 // </reviewed>
50 
51 // <prerequisite>
52 //# Classes you should understand before using this one.
53 // <li> VirtualColumnEngine
54 // <li> VirtualArrayColumn
55 // </prerequisite>
56 
57 // <synopsis>
58 // ScaledArrayEngine is a virtual column engine which scales an array
59 // of one type to another type to save disk storage.
60 // This resembles the classic AIPS compress method which scales the
61 // data from float to short.
62 // The scale factor and offset value can be given in two ways:
63 // <ul>
64 // <li> As a fixed value which is used for all arrays in the column.
65 // <li> As the name of a column. In this way each array in a
66 // column can have its own scale and offset value.
67 // The scale and offset value in a row must be put before
68 // the array is put and should not be changed anymore.
69 // </ul>
70 // It is also possible to have a variable scale factor with a fixed offset
71 // value.
72 // As in FITS the scale and offset values are used as:
73 // <br><src> True_value = Stored_value * scale + offset; </src>
74 //
75 // An engine object should be used for one column only, because the stored
76 // column name is part of the engine. If it would be used for more than
77 // one column, they would all share the same stored column.
78 // When the engine is bound to a column, it is checked if the name
79 // of that column matches the given virtual column name.
80 //
81 // The engine can be used for a column containing any kind of array
82 // (thus direct or indirect, fixed or variable shaped)) as long as the
83 // virtual array can be stored in the stored array. Thus a fixed shaped
84 // virtual can use a variable shaped stored, but not vice versa.
85 // A fixed shape indirect virtual can use a stored with direct arrays.
86 //
87 // This class can also serve as an example of how to implement
88 // a virtual column engine.
89 // </synopsis>
90 
91 // <motivation>
92 // This class allows to store data in a smaller representation.
93 // It is needed to resemble the classic AIPS compress option.
94 // It adds the scale and offset value on a per row basis.
95 //
96 // Because the engine can serve only one column, it was possible to
97 // combine the engine and the column functionality in one class.
98 // This has been achieved using multiple inheritance.
99 // The advantage of this is that only one templated class is used,
100 // so less template instantiations are needed.
101 // </motivation>
102 
103 // <example>
104 // <srcblock>
105 // // Create the table description and 2 columns with indirect arrays in it.
106 // // The Int column will be stored, while the double will be
107 // // used as virtual.
108 // TableDesc tableDesc ("", TableDesc::Scratch);
109 // tableDesc.addColumn (ArrayColumnDesc<Int> ("storedArray"));
110 // tableDesc.addColumn (ArrayColumnDesc<double> ("virtualArray"));
111 //
112 // // Create a new table using the table description.
113 // SetupNewTable newtab (tableDesc, "tab.data", Table::New);
114 //
115 // // Create the array scaling engine to scale from double to Int
116 // // and bind it to the double column.
117 // // Create the table.
118 // ScaledArrayEngine<double,Int> scalingEngine("virtualArray",
119 // "storedArray", 10);
120 // newtab.bindColumn ("virtualArray", scalingEngine);
121 // Table table (newtab);
122 //
123 // // Store a 3-D array (with dim. 2,3,4) into each row of the column.
124 // // The shape of each array in the column is implicitly set by the put
125 // // function. This will also set the shape of the underlying Int array.
126 // ArrayColumn data (table, "virtualArray");
127 // Array<double> someArray(IPosition(4,2,3,4));
128 // someArray = 0;
129 // for (uInt i=0, i<10; i++) { // table will have 10 rows
130 // table.addRow();
131 // data.put (i, someArray)
132 // }
133 // </srcblock>
134 // </example>
135 
136 // <templating arg=VirtualType>
137 // <li> only suited for built-in numerics data types
138 // </templating>
139 // <templating arg=StoredType>
140 // <li> only suited for built-in numerics data types
141 // </templating>
142 
143 template<class VirtualType, class StoredType> class ScaledArrayEngine : public BaseMappedArrayEngine<VirtualType, StoredType>
144 {
145  //# Make members of parent class known.
146 public:
148 protected:
153 
154 public:
155  // Construct an engine to scale all arrays in a column with
156  // the given offset and scale factor.
157  // StoredColumnName is the name of the column where the scaled
158  // data will be put and must have data type StoredType.
159  // The virtual column using this engine must have data type VirtualType.
160  ScaledArrayEngine (const String& virtualColumnName,
161  const String& storedColumnName,
162  VirtualType scale,
163  VirtualType offset = 0);
164 
165  // Construct an engine to scale the arrays in a column.
166  // The scale and offset values are taken from a column with
167  // the given names. In that way each array has its own scale factor
168  // and offset value.
169  // An exception is thrown if these columns do not exist.
170  // VirtualColumnName is the name of the virtual column and is used to
171  // check if the engine gets bound to the correct column.
172  // StoredColumnName is the name of the column where the scaled
173  // data will be put and must have data type StoredType.
174  // The virtual column using this engine must have data type VirtualType.
175  // <group>
176  ScaledArrayEngine (const String& virtualColumnName,
177  const String& storedColumnName,
178  const String& scaleColumnName,
179  VirtualType offset = 0);
180  ScaledArrayEngine (const String& virtualColumnName,
181  const String& storedColumnName,
182  const String& scaleColumnName,
183  const String& offsetColumnName);
184  // </group>
185 
186  // Construct from a record specification as created by getmanagerSpec().
187  ScaledArrayEngine (const Record& spec);
188 
189  // Destructor is mandatory.
191 
192  // Return the type name of the engine (i.e. its class name).
193  virtual String dataManagerType() const;
194 
195  // Get the name given to the engine (is the virtual column name).
196  virtual String dataManagerName() const;
197 
198  // Record a record containing data manager specifications.
199  virtual Record dataManagerSpec() const;
200 
201  // Return the name of the class.
202  // This includes the names of the template arguments.
203  static String className();
204 
205  // Register the class name and the static makeObject "constructor".
206  // This will make the engine known to the table system.
207  // The automatically invoked registration function in DataManReg.cc
208  // contains ScaledArrayEngine<double,Int>.
209  // Any other instantiation of this class must be registered "manually"
210  // (or added to DataManReg.cc).
211  static void registerClass();
212 
213 private:
214  // Copy constructor is only used by clone().
215  // (so it is made private).
217 
218  // Assignment is not needed and therefore forbidden
219  // (so it is made private and not implemented).
222 
223  // Clone the engine object.
224  DataManager* clone() const;
225 
226  // Initialize the object for a new table.
227  // It defines the keywords containing the engine parameters.
228  void create (uInt initialNrrow);
229 
230  // Preparing consists of setting the writable switch and
231  // adding the initial number of rows in case of create.
232  // Furthermore it reads the keywords containing the engine parameters.
233  void prepare();
234 
235  // Get an array in the given row.
236  // This will scale and offset from the underlying array.
237  void getArray (uInt rownr, Array<VirtualType>& array);
238 
239  // Put an array in the given row.
240  // This will scale and offset to the underlying array.
241  void putArray (uInt rownr, const Array<VirtualType>& array);
242 
243  // Get a section of the array in the given row.
244  // This will scale and offset from the underlying array.
245  void getSlice (uInt rownr, const Slicer& slicer, Array<VirtualType>& array);
246 
247  // Put into a section of the array in the given row.
248  // This will scale and offset to the underlying array.
249  void putSlice (uInt rownr, const Slicer& slicer,
250  const Array<VirtualType>& array);
251 
252  // Get an entire column.
253  // This will scale and offset from the underlying array.
254  void getArrayColumn (Array<VirtualType>& array);
255 
256  // Put an entire column.
257  // This will scale and offset to the underlying array.
258  void putArrayColumn (const Array<VirtualType>& array);
259 
260  // Get a section of all arrays in the column.
261  // This will scale and offset from the underlying array.
262  void getColumnSlice (const Slicer& slicer, Array<VirtualType>& array);
263 
264  // Put a section of all arrays in the column.
265  // This will scale and offset to the underlying array.
266  void putColumnSlice (const Slicer& slicer, const Array<VirtualType>& array);
267 
268  // Scale and/or offset stored to array.
269  // This is meant when reading an array from the stored column.
270  // It optimizes for scale=1 and/or offset=0.
271  void scaleOnGet (VirtualType scale, VirtualType offset,
272  Array<VirtualType>& array,
273  const Array<StoredType>& stored);
274 
275  // Scale and/or offset array to stored.
276  // This is meant when writing an array into the stored column.
277  // It optimizes for scale=1 and/or offset=0.
278  void scaleOnPut (VirtualType scale, VirtualType offset,
279  const Array<VirtualType>& array,
280  Array<StoredType>& stored);
281 
282  // Scale and/or offset stored to array for the entire column.
283  // When the scale and offset are fixed, it will do the entire array.
284  // Otherwise it iterates through the array and applies the scale
285  // and offset per row.
287  const Array<StoredType>& stored);
288 
289  // Scale and/or offset array to stored for the entire column.
290  // When the scale and offset are fixed, it will do the entire array.
291  // Otherwise it iterates through the array and applies the scale
292  // and offset per row.
293  void scaleColumnOnPut (const Array<VirtualType>& array,
294  Array<StoredType>& stored);
295 
296 
297  //# Now define the data members.
298  String scaleName_p; //# name of scale column
299  String offsetName_p; //# name of offset column
300  VirtualType scale_p; //# scale factor
301  VirtualType offset_p; //# offset value
302  Bool fixedScale_p; //# scale is a fixed column
303  Bool fixedOffset_p; //# scale is a fixed column
304  ScalarColumn<VirtualType>* scaleColumn_p; //# column with scale value
305  ScalarColumn<VirtualType>* offsetColumn_p; //# column with offset value
306 
307  // Get the scale value for this row.
308  VirtualType getScale (uInt rownr);
309 
310  // Get the offset value for this row.
311  VirtualType getOffset (uInt rownr);
312 
313 public:
314  //*display 4
315  // Define the "constructor" to construct this engine when a
316  // table is read back.
317  // This "constructor" has to be registered by the user of the engine.
318  // If the engine is commonly used, its registration can be added
319  // to the registerAllCtor function in DataManReg.cc.
320  // That function gets automatically invoked by the table system.
321  static DataManager* makeObject (const String& dataManagerType,
322  const Record& spec);
323 };
324 
325 
326 
327 } //# NAMESPACE CASACORE - END
328 
329 #ifndef CASACORE_NO_AUTO_TEMPLATES
330 #include <casacore/tables/DataMan/ScaledArrayEngine.tcc>
331 #endif //# CASACORE_NO_AUTO_TEMPLATES
332 #endif
static String className()
Return the name of the class.
VirtualType getScale(uInt rownr)
Get the scale value for this row.
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:2093
Templated virtual column engine for a table array of any type.
Templated virtual column engine to scale a table array.
void getArray(uInt rownr, Array< VirtualType > &array)
Get an array in the given row.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
ScaledArrayEngine(const String &virtualColumnName, const String &storedColumnName, VirtualType scale, VirtualType offset=0)
Construct an engine to scale all arrays in a column with the given offset and scale factor...
ScalarColumn< VirtualType > * scaleColumn_p
void create(uInt initialNrrow)
Initialize the object for a new table.
VirtualType getOffset(uInt rownr)
Get the offset value for this row.
ScalarColumn< VirtualType > * offsetColumn_p
DataManager * clone() const
Clone the engine object.
virtual String dataManagerType() const
Return the type name of the engine (i.e.
~ScaledArrayEngine()
Destructor is mandatory.
virtual String dataManagerName() const
Get the name given to the engine (is the virtual column name).
void prepare()
Preparing consists of setting the writable switch and adding the initial number of rows in case of cr...
void scaleOnPut(VirtualType scale, VirtualType offset, const Array< VirtualType > &array, Array< StoredType > &stored)
Scale and/or offset array to stored.
virtual Record dataManagerSpec() const
Record a record containing data manager specifications.
static void registerClass()
Register the class name and the static makeObject "constructor".
A hierarchical collection of named fields of various types.
Definition: Record.h:180
void putSlice(uInt rownr, const Slicer &slicer, const Array< VirtualType > &array)
Put into a section of the array in the given row.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
void putArray(uInt rownr, const Array< VirtualType > &array)
Put an array in the given row.
void getColumnSlice(const Slicer &slicer, Array< VirtualType > &array)
Get a section of all arrays in the column.
template <class T, class U> class vector;
Definition: Array.h:169
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
void putArrayColumn(const Array< VirtualType > &array)
Put an entire column.
Abstract base class for a data manager.
Definition: DataManager.h:222
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void getSlice(uInt rownr, const Slicer &slicer, Array< VirtualType > &array)
Get a section of the array in the given row.
void putColumnSlice(const Slicer &slicer, const Array< VirtualType > &array)
Put a section of all arrays in the column.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
void scaleColumnOnPut(const Array< VirtualType > &array, Array< StoredType > &stored)
Scale and/or offset array to stored for the entire column.
void scaleOnGet(VirtualType scale, VirtualType offset, Array< VirtualType > &array, const Array< StoredType > &stored)
Scale and/or offset stored to array.
void getArrayColumn(Array< VirtualType > &array)
Get an entire column.
unsigned int uInt
Definition: aipstype.h:51
void scaleColumnOnGet(Array< VirtualType > &array, const Array< StoredType > &stored)
Scale and/or offset stored to array for the entire column.