The TVRegularizer class provides an approximation of a total variation (TV) minimizing regularizer. More...

#include <regularizers.h>

Inheritance diagram for CTL::TVRegularizer:

Collaboration diagram for CTL::TVRegularizer:

Public Types
enum	{ Type = 2012 }

enum	NeighborHood { Box3x3x3, NearestOnly }

Public Types inherited from CTL::AbstractVolumeFilter
enum	{ Type = 2000 }

Public Types inherited from CTL::SerializationInterface
enum	{ Type = -1, UserType = 65536 }

Public Member Functions
int	type () const override

void	filter (VoxelVolume< float > &volume) override

	TVRegularizer (float maxChangeIn10HU=1.0f, NeighborHood neighbors=NearestOnly)
	Constructs a TVRegularizer with a maximum filter effect of maxChangeIn10HU times 10 HU on each voxel, according to an anisotropic version of total variation (TV) minimization in the voxel's neighborhood of type neighbors. More...

void	setNeighborHoodType (NeighborHood neighbors)
	Sets the neighborhood type used for computation of the TV gradient to neighbors. More...

void	setRegularizationStrength (float maxChangeIn10HU)
	Sets the strength of the filter effect to strength. More...

QVariant	parameter () const override

void	setParameter (const QVariant &parameter) override
	Sets the parameters contained in parameter (a QVariantMap). More...

Public Member Functions inherited from CTL::AbstractVolumeFilter
void	fromVariant (const QVariant &variant) override

QVariant	toVariant () const override

Public Member Functions inherited from CTL::SerializationInterface
virtual	~SerializationInterface ()=default

Private Member Functions
void	applyTV3 (VoxelVolume< float > &volume)
	Applies the TV filtering (wrt. to the filter strength) on a 3x3x3 neighborhood.

void	applyTVNN (VoxelVolume< float > &volume)
	Applies the TV filtering (wrt. to the filter strength) considering only the (six) nearest neighbors of a voxel.

Static Private Member Functions
static QMetaEnum	metaEnum ()
	QMetaEnum object used to decode/encode neighborhood enum values.

Private Attributes
float	_strength = 10.0f

NeighborHood	_neighbors = NearestOnly

Static Private Attributes
static constexpr float	_step = 0.02269f / 1000.0f

Friends
template<class >
struct	SerializationHelper::RegisterWithSerializationHelper

Additional Inherited Members
Protected Member Functions inherited from CTL::AbstractVolumeFilter
	AbstractVolumeFilter (const AbstractVolumeFilter &)=default

	AbstractVolumeFilter (AbstractVolumeFilter &&)=default

AbstractVolumeFilter &	operator= (const AbstractVolumeFilter &)=default

AbstractVolumeFilter &	operator= (AbstractVolumeFilter &&)=default

Protected Member Functions inherited from CTL::SerializationInterface
	SerializationInterface ()=default

	SerializationInterface (const SerializationInterface &)=default

	SerializationInterface (SerializationInterface &&)=default

SerializationInterface &	operator= (const SerializationInterface &)=default

SerializationInterface &	operator= (SerializationInterface &&)=default

Detailed Description

The TVRegularizer class provides an approximation of a total variation (TV) minimizing regularizer.

This is the CPU version of the TVRegularizer; for the GPU version, see OCL::TVRegularizer.

This class implements an anisotropic version of total variation (TV) regularization.

The strength of the regularization effect is controlled via the regularization parameter. This defines the maximum change in multiples of 10 Hounsfield units (HU) that can be applied to a single voxel in one execution of filter().

This change is applied proportionally, depending on the average number of neighbors of that voxel that have a positive / negative difference to the voxel. Hence, if all surrounding voxels have higher/lower values than the voxel of interest, its value will be increased/decreased by regularizationStrength * 10 HU. If the tendency of neighbor values is mixed, only the corresponding fraction of change is applied, respectively. The voxel's neighborhood that is considered for this operation can be selected from:

