A reconstructor class appropriate for emission data. More...

#include "stir/KOSMAPOSL/KOSMAPOSLReconstruction.h"

Inheritance diagram for stir::KOSMAPOSLReconstruction< TargetT >:

[legend]

Public Member Functions
	KOSMAPOSLReconstruction ()
	Default constructor (calling set_defaults())

	KOSMAPOSLReconstruction (const std::string &parameter_filename)
	Constructor, initialises everything from parameter file, or (when parameter_filename == "") by calling ask_parameters().

KOSMAPOSLReconstruction &	get_parameters ()
	accessor for the external parameters

const KOSMAPOSLReconstruction &	get_parameters () const
	accessor for the external parameters

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


const std::vector< std::string >	get_anatomical_image_filenames () const

const int	get_num_neighbours () const

const int	get_num_non_zero_feat () const

const std::vector< double >	get_sigma_m () const

const double	get_sigma_p () const

const double	get_sigma_dp () const

const double	get_sigma_dm () const

const bool	get_only_2D () const

const bool	get_hybrid () const

const int	get_freeze_iterative_kernel_at_subiter_num () const

std::vector< shared_ptr< TargetT > >	get_anatomical_prior_sptrs ()

Functions to set parameters
This can be used as alternative to the parsing mechanism. Warning Be careful with setting shared pointers. If you modify the objects in one place, all objects that use the shared pointer will be affected.
void	set_anatomical_prior_sptr (shared_ptr< TargetT >, int index)

void	set_anatomical_prior_sptr (shared_ptr< TargetT > arg)
	sets the vector of anatomical priors to a single value

void	set_anatomical_image_filename (const std::string &, const int index)

void	set_anatomical_image_filename (const std::string &)

void	set_num_neighbours (const int)

void	set_num_non_zero_feat (const int)

void	set_sigma_m (const double, const int index)

void	set_sigma_m (const double)
	sets all elements of vector sigma_m to the same value

void	set_sigma_p (const double)

void	set_sigma_dp (const double)

void	set_sigma_dm (const double)

void	set_only_2D (const bool)

void	set_hybrid (const bool)

void	set_freeze_iterative_kernel_at_subiter_num (const int)

Public Member Functions inherited from stir::RegisteredParsingObject< KOSMAPOSLReconstruction< TargetT >, Reconstruction< TargetT >, OSMAPOSLReconstruction< 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::OSMAPOSLReconstruction< TargetT >
	OSMAPOSLReconstruction ()
	Default constructor (calling set_defaults())

	OSMAPOSLReconstruction (const std::string &parameter_filename)
	Constructor, initialises everything from parameter file, or (when parameter_filename == "") by calling ask_parameters().

OSMAPOSLReconstruction &	get_parameters ()
	accessor for the external parameters

const OSMAPOSLReconstruction &	get_parameters () const
	accessor for the external parameters

std::string	method_info () const override
	gives method information

PoissonLogLikelihoodWithLinearModelForMean< TargetT > const &	get_objective_function () const
	Return current objective function.

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

Succeeded	set_up (shared_ptr< TargetT > const &target_image_ptr) override
	operations prior to the iterations

void	update_estimate (TargetT &current_image_estimate) override
	the principal operations for updating the image iterates at each iteration

void	set_inter_update_filter_interval (const int)
	subiteration interval at which to apply inter-update filters

void	set_inter_update_filter_ptr (const shared_ptr< DataProcessor< TargetT >> &)
	inter-update filter object

void	set_maximum_relative_change (const double)
	restrict updates (larger relative updates will be thresholded)

void	set_minimum_relative_change (const double)
	restrict updates (smaller relative updates will be thresholded)

void	set_enforce_initial_positivity (const bool)

void	set_write_update_image (const int)
	boolean value to determine if the update images have to be written to disk

void	set_MAP_model (const std::string &)
	should be either additive or multiplicative

Public Member Functions inherited from stir::IterativeReconstruction< TargetT >
int	get_subiteration_num () const
	accessor for the subiteration counter

int	get_subset_num ()
	accessor for finding the current subset number More...

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

Succeeded	reconstruct () override
	executes the reconstruction More...

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

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

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

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

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

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

const ExamData &	get_input_data () const override
	get input data More...

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

	~Reconstruction () override
	virtual destructor

void	set_disable_output (bool _val)
	set_disable_output More...

