The ARTReconstructor class is an implementation of the algebraic reconstruction technique that can utilize user-defined forward and backprojectors. More...

#include <artreconstructor.h>

Inheritance diagram for CTL::ARTReconstructor:

[legend]

Collaboration diagram for CTL::ARTReconstructor:

[legend]

Public Types
enum	{ Type = 200 }

enum	StoppingCriterion { NoStoppingCriterion = 0, MaximumNbIterations = 1 << 0, MaximumTime = 1 << 1, ProjectionErrorChange = 1 << 2, VolumeDomainChange = 1 << 3, RelativeProjectionError = 1 << 4, NormalEquationSatisfied = 1 << 5, AllStoppingCriteria }

Public Types inherited from CTL::AbstractReconstructor
enum	{ Type = 0 }

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

Public Member Functions
int	type () const override

	ARTReconstructor ()
	Constructs an ARTReconstructor that uses the default forward and backprojector. More...

	ARTReconstructor (std::unique_ptr< AbstractProjector > forwardProjector, std::unique_ptr< AbstractReconstructor > backprojector)
	Constructs an ARTReconstructor that uses forwardProjector and backprojector.

	ARTReconstructor (AbstractProjector forwardProjector, AbstractReconstructor backprojector)
	Constructs an ARTReconstructor that uses forwardProjector and backprojector. More...

void	configure (const AcquisitionSetup &setup) override
	Passes the AcquisitionSetup that describes the setting in which projections that shall be reconstructed have been acquired. More...

bool	reconstructToPlain (const ProjectionDataView &projections, VoxelVolume< float > &targetVolume) override
	Reconstructs projection data projections into targetVolume and returns `true` on success. More...

bool	reconstructToSpectral (const ProjectionDataView &projections, SpectralVolumeData &targetVolume) override
	Reconstructs projection data projections into targetVolume and returns `true` on success. More...

QVariant	parameter () const override
	Returns the parameters of this instance as a QVariant. More...

void	setParameter (const QVariant &parameter) override
	Sets the parameters of this instance based on the passed QVariant parameter. More...

QVariant	toVariant () const override
	Stores the contents of this instance in a QVariant. More...

void	setPositivityConstraintEnabled (bool enabled)
	Sets the use of the positivity constraint to enabled. More...

void	setRegularizationEnabled (bool enabled)
	Sets the use of the regularizer to enabled. More...

void	setRelaxationEstimationEnabled (bool enabled)
	Sets the use of an estimation for the relaxation parameter to enabled. More...

void	setRelaxation (float relax)
	Sets the relaxation parameter to relax. More...

void	setRelaxationByEstimation (const VoxelVolume< float > &targetVolume, uint nbPowerIter=1u)
	Computes an estimation for the relaxation parameter and sets it for this instance. More...

void	setRelaxationByEstimation (const AcquisitionSetup &setup, const VoxelVolume< float > &targetVolume, uint nbPowerIter=1u)
	Computes an estimation for the relaxation parameter and sets it for this instance. More...

void	setRegularizer (AbstractVolumeFilter *regularizer, bool enableRegularization=true)
	Sets the regularizer to regularizer and enables regularization if enableRegularization = `true`. More...

void	setRegularizer (std::unique_ptr< AbstractVolumeFilter > regularizer, bool enableRegularization=true)
	Sets the regularizer to regularizer and enables regularization if enableRegularization = `true`.

void	setSubsetGenerator (AbstractSubsetGenerator *generator)
	Sets the subset generator to be used for subset creation to generator. More...

void	setSubsetGenerator (std::unique_ptr< AbstractSubsetGenerator > generator)
	Sets the subset generator to be used for subset creation to generator. More...

void	setForwardProjector (std::unique_ptr< AbstractProjector > projector)
	Sets the forward projector to be used to projector. More...

void	setBackprojector (std::unique_ptr< AbstractReconstructor > projector)
	Sets the backprojector to be used to projector. More...

void	setForwardProjector (AbstractProjector *projector)
	Sets the forward projector to be used to projector. More...

void	setBackprojector (AbstractReconstructor *projector)
	Sets the backprojector to be used to projector. More...

void	useCustomSubsetGenerator ()
	Enables the use of the (previously set) custom subset generator. More...

void	useDefaultSubsetGenerator ()
	(Re-)Enables the use of the default subset generator. More...

void	setMaxNbIterations (uint nbIt, bool enableCriterion=true)
	Sets the maximum number of iterations to nbIt and enables the corresponding stopping criterion if enableCriterion = `true`.

void	setMaxTime (float seconds, bool enableCriterion=true)
	Sets the maximum runtime for the reconstruction to seconds and enables the corresponding stopping criterion if enableCriterion = `true`.

void	setMinChangeInVolumeDomain (float minRelativeChange, bool enableCriterion=true)
	Sets the minimum (relative) change in volume domain to minRelativeChange and enables the corresponding stopping criterion if enableCriterion = `true`.

void	setMinChangeInProjectionError (float minRelativeChange, bool enableCriterion=true)
	Sets the minimum (relative) change in projection domain to minRelativeChange and enables the corresponding stopping criterion if enableCriterion = `true`.

void	setMinRelativeProjectionError (float minRelativeError, bool enableCriterion=true)
	Sets the minimum (relative) projection error to minRelativeError and enables the corresponding stopping criterion if enableCriterion = `true`.

void	setNormalEqTolerance (float relativeTol, bool enableCriterion=true)
	Sets the minimum (relative) tolerance w.r.t the normal equation to relativeTol and enables the corresponding stopping criterion if enableCriterion = `true`.

void	setStoppingCriteria (int criteria)
	Sets the stopping criteria to be checked after each iteration to criteria. More...

void	setStoppingCriterionEnabled (StoppingCriterion criterion, bool enabled=true)
	Sets the use of the stopping criterion criterion to enabled. More...

bool	isCustomSubsetGeneratorInUse () const
	Returns `true` if a custom subset generator is currently used to create subsets.

