This class generates moments from an image. More...

#include <MomentSettingsWidgetRadio.qo.h>

Inheritance diagram for casa::ImageMoments< T >:

Public Member Functions
	ImageMoments ()=delete

	ImageMoments (const casacore::ImageInterface< T > &image, casacore::LogIO &os, casacore::Bool overWriteOutput=false, casacore::Bool showProgress=true)
	Constructor takes an image and a `casacore::LogIO` object for logging purposes. More...

	ImageMoments (const ImageMoments< T > &other)=delete

	~ImageMoments ()
	Destructor. More...

ImageMoments< T > &	operator= (const ImageMoments< T > &other)=delete

casacore::Bool	setMomentAxis (casacore::Int momentAxis)
	Set the moment axis (0 relative). More...

casacore::Bool	setSmoothMethod (const casacore::Vector< casacore::Int > &smoothAxes, const casacore::Vector< casacore::Int > &kernelTypes, const casacore::Vector< casacore::Quantum< casacore::Double > > &kernelWidths)
	This function invokes smoothing of the input image. More...

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

std::vector< std::shared_ptr < casacore::MaskedLattice< T > > >	createMoments (casacore::Bool doTemp, const casacore::String &outFileName, casacore::Bool removeAxes=true)
	This is the function that does all the computational work. More...

casacore::Bool	setNewImage (const casacore::ImageInterface< T > &image)
	Set a new image. More...

const casacore::CoordinateSystem &	coordinates ()
	Get CoordinateSystem. More...

casacore::IPosition	getShape () const
	Get shape. More...

void	setProgressMonitor (ImageMomentsProgressMonitor *progressMonitor)
	Set an ImageMomentsProgressMonitor interested in getting updates on the progress of the collapse process. More...

Public Member Functions inherited from casa::MomentsBase< T >
virtual	~MomentsBase ()
	Destructor. More...

casacore::Bool	setMoments (const casacore::Vector< casacore::Int > &moments)
	Set the desired moments via an `casacore::Int` array. More...

casacore::Bool	setWinFitMethod (const casacore::Vector< casacore::Int > &method)
	The method by which you compute the moments is specified by calling (or not calling) the `setWinFitMethod` and `setSmoothMethod` functions. More...

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

void	setInExCludeRange (const casacore::Vector< T > &include, const casacore::Vector< T > &exclude)
	You may specify a pixel intensity range as either one for which all pixels in that range are included in the moment calculation, or one for which all pixels in that range are excluded from the moment calculations. More...

void	setSnr (const T &peakSNR, const T &stdDeviation)
	This function is used to help assess whether a spectrum along the moment axis is all noise or not. More...

casacore::Bool	setSmoothOutName (const casacore::String &smOut)
	This is the output file name for the smoothed image. More...

void	setVelocityType (casacore::MDoppler::Types type)
	Set Velocity type. More...

void	resetError ()
	Reset argument error condition. More...

casacore::String	errorMessage () const
	Recover last error message. More...

casacore::Bool	shouldConvertToVelocity () const

Private Member Functions
SPIIT	_smoothImage ()
	casacore::Smooth an image More...

void	_whatIsTheNoise (T &noise, const casacore::ImageInterface< T > &image)
	Determine the noise by fitting a Gaussian to a histogram of the entire image above the 25% levels. More...

Private Attributes
SPCIIT	_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. More...

Additional Inherited Members
Public Types inherited from casa::MomentsBase< T >
enum	MethodTypes { WINDOW, FIT, NMETHODS }
	The `enum MethodTypes` is provided for use with the `setWinFitMethod` function. More...

enum	MomentTypes { AVERAGE, INTEGRATED, WEIGHTED_MEAN_COORDINATE, WEIGHTED_DISPERSION_COORDINATE, MEDIAN, MEDIAN_COORDINATE, STANDARD_DEVIATION, RMS, ABS_MEAN_DEVIATION, MAXIMUM, MAXIMUM_COORDINATE, MINIMUM, MINIMUM_COORDINATE, NMOMENTS, DEFAULT }
	This `enum MomentTypes` is provided for use with the `setMoments` function. More...

Static Public Member Functions inherited from casa::MomentsBase< T >
static casacore::Vector < casacore::Int >	toMethodTypes (const casacore::String &methods)
	Helper function to convert a string containing a list of desired methods to the correct `casacore::Vector<casacore::Int>` required for the `setWinFitMethod` function. More...

Protected Member Functions inherited from casa::MomentsBase< T >
	MomentsBase (casacore::LogIO &os, casacore::Bool overWriteOutput=false, casacore::Bool showProgress=true)
	Constructor takes an image and a `casacore::LogIO` object for logging purposes. More...

void	_checkMethod ()
	Check that the combination of methods that the user has requested is valid casacore::List a handy dandy table if not. More...

void	_setIncludeExclude (casacore::Vector< T > &range, casacore::Bool &noInclude, casacore::Bool &noExclude, const casacore::Vector< T > &include, const casacore::Vector< T > &exclude)
	Take the user's data inclusion and exclusion data ranges and generate the range and Booleans to say what sort it is. More...

casacore::Bool	_setOutThings (casacore::String &suffix, casacore::Unit &momentUnits, const casacore::Unit &imageUnits, const casacore::String &momentAxisUnits, const casacore::Int moment, casacore::Bool convertToVelocity)
	Set the output image suffixes and units. More...

