A class in the GeneralisedPrior hierarchy. This implements a quadratic Gibbs prior. More...

#include "stir_experimental/recon_buildblock/ParametricQuadraticPrior.h"

Inheritance diagram for stir::ParametricQuadraticPrior< TargetT >:

[legend]

Public Member Functions
	ParametricQuadraticPrior ()
	Default constructor.

	ParametricQuadraticPrior (const bool only_2D, float penalization_factor)
	Constructs it explicitly.

virtual bool	parabolic_surrogate_curvature_depends_on_argument () const
	A function that allows skipping some computations if the curvature is independent of the `current_estimate`. More...

double	compute_value (const TargetT &current_image_estimate)
	compute the value of the function

void	compute_gradient (TargetT &prior_gradient, const TargetT &current_image_estimate)
	compute gradient

void	parabolic_surrogate_curvature (TargetT &parabolic_surrogate_curvature, const TargetT &current_image_estimate)
	compute the parabolic surrogate for the prior More...

virtual Succeeded	add_multiplication_with_approximate_Hessian (TargetT &output, const TargetT &input) const
	This should compute the multiplication of the Hessian with a vector and add it to output. More...

Array< 3, float >	get_weights () const
	get penalty weights for the neigbourhood

void	set_weights (const Array< 3, float > &)
	set penalty weights for the neigbourhood

shared_ptr< TargetT >	get_kappa_sptr () const
	get current kappa image More...

void	set_kappa_sptr (const shared_ptr< TargetT > &)
	set kappa image

virtual Succeeded	set_up (shared_ptr< const TargetT > const &target_sptr)
	Has to be called before using this object.

template<>
const char *const	registered_name

Public Member Functions inherited from stir::RegisteredParsingObject< ParametricQuadraticPrior< TargetT >, GeneralisedPrior< TargetT >, PriorWithParabolicSurrogate< TargetT > >
std::string	get_registered_name () const override
	Returns Derived::registered_name.

std::string	parameter_info () override
	Returns a string with all parameters and their values, in a form suitable for parsing again.

Public Member Functions inherited from stir::GeneralisedPrior< TargetT >
virtual void	compute_Hessian (TargetT &prior_Hessian_for_single_densel, const BasicCoordinate< 3, int > &coords, const TargetT &current_image_estimate) const
	This computes a single row of the Hessian. More...

virtual void	accumulate_Hessian_times_input (TargetT &output, const TargetT &current_estimate, const TargetT &input) const
	This should compute the multiplication of the Hessian with a vector and add it to output. More...

float	get_penalisation_factor () const

void	set_penalisation_factor (float new_penalisation_factor)

virtual bool	is_convex () const=0
	Indicates if the prior is a smooth convex function. More...

Public Member Functions inherited from stir::ParsingObject
	ParsingObject (const ParsingObject &)

ParsingObject &	operator= (const ParsingObject &)

void	ask_parameters ()

bool	parse (std::istream &f)

bool	parse (const char *const filename)

Static Public Attributes
static const char *const	registered_name
	Name which will be used when parsing a GeneralisedPrior object.

Protected Member Functions
virtual void	check (TargetT const &current_image_estimate) const
	Check that the prior is ready to be used.

virtual void	set_defaults ()
	Set defaults before parsing.

virtual void	initialise_keymap ()
	Initialise all keywords.

virtual bool	post_processing ()
	This will be called at the end of the parsing. More...

Protected Member Functions inherited from stir::GeneralisedPrior< TargetT >
void	set_defaults () override
	sets value for penalisation factor More...

void	initialise_keymap () override
	sets key for penalisation factor More...

Protected Member Functions inherited from stir::ParsingObject
virtual void	set_key_values ()
	This will be called before parsing or parameter_info is called. More...

Protected Attributes
bool	only_2D
	can be set during parsing to restrict the weights to the 2D case

std::string	gradient_filename_prefix
	filename prefix for outputing the gradient whenever compute_gradient() is called. More...

Array< 3, float >	weights
	penalty weights More...

std::string	kappa_filename
	Filename for the $\kappa$ image that will be read by post_processing()

Protected Attributes inherited from stir::GeneralisedPrior< TargetT >
float	penalisation_factor

bool	_already_set_up

Protected Attributes inherited from stir::ParsingObject
KeyParser	parser

Additional Inherited Members
Static Public Member Functions inherited from stir::RegisteredParsingObject< ParametricQuadraticPrior< TargetT >, GeneralisedPrior< TargetT >, PriorWithParabolicSurrogate< TargetT > >
static GeneralisedPrior< TargetT > *	read_from_stream (std::istream *)
	Construct a new object (of type Derived) by parsing the istream. More...

Static Public Member Functions inherited from stir::RegisteredObject< GeneralisedPrior< TargetT > >
static GeneralisedPrior< TargetT > *	read_registered_object (std::istream *in, const std::string &registered_name)
	Construct a new object (of a type derived from Root, its actual type determined by the registered_name parameter) by parsing the istream. More...

static GeneralisedPrior< TargetT > *	ask_type_and_parameters ()
	ask the user for the type, and then calls read_registered_object(0, type) More...

static void	list_registered_names (std::ostream &stream)
	List all possible registered names to the stream. More...

Protected Types inherited from stir::RegisteredObject< GeneralisedPrior< TargetT > >
typedef GeneralisedPrior< TargetT > (	RootFactory) (std::istream *)
	The type of a root factory is a function, taking an istream* as argument, and returning a Root*.

typedef FactoryRegistry< std::string, RootFactory, interfile_less >	RegistryType
	The type of the registry.

Static Protected Member Functions inherited from stir::RegisteredObject< GeneralisedPrior< TargetT > >
static RegistryType &	registry ()
	Static function returning the registry. More...

