|
|
|
Division of Nuclear Medicine SimSET |
|
|
Photon history files contain records for each photon accepted by the module creating the history file. These files may be created for all photons which reach the target cylinder (PHG Module), all photons which leave the collimator (Collimator Module), all photons which are accepted by the detector (Detector Module), and all photons which are accepted by the Binning Module.
Body
Records in the default history file format contain an extensive list of photon parameter values. The ordering of the records is a repeating list of a decay record followed by one photon record for each decay which produces an acceptable photon (two photons for PET). Note, when forced detection is used each decay may produce more than one photon. For PET simulations we arbitrarily label the first photon produced by a decay blue and the second pink. Singles are not produced in PET, two photons must be accepted as a coincidence pair. When forced detection is used, a decay may produce more than one blue (or pink photon if PET):
Decay Blue Photon [Blue Photon ...] Pink Photon [Pink Photon ... ] Decay ... Hence, at the beginning of each record in the history file is a flag-byte which indicates if the following record is a decay, a blue photon, or a pink photon. Processing the history file requires reading a flag byte to determine what type of record follows and then reading the appropriate amount of data. A skeleton program named PhgBin (bin.phg.c) is provided for processing default history files. Refer to the Utilities page and the Binning page for more information about using this program.
Header
The history files and the histogram files share the same header, and the header format remains the same whether or not the history file has been created using a customized parameters file. The header is a binary component with size equal to 32768 bytes. The header is explained in detail in the Header page. Basically all of the parameters that are used to specify the simulation are retained in the header as well as a few run-time statistics. There are utilities available for displaying the header (DisplayHeader, print.header.c).
Activating history file creation
Each module of the SimSET software package can create a history file, this includes the PHG, the Collimator, the Detector, and the Binning modules. In each case the photon records for photons which "pass" through that module are written to the respective history files. To activate history file creation from any of these modules, set the parameter 'history_file' in the relevant parameters file to the name of the history file you wish to create. History files in default format will then by written to the file names you specify.
WARNING: If more than one history file is to be created in a given simulation run, ensure that they have unique names.
Customizing history files
Customization of history files was introduced in SimSET release 2.5. Customization allows the user to specify which parameters of a photon are recorded in the history file. To activate history file customization, create (or copy) a new history parameters file and set the parameter 'history_params_file' in the parameters file of the relevant module to it's path. Example history parameters files may be found below.
The history parameters file used to specify which parameters are written to the history file is similar to all other parameter files used by SimSET software. It is an ascii text file consisting of entries of the following format:
DATA_TYPE parameter_name = value For example,
BOOL scatters_in_collimator = TRUE In addition to specifying individual parameters, the user may optionally also specify an acceptance range for most parameters. This allows the filtering of photons according to a user-specified range. For example:
INT col_scatters_min = 1
INT col_scatters_max = 3
Parameters may be excluded from the history file by either setting their relevant boolean values to FALSE, or by simply omitting them from the parameter file.
Customized file format
The 32768-byte header format remains the same whether or not customization is used. However, in the body the records will vary depending on which parameter the user selects to have written to the file. As a result, the default body format described in the file format section above is lost, and post-processing the history file using the PhgBin utility (see the Binning page) is no longer possible. This is not considered a particular disadvantage though, as the user will only be customizing history files if s/he is also creating custom processing software to analyze them.
To calculate the record lengths in a customized history file, note that all parameters of type REAL are double precision, eight-byte values. All parameters of type INT are four-byte integer values.
For SPECT, each record starts with a single character containing the number of photons in the record. For each photon, the parameters specified in the history parameters file are then written to the record in the order shown in the parameter type table below. There is no padding between the fields or records.
Note: photons which are processed but not written (which will happen if they fall outside the parameter limits set in the history_params_file) are also recorded in the custom history file - in this case the record simply consists of a single character of value zero.
For PET, each record starts with a single character containing the number of coincidence pairs in the record. Data for all the blue photons are written first, followed by data for all the pink photons. Again, for each decay, the parameters specified in the history parameters file are written to the record in the order shown in the parameter type table below, and there is no padding between fields or records. The same rule about rejected photons also applies to PET data - that is, the first character in a record may be zero, in which case the record immediately terminates and the next record will start at the next byte
Parameter type definitions for history parameter files
Parameter name Units Data type Decay information decay_x_position . BOOL decay_x_pos_min cm REAL decay_x_pos_max cm REAL decay_y_position . BOOL decay_y_pos_min cm REAL decay_y_pos_max cm REAL decay_z_position . BOOL decay_z_pos_min cm REAL decay_z_pos_max cm REAL decay_time . BOOL decay_type . BOOL Importance sampling info: decay_weight . BOOL weight . BOOL Photon position and direction at the end of module processing (e.g., at the end of the collimator module for a collimator history file): x_position . BOOL x_pos_min cm REAL x_pos_max cm REAL y_position . BOOL y_pos_min cm REAL y_pos_max cm REAL z_position . BOOL z_pos_min cm REAL z_pos_max cm REAL x_cosine . BOOL x_cos_min . REAL x_cos_max . REAL y_cosine . BOOL y_cos_min . REAL y_cos_max . REAL z_cosine . BOOL z_cos_min . REAL z_cos_max . REAL Photon scatter info: scatters_in_object . BOOL obj_scatters_min . INT obj_scatters_max . INT scatters_in_collimator . BOOL col_scatters_min . INT col_scatters_max . INT Photon energy info: energy . BOOL
The detector module will record the enrgy deposited here - all other modules will record the energy of the photon as it leaves.energy_min keV REAL energy_max keV REAL Photon path info: travel_distance . BOOL
This is the cumulative distance the photon has travelled from decay to final destinationtravel_distance_min cm REAL travel_distance_max cm REAL LOR position: transaxial_distance . BOOL transaxial_distance_min cm REAL transaxial_distance_max cm REAL azimuthal_angle_index . BOOL aa_index_min INT aa_index_max INT axial_position . BOOL axial_position_min cm REAL axial_position_max cm REAL Interaction position in detector coordinates (flat detectors only): detector_x_position . BOOL detector_x_position_min cm REAL detector_x_position_max cm REAL detector_y_position . BOOL detector_y_position_min cm REAL detector_y_position_max cm REAL detector_z_position . BOOL detector_z_position_min cm REAL detector_z_position_max cm REAL Position of detector at interaction (flat detectors only): detector_angle . BOOL detector_angle_min degrees REAL detector_angle_max degrees REAL Detector interaction info: num_detector_interactions . BOOL num_detector_interactions_min . INT num_detector_interactions_max . INT det_interaction_positions . BOOL Detector crystal number (block detectors only): detector_crystal . BOOL
- Example 1. Simple custom history file - creates a history file with records containing three values representing the cartesian coordinates of each photon accepted by the module creating the history file. Only photons whose axial position falls within the central 10 cm of the FOV (+/- 5cm from tomograph 0-point) are accepted.
- Example 2. Template file - contains all possible history file options. Copy to your working directory and edit.
Last revised by: Robert Harrison Revision date: 06 Mar 2009