The base class for reading list mode data. More...

#include "stir/listmode/ListModeData.h"

Inheritance diagram for stir::ListModeData:

[legend]

Public Types
typedef ListModeData	hierarchy_base_type
	typedef used by read_from_file

typedef unsigned int	SavedPosition
	Use this typedef for save/set_get_position.

Public Member Functions
	ListModeData ()
	Default constructor.

virtual std::string	get_name () const =0
	Returns the name of the list mode data. More...

shared_ptr< ListRecord >	get_empty_record_sptr () const
	Get a pointer to an empty record. More...

virtual Succeeded	get_next_record (ListRecord &event) const
	Gets the next record in the listmode sequence.

virtual Succeeded	reset ()=0
	Call this function if you want to re-start reading at the beginning.

virtual SavedPosition	save_get_position ()=0
	Save the current reading position. More...

virtual Succeeded	set_get_position (const SavedPosition &)=0
	Set the position for reading to a previously saved point.

const Scanner &	get_scanner () const
	Get reference to scanner. More...

virtual bool	has_delayeds () const =0
	Return if the file stores delayed events as well (as opposed to prompts)

virtual unsigned long int	get_total_number_of_events () const
	Returns the total number of events in the listmode file. More...

virtual shared_ptr< const ProjDataInfo >	get_proj_data_info_sptr () const

Public Member Functions inherited from stir::ExamData
	ExamData ()
	ExamData. More...

	ExamData (const shared_ptr< const ExamInfo > &_this_exam)

virtual const ExamInfo &	get_exam_info () const

virtual shared_ptr< const ExamInfo >	get_exam_info_sptr () const
	Get shared pointer to exam info.

virtual void	set_exam_info (ExamInfo const &)
	change exam info More...

void	set_exam_info_sptr (shared_ptr< const ExamInfo > new_exam_info_sptr)

Protected Member Functions
virtual shared_ptr< ListRecord >	get_empty_record_helper_sptr () const =0

virtual Succeeded	get_next (ListRecord &event) const =0

virtual void	set_proj_data_info_sptr (shared_ptr< const ProjDataInfo >)

Protected Attributes
shared_ptr< const ProjDataInfo >	proj_data_info_sptr
	Has to be set by the derived class. More...

Protected Attributes inherited from stir::ExamData
shared_ptr< const ExamInfo >	exam_info_sptr

Detailed Description

The base class for reading list mode data.

What is list mode data?

List mode data is a format for storing detected counts as a list, as opposed to a histogram. For each count, a list mode event contains all the properties that the scanner can give you. Hence, the list mode data gives you all the information about your acquisition that you can possibly get. Which information this is obviously depends on the scanner.

For most (all?) scanners, events are stored in chronological order. In addition to events, time flags are inserted into the list mode data. So, generally list mode data is a list of 'records', which can be of different types. In STIR, this concept of a 'record' corresponds to the ListRecord class and its relatives (see the documentation for ListRecord).

Usage

For most applications, i.e. when one just wants to go through the list of all events, the code would be as follows:

shared_ptr<ListModeData>
  lm_data_sptr(read_from_file<ListModeData>(filename));
// get a pointer to a 'template' record that will work for the scanner
// from which we're reading data
shared_ptr <ListRecord> record_sptr =
  lm_data_ptr->get_empty_record_sptr();
// give the record a simple name to avoid cluttering the code below
ListRecord& record = *record_sptr;
double current_time = 0;
while (lm_data_sptr->get_next_record(record) == Succeeded::yes)
  {
    if (record.is_time())
    {
  current_time= record.time().get_time_in_secs();
    }
    if (record.is_event())
    {
      if (record.event().is_prompt())
  { // do something
      }
      // ...
    }
  }

In addition, there is a facility to 'remember' positions in the list, and go back to one of these positions. This could be useful to mark time frames. This goes as follows.

