Editing 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 Derived> 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 Derived> class CListEventMyScanner : public CListEvent
** needs the following abstract methods to be implemented in the custom class
*** virtual bool is_prompt () const =0
*** virtual LORAs2Points< float > get_LOR () const =0

* class CListRecordMyScanner : public CListRecord, public CListTime, public CListEventMyScanner<CListRecordMyScanner>
** 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

<pre>
template <class CListRecordT> class CListModeDataMyScanner : public CListModeData
{
public:
	CListModeDataMyScanner( const std::string& listmode_filename_prefix);
	
	virtual std::string get_name() const;
	virtual shared_ptr <CListRecord> 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<InputStreamWithRecords<CListRecordT, bool> > current_lm_data_ptr;
	mutable std::vector< unsigned int> saved_get_positions;
	Succeeded open_lm_file() const;
};
</pre>

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

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

* Set inherited Scanner pointer. If user-defined scanner, do something like this
<pre>
	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);
	));
</pre>

* call open_lm_file(). This function in a minimal version looks like
<pre>
template <class CListRecordT>
Succeeded
CListModeDataMyScanner<CListRecordT>::
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<istream> 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<CListRecordT, bool>
			( 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;
}
</pre>

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

== Creating class for reading the file ==

You need a class like
* class MyScannerCListmodeInputFileFormat : public InputFileFormat<CListModeData>

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<data_type> (0)
** An alternative might be a method like virtual std::auto_ptr<data_type> read_from_file(const std::string& filename) const { return std::auto_ptr<data_type>(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.
* static RegisterInputFileFormat<MyScannerCListmodeInputFileFormat> LMdummyMyScanner(4);
Proceed as written in the updated STIR developer's guide to integrate your new classes into the CMake framework of STIR.