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

#include "stir/recon_buildblock/LogcoshPrior.h"

Inheritance diagram for stir::LogcoshPrior< elemT >:

[legend]

Public Member Functions
	LogcoshPrior ()
	Default constructor.

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

	LogcoshPrior (const bool only_2D, float penalization_factor, const float scalar)
	Constructs it explicitly with scalar.

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

bool	is_convex () const override
	Indicates if the prior is a smooth convex function.

double	compute_value (const DiscretisedDensity< 3, elemT > &current_image_estimate) override
	compute the value of the function

void	compute_gradient (DiscretisedDensity< 3, elemT > &prior_gradient, const DiscretisedDensity< 3, elemT > &current_image_estimate) override
	compute gradient

void	parabolic_surrogate_curvature (DiscretisedDensity< 3, elemT > &parabolic_surrogate_curvature, const DiscretisedDensity< 3, elemT > &current_image_estimate) override
	compute the parabolic surrogate for the prior

void	compute_Hessian (DiscretisedDensity< 3, elemT > &prior_Hessian_for_single_densel, const BasicCoordinate< 3, int > &coords, const DiscretisedDensity< 3, elemT > &current_image_estimate) const override

void	accumulate_Hessian_times_input (DiscretisedDensity< 3, elemT > &output, const DiscretisedDensity< 3, elemT > &current_estimate, const DiscretisedDensity< 3, elemT > &input) const override
	Compute the multiplication of the hessian of the prior (at `current_estimate`) and the `input`.

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< DiscretisedDensity< 3, elemT > >	get_kappa_sptr () const
	get current kappa image

void	set_kappa_sptr (const shared_ptr< DiscretisedDensity< 3, elemT > > &)
	set kappa image

float	get_scalar () const
	Get the scalar value.

void	set_scalar (float scalar_v)
	Set the scalar value.

Public Member Functions inherited from stir::RegisteredParsingObject< LogcoshPrior< elemT >, GeneralisedPrior< DiscretisedDensity< 3, elemT > >, PriorWithParabolicSurrogate< DiscretisedDensity< 3, elemT > > >
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::PriorWithParabolicSurrogate< TargetT >
virtual void	parabolic_surrogate_curvature (TargetT &parabolic_surrogate_curvature, const TargetT &current_estimate)=0
	this should calculate the parabolic surrogate curvature

Public Member Functions inherited from stir::GeneralisedPrior< TargetT >
virtual double	compute_value (const TargetT &current_estimate)=0
	compute the value of the function

virtual void	compute_gradient (TargetT &prior_gradient, const TargetT &current_estimate)=0
	This should compute the gradient of the log of the prior function at the current_estimate.

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.

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

void	initialise_keymap () override
	sets key for penalisation factor

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

void	check (DiscretisedDensity< 3, elemT > const &current_image_estimate) const override
	Check that the prior is ready to be used.

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

float	scalar
	controls the transition between the quadratic (smooth) and linear (edge-preserving) nature of the prior

std::string	gradient_filename_prefix
	filename prefix for outputting 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< LogcoshPrior< elemT >, GeneralisedPrior< DiscretisedDensity< 3, elemT > >, PriorWithParabolicSurrogate< DiscretisedDensity< 3, elemT > > >
static GeneralisedPrior< DiscretisedDensity< 3, elemT > > *	read_from_stream (std::istream *)
	Construct a new object (of type Derived) by parsing the istream.

static GeneralisedPrior< DiscretisedDensity< 3, elemT > > *	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 elemT>
class stir::LogcoshPrior< elemT >

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

The log-cosh function is given by:

$f = \sum_{r,dr} w_{dr} \frac{1}{2 s^2} log(cosh(s(\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 neighbourhood 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.

Logcosh Prior Parameters:=
; next defaults to 0, set to 1 for 2D inverse Euclidean weights, 0 for 3D
only 2D:= 0
; scalar controls the transition between the quadratic (smooth) and linear (edge-preserving) nature of the function
; scalar:=
; 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 Logcosh Prior Parameters:=

Member Function Documentation

◆ parabolic_surrogate_curvature_depends_on_argument()

template<typename elemT>

bool stir::LogcoshPrior< elemT >::parabolic_surrogate_curvature_depends_on_argument ( ) const

inlineoverridevirtual

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

◆ is_convex()

template<typename elemT>

bool stir::LogcoshPrior< elemT >::is_convex ( ) const

overridevirtual

Indicates if the prior is a smooth convex function.

If true, the prior is expected to have 0th, 1st and 2nd order behaviour implemented.

Implements stir::GeneralisedPrior< TargetT >.

◆ get_weights()

template<typename elemT>

Array< 3, float > stir::LogcoshPrior< elemT >::get_weights ( ) const

get penalty weights for the neigbourhood

get penalty weights for the neighbourhood

References weights.

◆ set_weights()

template<typename elemT>

void stir::LogcoshPrior< elemT >::set_weights ( const Array< 3, float > & w )

set penalty weights for the neigbourhood

set penalty weights for the neighbourhood

References weights.

◆ get_kappa_sptr()

template<typename elemT>

shared_ptr< DiscretisedDensity< 3, elemT > > stir::LogcoshPrior< elemT >::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 referred to by this pointer. Unpredictable results will occur.

◆ set_defaults()

template<typename elemT>

void stir::LogcoshPrior< elemT >::set_defaults ( )

overrideprotectedvirtual

sets value for penalisation factor

Has to be called by set_defaults in the leaf-class

Reimplemented from stir::GeneralisedPrior< TargetT >.

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

Referenced by LogcoshPrior(), LogcoshPrior(), LogcoshPrior(), and set_defaults().

◆ initialise_keymap()

template<typename elemT>

void stir::LogcoshPrior< elemT >::initialise_keymap ( )

overrideprotectedvirtual

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, scalar, and weights.

Referenced by initialise_keymap().

◆ post_processing()

template<typename elemT>

bool stir::LogcoshPrior< elemT >::post_processing ( )

overrideprotectedvirtual

This will be called at the end of the parsing.

Returns: false if everything OK, true if not

Reimplemented from stir::ParsingObject.

References kappa_filename, post_processing(), stir::ParsingObject::post_processing(), stir::read_from_file(), stir::warning(), and weights.

Referenced by post_processing().

Member Data Documentation

◆ gradient_filename_prefix

template<typename elemT>

std::string stir::LogcoshPrior< elemT >::gradient_filename_prefix

protected

filename prefix for outputting 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 elemT>

Array<3, float> stir::LogcoshPrior< elemT >::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 accumulate_Hessian_times_input(), compute_gradient(), compute_value(), get_weights(), initialise_keymap(), parabolic_surrogate_curvature(), 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/recon_buildblock/LogcoshPrior.h
/home/kris/devel/STIRdistrib/STIR/src/recon_buildblock/LogcoshPrior.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()

◆ is_convex()

◆ get_weights()

◆ set_weights()

◆ get_kappa_sptr()

◆ set_defaults()

◆ initialise_keymap()

◆ post_processing()

Member Data Documentation

◆ gradient_filename_prefix

◆ weights