bool	isDefaultSubsetGeneratorInUse () const
	Returns `true` if the default subset generator is in use.

bool	isPositivityConstraintEnabled () const
	Returns `true` if the positivity constraint is enabled.

bool	isRelaxationEstimationEnabled () const
	Returns `true` if automatic estimation of a suitable relaxation parameter is enabled.

bool	isRegularizationEnabled () const
	Returns `true` if use of the regularizer is enabled.

bool	isStoppingCriterionEnabled (int criteria) const
	Returns `true` if the stopping criterion criteria is enabled. More...

float	relaxation () const
	Returns the relaxation parameter. More...

int	stoppingCriteria () const
	Returns the combination of stopping criteria flags that are currently enabled.

AbstractVolumeFilter &	regularizer () const
	Returns a reference to the currently set regularizer. More...

AbstractSubsetGenerator &	customSubsetGenerator () const
	Returns a reference to the current custom subset generator of this instance. More...

DefaultSubsetGenerator &	defaultSubsetGenerator () const
	Returns a reference to the default subset generator of this instance. More...

AbstractSubsetGenerator &	subsetGenerator () const
	Returns a reference to the subset generator that is currently enabled. More...

Public Member Functions inherited from CTL::AbstractReconstructor
	AbstractReconstructor (const AbstractReconstructor &)=delete

	AbstractReconstructor (AbstractReconstructor &&)=default

AbstractReconstructor &	operator= (const AbstractReconstructor &)=delete

AbstractReconstructor &	operator= (AbstractReconstructor &&)=default

	~AbstractReconstructor () override=default

virtual bool	isApplicableTo (const AcquisitionSetup &setup) const
	Returns true if the reconstruction method can be applied to data whose acquisition is described by setup. More...

virtual bool	reconstructToDynamic (const ProjectionDataView &projections, AbstractDynamicVolumeData &targetVolume)
	Reconstruct data (in-place) from projections into volume. More...

virtual bool	reconstructToComposite (const ProjectionDataView &projections, CompositeVolume &targetVolume)
	Reconstruct data (in-place) from projections into volume. More...

virtual bool	reconstructToSparse (const ProjectionDataView &projections, SparseVoxelVolume &targetVolume)
	Reconstruct data (in-place) from projections into volume. More...

template<class VolumeType >
bool	reconstructTo (const ProjectionDataView &projections, VolumeType &targetVolume)
	Convenience method wrapping up all `reconstructToXXX()` methods. More...

template<class VolumeType >
bool	configureAndReconstructTo (const AcquisitionSetup &setup, const ProjectionDataView &projections, VolumeType &targetVolume)
	Combines the calls to configure() and reconstructTo(). More...

template<class VolumeType , class = typename std::enable_if<!std::is_lvalue_reference<VolumeType>::value>::type>
Q_REQUIRED_RESULT VolumeType	reconstruct (const ProjectionDataView &projections, const VolumeType &initialVolume, bool *ok=nullptr)
	Reconstructs projections into a new volume object initialized with initialVolume and returns the result. More...

template<class VolumeType , class = typename std::enable_if<!std::is_lvalue_reference<VolumeType>::value>::type>
Q_REQUIRED_RESULT VolumeType	reconstruct (const ProjectionDataView &projections, VolumeType &&initialVolume, bool *ok=nullptr)
	Reconstructs projections into a new volume object initialized with initialVolume and returns the result. More...

template<class VolumeType , class = typename std::enable_if<!std::is_lvalue_reference<VolumeType>::value>::type>
Q_REQUIRED_RESULT VolumeType	configureAndReconstruct (const AcquisitionSetup &setup, const ProjectionDataView &projections, const VolumeType &initialVolume, bool *ok=nullptr)
	Combines the calls to configure() and reconstruct(). More...

template<class VolumeType , class = typename std::enable_if<!std::is_lvalue_reference<VolumeType>::value>::type>
Q_REQUIRED_RESULT VolumeType	configureAndReconstruct (const AcquisitionSetup &setup, const ProjectionDataView &view, VolumeType &&initialVolume, bool *ok=nullptr)
	Combines the calls to configure() and reconstruct(). More...

void	fromVariant (const QVariant &variant) override
	Sets the contents of the object based on the QVariant variant. More...

virtual ReconstructorNotifier *	notifier ()
	Returns a pointer to the notifier of the reconstructor. More...

void	connectNotifierToMessageHandler (bool includeProgress=false)
	Connects this instance's notifier to the CTL's MessageHandler. More...

template<>
bool	reconstructTo (const ProjectionDataView &projections, VoxelVolume< float > &targetVolume)
	Convenience method wrapping up all reconstructToXXX() methods. More...

template<>
bool	reconstructTo (const ProjectionDataView &projections, SpectralVolumeData &targetVolume)
	Convenience method wrapping up all reconstructToXXX() methods. More...

template<>
bool	reconstructTo (const ProjectionDataView &projections, CompositeVolume &targetVolume)
	Convenience method wrapping up all reconstructToXXX() methods. More...

template<>
bool	reconstructTo (const ProjectionDataView &projections, SparseVoxelVolume &targetVolume)
	Convenience method wrapping up all reconstructToXXX() methods. More...

template<>
bool	configureAndReconstructTo (const AcquisitionSetup &setup, const ProjectionDataView &projections, VoxelVolume< float > &targetVolume)
	Combines calls to configure() and reconstructTo(). More...

template<>
bool	configureAndReconstructTo (const AcquisitionSetup &setup, const ProjectionDataView &projections, SpectralVolumeData &targetVolume)

template<>
bool	configureAndReconstructTo (const AcquisitionSetup &setup, const ProjectionDataView &projections, CompositeVolume &targetVolume)

template<>
bool	configureAndReconstructTo (const AcquisitionSetup &setup, const ProjectionDataView &projections, SparseVoxelVolume &targetVolume)

template<class DynamicVolumeType >
bool	reconstructTo (const ProjectionDataView &projections, DynamicVolumeType &targetVolume)

