casacore
Loading...
Searching...
No Matches
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
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37//# Forward Declarations
38template<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 (rownr_t 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
143template<class VirtualType, class StoredType> class ScaledArrayEngine : public BaseMappedArrayEngine<VirtualType, StoredType>
144{
145 //# Make members of parent class known.
146public:
147 using BaseMappedArrayEngine<VirtualType,StoredType>::virtualName;
148protected:
149 using BaseMappedArrayEngine<VirtualType,StoredType>::storedName;
150 using BaseMappedArrayEngine<VirtualType,StoredType>::table;
151 using BaseMappedArrayEngine<VirtualType,StoredType>::column;
152 using BaseMappedArrayEngine<VirtualType,StoredType>::setNames;
153
154public:
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().
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.
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
213private:
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.
225
226 // Initialize the object for a new table.
227 // It defines the keywords containing the engine parameters.
228 void create64 (rownr_t 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.
238
239 // Put an array in the given row.
240 // This will scale and offset to the underlying 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 (rownr_t 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 (rownr_t rownr, const Slicer& slicer,
251
252 // Get an entire column.
253 // This will scale and offset from the underlying array.
255
256 // Put an entire column.
257 // This will scale and offset to the underlying array.
259
260 // Get a section of all arrays in the column.
261 // This will scale and offset from the underlying 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,
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,
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.
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 (rownr_t rownr);
309
310 // Get the offset value for this row.
311 VirtualType getOffset (rownr_t rownr);
312
313public:
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.
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
ArrayColumn< StoredType > & column()
Give access to the stored column.
void setNames(const String &virtualName, const String &storedName)
Set the virtual and stored column name.
const String & storedName() const
Get the stored column name.
const String & virtualName() const
Get the virtual column name.
Abstract base class for a data manager.
Table & table() const
Get the table this object is associated with.
static String className()
Return the name of the class.
void getArray(rownr_t rownr, Array< VirtualType > &array)
Get an array in the given row.
virtual String dataManagerName() const
Get the name given to the engine (is the virtual column name).
VirtualType getOffset(rownr_t rownr)
Get the offset value for this row.
virtual Record dataManagerSpec() const
Record a record containing data manager specifications.
void putArrayColumn(const Array< VirtualType > &array)
Put an entire column.
void scaleOnPut(VirtualType scale, VirtualType offset, const Array< VirtualType > &array, Array< StoredType > &stored)
Scale and/or offset array to stored.
ScaledArrayEngine(const ScaledArrayEngine< VirtualType, StoredType > &)
Copy constructor is only used by clone().
void putColumnSlice(const Slicer &slicer, const Array< VirtualType > &array)
Put a section of all arrays in the column.
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.
void scaleColumnOnGet(Array< VirtualType > &array, const Array< StoredType > &stored)
Scale and/or offset stored to array for the entire column.
void scaleColumnOnPut(const Array< VirtualType > &array, Array< StoredType > &stored)
Scale and/or offset array to stored for the entire column.
DataManager * clone() const
Clone the engine object.
void scaleOnGet(VirtualType scale, VirtualType offset, Array< VirtualType > &array, const Array< StoredType > &stored)
Scale and/or offset stored to array.
void getColumnSlice(const Slicer &slicer, Array< VirtualType > &array)
Get a section of all arrays in the column.
ScaledArrayEngine(const Record &spec)
Construct from a record specification as created by getmanagerSpec().
VirtualType getScale(rownr_t rownr)
Get the scale value for this row.
void putSlice(rownr_t rownr, const Slicer &slicer, const Array< VirtualType > &array)
Put into a section of the array in the given row.
virtual String dataManagerType() const
Return the type name of the engine (i.e.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
~ScaledArrayEngine()
Destructor is mandatory.
static void registerClass()
Register the class name and the static makeObject "constructor".
void getArrayColumn(Array< VirtualType > &array)
Get an entire column.
ScaledArrayEngine(const String &virtualColumnName, const String &storedColumnName, const String &scaleColumnName, VirtualType offset=0)
Construct an engine to scale the arrays in a column.
ScaledArrayEngine(const String &virtualColumnName, const String &storedColumnName, const String &scaleColumnName, const String &offsetColumnName)
ScalarColumn< VirtualType > * offsetColumn_p
void create64(rownr_t initialNrrow)
Initialize the object for a new table.
void prepare()
Preparing consists of setting the writable switch and adding the initial number of rows in case of cr...
void getSlice(rownr_t rownr, const Slicer &slicer, Array< VirtualType > &array)
Get a section of the array in the given row.
ScalarColumn< VirtualType > * scaleColumn_p
void putArray(rownr_t rownr, const Array< VirtualType > &array)
Put an array in the given row.
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition ExprNode.h:1929
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