// somehow I found out this is the start of the frame, so save it
ListModeData::SavedPosition start_of_this_frame =
   lm_data_sptr->save_get_position();
// now do something with this frame
// now get back to the start of the frame
if ( lm_data_sptr->set_get_position(start_of_this_frame)
   != Succeeded::yes)
  error("Help!");

Currently, this class (and ListRecord) is generic for emission modalities such as PET and SPECT.

Notes for developers

If you want to add a new type of list mode data, you have to make corresponding derived classes of ListModeData, ListRecord etc. You also have to modify make sure that read_from_file<ListModeData> recognises your data. This normally involves creating a new InputFileFormat class.

Member Function Documentation

◆ get_name()

virtual std::string stir::ListModeData::get_name ( ) const

pure virtual

Returns the name of the list mode data.

This name is not necessarily unique, and might be empty. However, it is expected (but not guaranteed) that ListModeData::read_from_file(lm_data_ptr->get_name()) would read the same list mode data.

The reason this cannot be guaranteed is largely in case the list mode data is not really on disk, but the object corresponds for instance to a Monte Carlo simulator.

Implemented in stir::CListModeDataROOT, stir::CListModeDataSAFIR< CListRecordT >, stir::ecat::ecat7::CListModeDataECAT< CListRecordT >, stir::ListModeData_dummy, stir::ecat::CListModeDataECAT8_32bit, stir::GE::RDF_HDF5::CListModeDataGEHDF5, and stir::CListModeDataPENN.

◆ get_empty_record_sptr()

shared_ptr<ListRecord> stir::ListModeData::get_empty_record_sptr ( ) const

inline

Get a pointer to an empty record.

Warning: Use with care. If you modify the object pointer to by a shared ptr, all objects using the same shared pointer will be affected.

This is mainly/only useful to get a record of the correct type, that can then be passed to get_next_record().

◆ save_get_position()

virtual SavedPosition stir::ListModeData::save_get_position ( )

pure virtual

Save the current reading position.

Note that the return value is not related to the number of events already read. In particular, you cannot do any arithmetic on it to skip a few events. This is different from e.g. std::streampos.

Warning: There is a maximum number of times this function can be called. This is determined by the SavedPosition type. Once you save more positions, the first positions will be overwritten. There is currently no way of finding out after how many times this will happen (but it's a large number...).; These saved positions are only valid for the lifetime of the ListModeData object.; A derived class might disable this facility. It will/should then always return Succeeded::no when calling set_get_position().

Implemented in stir::CListModeDataROOT, stir::CListModeDataSAFIR< CListRecordT >, stir::ecat::ecat7::CListModeDataECAT< CListRecordT >, stir::ListModeData_dummy, stir::ecat::CListModeDataECAT8_32bit, stir::GE::RDF_HDF5::CListModeDataGEHDF5, stir::CListModeDataLMF, and stir::CListModeDataPENN.

◆ get_scanner()

const Scanner & stir::ListModeData::get_scanner ( ) const

Get reference to scanner.

Returns a reference to a scanner object that is appropriate for the list mode data that is being read.

◆ get_total_number_of_events()

virtual unsigned long int stir::ListModeData::get_total_number_of_events ( ) const

inlinevirtual

Returns the total number of events in the listmode file.

Warning: This function currently works only with ROOT input files. By default it will throw an error.

Reimplemented in stir::CListModeDataROOT, and stir::CListModeDataPENN.

References stir::error().

Member Data Documentation

◆ proj_data_info_sptr

shared_ptr<const ProjDataInfo> stir::ListModeData::proj_data_info_sptr

protected

Has to be set by the derived class.

Has to be initialised by the derived class

Referenced by stir::CListModeDataPENN::CListModeDataPENN(), stir::CListModeDataROOT::CListModeDataROOT(), and stir::CListModeDataSAFIR< CListRecordT >::CListModeDataSAFIR().

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

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

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes