ArithmeticOperator Class Reference

Description

Applies arithmetic operations (scalar, image-to-image, averaging, maximum and weighted averaging) to loaded images while the Arithmetics operator is active.

Every operation can either modify an image in place or write its result into a new image appended to the data manager:

• Functions with a newImg / createNew flag modify the first image when it is false and create a new image when it is true.
• Functions that take only a list of images always create a new image.
• Functions that take a target index and a list write into the target, replacing its content.

Source images are never modified unless they are also the target. On failure, functions return an invalid Index (or -1 for the int overloads) and leave data unchanged unless stated otherwise.

Images are addressed by Index; use VQ.index() to obtain one (e.g. VQ.index(0) for the first data set, VQ.index(0, i) for frame i of a dynamic data set).

See also VQ.currentOp() to obtain this object and setViewMode() to enter the Arithmetics operator:

VQ.mainWin().setViewMode('Slice View', 'Arithmetics');
var op = VQ.currentOp();
var result = op.addScalar(VQ.index(0), 10, true);

Public Member Functions
void	execute (bool quiet=true)
	Runs the operation currently set up in the operator dialog.
Scalar operations
Index	addScalar (Index idx, float scalar, bool newImg=false)
	Adds a scalar value to every voxel of an image.
int	addScalar (int id, float scalar, bool newImg=false)
Index	multScalar (Index idx, float scalar, bool newImg=false)
	Multiplies every voxel of an image by a scalar value.
int	multScalar (int id, float scalar, bool newImg=false)
Index	multScalarSlices (Index idx, QList< Variant > scalars, bool newImg=false)
	Multiplies each slice of an image by its own scalar value.
Index	powImage (Index idx, float exponent, bool newImg=false)
	Raises every voxel of an image to a power.
int	powImage (int id, float exponent, bool newImg=false)
Image-to-image operations
Voxel-wise operations between two images of the same dimensions. If the units of the two images differ, the user is asked whether to continue (unless running quietly).
Index	addImage (Index idx, Index img, bool newImg=false)
	Adds a second image to a first image, voxel by voxel.
int	addImage (int id, int img, bool newImg=false)
Index	multImage (Index idx, Index img, bool newImg=false)
	Multiplies a first image by a second image, voxel by voxel.
int	multImage (int id, int img, bool newImg=false)
Index	subtractImage (Index idx, Index img, bool newImg=false)
	Subtracts a second image from a first image, voxel by voxel (idx - img).
int	subtractImage (int id, int img, bool newImg=false)
Index	divideImage (Index idx, Index img, bool newImg=false)
	Divides a first image by a second image, voxel by voxel (idx / img).
int	divideImage (int id, int img, bool newImg=false)
Multi-image operations
Index	averageImages (Index idx, Array< Index > list)
	Averages a list of images into an existing image, voxel by voxel.
Index	averageImages (Array< Index > list)
	Averages a list of images into a new image, voxel by voxel.
Index	maxImages (Index idx, Array< Index > list)
	Computes the voxel-wise maximum of a list of images into an existing image.
Index	maxImages (Array< Index > list)
	Computes the voxel-wise maximum of a list of images into a new image.
Index	mergeImages (Index idx, Array< Index > list)
	Voxel-wise maximum of a list of images into an existing image.
Index	mergeImages (Array< Index > list)
	Voxel-wise maximum of a list of images into a new image.
Weighted averaging
The result is (∑i wi · Ii) / ∑i wi over the images with a weight > 0. Weights can be given directly (weightedAvgImagesByWeights), read from DICOM headers (weightsFromDicomTag), or taken from the weights table in the operator dialog (weightedAvgImages, setWeights, getWeights, setAllIncluded).
Index	weightedAvgImagesByWeights (Index idx, Array< Index > list, QList< Variant > weights)
	Weighted average of a list of images into an existing image, using explicitly supplied weights.
Index	weightedAvgImagesByWeights (Array< Index > list, QList< Variant > weights)
	Weighted average of a list of images into a new image, using explicitly supplied weights.
QList< Variant >	weightsFromDicomTag (Array< Index > list, string tag)
	Reads a numeric DICOM value from each image, for use as (or as a basis for) weights.