template<class DynamicVolumeType >
bool	configureAndReconstructTo (const AcquisitionSetup &setup, const ProjectionDataView &projections, DynamicVolumeType &targetVolume)

template<class VolumeType , class >
VolumeType	reconstruct (const ProjectionDataView &projections, const VolumeType &initialVolume, bool *ok)
	Reconstructs projections into a new volume object initialized with initialVolume and returns the result. More...

template<class VolumeType , class >
VolumeType	reconstruct (const ProjectionDataView &projections, VolumeType &&initialVolume, bool *ok)
	Reconstructs projections into a new volume object initialized with initialVolume and returns the result. More...

template<class VolumeType , class >
VolumeType	configureAndReconstruct (const AcquisitionSetup &setup, const ProjectionDataView &projections, const VolumeType &initialVolume, bool *ok)
	Combines the calls to configure() and reconstruct(). More...

template<class VolumeType , class >
VolumeType	configureAndReconstruct (const AcquisitionSetup &setup, const ProjectionDataView &projections, VolumeType &&initialVolume, bool *ok)
	Combines the calls to configure() and reconstruct(). More...

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

Static Public Member Functions
static float	computeRelaxationEstimate (const AcquisitionSetup &setup, const VoxelVolume< float > &targetVolume, std::shared_ptr< AbstractProjector > forwardProjector, std::shared_ptr< AbstractReconstructor > backprojector, uint nbPowerIter=1u)
	Computes an estimation for a suitable relaxation parameter using the power method. More...

static float	computeRelaxationEstimate (const AcquisitionSetup &setup, const VoxelVolume< float > &targetVolume, AbstractProjector forwardProjector=nullptr, AbstractReconstructor backprojector=nullptr, uint nbPowerIter=1u)
	Computes an estimation for a suitable relaxation parameter using the power method. More...

Private Member Functions
bool	consistencyChecks (const ProjectionDataView &projections) const
	Returns `true` if projections are consistent with the AcquisitionSetup previously passed to configure(). More...

bool	hasAnyStoppingCriterion () const
	Returns `true` if any of the available stopping criteria is enabled. More...

bool	stoppingCriterionReached (const VoxelVolume< float > &oldVol, const VoxelVolume< float > &newVol, float oldProjError, float newProjError, float inputProjNorm, float normalEqNormalization, int msSpent, uint iteration) const
	Returns `true` if any of the enabled stopping criteria is hit.

bool	terminateByComputationTime (int msSpent) const
	Returns `true` if msSpent is greater than the corresponding stopping criterion value. More...

bool	terminateByIterationCount (uint iteration) const
	Returns `true` if iteration is greater or equal to the corresponding stopping criterion value. More...

bool	terminateByProjError (float projError, float inputProjNorm) const
	Returns `true` if the ratio between projError and inputProjNorm is less than the corresponding stopping criterion value. More...

bool	terminateByProjErrorChange (float oldProjError, float newProjError) const
	Returns `true` if the relative difference between oldProjError and newProjError is less than the corresponding stopping criterion value. More...

bool	terminateByVolumeChange (const VoxelVolume< float > &oldVol, const VoxelVolume< float > &newVol) const
	Returns `true` if newVol and oldVol differ by less than the corresponding stopping criterion value. More...

bool	terminateByNormalEqTol (const VoxelVolume< float > &oldVol, const VoxelVolume< float > &newVol, float normalization) const

bool	reconstructData (const ProjectionDataView &projections, SpectralVolumeData &targetVolume, AbstractProjector &fp, AbstractReconstructor &bp)
	Performs the iterative reconstruction of projections into targetVolume using fp and bp as forward and backprojector, respectively. More...

Static Private Member Functions
static float	computeRelaxationEstimate (const AcquisitionSetup &setup, const VoxelVolume< float > &targetVolume, AbstractProjector &fp, AbstractReconstructor &bp, uint nbPowerIter)

static QMetaEnum	metaEnum ()
	QMetaEnum object used to decode/encode subset order enum values.

Private Attributes
AcquisitionSetup	_setup

std::unique_ptr< AbstractProjector >	_fp

std::unique_ptr< AbstractReconstructor >	_bp

std::unique_ptr< AbstractVolumeFilter >	_regularizer

std::unique_ptr< AbstractSubsetGenerator >	_customSubsetGen

std::unique_ptr< DefaultSubsetGenerator >	_defaultSubsetGen

AbstractSubsetGenerator *	_activeSubsetGen

uint	_maxNbIterations = 5

bool	_usePositivityConstraint = true

bool	_useRegularization = false

bool	_useRelaxationEstimation = true

float	_relax = 1.0e-6f
	relaxation times number of views in setup (will be divided by subset size)

float	_terminateNormalEqTol = 0.001f
	relative change

float	_terminateVolChange = 0.001f
	relative change

float	_terminateProjErrChange = 0.01f
	relative change

float	_terminateProjErrRel = 0.01f
	relative error (wrt. input data)

uint	_terminateMaxTime = 60000u
	in ms

int	_stoppingCriteria = MaximumNbIterations

Friends
template<class >
struct	SerializationHelper::RegisterWithSerializationHelper

Additional Inherited Members
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

Related Functions inherited from CTL::AbstractReconstructor
std::unique_ptr< ReconstructorType >	makeReconstructor (ConstructorArguments &&... arguments)

Detailed Description

The ARTReconstructor class is an implementation of the algebraic reconstruction technique that can utilize user-defined forward and backprojectors.

This class implements image reconstruction by means of the algebraic reconstruction technique (ART). In brief, the routine alternates between computation of forward projections from the current volume estimate, comparing these with the projection data that shall be reconstructed, and backproject the difference between both dataset into the volume domain to achieve a better estimate. The routine is repeated until a stopping criterion is reached.