casacore::CoordinateSystem	_makeOutputCoordinates (casacore::IPosition &outShape, const casacore::CoordinateSystem &cSysIn, const casacore::IPosition &inShape, casacore::Int momentAxis, casacore::Bool removeAxis)
	Make output Coordinates. More...

Protected Attributes inherited from casa::MomentsBase< T >
casacore::LogIO	os_p

casacore::Bool	showProgress_p

casacore::Int	momentAxisDefault_p

T	peakSNR_p

T	stdDeviation_p

T	yMin_p

T	yMax_p

casacore::String	out_p

casacore::String	smoothOut_p

casacore::Bool	goodParameterStatus_p

casacore::Bool	doWindow_p

casacore::Bool	doFit_p

casacore::Bool	doSmooth_p

casacore::Bool	noInclude_p

casacore::Bool	noExclude_p

casacore::Bool	fixedYLimits_p

casacore::Int	momentAxis_p

casacore::Int	worldMomentAxis_p

casacore::Vector< casacore::Int >	kernelTypes_p

casacore::Vector < casacore::Quantity >	kernelWidths_p

casacore::Vector< casacore::Int >	moments_p

casacore::Vector< T >	selectRange_p

casacore::Vector< casacore::Int >	smoothAxes_p

casacore::Bool	overWriteOutput_p

casacore::String	error_p

casacore::Bool	convertToVelocity_p

casacore::MDoppler::Types	velocityType_p

Detailed Description

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

This class generates moments from an image.

Intended use:

Public interface

Review Status

Date Reviewed:: yyyy/mm/dd

Prerequisite

casacore::ImageInterface
MomentsBase
casacore::LatticeApply
MomentCalcBase

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 casacore::Float and casacore::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
---------------
casacore::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
 
 casacore::Vector<casacore::Int> moments(2);
 moments(0) = ImageMoments<casacore::Float>::AVERAGE;
 moments(1) = ImageMoments<casacore::Float>::WEIGHTED_MEAN_COORDINATE;
 casacore::Vector<int> methods(2);
 methods(0) = ImageMoments<casacore::Float>::WINDOW;
 methods(1) = ImageMoments<casacore::Float>::INTERACTIVE;
 casacore::Vector<casacore::Int> nxy(2);
 nxy(0) = 3;
 nxy(1) = 3;
 
// Open paged image
 
 casacore::PagedImage<casacore::Float> inImage(inName);  
 
// Construct moment helper object
 
 casacore::LogOrigin or("myClass", "myFunction(...)", WHERE);
 casacore::LogIO os(or);
 ImageMoments<casacore::Float> moment(casacore::SubImage<casacore::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 device called /xs (no longer supported). 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 48 of file MomentSettingsWidgetRadio.qo.h.

Constructor & Destructor Documentation

template<class T>

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

delete

template<class T>

casa::ImageMoments< T >::ImageMoments	(	const casacore::ImageInterface< T > &	image,
		casacore::LogIO &	os,
		casacore::Bool	overWriteOutput = `false`,
		casacore::Bool	showProgress = `true`
	)

Constructor takes an image and a casacore::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 )

delete

template<class T>

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

Destructor.

Member Function Documentation

template<class T>

SPIIT casa::ImageMoments< T >::_smoothImage ( )

private

casacore::Smooth an image

template<class T>

void casa::ImageMoments< T >::_whatIsTheNoise	(	T &	noise,
		const casacore::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.

template<class T>

const casacore::CoordinateSystem& casa::ImageMoments< T >::coordinates ( )

inlinevirtual

Get CoordinateSystem.

Implements casa::MomentsBase< T >.

Definition at line 320 of file ImageMoments.h.

template<class T>

std::vector<std::shared_ptr<casacore::MaskedLattice<T> > > casa::ImageMoments< T >::createMoments	(	casacore::Bool	doTemp,
		const casacore::String &	outFileName,
		casacore::Bool	removeAxes = `true`
	)

This is the function that does all the computational work.

It should be called after the set functions. 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 vector will hold PagedImages or TempImages (doTemp=true). If doTemp is true, the outFileName is not used.

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>

casacore::IPosition casa::ImageMoments< T >::getShape ( ) const

inlinevirtual

Get shape.

Implements casa::MomentsBase< T >.

Definition at line 323 of file ImageMoments.h.

template<class T>

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

delete

template<class T>

casacore::Bool casa::ImageMoments< T >::setMomentAxis ( casacore::Int momentAxis )

virtual

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.

Implements casa::MomentsBase< T >.

template<class T>

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

Set a new image.

A return value of false indicates the image had an invalid type (this class only accepts casacore::Float or casacore::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>

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

virtual

This function invokes smoothing of the input image.

Give casacore::Int arrays for the axes (0 relative) to be smoothed and the smoothing kernel types (use the enum KernelTypes) for each axis. Give a casacore::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 casacore::VectorKernel::KernelTypes enum

Implements casa::MomentsBase< T >.

template<class T>

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

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 !

Definition at line 240 of file ImageMoments.h.

Member Data Documentation

template<class T>

SPCIIT casa::ImageMoments< T >::_image

private

Definition at line 331 of file ImageMoments.h.

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

template<class T>

ImageMomentsProgressMonitor* casa::ImageMoments< T >::_progressMonitor

private

Definition at line 332 of file ImageMoments.h.

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

casa/code/display/QtPlotter/MomentSettingsWidgetRadio.qo.h
casa/code/imageanalysis/ImageAnalysis/ImageMoments.h

Public Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

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 >