casa::Cube< T > Class Template Reference

A 3-D Specialization of the Array class. More...

#include <Cube.h>

Inheritance diagram for casa::Cube< T >:

List of all members.

Public Member Functions
	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.
	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.
	Cube (const Cube< T > &)
	The copy constructor uses reference semantics.
	Cube (const Array< T > &)
	Construct a cube by reference from "other".
	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.
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.
virtual void	reference (const Array< T > &other)
	Make this cube a reference to other.
void	resize (uInt nx, uInt ny, uInt nz, Bool copyValues=False)
	Resize to the given shape.
virtual void	resize ()
	Make this array a different shape.
virtual void	resize (const IPosition &newShape, Bool copyValues=False)
Cube< T > &	operator= (const Cube< T > &other)
	Copy the values from other to this cube.
virtual Array< T > &	operator= (const Array< T > &other)
	Copy the values in other to this.
Array< T > &	operator= (const T &val)
	Copy val into every element of this cube; i.e.
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)
	Single-pixel addressing.
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
T &	at (uInt i1, uInt i2, uInt i3)
const T &	at (uInt i1, uInt i2, uInt i3) const
Cube< T >	operator() (const Slice &sliceX, const Slice &sliceY, const Slice &sliceZ)
	Take a slice of this cube.
const Cube< T >	operator() (const Slice &sliceX, const Slice &sliceY, const Slice &sliceZ) const
Array< T >	operator() (const IPosition &blc, const IPosition &trc, const IPosition &incr)
	Slice using IPositions.
const Array< T >	operator() (const IPosition &blc, const IPosition &trc, const IPosition &incr) const
Array< T >	operator() (const IPosition &blc, const IPosition &trc)
	Get a reference to an array section extending from start to end (inclusive).
const Array< T >	operator() (const IPosition &blc, const IPosition &trc) const
Array< T >	operator() (const Slicer &slicer)
	Get a reference to an array section using a Slicer.
const Array< T >	operator() (const Slicer &slicer) const
const MaskedArray< T >	operator() (const LogicalArray &mask) const
	The array is masked by the input LogicalArray.
MaskedArray< T >	operator() (const LogicalArray &mask)
	Return a MaskedArray.
const MaskedArray< T >	operator() (const MaskedLogicalArray &mask) const
	The array is masked by the input MaskedLogicalArray.
MaskedArray< T >	operator() (const MaskedLogicalArray &mask)
	Return a MaskedArray.
Matrix< T >	xyPlane (uInt zplane)
	Extract a plane as a matrix referencing the original data.
const Matrix< T >	xyPlane (uInt zplane) const
Matrix< T >	xzPlane (uInt yplane)
const Matrix< T >	xzPlane (uInt yplane) const
Matrix< T >	yzPlane (uInt xplane)
const Matrix< T >	yzPlane (uInt xplane) const
void	shape (Int &s1, Int &s2, Int &s3) const
	The length of each axis of the cube.
const IPosition &	shape () const
	The length of each axis.
uInt	nrow () const
	The number of rows in the Cube, i.e.
uInt	ncolumn () const
	The number of columns in the Cube, i.e.
uInt	nplane () const
	The number of planes in the Cube, i.e.
virtual void	takeStorage (const IPosition &shape, T *storage, StorageInitPolicy policy=COPY)
	Replace the data values with those in the pointer storage.
virtual void	takeStorage (const IPosition &shape, const T *storage)
	Since the pointer is const, a copy is always taken.
virtual Bool	ok () const
	Checks that the cube is consistent (invariants check out).
Protected Member Functions
virtual void	doNonDegenerate (const Array< T > &other, const IPosition &ignoreAxes)
	Remove the degenerate axes from other and store result in this cube.
Private Member Functions
void	makeIndexingConstants ()
	Helper fn to calculate the indexing constants.
Private Attributes
Int	xinc_p
	Cached constants to improve indexing.
Int	yinc_p
Int	zinc_p

---

Detailed Description

template<class T>
class casa::Cube< T >

A 3-D Specialization of the Array class.

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

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.

Definition at line 81 of file Cube.h.

---

Constructor & Destructor Documentation

template<class T>