Index	weightedAvgImages (Index idx, Array< Index > list)
	Weighted average into an existing image, using the weights table in the operator dialog.
Index	weightedAvgImages (Array< Index > list)
	Weighted average into a new image, using the weights table in the operator dialog.
bool	setWeights (QList< Variant > weights)
	Fills the weights table in the operator dialog so execute() uses these weights.
QList< Variant >	getWeights ()
	Returns the weights currently held by the weights table, in selection order.
void	setAllIncluded (bool include)
	Checks (includes) or unchecks (excludes) every row of the weights table.

Protected Member Functions
Index	mergeImages (Index idx, Array< Index > list, bool newImg)

Member Function Documentation

addImage() [1/2]

Index addImage	(	Index	idx,
		Index	img,
		bool	newImg = false )

Adds a second image to a first image, voxel by voxel.

Parameters

idx	First image (see VQ.index()); receives the result unless newImg is true.
img	Second image; added to the first and left unchanged.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

The first image, or the new image if newImg is true; an invalid index if either input is not valid or the operation was cancelled.

addImage() [2/2]

int addImage	(	int	id,
		int	img,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened number of the first image, as used by the older integer-based scripting API.
img	Flattened number of the second image.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

Top-level row of the resulting image.

addScalar() [1/2]

Index addScalar	(	Index	idx,
		float	scalar,
		bool	newImg = false )

Adds a scalar value to every voxel of an image.

Parameters

idx	Image to add the scalar to (see VQ.index()).
scalar	Value added to every voxel.
newImg	If true, the result is written to a new image and idx is left unchanged.

Returns

The modified image (idx), or the new image if newImg is true; an invalid index if idx is not valid.

addScalar() [2/2]

int addScalar	(	int	id,
		float	scalar,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened image number, as used by the older integer-based scripting API.
scalar	Value added to every voxel.
newImg	If true, the result is written to a new image and id is left unchanged.

Returns

Top-level row of the resulting image.

averageImages() [1/2]

Index averageImages

(

Array< Index >

list

)

Averages a list of images into a new image, voxel by voxel.

Parameters

list	Images to average; left unchanged.

Returns

The new image, or an invalid index if list is empty or contains an invalid image (no image is created in that case) or the operation was cancelled (the new image is unloaded again).

averageImages() [2/2]

Index averageImages	(	Index	idx,
		Array< Index >	list )

Averages a list of images into an existing image, voxel by voxel.

The target's content is replaced by the mean of the images in list. The target may be one of the images in the list.

Parameters

idx	Target image (see VQ.index()); its content is replaced by the average.
list	Images to average; left unchanged unless one of them is idx.

Returns

The target image, or an invalid index if any image is not valid, list is empty or the operation was cancelled.

divideImage() [1/2]

Index divideImage	(	Index	idx,
		Index	img,
		bool	newImg = false )

Divides a first image by a second image, voxel by voxel (idx / img).

Parameters

idx	First image (see VQ.index()); receives the result unless newImg is true.
img	Second image (divisor); left unchanged.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

The first image, or the new image if newImg is true; an invalid index if either input is not valid or the operation was cancelled.

Note

The resulting unit is set to "unitA/unitB" when the units of the two images differ.

divideImage() [2/2]

int divideImage	(	int	id,
		int	img,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened number of the first image, as used by the older integer-based scripting API.
img	Flattened number of the second image.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

Top-level row of the resulting image.

execute()

void execute

(

bool

quiet = true

)

Runs the operation currently set up in the operator dialog.

Uses the selected operation, the image selections, the scalar value, the weights table and the "Append Data" option exactly as the OK button does. Does nothing if the current setup is not valid (the same condition that disables the OK button).

Parameters

quiet

If true (the default), no message boxes are shown; warnings and information go to the log instead, and questions such as "units differ, continue?" are answered with continue.

getWeights()

QList< Variant > getWeights

(

)

Returns the weights currently held by the weights table, in selection order.

Returns

One entry per row: the weight for checked rows, 0 for unchecked (excluded) rows, and null for checked rows without a valid weight (e.g. "Not Found" in Frame Duration mode). Because of the null entries, the result is only accepted by setWeights when every checked row has a valid weight.

maxImages() [1/2]

Index maxImages

(

Array< Index >

list

)

Computes the voxel-wise maximum of a list of images into a new image.

Parameters

list	Images to include; left unchanged.

Returns

The new image, or an invalid index if list is empty or contains an invalid image (no image is created in that case) or the operation was cancelled (the new image is unloaded again).

maxImages() [2/2]

Index maxImages	(	Index	idx,
		Array< Index >	list )

Computes the voxel-wise maximum of a list of images into an existing image.

Parameters

idx	Target image; its content is replaced by the voxel-wise maximum.
list	Images to include; left unchanged unless one of them is idx.

Returns

The target image, or an invalid index if any image is not valid, list is empty or the operation was cancelled (the target is restored).

mergeImages() [1/3]

Index mergeImages ( Array< Index > list )

inline

Voxel-wise maximum of a list of images into a new image.

Deprecated

Use maxImages(Array<Index>) instead; the name states what it computes.

Deprecated

Use maxImages instead. Purpose more explicit

mergeImages() [2/3]

Index mergeImages ( Index idx, Array< Index > list )

inline

Voxel-wise maximum of a list of images into an existing image.

Deprecated

Use maxImages(Index, Array<Index>) instead; the name states what it computes.

Deprecated

Use maxImages instead. Purpose more explicit

mergeImages() [3/3]

Index mergeImages ( Index idx, Array< Index > list, bool newImg )

inlineprotected

Deprecated

Use maxImages instead. Purpose more explicit

multImage() [1/2]

Index multImage	(	Index	idx,
		Index	img,
		bool	newImg = false )

Multiplies a first image by a second image, voxel by voxel.

Parameters

idx	First image (see VQ.index()); receives the result unless newImg is true.
img	Second image; multiplied into the first and left unchanged.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

The first image, or the new image if newImg is true; an invalid index if either input is not valid or the operation was cancelled.

multImage() [2/2]

int multImage	(	int	id,
		int	img,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened number of the first image, as used by the older integer-based scripting API.
img	Flattened number of the second image.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

Top-level row of the resulting image.

multScalar() [1/2]

Index multScalar	(	Index	idx,
		float	scalar,
		bool	newImg = false )

Multiplies every voxel of an image by a scalar value.

Parameters

idx	Image to multiply (see VQ.index()).
scalar	Factor applied to every voxel.
newImg	If true, the result is written to a new image and idx is left unchanged.

Returns

The modified image (idx), or the new image if newImg is true; an invalid index if idx is not valid.

multScalar() [2/2]

int multScalar	(	int	id,
		float	scalar,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened image number, as used by the older integer-based scripting API.
scalar	Factor applied to every voxel.
newImg	If true, the result is written to a new image and id is left unchanged.

Returns

Top-level row of the resulting image.

multScalarSlices()

Index multScalarSlices	(	Index	idx,
		QList< Variant >	scalars,
		bool	newImg = false )

Multiplies each slice of an image by its own scalar value.

Slice z is multiplied by scalars[z]. If the list is shorter than the number of slices, the remaining slices are left unchanged; extra values are ignored.

Parameters

idx	Image to multiply (see VQ.index()).
scalars	One factor per slice, starting at slice 0.
newImg	If true, the result is written to a new image and idx is left unchanged.

Returns

The modified image (idx), or the new image if newImg is true; an invalid index if idx is not valid or scalars is empty.

powImage() [1/2]

Index powImage	(	Index	idx,
		float	exponent,
		bool	newImg = false )

Raises every voxel of an image to a power.

Parameters

idx	Image to modify (see VQ.index()).
exponent	Exponent applied to every voxel value.
newImg	If true, the result is written to a new image and idx is left unchanged.

Returns

The modified image (idx), or the new image if newImg is true; an invalid index if idx is not valid.

powImage() [2/2]

int powImage	(	int	id,
		float	exponent,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened image number, as used by the older integer-based scripting API.
exponent	Exponent applied to every voxel value.
newImg	If true, the result is written to a new image and id is left unchanged.

Returns

Top-level row of the resulting image.

setAllIncluded()

void setAllIncluded

(

bool

include

)

Checks (includes) or unchecks (excludes) every row of the weights table.

Same as clicking the "Use" column header, which checks all rows, or unchecks all of them if they are already all checked. Weight values are kept.

Parameters

include

true to check all rows, false to uncheck them.

setWeights()

bool setWeights

(

QList< Variant >

weights

)

Fills the weights table in the operator dialog so execute() uses these weights.

Switches the weighting mode to Manual. A weight of 0 unchecks that row (the image is excluded); a weight > 0 checks it and sets its value. Applies to the images currently selected in the first image selector, one weight per selected image, in selection order. Changing the selection afterwards resets the table.

Parameters

weights

One weight per selected image (same value rules as weightedAvgImagesByWeights).

Returns

true on success; false if the count or values are invalid, in which case the table is left unchanged.

subtractImage() [1/2]

Index subtractImage	(	Index	idx,
		Index	img,
		bool	newImg = false )

Subtracts a second image from a first image, voxel by voxel (idx - img).

Parameters

idx	First image (see VQ.index()); receives the result unless newImg is true.
img	Second image; subtracted from the first and left unchanged.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

The first image, or the new image if newImg is true; an invalid index if either input is not valid or the operation was cancelled.

subtractImage() [2/2]

int subtractImage	(	int	id,
		int	img,
		bool	newImg = false )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

id	Flattened number of the first image, as used by the older integer-based scripting API.
img	Flattened number of the second image.
newImg	If true, the result is written to a new image and both inputs are left unchanged.

Returns

Top-level row of the resulting image.

weightedAvgImages() [1/2]

Index weightedAvgImages

(

Array< Index >

list

)

Weighted average into a new image, using the weights table in the operator dialog.

Parameters

list	Source images; left unchanged. Same table requirements as the in-place overload.

Returns

The new image, or an invalid index on failure (no image is created in that case).

See also

weightedAvgImagesByWeights to pass weights directly instead.

weightedAvgImages() [2/2]

Index weightedAvgImages	(	Index	idx,
		Array< Index >	list )

Weighted average into an existing image, using the weights table in the operator dialog.

Only checked rows contribute. The table must hold one row per image in list, in the same order, which is the case when list matches the selection of the first image selector.

Parameters

idx	Target image; its content is replaced by the weighted average.
list	Source images; left unchanged unless one of them is idx.

Returns

The target image, or an invalid index if the table doesn't match list, a checked row has no valid weight (> 0), no row is checked, or an image is not valid.

See also

weightedAvgImagesByWeights to pass weights directly instead.

weightedAvgImagesByWeights() [1/2]

Index weightedAvgImagesByWeights	(	Array< Index >	list,
		QList< Variant >	weights )

Weighted average of a list of images into a new image, using explicitly supplied weights.

Parameters

list	Source images; left unchanged.
weights	One weight per entry in list (same rules as the in-place overload; 0 excludes an image).

Returns

The new image, or an invalid index on failure (no image is created if the weights or images are invalid).

weightedAvgImagesByWeights() [2/2]

Index weightedAvgImagesByWeights	(	Index	idx,
		Array< Index >	list,
		QList< Variant >	weights )

Weighted average of a list of images into an existing image, using explicitly supplied weights.

Independent of the weights table and weighting mode in the dialog. Weights are normalised by their sum, so only their ratios matter.

Parameters

idx	Target image; its content is replaced by the weighted average. May be one of the images in list.
list	Source images; left unchanged unless one of them is idx.
weights	One weight per entry in list. A weight of 0 excludes that image; at least one must be > 0. Negative, non-numeric, null or undefined values are rejected.

Returns

The target image, or an invalid index on failure. Weights and images are checked before anything is modified.

var w = op.weightsFromDicomTag(frames, "ActualFrameDuration").map(function (d) { return d * 2; });
op.weightedAvgImagesByWeights(frames[0], frames, w);

weightsFromDicomTag()

QList< Variant > weightsFromDicomTag	(	Array< Index >	list,
		string	tag )

Reads a numeric DICOM value from each image, for use as (or as a basis for) weights.

Parameters

list	Images to read from.
tag	DICOM keyword, e.g. "ActualFrameDuration", "FrameAcquisitionDuration".

Returns

One entry per image: the value as a number, or null if the tag is missing or not numeric. Passing a list containing null to weightedAvgImagesByWeights is rejected, so missing values can't silently exclude an image.