Both the forward and the backprojector that are used within the iterative scheme can be provided by the user to grant full flexibility. By default, ARTReconstructor uses OCL::RayCasterProjector and OCL::SimpleBackprojector as its forward and backprojector, respectively. In addition, the ART scheme can be used in combination with the so-called ordered subsets (OS) routine. When using OS, instead of performing the aforementioned alternating pattern of forward and backprojection on the entire set of projections, a subset of projections is selected and used to perform the update step. This is done for all available subsets (usually constructed such that all projections are processed once). The generation of subsets for the OS routine is done by a subset generator, which can be a custom type provided by the user as well. Alternatively, a default subset generator, featuring a wide range of possibilities, is also available (see defaultSubsetGenerator() and DefaultSubsetGenerator).

The fraction of the difference between simulated and actual projection data that gets backprojected is controlled with the so-called relaxation parameter. This parameter can either be provided manually (see setRelaxation()) or estimated using an approach based on the so-called power method. By default, relaxation parameter estimation is enabled. This can be changed by means of setRelaxationEstimationEnabled(). For details on the estimation procedure, please refer to computeRelaxationEstimate().

ARTReconstructor also supports regularization. A custom regularizer can be set via setRegularizer(). The regularization operation (i.e. volume filtering) is applied after each backprojection operation. Use of regularization can be enabled/disabled be means of setRegularizationEnabled().

By default, ARTReconstructor uses a positivity constraint on the volume estimate that is applied immediately after (a potential) regularization, i.e. after backprojecting a subset. This constraint means that all values in the volume estimate that are negative will be set to zero. You can enable/disable the use of the positivity constraint by means of setPositivityConstraintEnabled().

Stopping criteria: The ARTReconstructor supports six different stopping criteria, namely

The individual criteria are explained in their respective documentation (see ARTReconstructor::StoppingCriterion). Parameters for individual criteria can be set through a range of dedicated setter and the corresponding criteria can be enabled/disabled as desired (see setStoppingCriterionEnabled()). It is also possible to use any combination of stopping criteria (see setStoppingCriteria()). Stopping criteria are evaluated at the end of a full iteration (i.e. after processing all subsets). As soon as (at least) one enabled criterion is reached, the reconstruction is stopped. If required, for special purposes, reconstruction can also be carried out without any stopping criterion enabled at all. Note that calls to reconstruct() (or any other version of reconstruction call) will not terminate in such a setting.

Member Enumeration Documentation

◆ StoppingCriterion

enum CTL::ARTReconstructor::StoppingCriterion

Enumeration for stopping criteria that can be used in ARTReconstructor. The enumeration values can be used as flags, i.e. they can be combined via bitwise OR operation (crit1 | crit2 | ...) to create arbitrary combinations of criteria to enable (for enabling see setStoppingCriteria()).

Enumerator
NoStoppingCriterion	Using no stopping criterion at all. Note that reconstructions performed with this stopping criterion mode will not terminate.
MaximumNbIterations	Reconstruction will terminate after a defined total number of iterations has been performed. A single iteration includes processing all subsets associated with that particular iteration. The maximum number of iterations to check for when using this criterion can be set via setMaxNbIterations().
MaximumTime	Reconstruction will terminate after a defined total time for reconstruction has passed. Note that stopping criteria are evaluated at the end of a full iteration (i.e. after all subsets have been processed). Therefore, the specified time may be exceeded by a more or less extensive amount, depending on the required duration for a single iteration. In other words, reconstruction stops after the first full iteration at which total time exceeds the threshold. The maximum reconstruction time to check for when using this criterion can be set via setMaxNbIterations().
ProjectionErrorChange	Reconstruction will terminate when the relative change in the projection error from one iteration to the other falls below a defined threshold. Assume that \( \Delta P_{old}\) is the projection error of the previous iteration and \( \Delta P_{new}\) that of the current one, and given a threshold of \( \Delta P_{min}\), the stopping criterion is reached if \( \frac{\|\Delta P_{new} - \Delta P_{old}\|} {\Delta P_{old}} < \Delta P_{min} \) The minimum relative change in projection error (i.e. threshold \( \Delta P_{min} \)) to check for when using this criterion can be set via setMinChangeInProjectionError().
VolumeDomainChange	Reconstruction will terminate when the relative change in the volume domain from one iteration to the other falls below a defined threshold. Assume that \( V_{old} \) is the volume estimate of the previous iteration and \( V_{new} \) that of the current one, and given a threshold of \( \Delta V_{min}\), the stopping criterion is reached if \( \frac{\left\Vert V_{new} - V_{old} \right\Vert_{L2}} {\left\Vert V_{new} \right\Vert_{L2}} < \Delta V_{min} \) The minimum relative change in projection error (i.e. threshold \( \Delta V_{min} \)) to check for when using this criterion can be set via setMinChangeInVolumeDomain().
RelativeProjectionError	Reconstruction will terminate when the relative projection error in an iteration (w.r.t. the norm of the original projections) falls below a defined threshold. Assume that \( \ P_{sim}\) are the simulated projections of the current iteration and \( P_{orig}\) are the original ('measured') data, and given a threshold of \( \Delta P_{min}\), the stopping criterion is reached if \( \frac{\left\Vert P_{sim} - P_{orig} \right\Vert_{L2}} {\left\Vert P_{orig} \right\Vert_{L2}} < \Delta P_{min} \) The minimum relative projection error (i.e. threshold \( \Delta P_{min} \)) to check for when using this criterion can be set via setMinRelativeProjectionError().
NormalEquationSatisfied	Reconstruction will terminate when the relative deviation from fulfilling the normal equation in an iteration falls below a defined threshold. Full details on the criterion can be found in terminateByNormalEqTol(). The threshold to check for when using this criterion can be set via setNormalEqTolerance().
AllStoppingCriteria	Convenience enumeration value that contains all flags. Thus, enables all stopping criteria simultaneously if used.

Constructor & Destructor Documentation

◆ ARTReconstructor() [1/2]

CTL::ARTReconstructor::ARTReconstructor ( )

Constructs an ARTReconstructor that uses the default forward and backprojector.

Forward and backprojector default to OCL::RayCasterProjector and OCL::SimpleBackprojector, respectively.