casa::Cube< T >::Cube

(

)

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

template<class T>

casa::Cube< T >::Cube	(	uInt	l1,
		uInt	l2,
		uInt	l3
	)

A l1xl2xl3 sized cube.

template<class T>

casa::Cube< T >::Cube	(	uInt	l1,
		uInt	l2,
		uInt	l3,
		const T &	initialValue
	)

A l1xl2xl3 sized cube.

Fill it with the initial value.

template<class T>

casa::Cube< T >::Cube

(

const IPosition &

len

)

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

template<class T>

casa::Cube< T >::Cube	(	const IPosition &	len,
		const T &	initialValue
	)

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

Fill it with the initial value.

template<class T>

casa::Cube< T >::Cube

(

const Cube< T > &

)

The copy constructor uses reference semantics.

template<class T>

casa::Cube< T >::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.

template<class T>

casa::Cube< T >::Cube	(	const IPosition &	shape,
		T *	storage,
		StorageInitPolicy	policy = COPY
	)

Create an Cube of a given shape from a pointer.

template<class T>

casa::Cube< T >::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.

template<class T>

virtual casa::Cube< T >::~Cube

(

)

[virtual]

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

---

Member Function Documentation

template<class T>

virtual void casa::Cube< T >::assign

(

const Array< T > &

other

)

[virtual]

Assign the other array (which must be dimension 3) to this cube.

If the shapes mismatch, this array is resized.

Reimplemented from casa::Array< T >.

Referenced by casa::ConvolutionFunction::setSpwSelection().

template<class T>

T& casa::Cube< T >::at	(	uInt	i1,
		uInt	i2,
		uInt	i3
	)		[inline]

Definition at line 182 of file Cube.h.

Referenced by ASDM_TABLE_BASE::_2CASAString3D(), ASDM_TABLE_BASE::at2CASA3D(), ASDM_TABLE_BASE::basic2CASA3D(), ASDM_TABLE_BASE::ext2CASA3D(), and ASDM_TABLE_BASE::interval2CASA3D().

template<class T>

const T& casa::Cube< T >::at	(	uInt	i1,
		uInt	i2,
		uInt	i3
	)		const [inline]

Definition at line 191 of file Cube.h.

template<class T>

virtual void casa::Cube< T >::doNonDegenerate	(	const Array< T > &	other,
		const IPosition &	ignoreAxes
	)		[protected, virtual]

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.

Reimplemented from casa::Array< T >.

template<class T>

void casa::Cube< T >::makeIndexingConstants

(

)

[private]

Helper fn to calculate the indexing constants.

template<class T>

uInt casa::Cube< T >::ncolumn

(

)

const [inline]

The number of columns in the Cube, i.e.

the length of the 2nd axis.

Definition at line 293 of file Cube.h.

template<class T>

uInt casa::Cube< T >::nplane

(

)

const [inline]

The number of planes in the Cube, i.e.

the length of the 3rd axis.

Definition at line 297 of file Cube.h.

template<class T>

uInt casa::Cube< T >::nrow

(

)

const [inline]

The number of rows in the Cube, i.e.

the length of the first axis.

Definition at line 289 of file Cube.h.

template<class T>

virtual Bool casa::Cube< T >::ok

(

)

const [virtual]

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

Reimplemented from casa::Array< T >.

template<class T>

T& casa::Cube< T >::operator()

(

const IPosition &

i

)

[inline]

Single-pixel addressing.

If AIPS_ARRAY_INDEX_CHECK is defined, bounds checking is performed.

Reimplemented from casa::Array< T >.

Definition at line 159 of file Cube.h.

Referenced by casa::Cube< Complex >::operator()().

template<class T>

const T& casa::Cube< T >::operator()

(

const IPosition &

i

)

const [inline]

Reimplemented from casa::Array< T >.

Definition at line 161 of file Cube.h.

template<class T>

T& casa::Cube< T >::operator()	(	uInt	i1,
		uInt	i2,
		uInt	i3
	)		[inline]

Definition at line 164 of file Cube.h.

template<class T>

const T& casa::Cube< T >::operator()	(	uInt	i1,
		uInt	i2,
		uInt	i3
	)		const [inline]

