ScaledArrayEngine.h

Go to the documentation of this file.
00001 //# ScaledArrayEngine.h: Templated virtual column engine to scale a table array
00002 //# Copyright (C) 1994,1995,1996,1999,2001
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef TABLES_SCALEDARRAYENGINE_H
00029 #define TABLES_SCALEDARRAYENGINE_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/tables/DataMan/BaseMappedArrayEngine.h>
00034 
00035 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00036 
00037 //# Forward Declarations
00038 template<class T> class ScalarColumn;
00039 
00040 
00041 
00042 // <summary>
00043 // Templated virtual column engine to scale a table array
00044 // </summary>
00045 
00046 // <use visibility=export>
00047 
00048 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
00049 // </reviewed>
00050 
00051 // <prerequisite>
00052 //# Classes you should understand before using this one.
00053 //   <li> VirtualColumnEngine
00054 //   <li> VirtualArrayColumn
00055 // </prerequisite>
00056 
00057 // <synopsis> 
00058 // ScaledArrayEngine is a virtual column engine which scales an array
00059 // of one type to another type to save disk storage.
00060 // This resembles the classic AIPS compress method which scales the
00061 // data from float to short.
00062 // The scale factor and offset value can be given in two ways:
00063 // <ul>
00064 //  <li> As a fixed value which is used for all arrays in the column.
00065 //  <li> As the name of a column. In this way each array in a
00066 //         column can have its own scale and offset value.
00067 //         The scale and offset value in a row must be put before
00068 //         the array is put and should not be changed anymore.
00069 // </ul>
00070 // It is also possible to have a variable scale factor with a fixed offset
00071 // value.
00072 // As in FITS the scale and offset values are used as:
00073 // <br><src> True_value = Stored_value * scale + offset; </src>
00074 //
00075 // An engine object should be used for one column only, because the stored
00076 // column name is part of the engine. If it would be used for more than
00077 // one column, they would all share the same stored column.
00078 // When the engine is bound to a column, it is checked if the name
00079 // of that column matches the given virtual column name.
00080 //
00081 // The engine can be used for a column containing any kind of array
00082 // (thus direct or indirect, fixed or variable shaped)) as long as the
00083 // virtual array can be stored in the stored array. Thus a fixed shaped
00084 // virtual can use a variable shaped stored, but not vice versa.
00085 // A fixed shape indirect virtual can use a stored with direct arrays.
00086 //
00087 // This class can also serve as an example of how to implement
00088 // a virtual column engine.
00089 // </synopsis> 
00090 
00091 // <motivation>
00092 // This class allows to store data in a smaller representation.
00093 // It is needed to resemble the classic AIPS compress option.
00094 // It adds the scale and offset value on a per row basis.
00095 //
00096 // Because the engine can serve only one column, it was possible to
00097 // combine the engine and the column functionality in one class.
00098 // This has been achieved using multiple inheritance.
00099 // The advantage of this is that only one templated class is used,
00100 // so less template instantiations are needed.
00101 // </motivation>
00102 
00103 // <example>
00104 // <srcblock>
00105 // // Create the table description and 2 columns with indirect arrays in it.
00106 // // The Int column will be stored, while the double will be
00107 // // used as virtual.
00108 // TableDesc tableDesc ("", TableDesc::Scratch);
00109 // tableDesc.addColumn (ArrayColumnDesc<Int> ("storedArray"));
00110 // tableDesc.addColumn (ArrayColumnDesc<double> ("virtualArray"));
00111 //
00112 // // Create a new table using the table description.
00113 // SetupNewTable newtab (tableDesc, "tab.data", Table::New);
00114 //
00115 // // Create the array scaling engine to scale from double to Int
00116 // // and bind it to the double column.
00117 // // Create the table.
00118 // ScaledArrayEngine<double,Int> scalingEngine("virtualArray",
00119 //                                             "storedArray", 10);
00120 // newtab.bindColumn ("virtualArray", scalingEngine);
00121 // Table table (newtab);
00122 //
00123 // // Store a 3-D array (with dim. 2,3,4) into each row of the column.
00124 // // The shape of each array in the column is implicitly set by the put
00125 // // function. This will also set the shape of the underlying Int array.
00126 // ArrayColumn data (table, "virtualArray");
00127 // Array<double> someArray(IPosition(4,2,3,4));
00128 // someArray = 0;
00129 // for (uInt i=0, i<10; i++) {          // table will have 10 rows
00130 //     table.addRow();
00131 //     data.put (i, someArray)
00132 // }
00133 // </srcblock>
00134 // </example>
00135 
00136 // <templating arg=VirtualType>
00137 //  <li> only suited for built-in numerics data types
00138 // </templating>
00139 // <templating arg=StoredType>
00140 //  <li> only suited for built-in numerics data types
00141 // </templating>
00142 
00143 template<class VirtualType, class StoredType> class ScaledArrayEngine : public BaseMappedArrayEngine<VirtualType, StoredType>
00144 {
00145   //# Make members of parent class known.
00146 public:
00147   using BaseMappedArrayEngine<VirtualType,StoredType>::virtualName;
00148 protected:
00149   using BaseMappedArrayEngine<VirtualType,StoredType>::storedName;
00150   using BaseMappedArrayEngine<VirtualType,StoredType>::table;
00151   using BaseMappedArrayEngine<VirtualType,StoredType>::column;
00152   using BaseMappedArrayEngine<VirtualType,StoredType>::setNames;
00153 
00154 public:
00155     // Construct an engine to scale all arrays in a column with
00156     // the given offset and scale factor.
00157     // StoredColumnName is the name of the column where the scaled
00158     // data will be put and must have data type StoredType.
00159     // The virtual column using this engine must have data type VirtualType.
00160     ScaledArrayEngine (const String& virtualColumnName,
00161                        const String& storedColumnName,
00162                        VirtualType scale,
00163                        VirtualType offset = 0);
00164 
00165     // Construct an engine to scale the arrays in a column.
00166     // The scale and offset values are taken from a column with
00167     // the given names. In that way each array has its own scale factor
00168     // and offset value.
00169     // An exception is thrown if these columns do not exist.
00170     // VirtualColumnName is the name of the virtual column and is used to
00171     // check if the engine gets bound to the correct column.
00172     // StoredColumnName is the name of the column where the scaled
00173     // data will be put and must have data type StoredType.
00174     // The virtual column using this engine must have data type VirtualType.
00175     // <group>
00176     ScaledArrayEngine (const String& virtualColumnName,
00177                        const String& storedColumnName,
00178                        const String& scaleColumnName,
00179                        VirtualType offset = 0);
00180     ScaledArrayEngine (const String& virtualColumnName,
00181                        const String& storedColumnName,
00182                        const String& scaleColumnName,
00183                        const String& offsetColumnName);
00184     // </group>
00185 
00186     // Construct from a record specification as created by getmanagerSpec().
00187     ScaledArrayEngine (const Record& spec);
00188 
00189     // Destructor is mandatory.
00190     ~ScaledArrayEngine();
00191 
00192     // Return the type name of the engine (i.e. its class name).
00193     virtual String dataManagerType() const;
00194 
00195     // Get the name given to the engine (is the virtual column name).
00196     virtual String dataManagerName() const;
00197   
00198     // Record a record containing data manager specifications.
00199     virtual Record dataManagerSpec() const;
00200 
00201     // Return the name of the class.
00202     // This includes the names of the template arguments.
00203     static String className();
00204 
00205     // Register the class name and the static makeObject "constructor".
00206     // This will make the engine known to the table system.
00207     // The automatically invoked registration function in DataManReg.cc
00208     // contains ScaledArrayEngine<double,Int>.
00209     // Any other instantiation of this class must be registered "manually"
00210     // (or added to DataManReg.cc).
00211     static void registerClass();
00212 
00213 private:
00214     // Copy constructor is only used by clone().
00215     // (so it is made private).
00216     ScaledArrayEngine (const ScaledArrayEngine<VirtualType,StoredType>&);
00217 
00218     // Assignment is not needed and therefore forbidden
00219     // (so it is made private and not implemented).
00220     ScaledArrayEngine<VirtualType,StoredType>& operator=
00221                            (const ScaledArrayEngine<VirtualType,StoredType>&);
00222 
00223     // Clone the engine object.
00224     DataManager* clone() const;
00225 
00226     // Initialize the object for a new table.
00227     // It defines the keywords containing the engine parameters.
00228     void create (uInt initialNrrow);
00229 
00230     // Preparing consists of setting the writable switch and
00231     // adding the initial number of rows in case of create.
00232     // Furthermore it reads the keywords containing the engine parameters.
00233     void prepare();
00234 
00235     // Get an array in the given row.
00236     // This will scale and offset from the underlying array.
00237     void getArray (uInt rownr, Array<VirtualType>& array);
00238 
00239     // Put an array in the given row.
00240     // This will scale and offset to the underlying array.
00241     void putArray (uInt rownr, const Array<VirtualType>& array);
00242 
00243     // Get a section of the array in the given row.
00244     // This will scale and offset from the underlying array.
00245     void getSlice (uInt rownr, const Slicer& slicer, Array<VirtualType>& array);
00246 
00247     // Put into a section of the array in the given row.
00248     // This will scale and offset to the underlying array.
00249     void putSlice (uInt rownr, const Slicer& slicer,
00250                    const Array<VirtualType>& array);
00251 
00252     // Get an entire column.
00253     // This will scale and offset from the underlying array.
00254     void getArrayColumn (Array<VirtualType>& array);
00255 
00256     // Put an entire column.
00257     // This will scale and offset to the underlying array.
00258     void putArrayColumn (const Array<VirtualType>& array);
00259 
00260     // Get a section of all arrays in the column.
00261     // This will scale and offset from the underlying array.
00262     void getColumnSlice (const Slicer& slicer, Array<VirtualType>& array);
00263 
00264     // Put a section of all arrays in the column.
00265     // This will scale and offset to the underlying array.
00266     void putColumnSlice (const Slicer& slicer, const Array<VirtualType>& array);
00267 
00268     // Scale and/or offset stored to array.
00269     // This is meant when reading an array from the stored column.
00270     // It optimizes for scale=1 and/or offset=0.
00271     void scaleOnGet (VirtualType scale, VirtualType offset,
00272                      Array<VirtualType>& array,
00273                      const Array<StoredType>& stored);
00274 
00275     // Scale and/or offset array to stored.
00276     // This is meant when writing an array into the stored column.
00277     // It optimizes for scale=1 and/or offset=0.
00278     void scaleOnPut (VirtualType scale, VirtualType offset,
00279                      const Array<VirtualType>& array,
00280                      Array<StoredType>& stored);
00281 
00282     // Scale and/or offset stored to array for the entire column.
00283     // When the scale and offset are fixed, it will do the entire array.
00284     // Otherwise it iterates through the array and applies the scale
00285     // and offset per row.
00286     void scaleColumnOnGet (Array<VirtualType>& array,
00287                            const Array<StoredType>& stored);
00288 
00289     // Scale and/or offset array to stored for the entire column.
00290     // When the scale and offset are fixed, it will do the entire array.
00291     // Otherwise it iterates through the array and applies the scale
00292     // and offset per row.
00293     void scaleColumnOnPut (const Array<VirtualType>& array,
00294                            Array<StoredType>& stored);
00295 
00296 
00297     //# Now define the data members.
00298     String         scaleName_p;          //# name of scale column
00299     String         offsetName_p;         //# name of offset column
00300     VirtualType    scale_p;              //# scale factor
00301     VirtualType    offset_p;             //# offset value
00302     Bool           fixedScale_p;         //# scale is a fixed column
00303     Bool           fixedOffset_p;        //# scale is a fixed column
00304     ScalarColumn<VirtualType>* scaleColumn_p;  //# column with scale value
00305     ScalarColumn<VirtualType>* offsetColumn_p; //# column with offset value
00306 
00307     // Get the scale value for this row.
00308     VirtualType getScale (uInt rownr);
00309 
00310     // Get the offset value for this row.
00311     VirtualType getOffset (uInt rownr);
00312 
00313 public:
00314     //*display 4
00315     // Define the "constructor" to construct this engine when a
00316     // table is read back.
00317     // This "constructor" has to be registered by the user of the engine.
00318     // If the engine is commonly used, its registration can be added
00319     // to the registerAllCtor function in DataManReg.cc. 
00320     // That function gets automatically invoked by the table system.
00321     static DataManager* makeObject (const String& dataManagerType,
00322                                     const Record& spec);
00323 };
00324 
00325 
00326 
00327 } //# NAMESPACE CASACORE - END
00328 
00329 #ifndef CASACORE_NO_AUTO_TEMPLATES
00330 #include <casacore/tables/DataMan/ScaledArrayEngine.tcc>
00331 #endif //# CASACORE_NO_AUTO_TEMPLATES
00332 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1