Cube.h

Classes

Cube -- A 3-D Specialization of the Array class (full description)

template<class T> class Cube : public Array<T>

Interface

Public Members
Cube()
Cube(uInt l1, uInt l2, uInt l3)
Cube(uInt l1, uInt l2, uInt l3, const T &initialValue)
Cube(const IPosition &len)
Cube(const IPosition &len, const T &initialValue)
Cube(const Cube<T> &)
Cube(const Array<T> &)
Cube(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY)
Cube(const IPosition &shape, const T *storage)
virtual ~Cube()
virtual void assign (const Array<T>& other)
virtual void reference(Array<T> &other)
void resize(uInt nx, uInt ny, uInt nz)
virtual void resize()
virtual void resize(const IPosition &)
Cube<T> &operator=(const Cube<T> &other)
virtual Array<T> &operator=(const Array<T> &other)
Array<T> &operator=(const T &val)
Cube<T> &operator= (const MaskedArray<T> &marray)
T &operator()(const IPosition &i)
const T &operator()(const IPosition &i) const
T &operator()(uInt i1, uInt i2, uInt i3)
const T &operator()(uInt i1, uInt i2, uInt i3) const
Cube<T> operator()(const Slice &sliceX, const Slice &sliceY, const Slice &sliceZ)
Array<T> operator()(const IPosition &blc, const IPosition &trc, const IPosition &incr)
Array<T> operator()(const IPosition &blc, const IPosition &trc)
Array<T> operator()(const Slicer& slicer)
MaskedArray<T> operator() (const LogicalArray &mask) const
MaskedArray<T> operator() (const LogicalArray &mask)
MaskedArray<T> operator() (const MaskedLogicalArray &mask) const
MaskedArray<T> operator() (const MaskedLogicalArray &mask)
Matrix<T> xyPlane(uInt zplane)
const Matrix<T> xyPlane(uInt zplane) const
void shape(Int &s1, Int &s2, Int &s3) const
const IPosition &shape() const
uInt nrow() const
uInt ncolumn() const
uInt nplane() const
virtual void takeStorage(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY)
virtual void takeStorage(const IPosition &shape, const T *storage)
virtual Bool ok() const
Protected Members
virtual void doNonDegenerate(Array<T> &other, const IPosition &ignoreAxes)
Private Members
void makeIndexingConstants()
See Also
Array general global functions -- General global functions for Arrays.
Array IO -- Input/output operators for Arrays.
Array binary IO -- Simple binary input/output for Arrays.
ArrayIterator -- Iterate an Array cursor through another Array.
ReadOnlyArrayIterator -- Iterate a const Array cursor through a const Array.
Array logical operations -- Logical operations for Arrays.
Array mathematical operations -- Mathematical operations for Arrays.
LogicalArray -- Logical valued Arrays.
LogicalCube -- Logical valued Cubes.
MaskedArray logical operations -- Logical operations for MaskedArrays, and between MaskedArrays and Arrays.
MaskedArray mathematical operations -- Mathematical operations for MaskedArrays, and between MaskedArrays and Arrays.
MaskedLogicalArray -- Masked LogicalArrays.
MaskedArray general global functions -- General global functions for MaskedArrays, and between MaskedArrays and Arrays.

Description

Cube objects are three-dimensional specializations (e.g., more convenient and efficient indexing) of the general Array class. You might also want to look at the Array documentation to see inherited functionality. A tutorial on using the array classes in general is available in the "AIPS++ Programming Manual".

Generally the member functions of Array are also available in Cube versions which take a pair of integers where the array needs an IPosition. Since the Cube is three-dimensional, the IPositions are overkill, although you may use those versions if you want to.

    Cube<Int> ci(100,100,100);   // Shape is 100x100
    ci.resize(50,50,50);         // Shape now 50x50
    

Slices may be taken with the Slice class. To take a slice, one "indexes" with one Slice(start, length, inc) for each axis, where end and inc are optional. Additionally, there is an xyPlane() member function which return a Matrix which corresponds to some plane:

    Cube<Float> cube(10,20,30);
    for(uInt i=0; i < 30; i++) {
       cube.xyPlane(i) = i;   // Set every 10x20 plane to its "height"
    }
    

Element-by-element arithmetic and logical operations are available (in aips/ArrayMath.h and aips/ArrayLogical.h).

As with the Arrays, if the preprocessor symbol AIPS_DEBUG is defined at compile time invariants will be checked on entry to most member functions. Additionally, if AIPS_ARRAY_INDEX_CHECK is defined index operations will be bounds-checked. Neither of these should be defined for production code.

Member Description

Cube()

A Cube of length zero in each dimension; zero origin.

Cube(uInt l1, uInt l2, uInt l3)

A l1xl2xl3 sized cube.

Cube(uInt l1, uInt l2, uInt l3, const T &initialValue)

A l1xl2xl3 sized cube. Fill it with the initial value.

Cube(const IPosition &len)

A Cube where the shape ("len") is defined with IPositions.

