Loading...
Searching...
No Matches
casacore::LatticeApply< T, U > Class Template Reference
lattices package (libcasa_lattices) » LatticeMath_module

More...

`#include <LatticeApply.h>`

## Static Public Member Functions

static void | lineApply (MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
| This function iterates line by line through an input lattice and applies a user supplied function object to each line along the specified axis.
static void | lineApply (MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
static void | lineMultiApply (Block< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
| This function iterates line by line through an input lattice and applies a user supplied function object to each line along the specified axis.
static void | lineMultiApply (Block< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
static void | tiledApply (MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, Int newOutAxis=-1, LatticeProgress *tellProgress=0)
| This function iterates tile by tile through an input lattice and applies a user supplied function object to each chunk along the specified axes.
static void | tiledApply (MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, Int newOutAxis=-1, LatticeProgress *tellProgress=0)
static void | tiledMultiApply (Block< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, LatticeProgress *tellProgress=0)
| This function iterates tile by tile through an input lattice and applies a user supplied function object to each chunk along the specified axes.
static void | tiledMultiApply (Block< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, LatticeProgress *tellProgress=0)

## Static Private Member Functions

static IPosition | prepare (const IPosition &shapeIn, const IPosition &shapeOut, const IPosition &collapseAxes, Int newOutAxis)
| Do some checks on the given arguments.
static IPosition | _chunkShape (uInt axis, const MaskedLattice< T > &latticeIn)

## Detailed Description

template<class T, class U = T>
class casacore::LatticeApply< T, U >

Optimally iterate through a Lattice and apply provided function object

### Intended use:

Public interface

### Review Status

Date Reviewed:
  yyyy/mm/dd

### Prerequisite

- MaskedLattice
- LineCollapser
- TiledCollapser

### Synopsis

This function iterates through a Lattice and applies a user given function object to chunks along the specified axes. Usually the function collapses the chunk to 1 or a few values (e.g. get min/max). The result of the function is written into the output Lattice(s) at the location of the collapsed chunk. The output lattice(s) must be supplied with the correct shape. E.g. when a lattice with shape [nx,ny,nz] is collapsed by calculating the mean of each y-line, the output lattice has to have shape [nx,nz]. It is also possible to have output shape [nx,1,nz], [1,nx,nz], [nx,nz,1] or even e.g. [nx,1,1,1,nz].

By specifying a region it is possible to apply the function object to a subset of the lattice. Of course, the shape of the output lattice(s) have to match the shape of the region.

The iteration is done in an optimal way. To keep memory usage down, it caches as few tiles as possible. There are 2 ways to iterate.

1. For some applications an entire line is needed. An example is the calculation of the moment. The functions lineApply and lineMultiApply can be used for that purpose. Internally they use the TiledLineStepper navigator, so only a few tiles are kept in the cache.
   One can also think of applications where an entire plane (or cube) is needed. This is not supported, but can be implemented when needed.
2. Other applications do not care how the data are traversed, making it possible to iterate tile by tile (which is optimal). An example is the calculation of the minimum, maximum, mean of a line, plane, etc.. For this purpose the function tiledApply can be used. This function is faster and uses less memory than lineApply, so whenever possible this one should be used. Another advantage of this function is that it is possible to operate per line, plane, etc. or even for the entire lattice.

The user has to supply a function object derived from the abstract base class LineCollapser or TiledCollapser, resp.. The process function in these classes has to process the chunk of data passed in. The nstepsDone function in these classes can be used to monitor the progress.

The class is Doubly templated. Ths first template type is for the data type you are processing. The second type is for what type you want the results of the processing assigned to. For example, if you are computing sums of squares for statistical purposes, you might use higher precision (Float->Double) for this. No check is made that the template types are self-consistent.

### Example

Collapse each line in the y-direction using my collapser function object.

MyLineCollapser collapser;
PagedArray<Float> latticeIn("lattice.file");
IPosition shape = latticeIn.shape();
shape(1) = 1;
ArrayLattice<Double> latticeOut(shape);
LatticeApply<Float,Double>::lineApply (latticeOut, latticeIn, collapser, 1);
casacore::ArrayLattice
Definition ArrayLattice.h:144
casacore::IPosition
Definition IPosition.h:117
casacore::LatticeApply::lineApply
static void lineApply(MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
This function iterates line by line through an input lattice and applies a user supplied function obj...
casacore::PagedArray
Definition PagedArray.h:372
casacore::shape
IPosition shape(const RecordFieldId &) const
Get the actual shape of this field.

### Motivation

This class makes it possible that a user can apply functions to a lattice in an optimal way, without having to know all the details of iterating through a lattice.

Definition at line 135 of file LatticeApply.h.

## Member Function Documentation

## _chunkShape()

template<class T, class U = T>

IPosition casacore::LatticeApply< T, U >::_chunkShape | ( | uInt | axis,
|  | const MaskedLattice< T > & | latticeIn )

static private

## lineApply() [1/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::lineApply | ( | MaskedLattice< U > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | const LatticeRegion & | region,
|  | LineCollapser< T, U > & | collapser,
|  | uInt | collapseAxis,
|  | LatticeProgress * | tellProgress = 0 )

static

## lineApply() [2/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::lineApply | ( | MaskedLattice< U > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | LineCollapser< T, U > & | collapser,
|  | uInt | collapseAxis,
|  | LatticeProgress * | tellProgress = 0 )

static

This function iterates line by line through an input lattice and applies a user supplied function object to each line along the specified axis.

The scalar result of the function object is written into the output lattice at the location of the collapsed line. The output lattice must be supplied with the correct shape (the shape of the supplied region). The default region is the entire input lattice.

## lineMultiApply() [1/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::lineMultiApply | ( | Block< MaskedLattice< U > * > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | const LatticeRegion & | region,
|  | LineCollapser< T, U > & | collapser,
|  | uInt | collapseAxis,
|  | LatticeProgress * | tellProgress = 0 )

static

## lineMultiApply() [2/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::lineMultiApply | ( | Block< MaskedLattice< U > * > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | LineCollapser< T, U > & | collapser,
|  | uInt | collapseAxis,
|  | LatticeProgress * | tellProgress = 0 )

static

This function iterates line by line through an input lattice and applies a user supplied function object to each line along the specified axis.

The vector result of the function object is written into the output lattices at the location of the collapsed line (1 value per lattice). The output lattices must be supplied with the correct shape (the shape of the supplied region). The default region is the entire input lattice.

## prepare()

template<class T, class U = T>

IPosition casacore::LatticeApply< T, U >::prepare | ( | const IPosition & | shapeIn,
|  | const IPosition & | shapeOut,
|  | const IPosition & | collapseAxes,
|  | Int | newOutAxis )

static private

Do some checks on the given arguments.

It returns an IPosition with the same length as shapeOut. It contains a mapping of output to input axes. A value of -1 indicates that the axis is new (to contain the collapse result).
Argument newOutAxis tells the output axis to store the results. -1 means that the function has to find it out itself; it takes the first axis with a length mismatching the corresponding input axis.

## tiledApply() [1/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::tiledApply | ( | MaskedLattice< U > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | const LatticeRegion & | region,
|  | TiledCollapser< T, U > & | collapser,
|  | const IPosition & | collapseAxes,
|  | Int | newOutAxis = -1,
|  | LatticeProgress * | tellProgress = 0 )