Detailed Description

template<typename TargetT>
class stir::ParametricQuadraticPrior< TargetT >

A class in the GeneralisedPrior hierarchy. This implements a quadratic Gibbs prior.

The gradient of the prior is computed as follows:

$g_r = \sum_dr w_{dr} (\lambda_r - \lambda_{r+dr}) * \kappa_r * \kappa_{r+dr}$

where $\lambda$ is the image and $r$ and $dr$ are indices and the sum is over the neighbourhood where the weights $w_{dr}$ are non-zero.

The $\kappa$ image can be used to have spatially-varying penalties such as in Jeff Fessler's papers. It should have identical dimensions to the image for which the penalty is computed. If $\kappa$ is not set, this class will effectively use 1 for all $\kappa$ 's.

By default, a 3x3 or 3x3x3 neigbourhood is used where the weights are set to x-voxel_size divided by the Euclidean distance between the points.

Parsing

These are the keywords that can be used in addition to the ones in GeneralPrior.

Quadratic Prior Parameters:=
; next defaults to 0, set to 1 for 2D inverse Euclidean weights, 0 for 3D
only 2D:= 0
; next can be used to set weights explicitly. Needs to be a 3D array (of floats).
' value of only_2D is ignored
; following example uses 2D 'nearest neighbour' penalty
; weights:={{{0,1,0},{1,0,1},{0,1,0}}}
; use next parameter to specify an image with penalisation factors (a la Fessler)
; see class documentation for more info
; kappa filename:=
; use next parameter to get gradient images at every subiteration
; see class documentation
gradient filename prefix:=
END Quadratic Prior Parameters:=

Member Function Documentation

◆ parabolic_surrogate_curvature_depends_on_argument()

template<typename TargetT >

virtual bool stir::ParametricQuadraticPrior< TargetT >::parabolic_surrogate_curvature_depends_on_argument ( ) const

inlinevirtual

A function that allows skipping some computations if the curvature is independent of the current_estimate.

Defaults to return true, but can be overloaded by the derived class.

Reimplemented from stir::PriorWithParabolicSurrogate< TargetT >.

◆ parabolic_surrogate_curvature()

template<typename TargetT >

void stir::ParametricQuadraticPrior< TargetT >::parabolic_surrogate_curvature	(	TargetT &	parabolic_surrogate_curvature,
		const TargetT &	current_image_estimate
	)

virtual

compute the parabolic surrogate for the prior

in the case of quadratic priors this will just be the sum of weighting coefficients

Implements stir::PriorWithParabolicSurrogate< TargetT >.

References stir::ParametricQuadraticPrior< TargetT >::check().

◆ add_multiplication_with_approximate_Hessian()

template<typename TargetT >

Succeeded stir::ParametricQuadraticPrior< TargetT >::add_multiplication_with_approximate_Hessian	(	TargetT &	output,
		const TargetT &	input
	)		const

virtual

This should compute the multiplication of the Hessian with a vector and add it to output.

Default implementation just call error(). This function needs to be overridden by the derived class. This method assumes that the hessian of the prior is 1 and hence the function quadratic. Instead, accumulate_Hessian_times_input() should be used. This method remains for backwards comparability.

Warning: The derived class should accumulate in output.

Reimplemented from stir::GeneralisedPrior< TargetT >.

References stir::ParametricQuadraticPrior< TargetT >::check().

◆ get_kappa_sptr()

template<typename TargetT >

shared_ptr< TargetT > stir::ParametricQuadraticPrior< TargetT >::get_kappa_sptr ( ) const

get current kappa image

Warning: As this function returns a shared_ptr, this is dangerous. You should not modify the image by manipulating the image refered to by this pointer. Unpredictable results will occur.

◆ post_processing()

template<typename TargetT >

bool stir::ParametricQuadraticPrior< TargetT >::post_processing ( )

protectedvirtual

This will be called at the end of the parsing.

Returns: false if everything OK, true if not

Reimplemented from stir::ParsingObject.

References stir::ParametricQuadraticPrior< TargetT >::set_weights().

Member Data Documentation

◆ gradient_filename_prefix

template<typename TargetT >

std::string stir::ParametricQuadraticPrior< TargetT >::gradient_filename_prefix

protected

filename prefix for outputing the gradient whenever compute_gradient() is called.

An internal counter is used to keep track of the number of times the gradient is computed. The filename will be constructed by concatenating gradient_filename_prefix and the counter.

Referenced by stir::ParametricQuadraticPrior< TargetT >::compute_gradient().

◆ weights

template<typename TargetT >

Array<3, float> stir::ParametricQuadraticPrior< TargetT >::weights

mutableprotected

penalty weights

Todo:: This member is mutable at present because some const functions initialise it. That initialisation should be moved to a new set_up() function.

Referenced by stir::ParametricQuadraticPrior< TargetT >::get_weights(), and stir::ParametricQuadraticPrior< TargetT >::set_weights().

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

/home/sirfuser/devel/STIRdistrib/STIR/src/include/stir_experimental/recon_buildblock/ParametricQuadraticPrior.h
/home/sirfuser/devel/STIRdistrib/STIR/src/experimental/recon_buildblock/ParametricQuadraticPrior.cxx

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

template<typename TargetT> class stir::ParametricQuadraticPrior< TargetT >

Member Function Documentation

◆ parabolic_surrogate_curvature_depends_on_argument()

◆ parabolic_surrogate_curvature()

◆ add_multiplication_with_approximate_Hessian()

◆ get_kappa_sptr()

◆ post_processing()

Member Data Documentation

◆ gradient_filename_prefix

◆ weights

template<typename TargetT>
class stir::ParametricQuadraticPrior< TargetT >