base class for iterative reconstruction objects More...

#include "stir/recon_buildblock/IterativeReconstruction.h"

Inheritance diagram for stir::IterativeReconstruction< TargetT >:

[legend]

Public Member Functions
int	get_subiteration_num () const
	accessor for the subiteration counter

int	get_subset_num ()
	accessor for finding the current subset number

virtual TargetT *	get_initial_data_ptr () const
	Gets a pointer to the initial data.

Succeeded	reconstruct () override
	executes the reconstruction

Succeeded	reconstruct (shared_ptr< TargetT > const &target_data_sptr) override
	executes the reconstruction with target_data_sptr as initial value

std::string	make_filename_prefix_subiteration_num (const std::string &filename_prefix) const
	A utility function that creates a filename_prefix by appending the current subiteration number.

std::string	make_filename_prefix_subiteration_num () const
	A utility function that creates the output filename_prefix for the current subiteration number.

Functions to get parameters
Warning Be careful with changing shared pointers. If you modify the objects in one place, all objects that use the shared pointer will be affected.
GeneralisedObjectiveFunction< TargetT > const &	get_objective_function () const

shared_ptr< GeneralisedObjectiveFunction< TargetT > >	get_objective_function_sptr () const

const int	get_max_num_full_iterations () const
	the maximum allowed number of full iterations

const int	get_num_subsets () const
	the number of ordered subsets

const int	get_num_subiterations () const
	the number of subiterations

const int	get_start_subiteration_num () const
	value with which to initialize the subiteration counter

const int	get_start_subset_num () const
	the starting subset number

const int	get_save_interval () const
	subiteration interval at which data will be saved

const bool	get_randomise_subset_order () const
	signals whether to randomise the subset order in each iteration

const DataProcessor< TargetT > &	get_inter_iteration_filter () const
	inter-iteration filter

shared_ptr< DataProcessor< TargetT > >	get_inter_iteration_filter_sptr ()

const int	get_inter_iteration_filter_interval () const
	subiteration interval at which to apply inter-iteration filters

const int	get_report_objective_function_values_interval () const
	subiteration interval at which to report the values of the objective function

Public Member Functions inherited from stir::Reconstruction< TargetT >
	Reconstruction ()
	default constructor (calls set_defaults())

	~Reconstruction () override
	virtual destructor

virtual std::string	method_info () const =0
	gives method information

void	set_output_filename_prefix (const std::string &)
	file name for output reconstructed images

void	set_output_file_format_ptr (const shared_ptr< OutputFileFormat< TargetT > > &)
	defines the format of the output files

void	set_post_processor_sptr (const shared_ptr< DataProcessor< TargetT > > &)
	post-filter

void	set_disable_output (bool _val)
	set_disable_output

shared_ptr< TargetT >	get_target_image ()
	get_reconstructed_image

Public Member Functions inherited from stir::RegisteredObjectBase
virtual std::string	get_registered_name () const =0
	Returns the name of the type of the 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 ()

virtual std::string	parameter_info ()

Public Member Functions inherited from stir::TimedObject
void	reset_timers ()
	reset all timers kept by this object

void	stop_timers () const
	stop all timers kept by this object

void	start_timers (bool do_reset=false) const
	start all timers kept by this object

double	get_CPU_timer_value () const
	get current value of the CPU timer (since first use or last reset)

double	get_wall_clock_timer_value () const
	get current value of the wall-clock timer (since first use or last reset)

Functions to set parameters
This can be used as alternative to the parsing mechanism. Warning Be careful with changing shared pointers. If you modify the objects in one place, all objects that use the shared pointer will be affected.
shared_ptr< GeneralisedObjectiveFunction< TargetT > >	objective_function_sptr

int	subiteration_num
	the subiteration counter

bool	terminate_iterations
	used to abort the loop over iterations

int	max_num_full_iterations
	the maximum allowed number of full iterations

int	num_subsets
	the number of ordered subsets

int	num_subiterations
	the number of subiterations

int	start_subiteration_num
	value with which to initialize the subiteration counter

std::string	initial_data_filename
	name of the file containing the data for intializing the reconstruction

int	start_subset_num
	the starting subset number