static

## tiledApply() [2/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::tiledApply | ( | MaskedLattice< U > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | TiledCollapser< T, U > & | collapser,
|  | const IPosition & | collapseAxes,
|  | Int | newOutAxis = -1,
|  | LatticeProgress * | tellProgress = 0 )

static

This function iterates tile by tile through an input lattice and applies a user supplied function object to each chunk along the specified axes.

A chunk can be a line, plane, etc. which is determined by the argument collapseAxes. E.g. IPosition(2,1,2) means planes along axes 1 and 2 (thus y,z planes). The result of the function object is written into the output lattice at the location of the collapsed chunk. The output lattice must be supplied with the correct shape (the shape of the supplied region plus the number of values resulting from the collapse). The default region is the entire input lattice.

## tiledMultiApply() [1/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::tiledMultiApply | ( | Block< MaskedLattice< U > * > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | const LatticeRegion & | region,
|  | TiledCollapser< T, U > & | collapser,
|  | const IPosition & | collapseAxes,
|  | LatticeProgress * | tellProgress = 0 )

static

## tiledMultiApply() [2/2]

template<class T, class U = T>

void casacore::LatticeApply< T, U >::tiledMultiApply | ( | Block< MaskedLattice< U > * > & | latticeOut,
|  | const MaskedLattice< T > & | latticeIn,
|  | TiledCollapser< T, U > & | collapser,
|  | const IPosition & | collapseAxes,
|  | LatticeProgress * | tellProgress = 0 )

static

This function iterates tile by tile through an input lattice and applies a user supplied function object to each chunk along the specified axes.

A chunk can be a line, plane, etc. which is determined by the argument collapseAxes. E.g. IPosition(2,1,2) means planes along axes 1 and 2 (thus y,z planes). The result of the function object is written into the output lattices at the location of the collapsed chunk. The output lattices must be supplied with the correct shape (the shape of the supplied region). The default region is the entire input lattice.
Warning: These functions are only declared, but not implemented yet; Thus they cannot be used yet;

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

- lattices/LatticeMath/LatticeApply.h