◆ ARTReconstructor() [2/2]

CTL::ARTReconstructor::ARTReconstructor	(	AbstractProjector *	forwardProjector,
		AbstractReconstructor *	backprojector
	)

Constructs an ARTReconstructor that uses forwardProjector and backprojector.

The ARTReconstructor takes ownership of forwardProjector and backprojector.

Member Function Documentation

◆ computeRelaxationEstimate() [1/3]

float CTL::ARTReconstructor::computeRelaxationEstimate	(	const AcquisitionSetup &	setup,
		const VoxelVolume< float > &	targetVolume,
		std::shared_ptr< AbstractProjector >	forwardProjector,
		std::shared_ptr< AbstractReconstructor >	backprojector,
		uint	nbPowerIter = `1u`
	)

static

Computes an estimation for a suitable relaxation parameter using the power method.

If forwardProjector or backprojector is nullptr, default projectors will be used. These are OCL::RayCasterProjector and OCL::SimpleBackprojector, respectively.

◆ computeRelaxationEstimate() [2/3]

float CTL::ARTReconstructor::computeRelaxationEstimate	(	const AcquisitionSetup &	setup,
		const VoxelVolume< float > &	targetVolume,
		AbstractProjector *	forwardProjector = `nullptr`,
		AbstractReconstructor *	backprojector = `nullptr`,
		uint	nbPowerIter = `1u`
	)

static

Computes an estimation for a suitable relaxation parameter using the power method.

If forwardProjector or backprojector is nullptr, default projectors will be used. These are OCL::RayCasterProjector and OCL::SimpleBackprojector, respectively.

◆ computeRelaxationEstimate() [3/3]

float CTL::ARTReconstructor::computeRelaxationEstimate	(	const AcquisitionSetup &	setup,
		const VoxelVolume< float > &	targetVolume,
		AbstractProjector &	fp,
		AbstractReconstructor &	bp,
		uint	nbPowerIter
	)

staticprivate

Performs the power method in order to estimate and return an appropriate relaxation parameter for the iterative reconstruction

\(x\mapsto x-\omega A^{T}(Ax-b)\)

Note that \(\omega\) is not returned directly. Instead, the product with nbViews of the setup is returned, i.e. the returned values is relax \(=\omega*\)nbViews. This allows using the returned value relax also for an estimate of the relaxation parameter in (ordered) subsets of the setup by computing relax/nbViewsInSubset. The forward operator \(A\) is specified by fp and \(A^{T}\) by bp.

The power method itself approximates the largest eigenvalue \(\mu\) of \(A^{T}A\) in an iterative scheme. This eigenvalue \(\mu\) is used to estimate the relaxation parameter as \(\omega=1/\mu\). To obtain \(\mu\), the eigenvector \(v\) of \(A^{T}A\) that corresponds to \(\mu\) is approximated. An initial guess for this (normalized) eigenvector \(v\) is set as a constant vector (all entries are equal). Then \(A^{T}A\) is applied to this vector nbPowerIter times (with subsequent normalization in each iteration). If the procedure has converged, the eigenvalue can be computed using the norm of \(A^{T}Av\) (since \(A^{T}Av=\mu v\)).

For a common CT setup, nbPowerIter = 1 is already sufficient to obtain an appropriate estimate for the relaxation parameter. However, there may be cases, such as projection truncation, where the initial guess for the eigenvector \(v\) is insufficient so that more than one iteration is required.

◆ configure()

void CTL::ARTReconstructor::configure ( const AcquisitionSetup & setup )

overridevirtual

Passes the AcquisitionSetup that describes the setting in which projections that shall be reconstructed have been acquired.

This takes a copy of setup to make it available during the time of reconstruction. Any reconstruction performed after configure() was called, will use the passed setup to extract geometry information about the scan. Note that setup must be consistent with the projections that shall be reconstructed, that means it should contain information that actually corresponds to the projections.

Please also note that, in case that a subset of projections (by means of a ProjectionDataView) is used in reconstruction later on, the setup passed here must still refer to the full projection data set, the ProjectionDataView belongs to.

Implements CTL::AbstractReconstructor.

◆ consistencyChecks()

bool CTL::ARTReconstructor::consistencyChecks ( const ProjectionDataView & projections ) const

private

Returns true if projections are consistent with the AcquisitionSetup previously passed to configure().

In particular, this validates whether:

The configured setup is valid (see AcquisitionSetup::isValid()),
the number of detector modules in projections is the same as in the configured setup
projections contains no view id larger than the number of views in the configured setup.

Returns true is all abovementioned criteria are satisfied. Returns false if any of them is not fulfilled; note that criteria are checked in the order they are listed above. Issues a warning message if a criterion is not fulfilled and returns immediately afterwards, i.e. criteria appearing later in the list will not be checked.

Additionally, this also checks whether at least one stopping criterion is enabled (see hasAnyStoppingCriterion()). Issues a warning otherwise, but still returns true if all other checks were successful.

◆ customSubsetGenerator()

AbstractSubsetGenerator & CTL::ARTReconstructor::customSubsetGenerator ( ) const

Returns a reference to the current custom subset generator of this instance.

This requires that a valid (i.e. no nullptr) custom subset generator has been set.

Use this reference to change settings of the custom subset generator.

Please note that using this method (and changing settings) does not automatically imply that the custom subset generator will be used for subset generation. After setting a custom subset generator, its use will automatically be enabled. However, if the default generator has been re-enable manually since then, you need to switch back to the custom generator using useCustomSubsetGenerator() if desired. You may check whether or not the custom generator is currently used with isCustomSubsetGeneratorInUse().

◆ defaultSubsetGenerator()

DefaultSubsetGenerator & CTL::ARTReconstructor::defaultSubsetGenerator ( ) const

Returns a reference to the default subset generator of this instance.

Use this reference to change settings of the default subset generator.

Please note that using this method (and changing settings) does not automatically imply that the default subset generator will be used for subset generation. If a custom generator has been set previously, this might still be active. Re-enable the use of the default generator with useDefaultSubsetGenerator() if desired. You may check whether or not the default generator is currently used with isDefaultSubsetGeneratorInUse().

