template <class t>=""> class MomentsBase; More...

#include <ImageMoments.h>

Inheritance diagram for casa::ImageMoments< T >:

Public Member Functions
	ImageMoments (ImageInterface< T > &image, LogIO &os, Bool overWriteOutput=False, Bool showProgress=True)
	Constructor takes an image and a `LogIO` object for logging purposes.
	ImageMoments (const ImageMoments< T > &other)
	Copy constructor.
	ImageMoments (ImageMoments< T > &other)
	Copy constructor.
	~ImageMoments ()
	Destructor.
ImageMoments< T > &	operator= (const ImageMoments< T > &other)
	Assignment operator.
void	setMomentAxis (const Int momentAxis)
	Set the moment axis (0 relative).
Bool	setSmoothMethod (const Vector< Int > &smoothAxes, const Vector< Int > &kernelTypes, const Vector< Quantum< Double > > &kernelWidths)
	This function invokes smoothing of the input image.
Bool	setSmoothMethod (const Vector< Int > &smoothAxes, const Vector< Int > &kernelTypes, const Vector< Double > &kernelWidths)
void	createMoments (PtrBlock< MaskedLattice< T > * > &images, Bool doTemp, const String &outFileName, Bool removeAxes=True)
	This is the function that does all the computational work.
Bool	setNewImage (ImageInterface< T > &image)
	Set a new image.
CoordinateSystem	coordinates ()
	Get CoordinateSystem.
IPosition	getShape ()
	Get shape.
void	setProgressMonitor (ImageMomentsProgressMonitor *progressMonitor)
	Set an ImageMomentsProgressMonitor interested in getting updates on the progress of the collapse process.
Private Member Functions
Bool	smoothImage (PtrHolder< ImageInterface< T > > &pSmoothedImage, String &smoothName)
	Smooth an image.
Bool	whatIsTheNoise (T &noise, ImageInterface< T > &image)
	Determine the noise by fitting a Gaussian to a histogram of the entire image above the 25% levels.
Private Attributes
std::auto_ptr< ImageInterface < T > >	_image
ImageMomentsProgressMonitor *	progressMonitor
Friends
class	MomentCalcBase< T >
	Note that if I don't put MomentCalcBase as a forward declaration and use instead "friend class MomentCalcBase<T>" The gnu compiler fails with a typedef problem.

Detailed Description

template<class T>
class casa::ImageMoments< T >

template <class t>=""> class MomentsBase;

This class generates moments from an image.

Intended use:

Public interface

Review Status

Date Reviewed:: yyyy/mm/dd

Prerequisite

Etymology

This class computes moments from images

Synopsis

The primary goal of this class is to help spectral-line astronomers analyze their multi-dimensional images by generating moments of a specified axis. The word "moment" is used loosely here. It refers to collapsing an axis to one pixel and putting the value of that pixel (for all of the other non-collapsed axes) to something computed from the data values along the moment axis. For example, take an RA-DEC-Velocity cube, collapse the velocity axis by computing the mean intensity at each RA-DEC pixel. This class offers many different moments and a variety of interactive and automatic ways to compute them.

This class only accepts images of type Float and Double. This restriction is because of the plotting capabilities which are a bit awkward for other types.

This class makes a distinction between a "moment" and a "method". This boundary is a little blurred, but it claims to refer to the distinction of what you are computing, as to how the pixels that were included in the computation were selected. For example, a "moment" would be the average value of some pixels. A method for selecting those pixels would be a simple range specifying a range for which pixels should be included.

The default state of this class is to do nothing. If you specify an image via the setImage function then invoking the createMoments function will cause it to compute the integrated itensity along the spectral axis of the image (if it can find one). You can change the computational state of the class from this basic form via the remaining set functions. You can call any number of these functions to suit your needs.

Because there are a wide variety of methods available, if you specify an invalid combination, a table showing the available methods is listed. It is reproduced below for convenience.

The basic method is to just compute moments directly from the pixel intensities. This can be modified by applying pixel intensity inclusion or exclusion ranges. You can then also smooth the image and compute a mask based on the inclusion or exclusion ranges applied to the smoothed image. This mask is then applied to the unsmoothed data for moment computation.

The window method does no pixel intensity range selection. Instead a spectral window is found (hopefully surrounding the spectral line feature) and only the pixels in that window are used for computation. This window can be found from the smoothed or unsmoothed data. The moments are always computed from the unsmoothed data. For each spectrum, the window can be found interactively or automatically. There are two interactive methods. Either you just mark the window with the cursor, or you interactively fit a Gaussian to the profile and the +/- 3-sigma window is returned. There are two automatic methods. Either Bosma's converging mean algorithm is used, or an automatically fit Gaussian +/- 3-sigma window is returned.

The fitting method fits Gaussians to spectral features either automatically or interactively. The moments are then computed from the Gaussian fits (not the data themselves).

