This class is used to bin listmode data to projection data, i.e. (3d) sinograms. More...

#include "stir/listmode/LmToProjData.h"

Inheritance diagram for stir::LmToProjData:

[legend]

Public Member Functions
	LmToProjData (const char *const par_filename)
	Constructor taking a filename for a parameter file.

	LmToProjData ()
	Default constructor.

Public Member Functions inherited from stir::LmToProjDataAbstract
	~LmToProjDataAbstract () override
	Destructor.

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 Member Functions
parsing 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.

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

Protected Attributes
parsing variables
std::string	input_filename

std::string	output_filename_prefix

std::string	template_proj_data_name

std::string	frame_definition_filename
	frame definitions

bool	do_pre_normalisation

bool	store_prompts

bool	store_delayeds

int	num_segments_in_memory

int	num_timing_poss_in_memory

long int	num_events_to_store

int	max_segment_num_to_process

bool	interactive
	Toggle readable output on stdout or actual projdata.

shared_ptr< ProjDataInfo >	template_proj_data_info_ptr

shared_ptr< BinNormalisation >	normalisation_ptr
	This will be used for pre-normalisation.

shared_ptr< BinNormalisation >	post_normalisation_ptr
	This will be used for post-normalisation.

shared_ptr< ProjData >	output_proj_data_sptr
	This will be used to return the output directly, if set.

shared_ptr< ListModeData >	lm_data_ptr
	Pointer to the actual data.

TimeFrameDefinitions	frame_defs
	Time frames.

double	current_time
	stores the time (in secs) recorded in the previous timing event

unsigned int	current_frame_num
	stores the current frame number

shared_ptr< const ProjDataInfo >	proj_data_info_cyl_uncompressed_ptr
	Internal variable that will be used for pre-normalisation.

bool	do_time_frame
	variable that will be set according to if we are using time frames or num_events_to_store

int	delayed_increment
	A variable that will be set to 1,0 or -1, according to store_prompts and store_delayeds.

bool	_already_setup
	an internal bool variable to check if the object has been set-up or not

KeyParser	parser

Functions to get/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_template_proj_data_info_sptr (shared_ptr< const ProjDataInfo >)
	Optional `proj` data_info to use as "template".

shared_ptr< const ProjDataInfo >	get_template_proj_data_info_sptr () const
	Get the current template.

virtual void	set_input_data (const shared_ptr< ExamData > &)
	set input data

virtual void	set_input_data (const std::string &filename)
	set input data

void	set_output_filename_prefix (const std::string &)

std::string	get_output_filename_prefix () const

void	set_output_projdata_sptr (shared_ptr< ProjData > &)
	set projdata to be filled with output

void	set_store_prompts (bool)

bool	get_store_prompts () const

void	set_store_delayeds (bool)

bool	get_store_delayeds () const

double	get_last_processed_lm_rel_time () const
	Returns the last processed timestamp in the listmode file.

void	set_num_segments_in_memory (int)

int	get_num_segments_in_memory () const

void	set_num_events_to_store (long int)

long int	get_num_events_to_store () const

void	set_time_frame_definitions (const TimeFrameDefinitions &)

const TimeFrameDefinitions &	get_time_frame_definitions () const

virtual Succeeded	set_up () override
	Perform various checks.

virtual void	process_data () override
	This function does the actual work.

virtual void	start_new_time_frame (const unsigned int new_frame_num)
	will be called when a new time frame starts

virtual void	process_new_time_event (const ListTime &)
	will be called after a new timing event is found in the file

virtual void	get_bin_from_event (Bin &bin, const ListEvent &) const
	will be called to get the bin for a coincidence event

int	get_compression_count (const Bin &bin) const
	A function that should return the number of uncompressed bins in the current bin.

void	do_post_normalisation (Bin &bin) const
	Computes a post-normalisation factor (if any) for this bin.

Detailed Description

This class is used to bin listmode data to projection data, i.e. (3d) sinograms.

It provides the basic machinery to go through a list mode data file, and write projection data for each time frame.

The class can parse its parameters from an input file. This has the following format:

lm_to_projdata Parameters:=

input file := some_lm_file
output filename prefix := my_favorite_name_for_the_projdata

