STIR ASIM Howto
This work was undertaken in order to demonstrate the effects of a breathing motion correction process on a cycle of Nuclear Medicine images in the absence of suitable patient data.
The work was carried out in the summer of 2012. The XCAT release was the latest binary release for Linux. ASIM was built using gcc version 4.4.3 (Ubuntu 4.4.3-4ubuntu5.1) which is known colloquially as Ubuntu 10.04. The STIR release was 2.1.
This document is aimed at those readers who are new to ASIM, PET and STIR and have the aim of obtaining good, but not the best available, PET images. It tells of some of the problems that may be encountered if a similar path is adopted but it doesn't provide detailed instructions to fix them. It assumes access to IT skills. The document assumes familiarity with XCAT or that you will obtain the necessary information elsewhere.
XCAT is an anthropomorphic software phantom based on patient CT data.(google 'XCAT phantom' May 2012). Its principal outputs are images of radiopharmaceutical emissions and images of linear attenuation coefficients. The emission images are based on the anatomy of the phantom and user parameters. (XCAT comes with a set of radiopharmaceutical uptakes which agree well with values determined from another source :
http://www.iba-molecular.com/sites/default/files/P7009nA_0.pdf)
ASIM is an analytical PET Simulator (google 'ASIM PET Simulator Washington' May 2012) that takes emission images of the XCAT phantom, applies the major effects of PET imaging (noise, attenuation, scatter, randoms, etc) to produce simulated PET sinograms. ASIM uses simplified analytical models rather than using painstaking Monte Carlo simulations such as are employed by GATE (google 'GATE opengatecollaboration' May 2012). ASIM is a special purpose tool that uses many fewer computer resources than GATE which is a very general tool capable of simulating the idiosyncrasies of individual PET camera models. ASIM was thought to be an easier route to acceptable simulated PET sinograms than GATE.
STIR (google 'stir software for tomographic image reconstruction' May 2012). STIR converts the sinogram output from ASIM into reconstructed images.
ASIM can simulate a variety of instruments and has the capability of defining new Instruments. STIR is capable of reconstructing images using sinograms from a variety of instruments. Both ASIM and STIR have definitions of the Ecat instrument model 962. In order to avoid unnecessary difficulties in obtaining the final images the Ecat model 962 was specified where necessary.
We investigated how to produce a single bed-position image from a full-sized XCAT phantom, passing it through ASIM, where a single bed-position is selected, and then through STIR to obtain a simulated PET image. Optionally this may involve the placement of several lesions using XCAT, incorporating these lesions into ASIM to produce a single sinogram of phantom with lesions.
As an alternative to joining several bed-position images to obtain the PET image of an entire torso, we investigated amending the specification of the number of crystal rings in the ASIM machine definition file. It was determined that this could be accomplished with a minor alteration to the ASIM machine definition file, together with an amended sinogram header for input to STIR. Reassuringly, no code changes were necessary. Only the selection of a non-standard ASIM build feature was required. Success was achieved with the standard 32 ring configuration and with a 128 ring configuration.
Having succeeded in obtaining the desired FOV with a single enlarged bed-position the use of multiple bed positions was dropped. It appears that ASIM has some provision for multiple bed positions and produces a single multi-position sinogram. STIR has no provision for processing them. It seems to be necessary that STIR utilities and possibly new facilities outside STIR would have to be used to accomplish the join.
We predict that novice users will, like me, experience difficulties with file headers - but that would also be true of GATE which may be viewed as an alternative to ASIM.
This section does not detail exactly how we used ASIM, but it covers the difficulties encountered in getting as far as producing an image. It may serve to speed up the progress of others who attempt a similar task. The difficulties fall into three categories: a) software port; b) ASIM idiosyncrasies in terms of usage; c) file headers and formats.
XCAT is delivered as binary images acceptable to our (Surrey) systems. The XCAT release was the latest binary release for Linux.
On contacting the main e-mail address on the web site for assistance with ASIM, I was given contact details for B.E. (Washington).
ASIM was developed for the MAC (gcc 4.0 and 4.2.1.) but I wanted to use it with LINUX (Ubuntu 10.04 with gcc 4.4.3). The build at Surrey was done by J.F. He encountered one problem with the build which required him to specify the inclusion of one math library which is included by default on the MAC version.
We encountered two other problems with ASIM. One was a small bug in the command line parameter handling. This was apparent in the LINUX version only but was due to a difference in the memory allocation routines. MAC allocation fills allocated memory with nulls before return to the caller, Linux does not do this. The other was a bug-fix which was missing from the downloadable version. It is possible that all these problems will be fixed on the download site.
The STIR 2.1 installation was carried out by J.F. We have encountered no problems with the STIR software other than that the ASIM output, .yaff sonograms, was not accepted as an Ecat 7 formatted file. It is not clear whether ASIM or STIR or both require modification.
According to the ASIM user guide, the PET machine definitions, which are text files, should be present in the same directory as the phantoms input. However, we found that with LINUX these machine definitions are first searched for in the present working directory (pwd) even when the phantom files are specified with a full path.
Simul, the program which interprets the voxelised emission phantom image which come from XCAT, seems to require that the phantom is a 16 bit big endian file. We found no way to modify this and it is possible that this behaviour is a bug.
One issue with the documentation is that the ASIM users Guide was prepared on an old MAC using MS Word. This meant we have been unable to see many of the images and diagrams. This defeated me but also defeated J.F. The images are replaced with the message "QuickTime and a decompressor are needed to see this picture"
One nice feature is that the program logs include a print of the supplied command line together with an interpretation of what the parameters are taken to mean in terms of program actions.
The most frustrating aspect of setting up and using ASIM is undoubtedly file formats and headers. Although headers are necessary the problems they cause are disproportionately irksome.
ASIM uses a file header system analogous to, but not compatible with, Interfile Headers. It was suggested (B.E. Washington) that we run Simul with the --I option and use the ASIM demo data as input. One of the output files from that run would provide a template for a header, a text file with extension .yhdr, suitable for use with a voxelised phantom.
XCAT avoids the problem of headers by producing raw binary files without headers of any kind. Using the computer configuration at Surrey, XCAT output files are little endian 32 bit floats and have to be converted to 16-bit big endian format with a corresponding .yhdr file which points to it.
It was found to be necessary to insert or adjust a fairly small number of parameters of the template header as follows:
original_file_name=${yaff_basename}
num_planes=${IF_dim3}
x_dimension=${IF_dim1}
y_dimension=${IF_dim2}
z_dimension=${IF_dim3}
x_pixel_size_cm=${IF_pixdim1cm}
y_pixel_size_cm=${IF_pixdim2cm}
z_pixel_size_cm=${IF_pixdim3cm}
Other parameters were left unchanged. The above list includes the shell variable substitution used to edit the actual parameter values into place. For those familiar with LINUX shell scripting the crude technique I used was to pass the entire .yhdr skeleton file with the above variables as shown as a 'here is' document input to the 'cat' utility, having previously set the shell variables to the actual parameter values. Note - pixel dimensions are in cm rather than mm units.
As mentioned above we found the only way to get a voxelised phantom into ASIM was by converting it to 16 bit big endian format from the XCAT little endian 32 bit floats. MATLAB (google 'MATLAB') was used to do this.
ASIM works satisfactorily reading and writing its intermediate files which have extension .yaff and textual headers which have extension .yhdr. It was never necessary to adjust intermediate file headers. The final output sinograms have a corresponding .yhdr file but the data file (.yaff) is almost an Ecat 7/STIR compatible file. At the first attempt at getting it into STIR, FBP2D failed to recognise it as an Ecat 7 file. Then an attempt was made to use the STIR utility 'if_headers_for_ecat7' but it also refused to recognise the .yaff as Ecat 7 format. An interfile header was produced by editing one obtained from a GATE run. There is also an example .hs file in section F of the ASIM user guide. The following parameters were changed using the .ydhr as a guide. This inability to process the .yaff files directly could be a limitation of ASIM or STIR or both.
name of data file := asim_nrmd_noisey_sino.yaff
originating system := ECAT 962
imagedata byte order := BIGENDIAN
!number format := float
!number of bytes per pixel := 4
number of dimensions := 4
matrix axis label [4] := segment
!matrix size [4] := 5
matrix axis label [3] := view
!matrix size [3] := 144
matrix axis label [2] := axial coordinate
!matrix size [2] := { 63,53,53,45,45}
matrix axis label [1] := tangential coordinate
!matrix size [1] := 288
minimum ring difference per segment := { -4,-13, 5,-22, 14}
maximum ring difference per segment := { 4, -5, 13,-14, 22}
It is important to remember that the above values may not be appropriate in any other case, they are intended only as a guide about which parameters may need attention. The list above is for the standard 32 ring configuration. When processing the 128 ring configuration use :
!matrix size [2] := { 255, 245, 245, 227, 227}
An ASIM run from phantom files to sinogram ready for reconstruction is shown in figure 1. The section from a bash script which implements this follows the diagram:
Figure 1 Flowchart of the process of producing STIR ready sinograms.
# Process lesions file
Simul -i ${IMGDIR}/lsns.yaff \
-o asim_lsns_em_sino.yaff \
-E -a -m 962 -k -h
# Process activity phantom
Simul -i ${IMGDIR}/act.yaff \
-o asim_em_sino.yaff \
-E -a -m 962 -k -h
# Obtain a Normalisation sinogram
Simul -i ${IMGDIR}/act.yaff \
-o asim_nrm_sino.yaff \
-N -m 962 -k -h
# Combine main and lesion phantom sinograms and apply noise
Noise -i asim_em_sino.yaff \
-t 51000000 -r 51000000 -R -s 16000000 –S \
-J 2.0 -I asim_lsns_em_sino.yaff \
-o asim_noisy_em_sino.yaff
# Combine noisy sinogram and the normalisation sinogram to produce final sinogram
Normalize -i asim_noisy_em_sino.yaff \
-n asim_nrm_sino.yaff \
-k -o asim_nrmd_noisy_sino.yaff
Further information on each run may be found in the ASIM User guide.
Use of STIR FBP2D and FBP3DRP produce the expected images. However OSMAPOSL took a long time to run and produced no output for either the 32 ring or 128 ring configurations.
A willing volunteer is required to pursue use of OSMAPOSL.
Example FBP2D.par
fbp2dparameters :=
input file := asim_nrmd_noisy_sino_5.hs
output filename prefix := img_ias1_asim_FBP2D_5
; output image parameters
; zoom defaults to 1
zoom := 1
; image size defaults to whole FOV
xy output image size (in pixels) := -1
; default means: call SSRB only if no axial compression is already present
num segments to combine with ssrb := 5
; filter parameters, default to pure ramp
alpha parameter for ramp filter := 0.5
cut-off for ramp filter (in cycles) := 0.5
end :=
Example FBP3DRP.par
fbp3drpparameters :=
input file := asim_nrmd_noisy_sino_5.hs
output filename prefix := img_ias1_asim_FBP3DRP_5
; all following parameters are optional
;;;;;;; output image parameters
zoom := 1
; defaults to cover whole FOV
xy output image size (in pixels) := 180
maximum absolute segment number to process := 2
;;;;;;; parameters for initial image you can use an existing image (but be careful about the scale!)
; image to be used for reprojection := some_image
; or you can use FBP on 2D data. following are reconstruction parameters for 2D
; default means: call SSRB only if no axial compression is already present
num segments to combine with ssrb := -1
; filter parameters for initial FBP2D, default to pure ramp
alpha parameter for ramp filter := 1
cut-off for ramp filter (in cycles) := 0.5
; parameters for Colsher filter
alpha parameter for colsher filter in axial direction := 1
cut-off for colsher filter in axial direction (in cycles) := 0.5
alpha parameter for colsher filter in planar direction := 1
cut-off for colsher filter in planar direction (in cycles) := 0.5
; define colsher on finer grid. The higher the number, the better (but slower)
stretch factor for colsher filter definition in axial direction := 2
stretch factor for colsher filter definition in planar direction := 2
;;;;;;;;; other parameters
save intermediate images := 0
display level := 0
end :=
This work involved assistance from
J.F., Software Support, Centre for Vision, Speech and Signal Processing, University of Surrey, U.K.
Brian Elston, Senior Computer Specialist, University of Washington, Department of Radiology, U.S.A.
Please do not contact them directly. Rather, use the STIR user list and the ASIM website managed by UWMC IRL; University of Washington.
