The envelope and bridge provide the interface which the programmer sees. The letter classes do the real work and are hidden from the programmer.
All the expression manipulation functionality that the user has access to is viewable in this class; it is here that the operators, functions and constructors are defined. These allow the programmer to write mathematical expressions which involve Lattices. The letter classes take care of the optimal traversal of the Lattice and the memory mangement thereof. Thus the Lattices are iterated through and the expressions evaluated for each chunk (usually a tile shape) of the iteration.
A description of the implementation details of these classes can be found in Note 216
The available functionality is defined by the global friend functions and operators, plus the public constructors. The other public members functions are generally not of interest to the user of this class.
Generally, if one writes an expression such as a.copyData(sin(b)),
the expression is automatically converted first to a LatticeExprNode and
then to a LatticeExpr (which is a Lattice) before evaluation occurs.
However, it may occur that you wish to build an expression from
subexpressions. To do this, you must explcitly create objects of
class LatticeExprNode. You cannot manipulate subexpressions of type
LatticeExpr
Note that :
1) the Lattice::copyData function is expecting a Lattice argument.
2) LatticeExpr inherits from Lattice and therefore a LatticeExpr
object is a valid argument object type
3) The expression in the copyData call is automatically converted to
a LatticeExprNode by the constructors and operators in LatticeExprNode
4) The LatticeExprNode object so created is automatically converted
to a LatticeExpr by casting functions in LatticeExprNode.
In this rather silly example, we fill Lattice "f1" with the result of the
expression. The expression shows the use of constants, unary operations,
binary operations, 1D and 2D functions. It also shows how mixed types can
be handled. The output Lattice is a Float, whereas mixed into the
expression are subexpressions involving Float, Double, Complex and Bool
Lattices.
Numerical binary operators
Relational binary operators
Logical binary operators
Numerical 1-argument functions
Numerical 2-argument functions
Form a complex number from two real numbers.
Numerical 1-argument functions which result in a real number
regardless of input expression type
1-argument functions operating on a numeric expression resulting
in a scalar
Determine the value of the element at the part fraction
from the beginning of the given lattice.
Thus fraction=0.5 is equal to the median.
Determine the value range of the elements at the part fraction1
and fraction2 from the beginning of the given lattice. Both fractions
must be >=0 and <=1 and fraction1 must be <= fraction2.
By default
1-argument function to get the number of elements in a lattice.
If the lattice is masked, only the True elements are counted.
Results in a scalar Double.
1-argument function to get the dimensionality of a lattice.
0 is returned if it is a scalar.
Results in a scalar Float.
2-argument function to get the length of an axis.
Results in a scalar Float.
The 2nd expression (giving the axis number) has to be a real scalar.
2-argument function telling per pixel if its index on the given axis
is contained in the 2nd argument. The 2nd argument should be a boolean
vector where True means that the index is contained.
For indices >= vector_length, the 2nd argument defaults to False.
Results in a Bool array.
2-argument function rebinning Lattice by given factors. The 2nd argument
should be a vector (preferably Float - really Int but Int not well
supported in LEL yet). Results in a T array.
Test if a value is a NaN.
Functions operating on a logical expression resulting in a scalar;
Functions "any" (are any pixels "True") and "all" (are all pixels
"True") result in a Bool; functions "ntrue" and "nfalse" result
in a Double.
This functions returns the mask of the given expression.
If it has no mask, the result is an array with all True values.
This functions returns the value of the expression without a mask.
This function finds sqrt(left^2+right^2). This
could be used to find the (biased) polarized intensity if
left and right are images of Stokes Q and U.
This function finds 180/pi*atan2(left,right)/2. This could be
used to find the position of linear polarization if left
and right are images of Stokes U and Q, respectively.
This function finds the spectral index
alpha = log(s1/s2) / log(f1/f2).
Function resembling the ternary ?: construct in C++.
The argument "condition" has to be a Bool scalar or lattice.
If an element in "condition" is True, the corresponding element from
"arg1" is taken, otherwise it is taken from "arg2".
This function replaces every masked-off element in the first argument
with the corresponding element from the second argument.
The first argument has to be a lattice (expression), the second can
be a scalar or lattice. The mask of the first argument is not changed.
If the first argument does not have a mask, this function does nothing.
Functions to convert to the given data type. These are mostly
meaningful for down-conversions (e.g. double to float),
since up-conversions are automatically done to get matching data types
when needed. Note that some conversions are not supported, such
as Complex to Double or Float.
Unary constant expression constructors.
Constructor from an IPosition (containing indices or axes).
Lattice expression (gets Lattice pixels) constructors.
Create a lattice expression from a region.
It results in a boolean expression node.
Masking operator using a condition.
The given boolean expression forms a mask/region for this expression node.
Copy constructor (reference semantics)
Destructor, does nothing
Assignment (reference semantics)
Get the IPosition.
It throws an exception if the node does not contain an IPosition.
Convert the expression to another data type.
Evaluate the expression.
One can be sure that the result is not a reference to another array.
This function should be used by LatticeExpr and other users.
Evaluate the expression.
The result can be a reference to some internal array (in particular
to an array in an ArrayLattice object used as a lattice).
This function is meant for internal use by the LEL classes and
should not be used externally.
Evaluate the expression (in case it is a scalar). The "eval"
and "get*" functions do the same thing, they just have
a slightly different interface.
Evaluate the expression (in case it is a constant array).
Get the data type of the expression.
Is the expression node a region?
Is the result of "eval" a scalar?
Is the result of "eval" masked?
Holds the node an invalid scalar?
Return the shape of the Lattice including all degenerate axes
(ie. axes with a length of one)
Get the attribute object of the expression.
Replace a scalar subexpression by its result.
Make the object from a Counted
Determine the resulting data type from the given data types.
An exception is thrown if they are incompatible.
Check the arguments of a function and return the resulting attribute object.
The matchAxes argument tells if the axes have to match exactly or
whether it is possible that one expression is a subset of another
(i.e. that axes may be missing).
Handle locking of the LatticeExpr which is delegated to all of its parts.
Test if both operands represent a region.
An exception is thrown if only one of them is a region.
Create a new node for a numerical unary operation.
The result has the same data type as the input.
Create a new node for a numerical function with 1 argument.
The result has the same data type as the input.
Create a new node for a real numerical function with 1 argument.
The result has the same data type as the input.
Create a new node for a complex numerical function with 1 argument.
The result has the same data type as the input.
Create a new node for a numerical function with 1 argument that
returns a real number
Create a new node for a numerical function with 2 arguments.
The result has the same data type as the combined input type.
Create a new node for a numerical binary operator.
The result has the same data type as the combined input type.
Create a new node for a comparison binary operator.
The result has the same data type as the combined input type.
Make (if needed and if possible) the expression nodes such that
the dimensionalities are equal. This is only possible if both
nodes have a coordinate system.
It is done by creating an ExtendLattice object for the node
with the lower dimensionality.
Do the preparation for the evaluation.
Example
ArrayLattice<Float> f1(IPosition (2,nx,ny));
ArrayLattice<Float> f2(IPosition (2,nx,ny));
f2.set(2.0);
f1.copyData(2*f2+f2);
In this example, the values of the pixels in Lattice f1 are set
to the values resulting from the expression "2*f2 + f2"
I.e. the expression is evaluated for each pixel in the Lattices
Example
ArrayLattice<Float> f1(IPosition (2,nx,ny));
ArrayLattice<Float> f2(IPosition (2,nx,ny));
ArrayLattice<Double> d(IPosition (2,nx,ny));
ArrayLattice<Complex> c(IPosition (2,nx,ny));
ArrayLattice<Bool> b(IPosition (2,nx,ny));
f2.set(1.0); d.set(2.0); c.set(Complex(2.0,3.0)); b.set(True);
f1.copyData( (3.5*f2) + (cos(d)) - (10/min(d,f2)*(-abs(c))*ntrue(b)) - (C::pi) );
Example
ArrayLattice<Float> f1(IPosition (2,nx,ny));
ArrayLattice<Float> f2(IPosition (2,nx,ny));
f2.set(2.0);
LatticeExprNode exp1(sin(f2));
LatticeExprNode exp2(pow(f2,2.0));
f1.copyData(exp1+exp2);
In this example, the expression is "sin(f2) + pow(f2,2.0)",
but we have put it together from two subexpressions contained
in LatticeExprNode objects exp1 and exp2. Again the LatticeExprNode
object formed from summing exp1 and exp2 is automatically converted
to a LatticeExpr for consumption by copyData
Motivation
The Lattice expression classes enable the C++ programmer much simpler
handling of mathematical expressions involving lattices. In addition,
these classes provide the infrastructure on top of which we can build
an image calculator for Glish users
To Do
Member Description
friend LatticeExprNode operator+(const LatticeExprNode& expr)
Unary operators
friend LatticeExprNode operator-(const LatticeExprNode& expr)
friend LatticeExprNode operator!(const LatticeExprNode& expr)
friend LatticeExprNode operator+ (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator- (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator* (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator/ (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator% (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator== (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator> (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator>= (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator< (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator<= (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator!= (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator&& (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode operator|| (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode sin (const LatticeExprNode& expr)
friend LatticeExprNode sinh (const LatticeExprNode& expr)
friend LatticeExprNode asin (const LatticeExprNode& expr)
friend LatticeExprNode cos (const LatticeExprNode& expr)
friend LatticeExprNode cosh (const LatticeExprNode& expr)
friend LatticeExprNode acos (const LatticeExprNode& expr)
friend LatticeExprNode tan (const LatticeExprNode& expr)
friend LatticeExprNode tanh (const LatticeExprNode& expr)
friend LatticeExprNode atan (const LatticeExprNode& expr)
friend LatticeExprNode exp (const LatticeExprNode& expr)
friend LatticeExprNode log (const LatticeExprNode& expr)
friend LatticeExprNode log10(const LatticeExprNode& expr)
friend LatticeExprNode sqrt (const LatticeExprNode& expr)
friend LatticeExprNode sign (const LatticeExprNode& expr)
friend LatticeExprNode round(const LatticeExprNode& expr)
friend LatticeExprNode ceil (const LatticeExprNode& expr)
friend LatticeExprNode floor(const LatticeExprNode& expr)
friend LatticeExprNode conj (const LatticeExprNode& expr)
friend LatticeExprNode atan2 (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode pow (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode fmod (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode min (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode max (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode formComplex (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode abs (const LatticeExprNode& expr)
friend LatticeExprNode arg (const LatticeExprNode& expr)
friend LatticeExprNode real (const LatticeExprNode& expr)
friend LatticeExprNode imag (const LatticeExprNode& expr)
friend LatticeExprNode min (const LatticeExprNode& expr)
friend LatticeExprNode max (const LatticeExprNode& expr)
friend LatticeExprNode sum (const LatticeExprNode& expr)
friend LatticeExprNode median (const LatticeExprNode& expr)
friend LatticeExprNode mean (const LatticeExprNode& expr)
friend LatticeExprNode variance (const LatticeExprNode& expr)
friend LatticeExprNode stddev (const LatticeExprNode& expr)
friend LatticeExprNode avdev (const LatticeExprNode& expr)
friend LatticeExprNode fractile (const LatticeExprNode& expr, const LatticeExprNode& fraction)
friend LatticeExprNode fractileRange (const LatticeExprNode& expr, const LatticeExprNode& fraction1, const LatticeExprNode& fraction2)
friend LatticeExprNode fractileRange (const LatticeExprNode& expr, const LatticeExprNode& fraction)
friend LatticeExprNode nelements (const LatticeExprNode& expr)
friend LatticeExprNode ndim (const LatticeExprNode& expr)
friend LatticeExprNode length (const LatticeExprNode& expr, const LatticeExprNode& axis)
Axes start counting at 1.
If the axis is a number < 1, an exception is thrown.
If the axis is a number exceeding the dimensionality, 1 is returned.
friend LatticeExprNode indexin (const LatticeExprNode& axis, const LatticeExprNode& indexFlags)
Axes start counting at 1.
If the axis is a number < 1 or > ndim, an exception is thrown.
friend LatticeExprNode rebin (const LatticeExprNode& expr, const LatticeExprNode& bin)
friend LatticeExprNode isNaN (const LatticeExprNode& expr)
friend LatticeExprNode any (const LatticeExprNode& expr)
friend LatticeExprNode all (const LatticeExprNode& expr)
friend LatticeExprNode ntrue (const LatticeExprNode& expr)
friend LatticeExprNode nfalse(const LatticeExprNode& expr)
friend LatticeExprNode mask (const LatticeExprNode& expr)
friend LatticeExprNode value (const LatticeExprNode& expr)
friend LatticeExprNode amp (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode pa (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode spectralindex (const LatticeExprNode& left, const LatticeExprNode& right)
friend LatticeExprNode iif (const LatticeExprNode& condition, const LatticeExprNode& arg1, const LatticeExprNode& arg2)
friend LatticeExprNode replace (const LatticeExprNode& arg1, const LatticeExprNode& arg2)
friend LatticeExprNode toFloat (const LatticeExprNode& expr)
friend LatticeExprNode toDouble (const LatticeExprNode& expr)
friend LatticeExprNode toComplex (const LatticeExprNode& expr)
friend LatticeExprNode toDComplex(const LatticeExprNode& expr)
friend LatticeExprNode toBool (const LatticeExprNode& expr)
The conversion to Bool is useful to convert a region to a
boolean lattice, which is only possible if the region is given
in world coordinates. Otherwise an exception is thrown.
LatticeExprNode()
Default constructor
LatticeExprNode (Int constant)
LatticeExprNode (Float constant)
LatticeExprNode (Double constant)
LatticeExprNode (const Complex& constant)
LatticeExprNode (const DComplex& constant)
LatticeExprNode (Bool constant)
LatticeExprNode (const IPosition&)
LatticeExprNode (const Lattice<Float>& lattice)
LatticeExprNode (const Lattice<Double>& lattice)
LatticeExprNode (const Lattice<Complex>& lattice)
LatticeExprNode (const Lattice<DComplex>& lattice)
LatticeExprNode (const Lattice<Bool>& lattice)
LatticeExprNode (const MaskedLattice<Float>& lattice)
LatticeExprNode (const MaskedLattice<Double>& lattice)
LatticeExprNode (const MaskedLattice<Complex>& lattice)
LatticeExprNode (const MaskedLattice<DComplex>& lattice)
LatticeExprNode (const MaskedLattice<Bool>& lattice)
LatticeExprNode (const LCRegion& region)
LatticeExprNode (const Slicer& slicer)
LatticeExprNode (const LattRegionHolder& region)
LatticeExprNode operator[] (const LatticeExprNode& cond) const
LatticeExprNode (const LatticeExprNode& other)
virtual ~LatticeExprNode()
LatticeExprNode& operator= (const LatticeExprNode& other)
const IPosition& getIPosition() const
CountedPtr<LELInterface<Float> > makeFloat() const
CountedPtr<LELInterface<Double> > makeDouble() const
CountedPtr<LELInterface<Complex> > makeComplex() const
CountedPtr<LELInterface<DComplex> > makeDComplex() const
CountedPtr<LELInterface<Bool> > makeBool() const
void eval (LELArray<Float>& result, const Slicer& section) const
void eval (LELArray<Double>& result, const Slicer& section) const
void eval (LELArray<Complex>& result, const Slicer& section) const
void eval (LELArray<DComplex>& result, const Slicer& section) const
void eval (LELArray<Bool>& result, const Slicer& section) const
void evalRef (LELArrayRef<Float>& result, const Slicer& section) const
void evalRef (LELArrayRef<Double>& result, const Slicer& section) const
void evalRef (LELArrayRef<Complex>& result, const Slicer& section) const
void evalRef (LELArrayRef<DComplex>& result, const Slicer& section) const
void evalRef (LELArrayRef<Bool>& result, const Slicer& section) const
void eval (Float& result) const
void eval (Double& result) const
void eval (Complex& result) const
void eval (DComplex& result) const
void eval (Bool& result) const
Float getFloat() const
Double getDouble() const
Complex getComplex() const
DComplex getDComplex() const
Bool getBool() const
Array<Float> getArrayFloat() const
Array<Double> getArrayDouble() const
Array<Complex> getArrayComplex() const
Array<DComplex> getArrayDComplex() const
Array<Bool> getArrayBool() const
DataType dataType() const
Bool isRegion() const
Bool isScalar() const
Bool isMasked() const
Bool isInvalidScalar() const
const IPosition& shape() const
const LELAttribute& getAttribute() const
Bool replaceScalarExpr()
LatticeExprNode(const CountedPtr<LELInterface<Float> >& expr)
LatticeExprNode(const CountedPtr<LELInterface<Double> >& expr)
LatticeExprNode(const CountedPtr<LELInterface<Complex> >& expr)
LatticeExprNode(const CountedPtr<LELInterface<DComplex> >& expr)
LatticeExprNode(const CountedPtr<LELInterface<Bool> >& expr)
static DataType resultDataType (DataType left, DataType right)
static LELAttribute checkArg (const Block<LatticeExprNode>& arg, const Block<Int>& argType, Bool expectArray, Bool matchAxes = True)
The expectArray argument tells if the result should be an array
which is the case if one of the arguments is an array.
Bool lock (FileLocker::LockType, uInt nattempts)
void unlock()
Bool hasLock (FileLocker::LockType) const
void resync()
LatticeExprNode(LELInterface<Float>* expr)
Make the object from a LELInterface* pointer.
LatticeExprNode(LELInterface<Double>* expr)
LatticeExprNode(LELInterface<Complex>* expr)
LatticeExprNode(LELInterface<DComplex>* expr)
LatticeExprNode(LELInterface<Bool>* expr)
static Bool areRegions (const LatticeExprNode& left, const LatticeExprNode& right)
static LatticeExprNode newNumUnary (LELUnaryEnums::Operation oper, const LatticeExprNode& expr)
static LatticeExprNode newNumFunc1D (LELFunctionEnums::LELFunctionEnums func, const LatticeExprNode& expr)
static LatticeExprNode newRealFunc1D (LELFunctionEnums::LELFunctionEnums func, const LatticeExprNode& expr)
static LatticeExprNode newComplexFunc1D (LELFunctionEnums::LELFunctionEnums func, const LatticeExprNode& expr)
static LatticeExprNode newNumReal1D (LELFunctionEnums::LELFunctionEnums func, const LatticeExprNode& expr)
static LatticeExprNode newNumFunc2D (LELFunctionEnums::LELFunctionEnums func, const LatticeExprNode& left, const LatticeExprNode& right)
static LatticeExprNode newNumBinary (LELBinaryEnums::Operation oper, const LatticeExprNode& left, const LatticeExprNode& right)
static LatticeExprNode newBinaryCmp (LELBinaryEnums::Operation oper, const LatticeExprNode& left, const LatticeExprNode& right)
static Int makeEqualDim (LatticeExprNode& expr0, LatticeExprNode& expr1)
void doPrepare() const