A BinNormalisation class that uses component-based normalisation for PET. More...

#include "stir/recon_buildblock/BinNormalisationPETFromComponents.h"

Inheritance diagram for stir::BinNormalisationPETFromComponents:

[legend]

Public Member Functions
std::string	get_registered_name () const override
	Returns the name of the type of the object.

	BinNormalisationPETFromComponents ()
	Default constructor.

bool	is_trivial () const override
	check if we would be multiplying with 1 (i.e. do nothing)

Succeeded	set_up (const shared_ptr< const ExamInfo > &exam_info_sptr, const shared_ptr< const ProjDataInfo > &) override
	Checks if we can handle certain projection data.

void	apply (RelatedViewgrams< float > &viewgrams) const override
	Normalise some data.

void	undo (RelatedViewgrams< float > &viewgrams) const override
	Undo the normalisation of some data.

float	get_bin_efficiency (const Bin &bin) const override
	Return the 'efficiency' factor for a single bin.

void	allocate (shared_ptr< const ProjDataInfo >, bool do_eff, bool do_geo, bool do_block=false, bool do_symmetry_per_block=false)
	Allocate the relevant factors.

DetectorEfficiencies &	crystal_efficiencies ()

GeoData3D &	geometric_factors ()

BlockData3D &	block_factors ()

void	set_defaults () override
	Sets all factors to empty and flags that allocations need to be done.

void	apply (ProjData &, shared_ptr< DataSymmetriesForViewSegmentNumbers >=shared_ptr< DataSymmetriesForViewSegmentNumbers >()) const
	normalise some data

void	undo (ProjData &, shared_ptr< DataSymmetriesForViewSegmentNumbers >=shared_ptr< DataSymmetriesForViewSegmentNumbers >()) const
	undo the normalisation of some data

Public Member Functions inherited from stir::BinNormalisation
virtual float	get_calibration_factor () const

virtual bool	is_TOF_only_norm () const
	returns if the object can only handle TOF data

void	apply (ProjData &, shared_ptr< DataSymmetriesForViewSegmentNumbers >=shared_ptr< DataSymmetriesForViewSegmentNumbers >()) const
	normalise some data

void	undo (ProjData &, shared_ptr< DataSymmetriesForViewSegmentNumbers >=shared_ptr< DataSymmetriesForViewSegmentNumbers >()) const
	undo the normalisation of some data

void	set_exam_info_sptr (const shared_ptr< const ExamInfo > _exam_info_sptr)

shared_ptr< const ExamInfo >	get_exam_info_sptr () const

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 ()

Protected Attributes
DetectorEfficiencies	efficiencies

GeoData3D	geo_data

BlockData3D	block_data

Protected Attributes inherited from stir::BinNormalisation
bool	_already_set_up

shared_ptr< const ProjDataInfo >	proj_data_info_sptr

KeyParser	parser

checks if factors are initialised
bool	has_crystal_efficiencies () const

bool	has_geometric_factors () const

bool	has_block_factors () const

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

Protected Member Functions inherited from stir::BinNormalisation
virtual void	check (const ProjDataInfo &proj_data_info) const
	check if the argument is the same as what was used for set_up()

virtual void	check (const ExamInfo &exam_info) const

virtual void	initialise_keymap ()
	Initialise all keywords.

virtual bool	post_processing ()
	This will be called at the end of the 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< BinNormalisation >
static RegistryType &	registry ()
	Static function returning the registry.

Detailed Description

A BinNormalisation class that uses component-based normalisation for PET.

Components currently supported are crystal efficiencies, geometric factors (constrained by symmetry) and block data. The latter were introduced to cope with timing alignment issues between blocks, but are generally not recommended in the current estimation process (by ML_estimate_component_based_normalisation) as the model allows for too much freedom.

The detection efficiency of a crystal pair is modelled as

$\epsilon_i \epsilon_j g_{ij} B_{ij}$

with crystal indices, and $g_{ij}$ obtained from a GeoData3D object by using symmetries, and $B_{ij}$ from a BlockData3D object by finding which blocks the crystals belong to.

Symmetries for the geometric factors are described in
Niknejad, T., Tavernier, S., Varela, J. and Thielemans, K. Validation of 3D model-based maximum-likelihood estimation of normalisation factors for partial ring positron emission tomography. in 2016 IEEE Nuclear Science Symposium, Medical Imaging Conference and Room-Temperature Semiconductor Detector Workshop (NSS/MIC/RTSD) 1-5 (2016). doi:10.1109/NSSMIC.2016.8069577.
Note however that this describes rotational/translational symmetry per block, while the default is now to use symmetries per bucket ( see the do_symmetry_per_block argument of allocate()). (The block factors still work per block, not bucket).

This class does not actually set the relevant factors. That is left to external methods via the crystal_efficiencies(), geometric_factors() and block_factors() members. If they are not set, the factor is not applied (i.e. assumed to be 1).

The model is constructed for the "physical" crystals only. The "virtual" crystals are forced to have 0 detection efficiency.

Todo

This class should probably be derived from BinNormalisationWithCalibration.

The class currently does not handle "compressed" projection data (i.e. span etc).

Todo: Currently, set_up() creates a ProjDataInMemory object with the PET detection efficiencies. This uses a lot of memory unfortunately.

Constructor & Destructor Documentation

◆ BinNormalisationPETFromComponents()

stir::BinNormalisationPETFromComponents::BinNormalisationPETFromComponents ( )

Default constructor.

Warning: You should not call any member functions for any object just constructed with this constructor. Initialise the object properly first.

References BinNormalisationPETFromComponents(), and set_defaults().

Referenced by BinNormalisationPETFromComponents().

Member Function Documentation

◆ get_registered_name()