shared_ptr< TargetT >	get_target_image ()
	get_reconstructed_image More...

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

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)

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

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

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)

Static Public Attributes
static const char *const	registered_name = "KOSMAPOSL"
	Name which will be used when parsing a KOSMAPOSLReconstruction object.

Static Public Attributes inherited from stir::OSMAPOSLReconstruction< TargetT >
static const char *const	registered_name = "OSMAPOSL"
	Name which will be used when parsing a OSMAPOSLReconstruction object.

Protected Member Functions
void	set_defaults () override
	Set defaults before parsing.

void	initialise_keymap () override
	Initialise all keywords.

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

void	compute_kernelised_image (TargetT &kernelised_image_out, const TargetT &image_to_kernelise, const TargetT &current_alpha_estimate)
	Function that applies the kernel to the image_to_kernelise.

Protected Member Functions inherited from stir::OSMAPOSLReconstruction< TargetT >
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...

virtual void	compute_sub_gradient_without_penalty_plus_sensitivity (TargetT &gradient, const TargetT &current_estimate, const int subset_num)

virtual const TargetT &	get_subset_sensitivity (const int subset_num)

virtual void	apply_multiplicative_update (TargetT &current_image_estimate, const TargetT &multiplicative_update_image)

Protected Member Functions inherited from stir::IterativeReconstruction< TargetT >
virtual void	end_of_iteration_processing (TargetT &current_estimate)
	operations for the end of the iteration More...

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

Protected Member Functions inherited from stir::Reconstruction< TargetT >
virtual void	check (TargetT const &target_data) const
	do consistency checks More...

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

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 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
std::string	input_filename
	Filename with input projection data.

std::string	kernelised_output_filename_prefix

std::string	current_kimage_filename

std::string	sens_filenames

std::vector< std::string >	anatomical_image_filenames
	Anatomical image filename.

std::vector< shared_ptr< TargetT > >	anatomical_prior_sptrs

std::vector< shared_ptr< TargetT > >	kmnorm_sptrs

shared_ptr< TargetT >	kpnorm_sptr

int	num_neighbours

int	num_non_zero_feat

int	num_elem_neighbourhood

int	num_voxels

int	dimz

int	dimy

int	dimx

int	freeze_iterative_kernel_at_subiter_num

std::vector< double >	sigma_m

bool	only_2D

bool	hybrid

double	sigma_p

double	sigma_dp

double	sigma_dm

BasicCoordinate< 3, int >	min_ind

BasicCoordinate< 3, int >	max_ind

shared_ptr< TargetT >	iterative_kernel_image_frozen_sptr

Protected Attributes inherited from stir::OSMAPOSLReconstruction< TargetT >
bool	enforce_initial_positivity
	operations prior to the iterations More...

bool	do_rim_truncation
	determines wether voxels outside a circular FOV will be set to 0 or not More...

int	inter_update_filter_interval
	subiteration interval at which to apply inter-update filters

shared_ptr< DataProcessor< TargetT > >	inter_update_filter_ptr
	inter-update filter object

double	maximum_relative_change
	restrict updates (larger relative updates will be thresholded)

double	minimum_relative_change
	restrict updates (smaller relative updates will be thresholded)

int	write_update_image
	boolean value to determine if the update images have to be written to disk

std::string	MAP_model
	should be either additive or multiplicative

Protected Attributes inherited from stir::IterativeReconstruction< TargetT >
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 More...

Protected Attributes inherited from stir::Reconstruction< TargetT >
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 More...

int	_verbosity
	Verbosity level.

Protected Attributes inherited from stir::ParsingObject
KeyParser	parser

Friends
void	do_sensitivity (const char *const par_filename)

Additional Inherited Members
Static Public Member Functions inherited from stir::RegisteredParsingObject< KOSMAPOSLReconstruction< TargetT >, Reconstruction< TargetT >, OSMAPOSLReconstruction< TargetT > >
static Reconstruction< 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::RegisteredParsingObject< OSMAPOSLReconstruction< TargetT >, Reconstruction< TargetT >, IterativeReconstruction< TargetT > >
static Reconstruction< 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< 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. More...

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

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

Detailed Description

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

A reconstructor class appropriate for emission data.