Cube(const IPosition &len, const T &initialValue)

A Cube where the shape ("len") is defined with IPositions. Fill it with the initial value.

Cube(const Cube<T> &)

The copy constructor uses reference semantics.

Warning The copy constructor should normally be avoided. More details are available under the documentation for Array.

Cube(const Array<T> &)

Construct a cube by reference from "other". "other must have ndim() of 3 or less. The warning which applies to the copy constructor is also valid here.

Cube(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY)

Create an Cube of a given shape from a pointer.

Cube(const IPosition &shape, const T *storage)

Create an Cube of a given shape from a pointer. Because the pointer is const, a copy is always made.

virtual ~Cube()

Define a destructor, otherwise the (SUN) compiler makes a static one.

virtual void assign (const Array<T>& other)

Assign the other array (which must be dimension 3) to this cube. If the shapes mismatch, this array is resized.

virtual void reference(Array<T> &other)

Make this cube a reference to other. Other must be of dimensionality 3 or less.

void resize(uInt nx, uInt ny, uInt nz)
virtual void resize()
virtual void resize(const IPosition &)

Resize to the given shape. Resize without argument is equal to resize(0,0,0).

Cube<T> &operator=(const Cube<T> &other)
virtual Array<T> &operator=(const Array<T> &other)

Copy the values from other to this cube. If this cube has zero elements then it will resize to be the same shape as other; otherwise other must conform to this. Note that the assign function can be used to assign a non-conforming cube.

Array<T> &operator=(const T &val)

Copy val into every element of this cube; i.e. behaves as if val were a constant conformant cube.

Cube<T> &operator= (const MaskedArray<T> &marray)

Copy to this those values in marray whose corresponding elements in marray's mask are True.

T &operator()(const IPosition &i)
const T &operator()(const IPosition &i) const
T &operator()(uInt i1, uInt i2, uInt i3)
const T &operator()(uInt i1, uInt i2, uInt i3) const

Single-pixel addressing. If AIPS_ARRAY_INDEX_CHECK is defined, bounds checking is performed.

Cube<T> operator()(const Slice &sliceX, const Slice &sliceY, const Slice &sliceZ)

Take a slice of this cube. Slices are always indexed starting at zero. This uses reference semantics, i.e. changing a value in the slice changes the original.

    Cube<Double> vd(100,100,100);
    //...
    vd(Slice(0,10),Slice(10,10,Slice(0,10))) = -1.0; // sub-cube set to -1.0
    

Array<T> operator()(const IPosition &blc, const IPosition &trc, const IPosition &incr)
Array<T> operator()(const IPosition &blc, const IPosition &trc)
Array<T> operator()(const Slicer& slicer)

Slice using IPositions. Required to be defined, otherwise the base class versions are hidden.

MaskedArray<T> operator() (const LogicalArray &mask)

The array is masked by the input LogicalArray. This mask must conform to the array.

Return a MaskedArray.

MaskedArray<T> operator() (const LogicalArray &mask) const

The array is masked by the input LogicalArray. This mask must conform to the array.

MaskedArray<T> operator() (const MaskedLogicalArray &mask)

The array is masked by the input MaskedLogicalArray. The mask is effectively the AND of the internal LogicalArray and the internal mask of the MaskedLogicalArray. The MaskedLogicalArray must conform to the array.

Return a MaskedArray.

MaskedArray<T> operator() (const MaskedLogicalArray &mask) const

The array is masked by the input MaskedLogicalArray. The mask is effectively the AND of the internal LogicalArray and the internal mask of the MaskedLogicalArray. The MaskedLogicalArray must conform to the array.

Matrix<T> xyPlane(uInt zplane)
const Matrix<T> xyPlane(uInt zplane) const

Extract a plane as a cube. We could have xzPlane, etc also if that would be of use to anyone. Of course you could also use a Matrix iterator on the cube.

void shape(Int &s1, Int &s2, Int &s3) const
const IPosition &shape() const

The length of each axis of the cube.

uInt nrow() const

The number of rows in the Cube, i.e. the length of the first axis.

uInt ncolumn() const

The number of columns in the Cube, i.e. the length of the 2nd axis.

uInt nplane() const

The number of planes in the Cube, i.e. the length of the 3rd axis.

virtual void takeStorage(const IPosition &shape, const T *storage)

Replace the data values with those in the pointer storage. The results are undefined is storage does not point at nelements() or more data elements. After takeStorage() is called, unique() is True.

Since the pointer is const, a copy is always taken.

virtual void takeStorage(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY)

Replace the data values with those in the pointer storage. The results are undefined is storage does not point at nelements() or more data elements. After takeStorage() is called, unique() is True.

virtual Bool ok() const

Checks that the cube is consistent (invariants check out).

virtual void doNonDegenerate(Array<T> &other, const IPosition &ignoreAxes)

Remove the degenerate axes from other and store result in this cube. An exception is thrown if removing degenerate axes does not result in a cube.

void makeIndexingConstants()

Helper fn to calculate the indexing constants.