STIR Howto Create Custom InputFileFormat

When using a custom scanner, it might be convenient or needed to create one's own (coincidence) list-mode input file format. In the following are some basic steps. Two remarks:


 * The templation of the class as in the following and with ECAT96X is only needed when using different scanners with similar data format.
 * To save some work, classes can also be derived from intermediate classes available in STIR such as
 * class CListEventCylindricalScannerWithDiscreteDetectors : public CListEvent
 * template  class CListEventCylindricalScannerWithViewTangRingRingEncoding : public CListEventCylindricalScannerWithDiscreteDetectors

Creating classes for Coincidence list mode records
In coincidence list mode data (cLMD) there are usually two types of records: Event data records, which essentially store the coordinates of the two detectors in coincidence, and time data records, which contain a time stamps and are inserted every so and so many event records. Some inspiration of the following can be obtained from CListRecordECAT962.h in the STIR source code. In that you need


 * class CListEventDataMyScanner
 * contains the event data as POD types. Be sure not to have pointers or fancy data types. ECAT962 for example uses unsigned int bitfields. Careful with byte order!


 * class CListTimeDataMyScanner
 * Same as before just for time stamps. One bit of each class data should be reserved for labeling type and both classes data members should have same size, i.e. sizeof(CListEventDataMyScanner) == sizeof(CListTimeDataMyScanner) should be true.


 * template  class CListEventMyScanner : public CListEvent
 * needs the following abstract methods to be implemented in the custom class
 * virtual bool is_prompt const =0
 * virtual LORAs2Points get_LOR const =0


 * class CListRecordMyScanner : public CListRecord, public CListTime, public CListEventMyScanner
 * needs the following abstract methods to be implemented in the custom class (see also implementation for ECAT962)
 * virtual bool is_time const =0
 * virtual bool is_event const =0
 * virtual CListEvent & event =0
 * virtual const CListEvent & event const =0
 * virtual CListTime & time =0
 * virtual const CListTime & time const =0
 * virtual bool operator== (const CListRecord &e2) const =0
 * virtual unsigned long get_time_in_millisecs const =0
 * virtual Succeeded set_time_in_millisecs (const unsigned long time_in_millisecs)=0
 * nice to have is a private union data type to combine time and event data and provide a raw data access, where sizeXX corresponds to the size of an integer data type equal to the size of your event and time classes from above
 * union { CListEventDataMyScanner event_data; CListTimeDataMyScanner time_data; sizeXX raw; };

Creating classes for reading events
Again, files for ECAT962 provide some example. You need to create a class for cLMD from your scanner, which inherits from CListModeData. A minimal example header file looks like

template  class CListModeDataMyScanner : public CListModeData { public: CListModeDataMyScanner( const std::string& listmode_filename_prefix); virtual std::string get_name const; virtual shared_ptr  get_empty_record_sptr const; virtual Succeeded get_next_record(CListRecord& record_of_general_type) const; virtual Succeeded reset; virtual SavedPosition save_get_position; virtual Succeeded set_get_position(const SavedPosition&);

virtual bool has_delayeds const; private: std::string listmode_filename_prefix; mutable shared_ptr > current_lm_data_ptr; mutable std::vector saved_get_positions; Succeeded open_lm_file const; };

There are also two inherited data members which have to be set in the derived class.
 * shared_ptr scanner_sptr
 * shared_ptr exam_info_sptr

The filename of the file to be read has to be given as an argument to the constructor. It does the following:


 * Set inherited exam info pointer. Minimum: set empty ExamInfo
 * this->exam_info_sptr.reset(new ExamInfo);

scanner_sptr.reset(new Scanner(Scanner::User_defined_scanner, "MyScanner", 124, 63,     // int num_detectors_per_ring_v, int num_rings_v, 120,     // int max_num_non_arccorrected_bins_v, 120,     // int default_num_arccorrected_bins_v, 63, 10.0,     // float inner_ring_radius_v, float average_depth_of_interaction_v, 3.2, 1.2, 0.0,     // float ring_spacing_v, float bin_size_v, float intrinsic_tilt_v, 1, 2,      // int num_axial_blocks_per_bucket_v, int num_transaxial_blocks_per_bucket_v, 1, 1,      // int num_axial_crystals_per_block_v, int num_transaxial_crystals_per_block_v, 1,      // int num_axial_crystals_per_singles_unit_v, 1,     // int num_transaxial_crystals_per_singles_unit_v, 1     // int num_detector_layers_v);	));
 * Set inherited Scanner pointer. If user-defined scanner, do something like this

template  Succeeded CListModeDataMyScanner:: open_lm_file const {	// Could put something here to fiddle with file extensions, let's assume listmode_filename_prefix=filename cerr << "CListModeDataMyScanner: opening file " << listmode_filename_prefix << endl; shared_ptr stream_ptr(new fstream(listmode_filename_prefix.c_str, ios::in | ios::binary )); if(!(*stream_ptr)) {		warning("CListModeDataMyScanner: cannot open file %s\n", filename.c_str); return Succeeded::no; }	stream_ptr->seekg(32); // first 32 bytes of file used for signature, thus move stream forward. current_lm_data_ptr.reset(			new InputStreamWithRecords			( stream_ptr, sizeof(CListTimeDataMyScanner), sizeof(CListTimeDataMyScanner), ByteOrder::little_endian !=ByteOrder::get_native_order)); // Pay attention to byte order in your binary file! return Succeeded::yes; }
 * call open_lm_file. This function in a minimal version looks like

Last thing to do is to create an instance of your templated class by
 * template class CListModeDataMyScanner;

Creating class for reading the file
You need a class like
 * class MyScannerCListmodeInputFileFormat : public InputFileFormat

Methods to be implemented are
 * virtual std::auto_ptr< DataT > read_from_file (std::istream &input) const =0
 * Actually does the work. Should return std::auto_ptr (0)
 * An alternative might be a method like virtual std::auto_ptr read_from_file(const std::string& filename) const { return std::auto_ptr(new CListModeDataMyScanner<CListRecordMyScanner>(filename));}
 * virtual const std::string get_name const =0
 * simple, just returns a name
 * virtual bool actual_can_read (const FileSignature &signature, std::istream &input) const =0
 * checks if the class can read a file format identified by signature or from given istream (e.g. reading a header). Alternatively, one of virtual can_read(...) methods can be overwritten

Registering your file format
In a file like MyScanner_registries.cxx create a variable, where the 4 corresponds to the "importance" within the registry. Proceed as written in the updated STIR developer's guide to integrate your new classes into the CMake framework of STIR.
 * static RegisterInputFileFormat<MyScannerCListmodeInputFileFormat> LMdummyMyScanner(4);