Definition at line 172 of file Cube.h.

template<class T>

Cube<T> casa::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

template<class T>

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

template<class T>

Array<T> casa::Cube< T >::operator()	(	const IPosition &	blc,
		const IPosition &	trc,
		const IPosition &	incr
	)		[inline]

Slice using IPositions.

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

Reimplemented from casa::Array< T >.

Definition at line 219 of file Cube.h.

template<class T>

const Array<T> casa::Cube< T >::operator()	(	const IPosition &	blc,
		const IPosition &	trc,
		const IPosition &	incr
	)		const [inline]

Reimplemented from casa::Array< T >.

Definition at line 222 of file Cube.h.

template<class T>

Array<T> casa::Cube< T >::operator()	(	const IPosition &	start,
		const IPosition &	end
	)		[inline]

Get a reference to an array section extending from start to end (inclusive).

Reimplemented from casa::Array< T >.

Definition at line 225 of file Cube.h.

template<class T>

const Array<T> casa::Cube< T >::operator()	(	const IPosition &	blc,
		const IPosition &	trc
	)		const [inline]

Reimplemented from casa::Array< T >.

Definition at line 227 of file Cube.h.

template<class T>

Array<T> casa::Cube< T >::operator()

(

const Slicer &

)

[inline]

Get a reference to an array section using a Slicer.

Reimplemented from casa::Array< T >.

Definition at line 229 of file Cube.h.

template<class T>

const Array<T> casa::Cube< T >::operator()

(

const Slicer &

slicer

)

const [inline]

Reimplemented from casa::Array< T >.

Definition at line 231 of file Cube.h.

template<class T>

const MaskedArray<T> casa::Cube< T >::operator()

(

const LogicalArray &

mask

)

const [inline]

The array is masked by the input LogicalArray.

This mask must conform to the array.

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 241 of file Cube.h.

template<class T>

MaskedArray<T> casa::Cube< T >::operator()

(

const LogicalArray &

mask

)

[inline]

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 245 of file Cube.h.

template<class T>

const MaskedArray<T> casa::Cube< T >::operator()

(

const MaskedLogicalArray &

mask

)

const [inline]

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.

Reimplemented from casa::Array< T >.

Definition at line 258 of file Cube.h.

template<class T>

MaskedArray<T> casa::Cube< T >::operator()

(

const MaskedLogicalArray &

mask

)

[inline]

Return a MaskedArray.

Reimplemented from casa::Array< T >.

Definition at line 262 of file Cube.h.

template<class T>

Cube<T>& casa::Cube< T >::operator=

