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:

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

	LmToProjData ()
	Default constructor. More...

virtual Succeeded	set_up () override
	Perform various checks. More...

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

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

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

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

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

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

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

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

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

Public Member Functions inherited from stir::ParsingObject
	ParsingObject (const ParsingObject &)

ParsingObject &	operator= (const ParsingObject &)

void	ask_parameters ()

virtual std::string	parameter_info ()

bool	parse (std::istream &f)

bool	parse (const char *const filename)

Protected Member Functions
virtual void	start_new_time_frame (const unsigned int new_frame_num)
	will be called when a new time frame starts More...

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

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

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

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

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

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

parsing variables
std::string	input_filename

std::string	output_filename_prefix

std::string	template_proj_data_name

std::string	frame_definition_filename
	frame definitions More...

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

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.

Protected Attributes inherited from stir::ParsingObject
KeyParser	parser

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() [2/2]

stir::LmToProjData::LmToProjData ( )

Default constructor.

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

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

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

◆ 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

◆ 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

◆ 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!

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

◆ 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 stir::error().

◆ process_data()

void stir::LmToProjData::process_data ( )

overridevirtual

This function does the actual work.

You need to call set_up() first.

Implements stir::LmToProjDataAbstract.

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

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

Todo:: Would need timing info or so for e.g. time dependent normalisation or angle info for a rotating scanner.

References stir::Bin::axial_pos_num(), stir::Bin::get_bin_value(), stir::SegmentIndices::segment_num(), stir::Bin::set_bin_value(), stir::Bin::tangential_pos_num(), stir::ViewgramIndices::view_num(), and stir::warning().

◆ get_compression_count()

int stir::LmToProjData::get_compression_count ( const Bin & bin ) const

protected

A function that should return the number of uncompressed bins in the current bin.

Todo:: it is not compatiable with e.g. HiDAC doesn't belong here anyway (more ProjDataInfo?)

References stir::Bin::axial_pos_num(), stir::ProjDataInfoCylindrical::get_num_ring_pairs_for_segment_axial_pos_num(), stir::ProjDataInfoCylindrical::get_view_mashing_factor(), and stir::SegmentIndices::segment_num().

◆ do_post_normalisation()

void stir::LmToProjData::do_post_normalisation ( Bin & bin ) const

protected

Computes a post-normalisation factor (if any) for this bin.

This uses get_compression_count() when do_pre_normalisation=true, or post_normalisation_ptr otherwise.

References stir::Bin::axial_pos_num(), stir::Bin::get_bin_value(), stir::SegmentIndices::segment_num(), stir::Bin::set_bin_value(), stir::Bin::tangential_pos_num(), stir::ViewgramIndices::view_num(), and stir::warning().

◆ post_processing()

bool stir::LmToProjData::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.

Reimplemented in stir::LmToProjDataWithMC.

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

Member Data Documentation

◆ frame_definition_filename

std::string stir::LmToProjData::frame_definition_filename

protected

frame definitions

Will be read using TimeFrameDefinitions

◆ interactive

bool stir::LmToProjData::interactive

protected

Toggle readable output on stdout or actual projdata.

corresponds to key "list event coordinates"

◆ current_frame_num

unsigned int stir::LmToProjData::current_frame_num

protected

stores the current frame number

The frame numbers start from 1.

◆ proj_data_info_cyl_uncompressed_ptr

shared_ptr<const ProjDataInfo> stir::LmToProjData::proj_data_info_cyl_uncompressed_ptr

protected

Internal variable that will be used for pre-normalisation.

Will be removed when we have EventNormalisation (or similar) hierarchy

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

/home/sirfuser/devel/STIRdistrib/STIR/src/include/stir/listmode/LmToProjData.h
/home/sirfuser/devel/STIRdistrib/STIR/src/listmode_buildblock/LmToProjData.cxx

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ LmToProjData() [1/2]

◆ LmToProjData() [2/2]

Member Function Documentation

◆ set_template_proj_data_info_sptr()

◆ get_template_proj_data_info_sptr()

◆ set_input_data() [1/2]

◆ set_input_data() [2/2]

◆ set_output_projdata_sptr()

◆ get_last_processed_lm_rel_time()

◆ set_up()

◆ process_data()

◆ start_new_time_frame()

◆ get_bin_from_event()

◆ get_compression_count()

◆ do_post_normalisation()

◆ post_processing()

Member Data Documentation

◆ frame_definition_filename

◆ interactive

◆ current_frame_num

◆ proj_data_info_cyl_uncompressed_ptr