When an output image is created, it will have N-1 axes, where the input image has N axes. In the output image, the physical axis corresponding to the moment axis will have been removed, but the coordinate information will be retained for future coordinate transformations. For example, if you have a RA-DEC-VELOCITY image and you collapsed axis 2 (the DEC axis) the output images would be RA-VELOCITY with the coordinate information retained for the DEC axis so that the coupled nature of RA/DEC coordinates is preserved.

Output images are created with an all True (good) mask. If, for a given pixel, the moment calculation fails, then the mask is set to F.

When making plots, the order in which the spectra are displayed is determined by the tiling sequence of the image (for optimum speed of access).

                      Allowed Methods
                      ---------------
   
      Smooth    Window      Fit   in/exclude   Interactive 
      -----------------------------------------------------
        N          N         N        N            N       
        Y/N        N         N        Y            N       
    
        Y/N        Y         N        N            Y       
        Y/N        Y         N        N            N       
        Y/N        Y         Y        N            Y/N     
   
        N          N         Y        N            Y/N     
      ----------------------------------------------------

Caution: Note that the MEDIAN_COORDINATE moment is not very robust; It is very useful for generating quickly a velocity field in a way that is not sensitive to noise; However, it will only give sensible results under certain conditions; It treats the spectrum as a probability distribution, generates the cumulative distribution for the selected pixels (via an include or exclude pixel range, and finds the (interpolated) coordinate coresponding to the 50% value; The generation of the cumulative distribution and the finding of the 50% level really only makes sense if the cumulative distribution is monotonically increasing; This essentially means only selecting pixels which are positive or negative; For this reason, this moment type is only supported with the basic method (i;e; no smoothing, no windowing, no fitting) with a pixel selection range that is either all positive, or all negative;

Tip: If you ignore return error statuses from the functions that set the state of the class, the internal status of the class is set to bad; This means it will just keep on returning error conditions until you explicitly recover the situation; A message describing the last error condition can be recovered with function errorMessage;

Example

   // Set state function argument values
   
         Vector<Int> moments(2);
         moments(0) = ImageMoments<Float>::AVERAGE;
         moments(1) = ImageMoments<Float>::WEIGHTED_MEAN_COORDINATE;
         Vector<int> methods(2);
         methods(0) = ImageMoments<Float>::WINDOW;
         methods(1) = ImageMoments<Float>::INTERACTIVE;
         Vector<Int> nxy(2);
         nxy(0) = 3;
         nxy(1) = 3;
   
   // Open paged image
        
         PagedImage<Float> inImage(inName);  
   
   // Construct moment helper object
   
         LogOrigin or("myClass", "myFunction(...)", WHERE);
         LogIO os(or);
         ImageMoments<Float> moment(SubImage<Float>(inName), os);
   
   // Specify state via control functions
   
         if (!moment.setMoments(moments)) return 1;
         if (!moment.setWinFitMethod(methods)) return 1;
         if (!moment.setMomentAxis(3)) return 1;
         if (!moment.setPlotting("/xs", nxy)) return 1;
   
   // Create the moments
   
         if (!moment.createMoments()) return 1;

In this example, we generate two moments (average intensity and intensity weighted mean coordinate -- usually the velocity field) of axis 3 by the interactive window method. The interactive plotting is done on the PGPLOT device called /xs. We put 9 subplots on each page. The output file names are constructed by the class from the input file name plus some internally generated suffixes.

Motivation

This is a fundamental and traditional piece of spectral-line image analysis.

To Do

more control over histogram of image noise at start (pixel range and number of bins)
better algorithm for seeing if spectrum is pure noise
Make this class extensible so users could add their own method.

Definition at line 248 of file ImageMoments.h.

Constructor & Destructor Documentation

template<class T>

casa::ImageMoments< T >::ImageMoments	(	ImageInterface< T > &	image,
		LogIO &	os,
		Bool	overWriteOutput = `False`,
		Bool	showProgress = `True`
	)

Constructor takes an image and a LogIO object for logging purposes.

You specify whether output images are automatically overwritten if pre-existing, or whether an intercative choice dialog widget appears (overWriteOutput=F) You may also determine whether a progress meter is displayed or not.

template<class T>

casa::ImageMoments< T >::ImageMoments ( const ImageMoments< T > & other )

Copy constructor.

Uses copy semantics.

template<class T>

casa::ImageMoments< T >::ImageMoments ( ImageMoments< T > & other )

Copy constructor.

Uses copy semantics.

template<class T>

casa::ImageMoments< T >::~ImageMoments ( )

Destructor.

Member Function Documentation

template<class T>

CoordinateSystem casa::ImageMoments< T >::coordinates ( ) [inline, virtual]

Get CoordinateSystem.

Reimplemented from casa::MomentsBase< T >.

Definition at line 335 of file ImageMoments.h.

References casa::ImageMoments< T >::_image.

template<class T>

void casa::ImageMoments< T >::createMoments	(	PtrBlock< MaskedLattice< T > * > &	images,
		Bool	doTemp,
		const String &	outFileName,
		Bool	removeAxes = `True`
	)

This is the function that does all the computational work.

It should be called after the set functions. A return value of False indicates that additional checking of the combined methods that you have requested has shown that you have not given consistent state to the class. If the axis being collapsed comes from a coordinate with one axis only, the axis and its coordinate are physically removed from the output image. Otherwise, if removeAxes=True then the output axis is logically removed from the the output CoordinateSystem. If removeAxes=False then the axis is retained with shape=1 and with its original coordinate information (which is probably meaningless).

The output PtrBlock will hold PagedImages or TempImages (doTemp=True). It is your responsibility to delete the pointers. If doTemp is True, the outFileName is irrelevant.

If you create PagedImages, outFileName is the root name for the output files. Suffixes will be made up internally to append to this root. If you only ask for one moment, this will be the actual name of the output file. If you don't set this variable, the default state of the class is to set the output name root to the name of the input file.

template<class T>

IPosition casa::ImageMoments< T >::getShape ( ) [inline, virtual]

Get shape.

Reimplemented from casa::MomentsBase< T >.

Definition at line 339 of file ImageMoments.h.

References casa::ImageMoments< T >::_image.

template<class T>

ImageMoments<T>& casa::ImageMoments< T >::operator= ( const ImageMoments< T > & other )

Assignment operator.

USes copy semantics.

template<class T>

void casa::ImageMoments< T >::setMomentAxis ( const Int momentAxis )

Set the moment axis (0 relative).

A return value of False indicates that the axis was not contained in the image. If you don't call this function, the default state of the class is to set the moment axis to the spectral axis if it can find one. Otherwise an error will result.

template<class T>

Bool casa::ImageMoments< T >::setNewImage ( ImageInterface< T > & image )

Set a new image.

A return value of False indicates the image had an invalid type (this class only accepts Float or Double images).

template<class T>

void casa::ImageMoments< T >::setProgressMonitor ( ImageMomentsProgressMonitor * progressMonitor )

Set an ImageMomentsProgressMonitor interested in getting updates on the progress of the collapse process.

template<class T>

Bool casa::ImageMoments< T >::setSmoothMethod	(	const Vector< Int > &	smoothAxes,
		const Vector< Int > &	kernelTypes,
		const Vector< Quantum< Double > > &	kernelWidths
	)		`[virtual]`

This function invokes smoothing of the input image.

Give Int arrays for the axes (0 relative) to be smoothed and the smoothing kernel types (use the enum KernelTypes) for each axis. Give a Double array for the widths (full width for BOXCAR and full width at half maximum for GAUSSIAN) in pixels of the smoothing kernels for each axis. For HANNING smoothing, you always get the quarter-half-quarter kernel (no matter what you might ask for). A return value of False indicates that you have given an inconsistent or invalid set of smoothing parameters. If you don't call this function the default state of the class is to do no smoothing. The kernel types are specified with the VectorKernel::KernelTypes enum

Reimplemented from casa::MomentsBase< T >.

template<class T>

Bool casa::ImageMoments< T >::setSmoothMethod	(	const Vector< Int > &	smoothAxes,
		const Vector< Int > &	kernelTypes,
		const Vector< Double > &	kernelWidths
	)

Reimplemented from casa::MomentsBase< T >.

template<class T>

Bool casa::ImageMoments< T >::smoothImage	(	PtrHolder< ImageInterface< T > > &	pSmoothedImage,
		String &	smoothName
	)		`[private]`

Smooth an image.

template<class T>

Bool casa::ImageMoments< T >::whatIsTheNoise	(	T &	noise,
		ImageInterface< T > &	image
	)		`[private]`

Determine the noise by fitting a Gaussian to a histogram of the entire image above the 25% levels.

If a plotting device is set, the user can interact with this process.

Friends And Related Function Documentation

template<class T>

friend class MomentCalcBase< T > [friend]

Note that if I don't put MomentCalcBase as a forward declaration and use instead "friend class MomentCalcBase<T>" The gnu compiler fails with a typedef problem.

But I can't solve it with say typedef MomentCalcBase<T> gpp_type; because you can only do a typedef with an actual type, not a T !

Reimplemented from casa::MomentsBase< T >.

Definition at line 257 of file ImageMoments.h.

Member Data Documentation

template<class T>

std::auto_ptr<ImageInterface<T> > casa::ImageMoments< T >::_image [private]

Definition at line 347 of file ImageMoments.h.

Referenced by casa::ImageMoments< T >::coordinates(), and casa::ImageMoments< T >::getShape().

template<class T>

ImageMomentsProgressMonitor* casa::ImageMoments< T >::progressMonitor [private]

Definition at line 359 of file ImageMoments.h.

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

code/imageanalysis/ImageAnalysis/ImageMoments.h

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

template<class T> class casa::ImageMoments< T >

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<class T>
class casa::ImageMoments< T >