This class implements the iterative algorithm obtained using the Kernel method (KEM) and Hybrid kernel method (HKEM). This implementation corresponds to the one presented by Deidda D et al, "Hybrid PET-MR list-mode kernelized expectation maximization reconstruction", Inverse Problems, 2019, DOI: https://doi.org/10.1088/1361-6420/ab013f. However, this allows also sinogram-based reconstruction. Furtermore, it is possible to use multiple side information images (they can be anatomical images or images from different modalities). This extension is called multiplexing-HKEM and is described in Deidda et al. "Multiplexing Kernelized Expectation Maximization Reconstruction for PET-MR." IEEE NSS/MIC Proceedings (NSS/MIC) 2018, DOI: https://doi.org/10.1109/NSSMIC.2018.8824312. Each voxel value of the image, $\boldsymbol{\lambda}$ , can be represented as a linear combination using the kernel method. If we have an image with prior information, we can construct for each voxel $ j $ of the emission image a feature vector, $\boldsymbol{v}_j$ , using the prior information. The voxel value, $\lambda_j$ , can then be described using the kernel matrix

$\lambda_j= \sum_{l=1}^L \alpha_l k_{jl}$

where $k_{jl}$ is the $jl^{th}$ kernel element of the matrix, $\boldsymbol{K}$ . The resulting algorithm with OSEM, for example, is the following:

$\alpha^{(n+1)}_j = \frac{ \alpha^{(n)}_j }{\sum_{m} k^{(n)}_{jm} \sum_i p_{mi}} \sum_{m}k^{(n)}_{jm}\sum_i p_{mi}\frac{ y_i }{\sum_{q} p_{iq} \sum_l k^{(n)}_{ql}\alpha^{(n)}_l + s_i}$

where the element, $ jl $ , of the kernel can be written as:

$k^{(n)}_{jl} = k_m(\boldsymbol{v}_j,\boldsymbol{v}_l) \cdot k_p(\boldsymbol{z}^{(n)}_j,\boldsymbol{z}^{(n)}_l);$

with

$k_m(\boldsymbol{v}_j,\boldsymbol{v}_l) = \exp \left(\tiny - \frac{\| \boldsymbol{v}_j-\boldsymbol{v}_l \|^2}{2 \sigma_m^2} \right) \exp \left(- \frac{\tiny \| \boldsymbol{x}_j-\boldsymbol{x}_l \|^2}{ \tiny 2 \sigma_{dm}^2} \right)$

being the MR component of the kernel and

$k_p(\boldsymbol{z}^{(n)}_j,\boldsymbol{z}^{(n)}_l) = \exp \left(\tiny - \frac{\| \boldsymbol{z}^{(n)}_j-\boldsymbol{z}^{(n)}_l \|^2}{2 \sigma_p^2} \right) \exp \left(\tiny - \frac{\| \boldsymbol{x}_j-\boldsymbol{x}_l \|^2}{ \tiny{2 \sigma_{dp}^2}} \right)$

is the part coming from the emission iterative update. Here, the Gaussian kernel functions have been modulated by the distance between voxels in the image space.

Parameters for parsing

Defaults are indicated below

KOSMAPOSL Parameters:=

kernelised_output_filename_prefix:= ; filename for the KOSMAPOSL estimates
hybrid:=1 ; defaults to 0
sigma m:= {} ; needs to be a list of the same size as 'anatomical image filename'
sigma p:=1
sigma dm:=1
sigma dp:=1
number of neighbours:= 3                   ;is the cubic root of the number of voxels in the neighbourhood;
anatomical image filenames:={}             ;a list of filenames of the anatomical images;
number of non-zero feature elements:=1     ;is the number of non zero elements in the feature vector.
                                           ;This makes you choose the size of your feature vector by default we only have one
element;

only_2D:=0                                 ;=1 if you want to reconstruct 2D images;

; other OSMAPOSL parameters
End KOSMAPOSL Parameters :=

Member Function Documentation

◆ post_processing()

template<typename TargetT >

bool stir::KOSMAPOSLReconstruction< TargetT >::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 stir::error(), and stir::info().

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

/home/sirfuser/devel/STIRdistrib/STIR/src/include/stir/KOSMAPOSL/KOSMAPOSLReconstruction.h
/home/sirfuser/devel/STIRdistrib/STIR/src/iterative/KOSMAPOSL/KOSMAPOSLReconstruction.cxx

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

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

Member Function Documentation

◆ post_processing()

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