int	save_interval
	subiteration interval at which data will be saved

bool	randomise_subset_order
	signals whether to randomise the subset order in each iteration

shared_ptr< DataProcessor< TargetT > >	inter_iteration_filter_ptr
	inter-iteration filter

int	inter_iteration_filter_interval
	subiteration interval at which to apply inter-iteration filters

int	report_objective_function_values_interval
	subiteration interval at which to report the values of the objective function

void	set_objective_function_sptr (const shared_ptr< GeneralisedObjectiveFunction< TargetT > > &)
	The objective function that will be optimised.

void	set_max_num_full_iterations (const int)
	the maximum allowed number of full iterations

void	set_num_subsets (const int)
	the number of ordered subsets

void	set_num_subiterations (const int)
	the number of subiterations

void	set_start_subiteration_num (const int)
	value with which to initialize the subiteration counter

void	set_start_subset_num (const int)
	the starting subset number

void	set_save_interval (const int)
	subiteration interval at which data will be saved

void	set_randomise_subset_order (const bool)
	signals whether to randomise the subset order in each iteration

void	set_inter_iteration_filter_ptr (const shared_ptr< DataProcessor< TargetT > > &)
	inter-iteration filter

void	set_inter_iteration_filter_interval (const int)
	subiteration interval at which to apply inter-iteration filters

void	set_report_objective_function_values_interval (const int)
	subiteration interval at which to report the values of the objective function

void	set_input_data (const shared_ptr< ExamData > &arg) override
	set_input_data

const ExamData &	get_input_data () const override
	get input data

Succeeded	set_up (shared_ptr< TargetT > const &target_data_ptr) override
	operations prior to the reconstruction

virtual void	update_estimate (TargetT &current_estimate)=0
	the principal operations for updating the data iterates at each iteration

virtual void	end_of_iteration_processing (TargetT &current_estimate)
	operations for the end of the iteration

virtual void	ask_parameters ()
	prompts the user to enter parameter values manually

void	set_defaults () override
	Set defaults before parsing.

void	initialise_keymap () override
	Initialise all keywords.

bool	post_processing () override
	used to check acceptable parameter ranges, etc...

Additional Inherited Members
Static Public Member Functions inherited from stir::RegisteredObject< Reconstruction< TargetT > >
static Reconstruction< 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 Reconstruction< 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< Reconstruction< TargetT > >
typedef Reconstruction< 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.

virtual void	check (TargetT const &target_data) const
	do consistency checks

void	initialise (const std::string &parameter_filename)
	This function initialises all parameters, either via parsing, or by calling ask_parameters() (when parameter_filename is the empty string).

void	set_defaults () override
	Set defaults before parsing.

void	initialise_keymap () override
	Initialise all keywords.

bool	post_processing () override
	used to check acceptable parameters after parsing

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

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

std::string	output_filename_prefix
	file name for output reconstructed images

shared_ptr< OutputFileFormat< TargetT > >	output_file_format_ptr
	defines the format of the output files

shared_ptr< DataProcessor< TargetT > >	post_filter_sptr
	post-filter

bool	_already_set_up

shared_ptr< TargetT >	target_data_sptr
	target_data_sptr

bool	_disable_output
	_disable_output

int	_verbosity
	Verbosity level.

KeyParser	parser

Detailed Description

template<class TargetT>
class stir::IterativeReconstruction< TargetT >

base class for iterative reconstruction objects

This is the base class for all iterative reconstruction methods. It provides the basic iteration mechanisms. What each iteration does has to be implemented in a derived class.

Parsing parameters

; any parameters from Reconstruction<TargetT>

; see GeneralisedObjectiveFunction<TargetT>
objective function type:=


number of subsets:= 1
start at subset:= 0
number of subiterations:= 1
save images at subiteration intervals:= 1
start at subiteration number:=2

initial image :=
enforce initial positivity condition:=1

; specify processing after every few subiterations, see DataProcessor<TargetT>
inter-iteration filter subiteration interval:=
inter-iteration filter type :=

; write objective function value to stderr at certain subiterations
; default value of 0 means: do not write it at all.
report_objective_function_values_interval:=0

Todo

move subset things somewhere else

all the compute functions should be const.

Member Function Documentation

◆ get_subset_num()

template<typename TargetT>

int stir::IterativeReconstruction< TargetT >::get_subset_num ( )

accessor for finding the current subset number

The subset number is determined from the subiteration number. If randomise_subset_order is false, the subset number is found as follows:

(subiteration_num+start_subset_num-1)%num_subsets

stir::IterativeReconstruction::subiteration_num

int subiteration_num

the subiteration counter

Definition IterativeReconstruction.h:260

stir::IterativeReconstruction::start_subset_num

int start_subset_num

the starting subset number

Definition IterativeReconstruction.h:283

stir::IterativeReconstruction::num_subsets

int num_subsets

the number of ordered subsets

Definition IterativeReconstruction.h:271

When randomise subsets are used, a new random order is initialised before every full iteration. In this case, start_subset_num is ignored (as it doesn't make any sense).

References get_subset_num(), randomise_subset_order, start_subset_num, and subiteration_num.

Referenced by get_subset_num(), stir::OSMAPOSLReconstruction< TargetT >::update_estimate(), and stir::OSSPSReconstruction< TargetT >::update_estimate().

◆ get_initial_data_ptr()

template<typename TargetT>

TargetT * stir::IterativeReconstruction< TargetT >::get_initial_data_ptr ( ) const

virtual

Gets a pointer to the initial data.

This is either read from file, or constructed by construct_target_ptr(). In the latter case, its values are set to 0 or 1, depending on the value of IterativeReconstruction::initial_data_filename.

Todo

Dependency on explicit strings "1" or "0" in IterativeReconstruction::initial_data_filename is not nice.

should not return a 'bare' pointer.

References stir::error(), get_initial_data_ptr(), get_input_data(), initial_data_filename, and stir::Reconstruction< TargetT >::target_data_sptr.

Referenced by get_initial_data_ptr(), reconstruct(), stir::PoissonLogLikelihoodWithLinearModelForMeanAndListModeDataWithProjMatrixByBinTests::run_tests(), and stir::PoissonLogLikelihoodWithLinearModelForMeanAndProjDataTests::run_tests().

◆ reconstruct() [1/2]

template<typename TargetT>

Succeeded stir::IterativeReconstruction< TargetT >::reconstruct ( )

overridevirtual

executes the reconstruction

Calls get_initial_data_ptr() and then reconstruct(shared_ptr<TargetT>const&). See end_of_iteration_processing() for info on saving to file.

Returns: Succeeded::yes if everything was alright.

Implements stir::Reconstruction< TargetT >.

References get_initial_data_ptr(), reconstruct(), set_up(), stir::TimedObject::start_timers(), stir::TimedObject::stop_timers(), and stir::Reconstruction< TargetT >::target_data_sptr.

Referenced by reconstruct(), and reconstruct().

◆ reconstruct() [2/2]

template<typename TargetT>

Succeeded stir::IterativeReconstruction< TargetT >::reconstruct ( shared_ptr< TargetT > const & target_data_sptr )

overridevirtual

executes the reconstruction with target_data_sptr as initial value

After calling set_up(), repeatedly calls update_estimate(); end_of_iteration_processing(); See end_of_iteration_processing() for info on saving to file.

Final reconstruction is saved in target_data_sptr

Implements stir::Reconstruction< TargetT >.

References stir::Reconstruction< TargetT >::check(), end_of_iteration_processing(), stir::TimedObject::get_CPU_timer_value(), stir::info(), num_subiterations, reconstruct(), set_up(), start_subiteration_num, stir::TimedObject::start_timers(), stir::TimedObject::stop_timers(), subiteration_num, stir::Reconstruction< TargetT >::target_data_sptr, terminate_iterations, and update_estimate().

◆ make_filename_prefix_subiteration_num() [1/2]

template<typename TargetT>

std::string stir::IterativeReconstruction< TargetT >::make_filename_prefix_subiteration_num ( const std::string & filename_prefix ) const

A utility function that creates a filename_prefix by appending the current subiteration number.

Only works when no extension is present.

References make_filename_prefix_subiteration_num(), and subiteration_num.

Referenced by end_of_iteration_processing(), make_filename_prefix_subiteration_num(), make_filename_prefix_subiteration_num(), and stir::OSSPSReconstruction< TargetT >::update_estimate().

◆ make_filename_prefix_subiteration_num() [2/2]

template<typename TargetT>

std::string stir::IterativeReconstruction< TargetT >::make_filename_prefix_subiteration_num ( ) const

A utility function that creates the output filename_prefix for the current subiteration number.

Uses output_filename_prefix. Only works when no extension is present.

References make_filename_prefix_subiteration_num(), and stir::Reconstruction< TargetT >::output_filename_prefix.

◆ set_input_data()

template<typename TargetT>

void stir::IterativeReconstruction< TargetT >::set_input_data ( const shared_ptr< ExamData > & arg )

overridevirtual

set_input_data

Author: Nikos Efthimiou

Implements stir::Reconstruction< TargetT >.

References stir::error(), and set_input_data().

Referenced by set_input_data().

◆ get_input_data()

template<typename TargetT>

const ExamData & stir::IterativeReconstruction< TargetT >::get_input_data ( ) const

overridevirtual

get input data

Will throw an exception if it wasn't set first

Implements stir::Reconstruction< TargetT >.

References stir::error(), and get_input_data().

Referenced by get_initial_data_ptr(), and get_input_data().

◆ set_up()

template<typename TargetT>

Succeeded stir::IterativeReconstruction< TargetT >::set_up ( shared_ptr< TargetT > const & target_data_sptr )

overridevirtual

operations prior to the reconstruction

Will do various consistency checks and return Succeeded::no if something is wrong.

Todo: Currently, set_up() is called by reconstruct(). This is in contrast with some other class hierarchies in STIR where set_up() has to be called before any actual processing. Maybe this should be made consistent.

Reimplemented from stir::Reconstruction< TargetT >.

Reimplemented in stir::OSMAPOSLReconstruction< TargetT >, and stir::OSSPSReconstruction< TargetT >.

References stir::error(), inter_iteration_filter_interval, inter_iteration_filter_ptr, num_subiterations, num_subsets, randomise_subset_order, save_interval, set_up(), stir::Reconstruction< TargetT >::set_up(), start_subiteration_num, start_subset_num, stir::Reconstruction< TargetT >::target_data_sptr, terminate_iterations, and stir::warning().

Referenced by reconstruct(), reconstruct(), set_up(), stir::OSMAPOSLReconstruction< TargetT >::set_up(), and stir::OSSPSReconstruction< TargetT >::set_up().

◆ update_estimate()

template<class TargetT>

virtual void stir::IterativeReconstruction< TargetT >::update_estimate ( TargetT & current_estimate )

pure virtual

the principal operations for updating the data iterates at each iteration

Implemented in stir::OSMAPOSLReconstruction< TargetT >, and stir::OSSPSReconstruction< TargetT >.

References end_of_iteration_processing().

Referenced by reconstruct().

◆ end_of_iteration_processing()

template<typename TargetT>

void stir::IterativeReconstruction< TargetT >::end_of_iteration_processing ( TargetT & current_estimate )

protectedvirtual

operations for the end of the iteration

At specific subiteration numbers, this

applies the inter-filtering and/or post-filtering data processor,
writes the current data to file at the designated subiteration numbers (including the final one). Filenames used are determined by Reconstruction::output_filename_prefix,
writes the objective function values (using GeneralisedObjectiveFunction::report_objective_function_values) to stderr.

If your derived class redefines this virtual function, you will probably want to call IterativeReconstruction::end_of_iteration_processing() in there anyway.

References stir::Reconstruction< TargetT >::_disable_output, end_of_iteration_processing(), stir::info(), inter_iteration_filter_interval, inter_iteration_filter_ptr, make_filename_prefix_subiteration_num(), stir::Reconstruction< TargetT >::method_info(), num_subiterations, stir::Reconstruction< TargetT >::output_file_format_ptr, stir::Reconstruction< TargetT >::post_filter_sptr, report_objective_function_values_interval, save_interval, and subiteration_num.

Referenced by end_of_iteration_processing(), reconstruct(), and update_estimate().

◆ ask_parameters()

template<typename TargetT>

void stir::IterativeReconstruction< TargetT >::ask_parameters ( )

protectedvirtual

prompts the user to enter parameter values manually

Reimplemented in stir::KOSMAPOSLReconstruction< TargetT >, stir::OSMAPOSLReconstruction< TargetT >, and stir::OSSPSReconstruction< TargetT >.

References stir::ask(), stir::ask_filename_with_extension(), stir::ask_num(), ask_parameters(), stir::ask_string(), initial_data_filename, inter_iteration_filter_interval, inter_iteration_filter_ptr, stir::RegisteredObject< DataProcessor< DataT > >::list_registered_names(), stir::max_filename_length, num_subiterations, num_subsets, randomise_subset_order, stir::RegisteredObject< DataProcessor< DataT > >::read_registered_object(), save_interval, start_subiteration_num, and start_subset_num.

Referenced by ask_parameters().

◆ set_defaults()

template<typename TargetT>

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

overrideprotectedvirtual

Set defaults before parsing.

Reimplemented from stir::ParsingObject.

Reimplemented in stir::KOSMAPOSLReconstruction< TargetT >, stir::OSMAPOSLReconstruction< TargetT >, and stir::OSSPSReconstruction< TargetT >.

References initial_data_filename, inter_iteration_filter_interval, inter_iteration_filter_ptr, max_num_full_iterations, num_subiterations, num_subsets, randomise_subset_order, report_objective_function_values_interval, save_interval, set_defaults(), stir::Reconstruction< TargetT >::set_defaults(), start_subiteration_num, and start_subset_num.

Referenced by set_defaults().

◆ initialise_keymap()

template<typename TargetT>

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

overrideprotectedvirtual

Initialise all keywords.

Reimplemented from stir::ParsingObject.

Reimplemented in stir::KOSMAPOSLReconstruction< TargetT >, stir::OSMAPOSLReconstruction< TargetT >, and stir::OSSPSReconstruction< TargetT >.

References initial_data_filename, initialise_keymap(), stir::Reconstruction< TargetT >::initialise_keymap(), inter_iteration_filter_interval, inter_iteration_filter_ptr, num_subiterations, num_subsets, randomise_subset_order, report_objective_function_values_interval, save_interval, start_subiteration_num, and start_subset_num.

Referenced by initialise_keymap().

◆ post_processing()

template<typename TargetT>

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

overrideprotectedvirtual

used to check acceptable parameter ranges, etc...

Reimplemented from stir::ParsingObject.

Reimplemented in stir::KOSMAPOSLReconstruction< TargetT >, stir::OSMAPOSLReconstruction< TargetT >, and stir::OSSPSReconstruction< TargetT >.

References initial_data_filename, post_processing(), stir::Reconstruction< TargetT >::post_processing(), and stir::warning().

Referenced by post_processing().

Member Data Documentation

◆ report_objective_function_values_interval

template<class TargetT>

int stir::IterativeReconstruction< TargetT >::report_objective_function_values_interval

protected

subiteration interval at which to report the values of the objective function

Warning: This is generally time-consuming.

Referenced by end_of_iteration_processing(), get_report_objective_function_values_interval(), initialise_keymap(), set_defaults(), and set_report_objective_function_values_interval().

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

/home/kris/devel/STIRdistrib/STIR/src/include/stir/recon_buildblock/IterativeReconstruction.h
/home/kris/devel/STIRdistrib/STIR/src/recon_buildblock/IterativeReconstruction.cxx

Public Member Functions

Functions to set parameters

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ get_subset_num()

◆ get_initial_data_ptr()

◆ reconstruct() [1/2]

◆ reconstruct() [2/2]

◆ make_filename_prefix_subiteration_num() [1/2]

◆ make_filename_prefix_subiteration_num() [2/2]

◆ set_input_data()

◆ get_input_data()

◆ set_up()

◆ update_estimate()

◆ end_of_iteration_processing()

◆ ask_parameters()

◆ set_defaults()

◆ initialise_keymap()

◆ post_processing()

Member Data Documentation

◆ report_objective_function_values_interval