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`.

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

virtual Succeeded	add_multiplication_with_approximate_Hessian (TargetT &output, const TargetT &input) const

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

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.

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.

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 double	compute_gradient_times_input (const TargetT &input, const TargetT &current_estimate)
	compute the dot product of the gradient of the log of the prior function at the current_estimate with input

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.

virtual void	compute_Hessian_diagonal (TargetT &Hessian_diagonal, const TargetT &current_estimate) const
	This computes the diagonal of the Hessian of the log of the prior function at the current_estimate and stores it in Hessian_diagonal.

virtual void	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.

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.

float	get_penalisation_factor () const

void	set_penalisation_factor (float new_penalisation_factor)

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

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

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

ParsingObject &	operator= (const ParsingObject &)

bool	parse (std::istream &f)

bool	parse (const char *const filename)

void	ask_parameters ()

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 ()
	sets value for penalisation factor

virtual void	initialise_keymap ()
	sets key for penalisation factor

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

Protected Member Functions inherited from stir::GeneralisedPrior< TargetT >
virtual void	check (TargetT const &current_estimate) const
	Check that the prior is ready to be used.

virtual void	set_key_values ()
	This will be called before parsing or parameter_info is called.

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.

Array< 3, float >	weights
	penalty weights

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

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.

static GeneralisedPrior< TargetT > *	read_from_stream (std::istream *)
	Construct a new object (of type Derived) by parsing the istream.

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.

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

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

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.

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 and 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 >.

◆ compute_value()

template<typename TargetT>

double stir::ParametricQuadraticPrior< TargetT >::compute_value ( const TargetT & current_image_estimate )

virtual

compute the value of the function

Implements stir::GeneralisedPrior< TargetT >.

References check(), compute_value(), and stir::sum().

Referenced by compute_value().

◆ compute_gradient()

template<typename TargetT>

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

virtual

compute gradient

Implements stir::GeneralisedPrior< TargetT >.

References check(), gradient_filename_prefix, and stir::write_to_file().

◆ 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 check(), and parabolic_surrogate_curvature().

Referenced by parabolic_surrogate_curvature().

◆ 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.

Referenced by post_processing().

◆ set_defaults()

template<typename TargetT>

void stir::ParametricQuadraticPrior< TargetT >::set_defaults ( )

protectedvirtual

sets value for penalisation factor

Has to be called by set_defaults in the leaf-class

Reimplemented from stir::GeneralisedPrior< TargetT >.

References only_2D, set_defaults(), stir::ParsingObject::set_defaults(), and weights.

Referenced by ParametricQuadraticPrior(), and set_defaults().

◆ initialise_keymap()

template<typename TargetT>

void stir::ParametricQuadraticPrior< TargetT >::initialise_keymap ( )

protectedvirtual

sets key for penalisation factor

Has to be called by initialise_keymap in the leaf-class

Reimplemented from stir::GeneralisedPrior< TargetT >.

References gradient_filename_prefix, initialise_keymap(), stir::ParsingObject::initialise_keymap(), kappa_filename, only_2D, and weights.

Referenced by initialise_keymap().

◆ 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 get_kappa_sptr(), get_weights(), kappa_filename, post_processing(), stir::ParsingObject::post_processing(), stir::read_from_file(), and weights.

Referenced by post_processing().

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 compute_gradient(), and initialise_keymap().

◆ 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 get_weights(), initialise_keymap(), post_processing(), set_defaults(), and set_weights().

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

/home/kris/devel/STIRdistrib/STIR/src/include/stir_experimental/recon_buildblock/ParametricQuadraticPrior.h
/home/kris/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

Member Function Documentation

◆ parabolic_surrogate_curvature_depends_on_argument()

◆ compute_value()

◆ compute_gradient()

◆ parabolic_surrogate_curvature()

◆ get_kappa_sptr()

◆ set_defaults()

◆ initialise_keymap()

◆ post_processing()

Member Data Documentation

◆ gradient_filename_prefix

◆ weights