NeighborHood::NearestOnly: takes only the six direct neighbors into account; in this setting, all considered neighbors are weighted equally [default]
NeighborHood::Box3x3x3: considers all 26 neighbors of a 3x3x3 box centered at the voxel of interest; in this setting, differences will be weighted wrt. the distance of the neighbor to the center voxel. Select the neighborhood type during construction or later on through setNeighborHoodType().

Constructor & Destructor Documentation

◆ TVRegularizer()

CTL::TVRegularizer::TVRegularizer	(	float	maxChangeIn10HU = `1.0f`,
		TVRegularizer::NeighborHood	neighbors = `NearestOnly`
	)

explicit

Constructs a TVRegularizer with a maximum filter effect of maxChangeIn10HU times 10 HU on each voxel, according to an anisotropic version of total variation (TV) minimization in the voxel's neighborhood of type neighbors.

For details on the neighborhood type, see setNeighborHoodType().

Member Function Documentation

◆ filter()

void CTL::TVRegularizer::filter ( VoxelVolume< float > & volume )

overridevirtual

This performs an anisotropic version of total variation (TV) regularization on volume.

volume must have a minimum size of 3x3x3 voxels; throws std::domain_error otherwise.

The strength of the regularization effect is controlled via the regularization parameter. This defines the maximum change in multiples of 10 Hounsfield units (HU) that can be applied to a single voxel. Regularization strength can be specified during construction or through setRegularizationStrength().

The computed change is applied proportionally, depending on the average number of neighbors of that voxel that have a positive / negative difference to the voxel. Hence, if all surrounding voxels have higher/lower values than the voxel of interest, its value will be increased/decreased by 'regularizationStrength' * 10 HU. If the tendency of neighbor values is mixed, only the corresponding fraction of change is applied, respectively.

See setNeighborHoodType() for details on the different neighborhood types (or filter sizes).

Implements CTL::AbstractVolumeFilter.

◆ setNeighborHoodType()

void CTL::TVRegularizer::setNeighborHoodType ( TVRegularizer::NeighborHood neighbors )

Sets the neighborhood type used for computation of the TV gradient to neighbors.

The voxel's neighborhood that is considered for computation of the TV gradient can be selected from:

NeighborHood::NearestOnly: takes only the six direct neighbors into account; in this setting, all considered neighbors are weighted equally
NeighborHood::Box3x3x3: considers all 26 neighbors of a 3x3x3 box centered at the voxel of interest; in this setting, differences will be weighted wrt. the distance of the neighbor to the center voxel.

◆ setParameter()

void CTL::TVRegularizer::setParameter ( const QVariant & parameter )

overridevirtual

Sets the parameters contained in parameter (a QVariantMap).

Note: it is not recommended to set parameters of the filter this way. Consider using the regular setter methods instead (see setRegularizationStrength() and setNeighborHoodType()).

The value passed to parameter must be a QVariantMap containing one or multiple of the following (key, value)-pairs:

("strength", [float] the regularization strength),
("neighbors", [string] a valid neighborhood type).

The neighborhood type can be either "Box3x3x3" or "NearestOnly".

Example: setting filter strength to 0.75 and the 3x3x3 neighborhood type

TVRegularizer filt;
filt.setParameter(QVariantMap{ { "strength", 0.75f },
                               { "neighbors", "Box3x3x3" } } );

Reimplemented from CTL::AbstractVolumeFilter.

◆ setRegularizationStrength()

void CTL::TVRegularizer::setRegularizationStrength ( float maxChangeIn10HU )

Sets the strength of the filter effect to strength.

The parameter strength defines the maximum change in multiples of 10 Hounsfield units (HU, at 50 keV) that can be applied to a single voxel in one execution of filter(). [1.0 means the maximum change is +-10 HU]

For details on the considered neighboring voxels, see setNeighborHoodType().

◆ type()

int CTL::TVRegularizer::type ( ) const

inlineoverridevirtual

Returns the type-id of the serializable object. Used in deserialization to determine the proper object type.

Add derived classes to the enumeration using the CTL_TYPE_ID macro.

Reimplemented from CTL::AbstractVolumeFilter.

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

modules/src/recon/regularizers.h
modules/src/recon/regularizers.cpp

Public Types

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Additional Inherited Members