; parameters that determine the sizes etc of the output

  ; Optional projection data to use as "template", i.e. the output
  ; will have the same size.
  ; If none is specified, we will use the proj_data_info from the input list-mode.
  ; Warning: for some scanners with TOF capabilities, this will result in very
  ; large projection data (possibly larger than the default from the vendor).
  template_projdata := some_projdata_file
  ; the next can be used to use a smaller number of segments than given
  ; in the template
  maximum absolute segment number to process :=

; parameters for saying which events will be stored

  ; time frames (see TimeFrameDefinitions doc for format)
  frame_definition file := frames.fdef
  ; or a total number of events (if  larger than 0, frame definitions will be ignored)
  ; note that this normally counts the total of prompts-delayeds (see below)
  num_events_to_store := -1

; parameters relating to prompts and delayeds

  ; with the default values, prompts will be added and delayed subtracted
  ; to give the usual estimate of the trues.

  ; store the prompts (value should be 1 or 0)
  store prompts := 1  ;default
  ; what to do if it's a delayed event
  store delayeds := 1  ;default


; parameters related to normalisation
; default settings mean no normalisation
; Use with care!

  ; in pre normalisation, each event will contribute its
  ; 'normalisation factor' to the bin
  ; in post normalisation, an average factor for the bin will be used
  do pre normalisation  := 0 ; default is 0
  ; type of pre-normalisation (see BinNormalisation doc)
  Bin Normalisation type for pre-normalisation := None ; default
  ; type of post-normalisation (see BinNormalisation doc)
  Bin Normalisation type for post-normalisation := None ; default

; miscellaneous parameters

  ; list each event on stdout and do not store any files (use only for testing!)
  ; has to be 0 or 1
  List event coordinates := 0

  ; if you're short of RAM (i.e. a single projdata does not fit into memory),
  ; you can use this to process the list mode data in multiple passes.
  num_segments_in_memory := -1
  ; same for TOF bins
  num_TOF_bins_in_memory := 1
End :=

Hopefully the only thing that needs explaining are the parameters related to prompts and delayeds. These are used to allow different ways of processing the data. There are really only 3 useful cases:

'online' subtraction of delayeds
This is the default, and adds prompts but subtracts delayeds.
store prompts := 1

store delayeds := 1
store prompts only
Use
store prompts := 1

store delayeds := 0
store delayeds only
Use
store prompts := 0

store delayeds := 1

Note that now the delayed events will be added, not subtracted.

Notes for developers

The class provides several virtual functions. If a derived class overloads these, the default behaviour might change. For example, get_bin_from_event() might do motion correction.

Todo

Currently, there is no support for gating or energy windows. This could in principle be added by a derived class, but it would be better to do it here.

Timing info or so for get_bin_from_event() for rotating scanners etc.

There is overlap between the normalisation and the current treatment of bin.get_bin_value(). This is really because we should be using something like a EventNormalisation class for pre-normalisation.

See also: ListModeData for more info on list mode data.

Constructor & Destructor Documentation

◆ LmToProjData() [1/2]

stir::LmToProjData::LmToProjData ( const char *const par_filename )

Constructor taking a filename for a parameter file.

Will attempt to open and parse the file.

References stir::error(), LmToProjData(), and set_defaults().

Referenced by LmToProjData(), and LmToProjData().

◆ LmToProjData() [2/2]

stir::LmToProjData::LmToProjData ( )

Default constructor.

Warning: leaves parameters ill-defined. Set them by parsing.

References LmToProjData(), and set_defaults().

Member Function Documentation

◆ set_template_proj_data_info_sptr()

void stir::LmToProjData::set_template_proj_data_info_sptr ( shared_ptr< const ProjDataInfo > t_sptr )

Optional proj data_info to use as "template".

Use this to specify the output output proj_data_info, i.e. the output will have the same size.

If not set, or when setting it explicitly to 0, the proj_data_info from the input list-mode will be used.

Warning: for some scanners with TOF capabilities, this will result in large projection data (possibly larger than the default from the vendor).

References _already_setup, and set_template_proj_data_info_sptr().

Referenced by post_processing(), set_template_proj_data_info_sptr(), and set_up().

◆ get_template_proj_data_info_sptr()

shared_ptr< const ProjDataInfo > stir::LmToProjData::get_template_proj_data_info_sptr ( ) const

Get the current template.

See also: set_template_proj_data_info_sptr()