std::string stir::BinNormalisationPETFromComponents::get_registered_name ( ) const

inlineoverridevirtual

Returns the name of the type of the object.

Each type that can be parsed has a unique (within its hierarchy) name associated with it. This function returns that name. KeyParser::parameter_info() needs to know this name such that it can fill it in.

Implements stir::RegisteredObjectBase.

◆ is_trivial()

bool stir::BinNormalisationPETFromComponents::is_trivial ( ) const

overridevirtual

check if we would be multiplying with 1 (i.e. do nothing)

Checks if all data is equal to 1 (up to a tolerance of 1e-4). To do this, it checks if all components are 1.

Reimplemented from stir::BinNormalisation.

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

Referenced by is_trivial().

◆ set_up()

Succeeded stir::BinNormalisationPETFromComponents::set_up	(	const shared_ptr< const ExamInfo > &	exam_info_sptr,
		const shared_ptr< const ProjDataInfo > &	check_proj_data_info_sptr )

overridevirtual

Checks if we can handle certain projection data.

Compares the stored ProjDataInfo with the ProjDataInfo supplied.

Reimplemented from stir::BinNormalisation.

References stir::error(), stir::ProjDataInfo::get_max_axial_pos_num(), stir::ProjDataInfo::get_max_segment_num(), stir::ProjDataInfo::get_max_tangential_pos_num(), stir::ProjDataInfo::get_min_axial_pos_num(), stir::ProjDataInfo::get_min_segment_num(), stir::ProjDataInfo::get_min_tangential_pos_num(), stir::ProjDataInfo::parameter_info(), stir::BinNormalisation::set_up(), set_up(), and stir::warning().

Referenced by set_up().

◆ apply() [1/2]

void stir::BinNormalisationPETFromComponents::apply ( RelatedViewgrams< float > & viewgrams ) const

overridevirtual

Normalise some data.

This means divide with the efficiency model. 0/0 is set to 0.

Reimplemented from stir::BinNormalisation.

References apply(), stir::RelatedViewgrams< elemT >::begin(), stir::BinNormalisation::check(), stir::divide(), stir::RelatedViewgrams< elemT >::end(), stir::RelatedViewgrams< elemT >::get_basic_view_segment_num(), stir::DataWithProjDataInfo::get_proj_data_info_sptr(), and stir::RelatedViewgrams< elemT >::get_symmetries_ptr().

Referenced by apply().

◆ undo() [1/2]

void stir::BinNormalisationPETFromComponents::undo ( RelatedViewgrams< float > & viewgrams ) const

overridevirtual

Undo the normalisation of some data.

This means multiply with the efficiency model.

Reimplemented from stir::BinNormalisation.

References stir::BinNormalisation::check(), stir::RelatedViewgrams< elemT >::get_basic_view_segment_num(), stir::DataWithProjDataInfo::get_proj_data_info_sptr(), stir::RelatedViewgrams< elemT >::get_symmetries_ptr(), and undo().

Referenced by undo().

◆ get_bin_efficiency()

float stir::BinNormalisationPETFromComponents::get_bin_efficiency ( const Bin & bin ) const

overridevirtual

Return the 'efficiency' factor for a single bin.

With the notation of the class documentation, this returns the factor $\mathrm{norm}_b$ .

Warning: Some derived classes might implement this very inefficiently.

Implements stir::BinNormalisation.

References get_bin_efficiency().

Referenced by get_bin_efficiency().

◆ allocate()

void stir::BinNormalisationPETFromComponents::allocate	(	shared_ptr< const ProjDataInfo >	pdi_sptr,
		bool	do_eff,
		bool	do_geo,
		bool	do_block = false,
		bool	do_symmetry_per_block = false )

Allocate the relevant factors.

They are currently probably set to 0, but do not rely on this.

References allocate().

Referenced by allocate().

◆ set_defaults()

void stir::BinNormalisationPETFromComponents::set_defaults ( )

overridevirtual

Sets all factors to empty and flags that allocations need to be done.

Also calls base_type::set_defaults()

Reimplemented from stir::BinNormalisation.

References stir::BinNormalisation::set_defaults(), and set_defaults().

Referenced by BinNormalisationPETFromComponents(), and set_defaults().

◆ apply() [2/2]

void stir::BinNormalisation::apply	(	ProjData &	proj_data,
		shared_ptr< DataSymmetriesForViewSegmentNumbers >	symmetries_sptr = shared_ptr<DataSymmetriesForViewSegmentNumbers>() ) const

normalise some data

This would be used for instance to precorrect unnormalised data. With the notation of the class documentation, this would divide by the factors $\mathrm{norm}_b$ .

This just loops over all RelatedViewgrams.

The default value for the symmetries means that TrivialDataSymmetriesForBins will be used.

◆ undo() [2/2]

void stir::BinNormalisation::undo	(	ProjData &	proj_data,
		shared_ptr< DataSymmetriesForViewSegmentNumbers >	symmetries_sptr = shared_ptr<DataSymmetriesForViewSegmentNumbers>() ) const

undo the normalisation of some data

This would be used for instance to bring geometrically forward projected data to the mean of the measured data. With the notation of the class documentation, this would multiply by the factors $\mathrm{norm}_b$ .

This just loops over all RelatedViewgrams.

The default value for the symmetries means that TrivialDataSymmetriesForBins will be used.

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

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

Public Member Functions

Protected Attributes

checks if factors are initialised

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BinNormalisationPETFromComponents()

Member Function Documentation

◆ get_registered_name()

◆ is_trivial()

◆ set_up()

◆ apply() [1/2]

◆ undo() [1/2]

◆ get_bin_efficiency()

◆ allocate()

◆ set_defaults()

◆ apply() [2/2]

◆ undo() [2/2]