(

const Cube< 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.

Referenced by casa::Cube< Complex >::operator=().

template<class T>

virtual Array<T>& casa::Cube< T >::operator=

(

const Array< T > &

other

)

[virtual]

Copy the values in other to this.

If the array on the left hand side has no elements, then it is resized to be the same size as as the array on the right hand side. Otherwise, the arrays must conform (same shapes).

        IPosition shape(2,10,10);     // some shape
        Array<Double> ad(shape);
        //..\.
        Array<Double> ad2;            // N.B. ad2.nelements() == 0
        ad2 = ad;                     // ad2 resizes, then elements
                                      //     are copied.
        shape = 20;
        Array<Double> ad3(shape);
        ad3 = ad;                     // Error: arrays do not conform

Note that the assign function can be used to assign a non-conforming array.

Reimplemented from casa::Array< T >.

template<class T>

Array<T>& casa::Cube< T >::operator=

(

const T &

val

)

[inline]

Copy val into every element of this cube; i.e.

behaves as if val were a constant conformant cube.

Reimplemented from casa::Array< T >.

Definition at line 147 of file Cube.h.

template<class T>

Cube<T>& casa::Cube< T >::operator=

(

const MaskedArray< T > &

marray

)

[inline]

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

Reimplemented from casa::Array< T >.

Definition at line 152 of file Cube.h.

template<class T>

virtual void casa::Cube< T >::reference

(

const Array< T > &

other

)

[virtual]

Make this cube a reference to other.

Other must be of dimensionality 3 or less.

Reimplemented from casa::Array< T >.

Referenced by casa::VBStore::reference(), and casa::LFBase::runMethod().

template<class T>

void casa::Cube< T >::resize	(	uInt	nx,
		uInt	ny,
		uInt	nz,
		Bool	copyValues = False
	)

Resize to the given shape.

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

Referenced by ASDM_TABLE_BASE::_2CASAString3D(), ASDM_TABLE_BASE::at2CASA3D(), ASDM_TABLE_BASE::ati2CASA3D(), ASDM_TABLE_BASE::basic2CASA3D(), ASDM_TABLE_BASE::enum2CASA3D(), ASDM_TABLE_BASE::ext2CASA3D(), ASDM_TABLE_BASE::interval2CASA3D(), casa::VisBuffer::modelVisCube(), casa::EPJones::setRPar(), and casa::LJJones::setRPar().

template<class T>

virtual void casa::Cube< T >::resize

(

)

[virtual]

Make this array a different shape.

If copyValues==True the old values are copied over to the new array. Copying is done on a per axis basis, thus a subsection with the minimum of the old and new shape is copied.
Resize without argument is equal to resize(IPosition()).
It is important to note that if multiple Array objects reference the same data storage, this Array object still references the same data storage as the other Array objects if the shape does not change. Otherwise this Array object references newly allocated storage, while the other Array objects still reference the existing data storage.
If you want to be sure that the data storage of this Array object is not referenced by other Array objects, the function unique should be called first.

Reimplemented from casa::Array< T >.

template<class T>

virtual void casa::Cube< T >::resize	(	const IPosition &	newShape,
		Bool	copyValues = False
	)		[virtual]

Reimplemented from casa::Array< T >.

template<class T>

void casa::Cube< T >::shape	(	Int &	s1,
		Int &	s2,
		Int &	s3
	)		const [inline]

The length of each axis of the cube.

Definition at line 282 of file Cube.h.

Referenced by casa::VBContinuumSubtractor::checkSize(), casa::EPJones::setRPar(), and casa::LJJones::setRPar().

template<class T>

const IPosition& casa::Cube< T >::shape

(

)

const [inline]

The length of each axis.

Reimplemented from casa::ArrayBase.

Definition at line 284 of file Cube.h.

template<class T>

virtual void casa::Cube< T >::takeStorage	(	const IPosition &	shape,
		T *	storage,
		StorageInitPolicy	policy = COPY
	)		[virtual]

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.

Reimplemented from casa::Array< T >.

template<class T>

virtual void casa::Cube< T >::takeStorage	(	const IPosition &	shape,
		const T *	storage
	)		[virtual]

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

Reimplemented from casa::Array< T >.

template<class T>

Matrix<T> casa::Cube< T >::xyPlane

(

uInt

zplane

)

Extract a plane as a matrix referencing the original data.

Of course you could also use a Matrix iterator on the cube.

template<class T>

const Matrix<T> casa::Cube< T >::xyPlane

(

uInt

zplane

)

const

template<class T>

Matrix<T> casa::Cube< T >::xzPlane

(

uInt

yplane

)

template<class T>

const Matrix<T> casa::Cube< T >::xzPlane

(

uInt

yplane

)

const

template<class T>

Matrix<T> casa::Cube< T >::yzPlane

(

uInt

xplane

)

template<class T>

const Matrix<T> casa::Cube< T >::yzPlane

(

uInt

xplane

)

const

---

Member Data Documentation

template<class T>

Int casa::Cube< T >::xinc_p [private]

Cached constants to improve indexing.

Definition at line 323 of file Cube.h.

Referenced by casa::Cube< Complex >::at(), and casa::Cube< Complex >::operator()().

template<class T>

Int casa::Cube< T >::yinc_p [private]

Definition at line 323 of file Cube.h.

Referenced by casa::Cube< Complex >::at(), and casa::Cube< Complex >::operator()().

template<class T>

Int casa::Cube< T >::zinc_p [private]

Definition at line 323 of file Cube.h.

Referenced by casa::Cube< Complex >::at(), and casa::Cube< Complex >::operator()().

---

The documentation for this class was generated from the following file:

• casacore/casa/Arrays/Cube.h