Warning: the return value can be the null pointer.

References get_template_proj_data_info_sptr().

Referenced by get_template_proj_data_info_sptr().

◆ set_input_data() [1/2]

void stir::LmToProjData::set_input_data ( const shared_ptr< ExamData > & v )

virtual

set input data

will throw of the input data is not of type ListModeData

References _already_setup, stir::error(), lm_data_ptr, set_input_data(), and stir::warning().

Referenced by post_processing(), set_input_data(), and set_input_data().

◆ set_input_data() [2/2]

void stir::LmToProjData::set_input_data ( const std::string & filename )

virtual

set input data

will throw of the input data is not of type ListModeData

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

◆ set_output_projdata_sptr()

void stir::LmToProjData::set_output_projdata_sptr ( shared_ptr< ProjData > & arg )

set projdata to be filled with output

will only store data from the last defined time frame!

References output_proj_data_sptr, and set_output_projdata_sptr().

Referenced by set_output_projdata_sptr().

◆ get_last_processed_lm_rel_time()

double stir::LmToProjData::get_last_processed_lm_rel_time ( ) const

Returns the last processed timestamp in the listmode file.

This can be used to find the duration (in seconds) of the last time frame processed.

References current_time, and get_last_processed_lm_rel_time().

Referenced by get_last_processed_lm_rel_time().

◆ set_up()

Succeeded stir::LmToProjData::set_up ( )

overridevirtual

Perform various checks.

Will likely call error() if there is a problem.

Reimplemented from stir::LmToProjDataAbstract.

Reimplemented in stir::LmToProjDataWithMC.

References _already_setup, delayed_increment, do_time_frame, stir::error(), frame_definition_filename, frame_defs, stir::info(), interactive, lm_data_ptr, normalisation_ptr, post_normalisation_ptr, proj_data_info_cyl_uncompressed_ptr, stir::ProjDataInfo::ProjDataInfoCTI(), set_template_proj_data_info_sptr(), set_up(), and stir::warning().

Referenced by post_processing(), and set_up().

◆ process_data()

void stir::LmToProjData::process_data ( )

overridevirtual

This function does the actual work.

You need to call set_up() first.

Implements stir::LmToProjDataAbstract.

References _already_setup, stir::Bin::axial_pos_num(), current_frame_num, current_time, delayed_increment, do_post_normalisation(), do_time_frame, stir::error(), frame_defs, get_bin_from_event(), stir::Bin::get_bin_value(), stir::VectorWithOffset< T >::get_max_index(), stir::VectorWithOffset< T >::get_min_index(), stir::Scanner::get_name(), interactive, stir::ListEvent::is_valid_template(), lm_data_ptr, output_proj_data_sptr, stir::Scanner::parameter_info(), process_data(), process_new_time_event(), stir::VectorWithOffset< T >::resize(), stir::SegmentIndices::segment_num(), stir::Bin::set_bin_value(), stir::Timer::start(), start_new_time_frame(), stir::Timer::stop(), stir::Bin::tangential_pos_num(), stir::Bin::time_frame_num(), stir::SegmentIndices::timing_pos_num(), stir::Timer::value(), stir::ViewgramIndices::view_num(), and stir::warning().

Referenced by process_data().

◆ start_new_time_frame()

void stir::LmToProjData::start_new_time_frame ( const unsigned int new_frame_num )

protectedvirtual

will be called when a new time frame starts

The frame numbers start from 1.

Reimplemented in stir::LmToProjDataWithMC.

References start_new_time_frame().

Referenced by process_data(), start_new_time_frame(), and stir::LmToProjDataWithMC::start_new_time_frame().

◆ process_new_time_event()

void stir::LmToProjData::process_new_time_event ( const ListTime & )

protectedvirtual

will be called after a new timing event is found in the file

Reimplemented in stir::LmToProjDataWithMC.

References process_new_time_event().

Referenced by process_data(), and process_new_time_event().

◆ get_bin_from_event()

void stir::LmToProjData::get_bin_from_event	(	Bin &	bin,
		const ListEvent &	event ) const

protectedvirtual

will be called to get the bin for a coincidence event

If bin.get_bin_value()<=0, the event will be ignored. Otherwise, the value will be used as a bin-normalisation factor (on top of anything done by normalisation_ptr).