Loading...
Searching...
No Matches
CompressFloat.h
Go to the documentation of this file.
//# CompressFloat.h: Virtual column engine to scale a table float array
//# Copyright (C) 2001,2002
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef TABLES_COMPRESSFLOAT_H
#define TABLES_COMPRESSFLOAT_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/tables/DataMan/BaseMappedArrayEngine.h>
#include <casacore/tables/Tables/ScalarColumn.h>
#include <casacore/casa/Arrays/Array.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <summary>
// Virtual column engine to scale a table float array
// </summary>
// <use visibility=export>
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tCompressFloat.cc">
// </reviewed>
// <prerequisite>
//# Classes you should understand before using this one.
// <li> VirtualColumnEngine
// <li> VirtualArrayColumn
// </prerequisite>
// <synopsis>
// CompressFloat is a virtual column engine which scales an array
// of one type to another type to save disk storage.
// This resembles the classic AIPS compress method which scales the
// data from float to short.
// The scale factor and offset values can be given in two ways:
// <ul>
// <li> As a fixed values which is used for all arrays in the column.
// These values have to be given when constructing of the engine.
// <li> As the name of a column. In this way each array in the
// column has its own scale and offset value.
// By default it uses auto-scaling (see below).
// Otherwise the scale and offset value in a row must be put
// before the array is put and should not be changed anymore.
// </ul>
// Auto-scaling means that the engine will determine the scale
// and offset value itself when an array (or a slice) is put.
// It does it by mapping the values in the array to the range [-32767,32767].
// At each put the scale/offset values are changed as needed.
// Note that with auto-scaling <src>putSlice</src> can be somewhat
// slower, because the entire array might need to be rescaled.
//
// As in FITS the scale and offset values are used as:
// <br><src> True_value = Stored_value * scale + offset; </src>
//
// An engine object should be used for one column only, because the stored
// column name is part of the engine. If it would be used for more than
// one column, they would all share the same stored column.
// When the engine is bound to a column, it is checked if the name
// of that column matches the given virtual column name.
//
// The engine can be used for a column containing any kind of array
// (thus direct or indirect, fixed or variable shaped)) as long as the
// virtual array can be stored in the stored array. Thus a fixed shaped
// virtual can use a variable shaped stored, but not vice versa.
// A fixed shape indirect virtual can use a stored with direct arrays.
//
// This class can also serve as an example of how to implement
// a virtual column engine.
// </synopsis>
// <motivation>
// This class allows to store data in a smaller representation.
// It is needed to resemble the classic AIPS compress option.
//
// Because the engine can serve only one column, it was possible to
// combine the engine and the column functionality in one class.
// </motivation>
// <example>
// <srcblock>
// // Create the table description and 2 columns with indirect arrays in it.
// // The Int column will be stored, while the double will be
// // used as virtual.
// TableDesc tableDesc ("", TableDesc::Scratch);
// tableDesc.addColumn (ArrayColumnDesc<Short> ("storedArray"));
// tableDesc.addColumn (ArrayColumnDesc<Float> ("virtualArray"));
// tableDesc.addColumn (ScalarColumnDesc<Float> ("scale"));
// tableDesc.addColumn (ScalarColumnDesc<Float> ("offset"));
//
// // Create a new table using the table description.
// SetupNewTable newtab (tableDesc, "tab.data", Table::New);
//
// // Create the array scaling engine (with auto-scale)
// // and bind it to the float column.
// CompressFloat scalingEngine("virtualArray", "storedArray",
// "scale", "offset");
// newtab.bindColumn ("virtualArray", scalingEngine);
// // Create the table.
// Table table (newtab);
//
// // Store a 3-D array (with dim. 2,3,4) into each row of the column.
// // The shape of each array in the column is implicitly set by the put
// // function. This will also set the shape of the underlying Int array.
// ArrayColumn data (table, "virtualArray");
// Array<double> someArray(IPosition(4,2,3,4));
// someArray = 0;
// for (rownr_t i=0, i<10; i++) { // table will have 10 rows
// table.addRow();
// data.put (i, someArray)
// }
// </srcblock>
// </example>
class CompressFloat : public BaseMappedArrayEngine<Float, Short>
{
public:
// Construct an engine to scale all arrays in a column with
// the given offset and scale factor.
// StoredColumnName is the name of the column where the scaled
// data will be put and must have data type Short.
// The virtual column using this engine must have data type Float.
CompressFloat (const String& virtualColumnName,
const String& storedColumnName,
Float scale,
Float offset = 0);
// Construct an engine to scale the arrays in a column.
// The scale and offset values are taken from a column with
// the given names. In that way each array has its own scale factor
// and offset value.
// An exception is thrown if these columns do not exist.
// VirtualColumnName is the name of the virtual column and is used to
// check if the engine gets bound to the correct column.
// StoredColumnName is the name of the column where the scaled
// data will be put and must have data type Short.
// The virtual column using this engine must have data type Float.
CompressFloat (const String& virtualColumnName,
const String& storedColumnName,
const String& scaleColumnName,
const String& offsetColumnName,
Bool autoScale = True);
// Construct from a record specification as created by getmanagerSpec().
CompressFloat (const Record& spec);
// Destructor is mandatory.
~CompressFloat();
// Assignment is not needed and therefore forbidden
CompressFloat& operator= (const CompressFloat&) = delete;
// Return the type name of the engine (i.e. its class name).
virtual String dataManagerType() const;
// Get the name given to the engine (is the virtual column name).
virtual String dataManagerName() const;
// Record a record containing data manager specifications.
virtual Record dataManagerSpec() const;
// Return the name of the class.
// This includes the names of the template arguments.
static String className();
// Register the class name and the static makeObject "constructor".
// This will make the engine known to the table system.
static void registerClass();
private:
// Copy constructor is only used by clone().
// (so it is made private).
CompressFloat (const CompressFloat&);
// Clone the engine object.
virtual DataManager* clone() const;
// Initialize the object for a new table.
// It defines the keywords containing the engine parameters.
virtual void create64 (rownr_t initialNrrow);
// Preparing consists of setting the writable switch and
// adding the initial number of rows in case of create.
// Furthermore it reads the keywords containing the engine parameters.
virtual void prepare();
// Reopen the engine for read/write access.
// It makes the column writable if the underlying column is writable.
virtual void reopenRW();
// Add rows to the table.
// If auto-scaling, it initializes the scale column with 0
// to indicate that no data has been processed yet.
virtual void addRowInit (rownr_t startRow, rownr_t nrrow);
// Get an array in the given row.
// This will scale and offset from the underlying array.
virtual void getArray (rownr_t rownr, Array<Float>& array);
// Put an array in the given row.
// This will scale and offset to the underlying array.
virtual void putArray (rownr_t rownr, const Array<Float>& array);
// Get a section of the array in the given row.
// This will scale and offset from the underlying array.
virtual void getSlice (rownr_t rownr, const Slicer& slicer,
Array<Float>& array);
// Put into a section of the array in the given row.
// This will scale and offset to the underlying array.
virtual void putSlice (rownr_t rownr, const Slicer& slicer,
const Array<Float>& array);
// Get an entire column.
// This will scale and offset from the underlying array.
virtual void getArrayColumn (Array<Float>& array);
// Put an entire column.
// This will scale and offset to the underlying array.
virtual void putArrayColumn (const Array<Float>& array);
// Get some array values in the column.
// This will scale and offset from the underlying array.
virtual void getArrayColumnCells (const RefRows& rownrs,
Array<Float>& data);
// Put some array values in the column.
// This will scale and offset to the underlying array.
virtual void putArrayColumnCells (const RefRows& rownrs,
const Array<Float>& data);
// Get a section of all arrays in the column.
// This will scale and offset from the underlying array.
virtual void getColumnSlice (const Slicer& slicer, Array<Float>& array);
// Put a section of all arrays in the column.
// This will scale and offset to the underlying array.
virtual void putColumnSlice (const Slicer& slicer,
const Array<Float>& array);
// Get a section of some arrays in the column.
// This will scale and offset from the underlying array.
virtual void getColumnSliceCells (const RefRows& rownrs,
const Slicer& slicer,
Array<Float>& data);
// Put into a section of some arrays in the column.
// This will scale and offset to the underlying array.
virtual void putColumnSliceCells (const RefRows& rownrs,
const Slicer& slicer,
const Array<Float>& data);
// Scale and/or offset target to array.
// This is meant when reading an array from the stored column.
// It optimizes for scale=1 and/or offset=0.
void scaleOnGet (Float scale, Float offset,
Array<Float>& array,
const Array<Short>& target);
// Scale and/or offset array to target.
// This is meant when writing an array into the stored column.
// It optimizes for scale=1 and/or offset=0.
void scaleOnPut (Float scale, Float offset,
const Array<Float>& array,
Array<Short>& target);
// Scale and/or offset target to array for the entire column.
// When the scale and offset are fixed, it will do the entire array.
// Otherwise it iterates through the array and applies the scale
// and offset per row.
void scaleColumnOnGet (Array<Float>& array,
const Array<Short>& target);
// Scale and/or offset array to target for the entire column.
// When the scale and offset are fixed, it will do the entire array.
// Otherwise it iterates through the array and applies the scale
// and offset per row.
void scaleColumnOnPut (const Array<Float>& array,
Array<Short>& target);
//# Now define the data members.
String scaleName_p; //# name of scale column
String offsetName_p; //# name of offset column
Float scale_p; //# fixed scale factor
Float offset_p; //# fixed offset value
Bool fixed_p; //# scale/offset is fixed
Bool autoScale_p; //# determine scale/offset automatically
ScalarColumn<Float>* scaleColumn_p; //# column with scale value
ScalarColumn<Float>* offsetColumn_p; //# column with offset value
Array<Short> buffer_p; //# buffer to avoid Array constructions
// Get the scale value for this row.
Float getScale (rownr_t rownr);
// Get the offset value for this row.
Float getOffset (rownr_t rownr);
// Find minimum and maximum from the array data.
// NaN and infinite values are ignored. If no values are finite,
// minimum and maximum are set to NaN.
void findMinMax (Float& minVal, Float& maxVal,
const Array<Float>& array) const;
// Make scale and offset from the minimum and maximum of the array data.
// If minVal is NaN, scale is set to 0.
void makeScaleOffset (Float& scale, Float& offset,
Float minVal, Float maxVal) const;
// Put a part of an array in a row using given scale/offset values.
void putPart (rownr_t rownr, const Slicer& slicer,
const Array<Float>& array,
Float scale, Float offset);
// Fill the array part into the full array and put it using the
// given min/max values.
void putFullPart (rownr_t rownr, const Slicer& slicer,
Array<Float>& fullArray,
const Array<Float>& partArray,
Float minVal, Float maxVal);
public:
// Define the "constructor" to construct this engine when a
// table is read back.
// This "constructor" has to be registered by the user of the engine.
// If the engine is commonly used, its registration can be added
// to the registerAllCtor function in DataManager.cc.
// That function gets automatically invoked by the table system.
static DataManager* makeObject (const String& dataManagerType,
const Record& spec);
};
inline Float CompressFloat::getScale (rownr_t rownr)
{
return (fixed_p ? scale_p : (*scaleColumn_p)(rownr));
}
inline Float CompressFloat::getOffset (rownr_t rownr)
{
return (fixed_p ? offset_p : (*offsetColumn_p)(rownr));
}
} //# NAMESPACE CASACORE - END
#endif
casacore::Array
Definition Array.h:155
casacore::BaseMappedArrayEngine< Float, Short >::BaseMappedArrayEngine
BaseMappedArrayEngine(const String &virtualColumnName, const String &storedColumnName)
casacore::CompressFloat::getOffset
Float getOffset(rownr_t rownr)
Get the offset value for this row.
Definition CompressFloat.h:361
casacore::CompressFloat::dataManagerSpec
virtual Record dataManagerSpec() const
Record a record containing data manager specifications.
casacore::CompressFloat::getArray
virtual void getArray(rownr_t rownr, Array< Float > &array)
Get an array in the given row.
casacore::CompressFloat::getColumnSlice
virtual void getColumnSlice(const Slicer &slicer, Array< Float > &array)
Get a section of all arrays in the column.
casacore::CompressFloat::getScale
Float getScale(rownr_t rownr)
Get the scale value for this row.
Definition CompressFloat.h:357
casacore::CompressFloat::getArrayColumn
virtual void getArrayColumn(Array< Float > &array)
Get an entire column.
casacore::CompressFloat::CompressFloat
CompressFloat(const String &virtualColumnName, const String &storedColumnName, const String &scaleColumnName, const String &offsetColumnName, Bool autoScale=True)
Construct an engine to scale the arrays in a column.
casacore::CompressFloat::scale_p
Float scale_p
Definition CompressFloat.h:308
casacore::CompressFloat::getSlice
virtual void getSlice(rownr_t rownr, const Slicer &slicer, Array< Float > &array)
Get a section of the array in the given row.
casacore::CompressFloat::CompressFloat
CompressFloat(const CompressFloat &)
Copy constructor is only used by clone().
casacore::CompressFloat::reopenRW
virtual void reopenRW()
Reopen the engine for read/write access.
casacore::CompressFloat::findMinMax
void findMinMax(Float &minVal, Float &maxVal, const Array< Float > &array) const
Find minimum and maximum from the array data.
casacore::CompressFloat::scaleColumnOnGet
void scaleColumnOnGet(Array< Float > &array, const Array< Short > &target)
Scale and/or offset target to array for the entire column.
casacore::CompressFloat::putSlice
virtual void putSlice(rownr_t rownr, const Slicer &slicer, const Array< Float > &array)
Put into a section of the array in the given row.
casacore::CompressFloat::clone
virtual DataManager * clone() const
Clone the engine object.
casacore::CompressFloat::fixed_p
Bool fixed_p
Definition CompressFloat.h:310
casacore::CompressFloat::scaleColumn_p
ScalarColumn< Float > * scaleColumn_p
Definition CompressFloat.h:312
casacore::CompressFloat::offsetColumn_p
ScalarColumn< Float > * offsetColumn_p
Definition CompressFloat.h:313
casacore::CompressFloat::autoScale_p
Bool autoScale_p
Definition CompressFloat.h:311
casacore::CompressFloat::className
static String className()
Return the name of the class.
casacore::CompressFloat::putArray
virtual void putArray(rownr_t rownr, const Array< Float > &array)
Put an array in the given row.
casacore::CompressFloat::prepare
virtual void prepare()
Preparing consists of setting the writable switch and adding the initial number of rows in case of cr...
casacore::CompressFloat::scaleColumnOnPut
void scaleColumnOnPut(const Array< Float > &array, Array< Short > &target)
Scale and/or offset array to target for the entire column.
casacore::CompressFloat::scaleName_p
String scaleName_p
Definition CompressFloat.h:306
casacore::CompressFloat::~CompressFloat
~CompressFloat()
Destructor is mandatory.
casacore::CompressFloat::offset_p
Float offset_p
Definition CompressFloat.h:309
casacore::CompressFloat::scaleOnPut
void scaleOnPut(Float scale, Float offset, const Array< Float > &array, Array< Short > &target)
Scale and/or offset array to target.
casacore::CompressFloat::makeObject
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Define the "constructor" to construct this engine when a table is read back.
casacore::CompressFloat::putColumnSliceCells
virtual void putColumnSliceCells(const RefRows &rownrs, const Slicer &slicer, const Array< Float > &data)
Put into a section of some arrays in the column.
casacore::CompressFloat::putFullPart
void putFullPart(rownr_t rownr, const Slicer &slicer, Array< Float > &fullArray, const Array< Float > &partArray, Float minVal, Float maxVal)
Fill the array part into the full array and put it using the given min/max values.
casacore::CompressFloat::registerClass
static void registerClass()
Register the class name and the static makeObject "constructor".
casacore::CompressFloat::dataManagerName
virtual String dataManagerName() const
Get the name given to the engine (is the virtual column name).
casacore::CompressFloat::getArrayColumnCells
virtual void getArrayColumnCells(const RefRows &rownrs, Array< Float > &data)
Get some array values in the column.
casacore::CompressFloat::putPart
void putPart(rownr_t rownr, const Slicer &slicer, const Array< Float > &array, Float scale, Float offset)
Put a part of an array in a row using given scale/offset values.
casacore::CompressFloat::putArrayColumnCells
virtual void putArrayColumnCells(const RefRows &rownrs, const Array< Float > &data)
Put some array values in the column.
casacore::CompressFloat::CompressFloat
CompressFloat(const String &virtualColumnName, const String &storedColumnName, Float scale, Float offset=0)
Construct an engine to scale all arrays in a column with the given offset and scale factor.
casacore::CompressFloat::putArrayColumn
virtual void putArrayColumn(const Array< Float > &array)
Put an entire column.
casacore::CompressFloat::putColumnSlice
virtual void putColumnSlice(const Slicer &slicer, const Array< Float > &array)
Put a section of all arrays in the column.
casacore::CompressFloat::addRowInit
virtual void addRowInit(rownr_t startRow, rownr_t nrrow)
Add rows to the table.
casacore::CompressFloat::getColumnSliceCells
virtual void getColumnSliceCells(const RefRows &rownrs, const Slicer &slicer, Array< Float > &data)
Get a section of some arrays in the column.
casacore::CompressFloat::offsetName_p
String offsetName_p
Definition CompressFloat.h:307
casacore::CompressFloat::create64
virtual void create64(rownr_t initialNrrow)
Initialize the object for a new table.
casacore::CompressFloat::operator=
CompressFloat & operator=(const CompressFloat &)=delete
Assignment is not needed and therefore forbidden.
casacore::CompressFloat::scaleOnGet
void scaleOnGet(Float scale, Float offset, Array< Float > &array, const Array< Short > &target)
Scale and/or offset target to array.
casacore::CompressFloat::makeScaleOffset
void makeScaleOffset(Float &scale, Float &offset, Float minVal, Float maxVal) const
Make scale and offset from the minimum and maximum of the array data.
casacore::CompressFloat::dataManagerType
virtual String dataManagerType() const
Return the type name of the engine (i.e.
casacore::CompressFloat::buffer_p
Array< Short > buffer_p
Definition CompressFloat.h:314
casacore::CompressFloat::CompressFloat
CompressFloat(const Record &spec)
Construct from a record specification as created by getmanagerSpec().
casacore::DataManager
Abstract base class for a data manager.
Definition DataManager.h:219
casacore::RefRows
Definition RefRows.h:84
casacore::ScalarColumn
Definition ScalarColumn.h:83
casacore::Slicer
Definition Slicer.h:287
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::Record
Record()
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::offset
int offset(int, int) const
compute a linear offset from array indicies
casacore::array
T * array
The actual storage.
Definition Block.h:689
casacore::Float
float Float
Definition aipstype.h:52
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::True
const Bool True
Definition aipstype.h:41
casacore::rownr_t
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:44