◆ hasAnyStoppingCriterion()

bool CTL::ARTReconstructor::hasAnyStoppingCriterion ( ) const

private

Returns true if any of the available stopping criteria is enabled.

Note that if this returns false, any subsequent call to a reconstruction method will not terminate.

◆ isStoppingCriterionEnabled()

bool CTL::ARTReconstructor::isStoppingCriterionEnabled ( int criteria ) const

Returns true if the stopping criterion criteria is enabled.

criteria may be a combination of multiple stopping criteria flags. In that case, true is returned if any of the flags that are part of criteria is enabled.

◆ parameter()

QVariant CTL::ARTReconstructor::parameter ( ) const

overridevirtual

Returns the parameters of this instance as a QVariant.

Returns a QVariantMap including the following (key, value)-pairs:

("forward projector", [QVariant] full QVariant of the forward projector),
("backprojector", [QVariant] full QVariant of the backprojector),
("regularizer", [QVariant] full QVariant of the regularizer),
("default subset generator", [QVariant] full QVariant of the default subset generator),
("custom subset generator", [QVariant] full QVariant of the custom subset generator),
("max nb iterations", [uint] maximum number of iterations (stopping criterion)),
("use positivity constraint", [bool] whether or not positivity constraint is applied),
("use regularization", [bool] whether or not positivity constraint is applied),
("use relaxation estimation", [bool] whether or not relaxation parameter estimation is used),
("relaxation parameter", [float] relaxation parameter value),
("terminate normal eq tol", [float] minimum normal equation tolerance (stopping criterion)),
("terminate volume change", [float] minimum volume change (stopping criterion)),
("terminate proj error change", [float] minimum projection error change(stopping criterion)),
("terminate relative proj error",[float] minimum projection error (stopping criterion)),
("terminate max time", [uint] maximum time (in ms) for reconstruction (stopping criterion)),
("active stopping criteria", [string] combination of flags of enabled stopping criteria
("uses default subset generator", [bool] whether or not the default subset generator is used).

Reimplemented from CTL::AbstractReconstructor.

◆ reconstructData()

bool CTL::ARTReconstructor::reconstructData	(	const ProjectionDataView &	projections,
		SpectralVolumeData &	targetVolume,
		AbstractProjector &	fp,
		AbstractReconstructor &	bp
	)

private

Performs the iterative reconstruction of projections into targetVolume using fp and bp as forward and backprojector, respectively.

Workflow: Assume a forward projector FP, backprojector BP, subset generator SubGen, a regularizer Regul, and an initial volume estimate

if useRelaxEstimate then relax = computeRelaxationEstimate
it = 0
do
     subsets = SubGen.generateSubsets(it)
     foreach subset in subsets
        configure FP for views in subset
        simProj = FP.project(estimate)
        diff    = relax * (simProj - subset)
        estimate = BP.reconstruct(diff, estimate)
        if useRegularization then Regul.filter(estimate)
        if usePositivity     then apply positivity constraint
     end foreach
     ++it
while (!stoppingCriterionReached)

◆ reconstructToPlain()

bool CTL::ARTReconstructor::reconstructToPlain	(	const ProjectionDataView &	projections,
		VoxelVolume< float > &	targetVolume
	)

overridevirtual

Reconstructs projection data projections into targetVolume and returns true on success.

Note that the AcquisitionSetup corresponding to projections must have been set previously with configure(). The requirements on the setup (i.e. acquisition geometry) are described in the detailed class description and in isApplicableTo().

targetVolume serves as an initialization, which means that data reconstructed from projections will be added to any values already present in targetVolume. If targetVolume has no memory allocated when passed here, memory allocation will be performed as part of the reconstruction and the volume is initialized with zero.

A rough breakdown of the reconstruction routine can be found in reconstructData().

Reimplemented from CTL::AbstractReconstructor.

◆ reconstructToSpectral()

bool CTL::ARTReconstructor::reconstructToSpectral	(	const ProjectionDataView &	projections,
		SpectralVolumeData &	targetVolume
	)

overridevirtual

Reconstructs projection data projections into targetVolume and returns true on success.

This implementation provides a means to perform a reconstruction considering the polyenergetic spectrum of the system defined in the configured acquisition setup. For that purpose, it uses the material information provided in targetVolume, i.e. it reconstructs a volume consisting of the material that is specified in that volume. To enable polyenergetic simulation within the iterative scheme, the forward projector of this instance will be wrapped in a SpectralEffectsExtension. Consequently, please do not use a forward projector that already includes this extension as a custom forward projector in this context.

If targetVolume is passed with values in density domain (see SpectralVolumeData::isDensityVolume()), it will be transformed to attenuation domain at a reference energy of 50 keV before it is passed to the actual reconstruction routine. In that case, it will be transformed back to density domain at the end of the reconstruction process.

Please also check reconstructToPlain() for some more detail on the procedures.

Reimplemented from CTL::AbstractReconstructor.

◆ regularizer()

AbstractVolumeFilter & CTL::ARTReconstructor::regularizer ( ) const

Returns a reference to the currently set regularizer.

By default (i.e. if no custom regularizer has been set; see setRegularizer()) this is a IdentityRegularizer, which has no effect when applied to volume data.

◆ relaxation()

float CTL::ARTReconstructor::relaxation ( ) const

Returns the relaxation parameter.

This method can be used, e.g. to query the relaxation parameter after automatic estimation.

◆ setBackprojector() [1/2]

void CTL::ARTReconstructor::setBackprojector ( std::unique_ptr< AbstractReconstructor > projector )

Sets the backprojector to be used to projector.

This replaces any previously set backprojector. projector must not be nullptr; throws an std::runtime_error otherwise.

◆ setBackprojector() [2/2]

void CTL::ARTReconstructor::setBackprojector ( AbstractReconstructor * projector )

Sets the backprojector to be used to projector.

This instance takes ownership of projector. This replaces any previously set backprojector. projector must not be nullptr; throws an std::runtime_error otherwise.

◆ setForwardProjector() [1/2]

void CTL::ARTReconstructor::setForwardProjector ( std::unique_ptr< AbstractProjector > projector )

Sets the forward projector to be used to projector.

This replaces any previously set projector. projector must not be nullptr; throws an std::runtime_error otherwise.

◆ setForwardProjector() [2/2]

void CTL::ARTReconstructor::setForwardProjector ( AbstractProjector * projector )

Sets the forward projector to be used to projector.

This instance takes ownership of projector. This replaces any previously set projector. projector must not be nullptr; throws an std::runtime_error otherwise.

◆ setParameter()

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

overridevirtual

Sets the parameters of this instance based on the passed QVariant parameter.

The passed parameter must be a QVariantMap containing the following (key, value)-pairs (note: no support for setting individual parameters here!):

("forward projector", [QVariant] full QVariant of the forward projector),
("backprojector", [QVariant] full QVariant of the backprojector),
("regularizer", [QVariant] full QVariant of the regularizer),
("default subset generator", [QVariant] full QVariant of the default subset generator),
("custom subset generator", [QVariant] full QVariant of the custom subset generator),
("max nb iterations", [uint] maximum number of iterations (stopping criterion)),
("use positivity constraint", [bool] whether or not positivity constraint is applied),
("use regularization", [bool] whether or not positivity constraint is applied),
("use relaxation estimation", [bool] whether or not relaxation parameter estimation is used),
("relaxation parameter", [float] relaxation parameter value),
("terminate normal eq tol", [float] minimum normal equation tolerance (stopping criterion)),
("terminate volume change", [float] minimum volume change (stopping criterion)),
("terminate proj error change", [float] minimum projection error change(stopping criterion)),
("terminate relative proj error",[float] minimum projection error (stopping criterion)),
("terminate max time", [uint] maximum time (in ms) for reconstruction (stopping criterion)),
("active stopping criteria", [string] combination of flags of enabled stopping criteria
("uses default subset generator", [bool] whether or not the default subset generator is used).

Note that it is strongly discouraged to use this method to set individual parameters of the instance. Please consider using individual setter methods for that purpose.

Reimplemented from CTL::AbstractReconstructor.

◆ setPositivityConstraintEnabled()

void CTL::ARTReconstructor::setPositivityConstraintEnabled ( bool enabled )

Sets the use of the positivity constraint to enabled.

If enabled, the positivity constraint is applied at the end of each iteration and sets all values in the current estimate that are negative to the value 0.

◆ setRegularizationEnabled()

void CTL::ARTReconstructor::setRegularizationEnabled ( bool enabled )

Sets the use of the regularizer to enabled.

If enabled, the regularizer is applied to the current volume estimate at the end of each iteration. The regularizer can be set through setRegularizer().

◆ setRegularizer()

void CTL::ARTReconstructor::setRegularizer	(	AbstractVolumeFilter *	regularizer,
		bool	enableRegularization = `true`
	)

Sets the regularizer to regularizer and enables regularization if enableRegularization = true.

This instance takes ownership of regularizer.

◆ setRelaxation()

void CTL::ARTReconstructor::setRelaxation ( float relax )

Sets the relaxation parameter to relax.

This also disables the use of an estimation for the relaxation parameter. To re-enable it, please see setRelaxationEstimationEnabled().

◆ setRelaxationByEstimation() [1/2]

void CTL::ARTReconstructor::setRelaxationByEstimation	(	const VoxelVolume< float > &	targetVolume,
		uint	nbPowerIter = `1u`
	)

Computes an estimation for the relaxation parameter and sets it for this instance.

The relaxation parameter will be computed based on the currently configured acquisition setup (see configure()) and the dimensions of targetVolume using nbPowerIter iterations of the power method.

◆ setRelaxationByEstimation() [2/2]

void CTL::ARTReconstructor::setRelaxationByEstimation	(	const AcquisitionSetup &	setup,
		const VoxelVolume< float > &	targetVolume,
		uint	nbPowerIter = `1u`
	)

Computes an estimation for the relaxation parameter and sets it for this instance.

The relaxation parameter will be computed based on the acquisition setup setup and the dimensions of targetVolume using nbPowerIter iterations of the power method.

Note that this does not configure the reconstructor with the passed setup. Use configure() separately for this purpose.

◆ setRelaxationEstimationEnabled()

void CTL::ARTReconstructor::setRelaxationEstimationEnabled ( bool enabled )

Sets the use of an estimation for the relaxation parameter to enabled.

If enabled, an estimation for the relaxation parameter is computed at the beginning of a reconstruction by means of computeRelaxationEstimate().

◆ setStoppingCriteria()

void CTL::ARTReconstructor::setStoppingCriteria ( int criteria )

Sets the stopping criteria to be checked after each iteration to criteria.

criteria may be a combination of multiple stopping criteria flags.

◆ setStoppingCriterionEnabled()

void CTL::ARTReconstructor::setStoppingCriterionEnabled	(	ARTReconstructor::StoppingCriterion	criterion,
		bool	enabled = `true`
	)

Sets the use of the stopping criterion criterion to enabled.

Note: does not influence the status of other stopping criteria than criterion.

◆ setSubsetGenerator() [1/2]

void CTL::ARTReconstructor::setSubsetGenerator ( AbstractSubsetGenerator * generator )

Sets the subset generator to be used for subset creation to generator.

This instance takes ownership of generator. This replaces any previously set generator. Automatically enables use of the passed generator for subset creation. To re-enable the use of the default generator, call useDefaultSubsetGenerator() if desired. generator must not be nullptr; throws an std::runtime_error otherwise.

◆ setSubsetGenerator() [2/2]

void CTL::ARTReconstructor::setSubsetGenerator ( std::unique_ptr< AbstractSubsetGenerator > generator )

Sets the subset generator to be used for subset creation to generator.

This replaces any previously set generator. Automatically enables use of the passed generator for subset creation. To re-enable the use of the default generator, call useDefaultSubsetGenerator() if desired. generator must not be nullptr; throws an std::runtime_error otherwise.

◆ subsetGenerator()

AbstractSubsetGenerator & CTL::ARTReconstructor::subsetGenerator ( ) const

Returns a reference to the subset generator that is currently enabled.

Use this reference to change settings of the currently enabled subset generator.

◆ terminateByComputationTime()

bool CTL::ARTReconstructor::terminateByComputationTime ( int msSpent ) const

private

Returns true if msSpent is greater than the corresponding stopping criterion value.

This compares against the value set through setMaxTime().

◆ terminateByIterationCount()

bool CTL::ARTReconstructor::terminateByIterationCount ( uint iteration ) const

private

Returns true if iteration is greater or equal to the corresponding stopping criterion value.

This compares against the value set through setMaxNbIterations().

◆ terminateByNormalEqTol()

bool CTL::ARTReconstructor::terminateByNormalEqTol	(	const VoxelVolume< float > &	oldVol,
		const VoxelVolume< float > &	newVol,
		float	normalization
	)		const

private

Approximatively evaluates whether the normal equation \(A^{T}(Ax-b)=0\) is satisfied relative to a reference norm, which is the norm of backprojected projections \(A^{T}b\), where \(b\) are the input projections and \(A\) the system matrix. This is implemented by keeping track of the change in the volume domain after each iteration. For the particular case of having only one subset including all projections, it checks whether \(\frac{\left\Vert A^{T}(Ax-b)\right\Vert }{\left\Vert A^{T}b\right\Vert }<\text{tol}\) is satisfied.

Note that the difference to the criterion VolumeDomainChange is that the norm between the current and old volume will be devided by the relaxation parameter and thus, this measure is independent from the relaxation, whereas VolumeDomainChange is not. Likewise, a division by the number of subsets is performed in order to have a criterion independent from the used ordered subset scheme.

◆ terminateByProjError()

bool CTL::ARTReconstructor::terminateByProjError	(	float	projError,
		float	inputProjNorm
	)		const

private

Returns true if the ratio between projError and inputProjNorm is less than the corresponding stopping criterion value.

This compares against the value set through setMinRelativeProjectionError().

◆ terminateByProjErrorChange()

bool CTL::ARTReconstructor::terminateByProjErrorChange	(	float	oldProjError,
		float	newProjError
	)		const

private

Returns true if the relative difference between oldProjError and newProjError is less than the corresponding stopping criterion value.

This compares (oldProjError - newProjError) / oldProjError against the value set through setMinChangeInProjectionError().

◆ terminateByVolumeChange()

bool CTL::ARTReconstructor::terminateByVolumeChange	(	const VoxelVolume< float > &	oldVol,
		const VoxelVolume< float > &	newVol
	)		const

private

Returns true if newVol and oldVol differ by less than the corresponding stopping criterion value.

This compares the relative L2 norm of oldVol and newVol with the value set through setMinChangeInVolumeDomain().

◆ toVariant()

QVariant CTL::ARTReconstructor::toVariant ( ) const

overridevirtual

Stores the contents of this instance in a QVariant.

Implementation of the serialization interface. Stores the object's type-id (from SerializationInterface::toVariant()).

This method uses parameter() to serialize class members.

In addition to any base class information, this introduces a (key,value)-pair: ("#", [string] this class' name).

Reimplemented from CTL::AbstractReconstructor.

◆ type()

int CTL::ARTReconstructor::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::AbstractReconstructor.

◆ useCustomSubsetGenerator()

void CTL::ARTReconstructor::useCustomSubsetGenerator ( )

Enables the use of the (previously set) custom subset generator.

Note that a valid (i.e. no nullptr) custom subset generator must be set in advance (see setSubsetGenerator()); throws an std::runtime_error otherwise.

◆ useDefaultSubsetGenerator()

void CTL::ARTReconstructor::useDefaultSubsetGenerator ( )

(Re-)Enables the use of the default subset generator.

Note that by default, the default subset generator is in use automatically. A call to this method should therefore only become necessary if a custom subset generator has been set, and the default subset generator shall be re-enabled.

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

modules/src/recon/artreconstructor.h
modules/src/recon/artreconstructor.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ StoppingCriterion

Constructor & Destructor Documentation

◆ ARTReconstructor() [1/2]

◆ ARTReconstructor() [2/2]

Member Function Documentation

◆ computeRelaxationEstimate() [1/3]

◆ computeRelaxationEstimate() [2/3]

◆ computeRelaxationEstimate() [3/3]

◆ configure()

◆ consistencyChecks()

◆ customSubsetGenerator()

◆ defaultSubsetGenerator()

◆ hasAnyStoppingCriterion()

◆ isStoppingCriterionEnabled()

◆ parameter()

◆ reconstructData()

◆ reconstructToPlain()

◆ reconstructToSpectral()

◆ regularizer()

◆ relaxation()

◆ setBackprojector() [1/2]

◆ setBackprojector() [2/2]

◆ setForwardProjector() [1/2]

◆ setForwardProjector() [2/2]

◆ setParameter()

◆ setPositivityConstraintEnabled()

◆ setRegularizationEnabled()

◆ setRegularizer()

◆ setRelaxation()

◆ setRelaxationByEstimation() [1/2]

◆ setRelaxationByEstimation() [2/2]

◆ setRelaxationEstimationEnabled()

◆ setStoppingCriteria()

◆ setStoppingCriterionEnabled()

◆ setSubsetGenerator() [1/2]

◆ setSubsetGenerator() [2/2]

◆ subsetGenerator()

◆ terminateByComputationTime()

◆ terminateByIterationCount()

◆ terminateByNormalEqTol()

◆ terminateByProjError()

◆ terminateByProjErrorChange()

◆ terminateByVolumeChange()

◆ toVariant()

◆ type()

◆ useCustomSubsetGenerator()

◆ useDefaultSubsetGenerator()