Interfile Keys Walk Through of the Program Summary

 

Syntax

Program used with following syntax.

R sinogram [original] [options...]

Order of parameters and options has no affect on results. The specified Interfile is loaded and reconstructed according to the options. Whether the Interfile contains a set of sinograms or (more usual) a set of projections will not affect the reconstruction. The data is reordered to sinogram sets for internal use. Sinogram will be referred to as S . Note: sinogram and set of sinograms are used interchangeably throughout this discussion.

You may also optionally specify the original phantom. This is purely for research purposes, to check your reconstruction is correct. In the field (or hospital) the orginal will not be known. If it were, you would not be using R ?!

Please note if you do not need the statistics MSE and CSQ for each iteration, feel free to make use of the -NoStats option. It will speed up your reconstruction greatly.

Default behaviour, given no options, is to reconstruct using EM, no smoothing, no scatter correction, no attenuation correction, parallel projections, virtually no camera blur, grid dimensions equivalent to camera dimensions, for one iteration and then display Chi-Squared statistic and save final reconstruction. The basic output of the program is a model file and a reconstruction, having the same basename as the sinogram, with extensions .log and .r respectively.

 

Advanced Command Line Features

You may also make use of the @ expansion character in your command line. e.g. r @mydefs myinterfile.s
would read the file mydefs as though you had type it on the command line. The file can use multiple lines for ease of reading. Any line beginning with a semicolon will be treated as a comment.

You can also use option-value level expansion. e.g. r myinterfile.s -times:@times.file
All lines in the file are stripped of spaces, tabs, newlines and commas and concatenated into a single line delimited by commas. Any line in the file that begins with a semicolon is treated as a comment.

[times.file]

  ;This is the times file!

  1 2 3 4 5 6 7 8 9 10

  ; comments with semicolon start. 

    11 12 13,14 15,

  16

   17

Equivalent to -times:1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17

Special slicing options for Interfiles are also available. Whenever you specify an Interfile you can follow it with up to five slicing parameters. e.g. fred.r,3,7 would use just the slices 3 through 7 from fred.r. e.g. fred.r,3,7,2,2,1 would average ajoining slices of fred.r, thereby halving number of slices. See -SliceSelect later for more details.

The many options available to alter the default behaviour are listed below.

 

Parameter Types

 

n

an integer.

r

a real.

vector

a vector of reals.

mat

a matrix of reals.

file

a file that is not an Interfile file.

ifile

an Interfile format file.

pdef

a phantom definition... pdef is PhantomName[,Xs,Ys,Zs,Xo,Yo,Zo] PhantomName is one of HIL SLB GRD HRT HAL HALAtt RD1 RD1Att PNT PTS MIX CMP SYM GRY.
Xs, Ys, Zs scales for axes. Default 1.0.
Xo, Yo, Zo offsets for axes. Default 0.0.
All of Xs through Zo are optional.
e.g. GRY,0.5,0.5,0.5 specifies a circular phantom of radius 0.5 (relative to reconstruction area), placed in the center.

 

 

-Algorithm:name (R)
Name of the algorithm to use. Value must be 'OSEM' which is also the default. (This is left here in case an algorithm better than OSEM comes along).

To make full use of OSEM you will also need to specify -OS:stylefile.

-AlwaysUseScale (R,P,Slice)
Always scale the output binary using "RPAH Scale". This only matters for Integer types e.g. signed integer etc. Float and text output will always use best computer precision and a "RPAH Scale" of 1.0. Default is to only scale for integers when all are below 8 or any are above 32000.

 

-AngDis:a,d,a,d,... (R,P)
Alternative to using -RadXY option. This form gives more precise control, useful for non elliptical orbits. (a,d) pair specifies the angle and distance of reconstruction from camera centre, for each projection angle in order. When using this option -RadXY is ignored. Note: You must order the (a,d) pairs according to the clockwise or counter clockwise nature of the data. Default is to use values from -RadXY or from interfile.

 

-Attenuate:{ifile|r[,pdef]} (R,P)
Attenuation for the system may be modeled by a constant value or an attenuation map. An attenuation map is an Interfile of same grid dimensions as the reconstruction, it may have less slices though. In the case of less slices, the slices are evenly spread to cover all the slices of the reconstruction. Values within IFile and value of r is loss per cm. The value of r will be used to create a GRY phantom to use as attenuation map. A GRY phantom is a cylinder with radius equal to 0.95 times the diameter of the reconstruction area.
Attenuation map Interfiles are automatically divided by 1000, unless they contain a key of form [mqu] image scale factor or RPAH Scale. In this case they are divided by the value of that key. Initial calculation takes reasonable time, but once calculated, attenuation has no per-iteration cost. r specifies uniform attenuation over the entire reconstruction grid. r must be a non-negative real. If the pdef qualifier is used the stated phantom description will be uniformly filled with the value r. ifile specifies an existing Interfile attenuation map to use. Default is no attenuation. See Section Weight Matrix Definition for more detail. -SliceSelect option applies to this option. First the ifile's own slice selection is processed. Then, if needed, the -SliceSelect parameters are used to slice except Method is set to 1 ie. average combined slices.

 

-BackgroundLevel:r (R,P)
Specifies the assumed background noise level to be ignored when calculating the patient reconstruction area. Only used if a starting image is not specified. To see the patient area produced by different levels, set the number of iterations to 0. The reconstruction will then be the assumed patient boundary image. Default value of 0 is usually best.

 

-BoundaryShrink:r (R)
Value to be treated as virtually zero for each iterations boundary shrink operation. After each iteration the R program attempts to reduce the area to be reconstructed by checking the edge of the current image for zeros and ignoring that area in future iterations. Default value of 0.0 means boundary reducation is not performed.

 

-Brief (IfInfo)
Display only the totals, not a slice by slice result. Default is to show details for all slices.

 

-CamDetect:n (P)
Number of camera bins used for projection. Default behaviour is to use value specified in the interfile.

 

-CamProjection:n (P)
Number of camera projections used for projection. Default behaviour is to use value specified in the interfile.

 

-Cammm:r (P)
Specifies size of camera in mm. r must be a non-negative real value in mm. Default behaviour, size of the camera is taken from the interfile.

 

-CollConst:r, -CollScale:r (R,P)
These describe the amount of camera blur in system. CollConst describes blur in mm at 0mm from camera. CollScale describes increase in blur per mm due to distance from camera. The blur function is a normal distribution with , where d is distance in mm from camera. Larger CollConst causes greater spread. Larger CollScale causes more depth dependance. The default is virtually no spread and no depth dependance. A better default value would be -CollConst:5, but for historic reasons the value is 1.84. CollConst, CollScale must not be negative. See also -PSxWidth, -PSzWidth.

 

-DebugMe (R,P)
Save some debug files during project or reconstruction as follows.
geometry.dbg files containing the positional information of the PBD matrix for each image pixel and angle combination, in the following format per line: A,X,Y,B,BOff,D
A = angle (radians), X = image pixel X coord, Y = image pixel Y coord, B = camera detector bin hit, BOff = position within detector bin, D = distance from camera in mm (round nearest 4 or so).
geohead.dbg one line containing: NumProjections, NumPixels (e.g. 64 for a 64 by 64 image), Pixelsizemm.
psf.dbg for each slice, distance from camera and detector bin offset the line represents the distribution of the pixel when projected onto the camera bins.
If attenuation is used there will also be...
attenuation.dbg for each image pixel and angle combination, the probability of being detected. Actual probability can be found by dividing output value by 255.0. atthead.dbg one line containing: NumProjections, NumPixels (e.g. 64 for a 64 by 64 image).
Default is no debug ie. no files are output.

 

-DirectBackProject:{a&s&p} (R,P)
Perform a quicker backproject by omitting some detail from the model. a include the attenuation modeling.
s include the scatter correction used by -Scat* options.
p include the point spread function.
Default is to include all factors (if needed) in the model.

 

-DivRecon:{f&p&t&m&a} (R)
Specify to scale final reconstruction.
f is divide by
where w is width of reconstruction in mm;
fbf is fan beam focus in mm;
r is average radius in mm.
p is divide by number of projections.
t is divide by study duration.
In the case of -Times option each time frame will be divided by its respective duration.
a is divide by 0.1. Useful for arbitary scaling. e.g. aaa divide by 0.001.
m is divide by pixel size in mm * number of projections.
m is the default for when -TransScale option is used. m is ignored in the presence of a -TransScale. Otherwise default is not to scale reconstruction.

 

-EnergyWindow:n,-EnergyARatio:r,-EnergySRatio:r (R,Slice)
Deals with multiple energy windows in the Interfile. You may select which window to reconstruct, or combine the first two windows into a single reconstruction. n is the energy window to reconstruct. If this is set to 0 the first two will be combined according to the Energy?Ratio's. Default behaviour is to reconstruct the first energy window only. r is only active when combining energy windows.
EnergyARatio is the amount to scale the attenuation map for the second window. Attenuation map is assumed to be correctly scaled for first window. EnergySRatio is the scale of source in second energy window compared to first.
Default behaviour is not to scale the attenuation map or source during reconstruction.

 

-FBFmm:r, -FBFOffmm:r (R,P)
Used mainly for transmission data, to model a point source of emission FBFmm from the camera, offset by FBFOffmm from camera centre, via a suitable fanbeam collimator. It affects the generation of the weight matrix, used by the algorithms, to position the emissions. Specifically, non zero values of FBFmm will cause convergence of projections at a point FBFmm in front (positive) or behind (negative) the camera. Default is not to use a fan beam weight matrix. i.e. Projections are parallel to one another. r may be any positive or negative real.
Notes:

	Lowest levels of OSEM (i.e. 1,2 or 3 projections per subset) will not work with fanbeam option. This is because, a single projection, in the case of fanbeam, does not define all pixels in the reconstruction space.
	It is necessary to provide a -StartImage, when using this option. The default start image is only possibly useful for non-fanbeam reconstructions, (even then I now suggest +GRY as start).
	The fanbeam option will spread pixels quite wide that are far from the camera, therefore it is a good idea to use the -CollScale and -PSxWidth options to provide some increased spread to the pixels' projections.

 

-FilterNoise (R,Slice)
A quick and dirty attempt at noise removal. Pixels surrounded by zeros on four sides are zeroed. Pixels that are greater than LA*sqrt(LA)+100 are set to LA. Where LA is the four point local average. This is performed to image just prior to saving. Can be used to quickly tidy up images that have a few "spots" in them. This option takes extra time for each image save. Default is to do no filtering of noise.

 

-GeometricMean (R,P)
If specified S will be assumed to have been produced by taking the geometric mean of opposing projections of a 360 degree data set. This option is, therefore, only valid for 180 degree data sets. The algorithm details are modified to simulate the effect of geometric meaned data. You would like more detail? Email me.

 

-GridPixel:n (R)
Usually reconstructions occur with reconstruction grid dimensions equal to the number of projection bins. A value of 0 is default and causes the number of projection bins in S to be used for reconstruction grid dimensions. Any other number will cause reconstruction to occur on grid of specified size. n must be a non-negative integer value.

 

-Gridmm:r (R)
The size of the grid pixels is usually scaled to be same as camera width in total. A value of 0 is default and causes the camera size in S divided by -GridPixel to be used for reconstruction grid pixel size. Any other number will cause reconstruction to occur on grid with pixels of specified size. r must be a non-negative real value in mm. Note: The reconstruction radius may change if you alter this value and have not specified the radius in the interfile or via the -RadXY,-AngDis options.

 

-Iterations:n (R)
Algorithms used are iterative. Each iteration improves upon the previous reconstruction. One iteration is usually adequate for OSEM algorithms. Default is to perform one iteration. When specified, n iterations will be performed. The special case of n=0, will cause the assumed body outline to be produced as the reconstruction. n must be a non-negative integer.

 

-MAP:r,r,n (R)
MAP stands for Maximum A Postiori. The first r represents , second and n is smoothing order or neighbourhood. Given suitable choices for , and n it will produce a smoother reconstruction. Good values to try are 0.01,2,1. The process is as follows.
where n is a neighbour of j.

New project function will then be based on...

Default is not to use MAP algorithm at all. and must be positive real. n must be a positive integer. Use of this smoothing option slows the execution somewhat based on neighbourhood selected (n = 1, 30%).

 

-ModelIKLOutput (R)
Output the internal model.ikl file to model.ikl in the current directory. This is useful if you wish to add aliases for interfile keys. This may need to be done if your camera hardware/software does not spell correctly. Unless model.ikl is found in directory pointed to by IMAGEDIRECTORY or current directory, internal model.ikl file is used. Default is not to output model.ikl file.

 

-NFormat (R P Slice)
Number format for output files, can be any one of Float4, Float8, Signed1, Signed2, Unsigned1, Unsigned2, ASCII. (Never actually tried float8, let me know if it works!) Default is input format.

 

-NoStats (R)
Chi-squared and (if Original image provided) Mean-squared errors are provided upon completion of each iteration, at an execution overhead of about 50%. If you are not interested in these values you may use -NoStats to turn off these statistical calculations. Mean-squared error is . Where O is original picture and E is current reconstruction. Chi-squared is . Where O is original sinogram, E is projection of current reconstruction, and is -StatEPSILONs' value. Default is to display these statistics. See also -StatEPSILON.

 

-NoiseSeed:{-1|0|n} (P)
Add poisson noise to projections. -1 random noise based on internal computers clock etc. 0 no noise generated. n use n as the random number seed for noise creation. If you use n=1 you will generate same noise as used by earlier versions of the program. Default is not to add noise to projections.

 

-NoiseScale:r (P)
Change "scale" of noise. Values greater than 1.0 decrease the noise. Values less then 1.0 increase the noise. The default is 1.0, giving truest poisson values.

 

-OS:(stylefile|+n,s|Xm,s) (R)
The OSEM algorithm makes use of multiple subsets of S to reconstruct in fewer (e.g. one) iterations. This simplifies OSEM to a special case referred to as EM. stylefile can be any existing style file in the IMAGEDIRECTORY. The easiest way to create the style files is by OSF program. Even easier is to use the +n value where n is number of projections per subset you want. Or similarly use the Xm value where m is number of subsets to use, which is also the speed up factor. The projections in the subsets will be spread around the rotation extent according to s. If s is 0, they will cover the area as quickly as possible. If s is 1 they will proceed sequentially from start to finish. Default method is to use a single subset containing all projections.

 

-AddOffsetSino:ifile (R)
If specified, this sinogram will be added to each projection. By default nothing is added to each projection. -SliceSelect option applies to this option. First the ifile's own slice selection is processed. Then, if needed, the -SliceSelect parameters are used to slice.

 

-MultOffsetSino:ifile (R)
If specified, each projection will be multiplied by this sinogram. By default projections are not scaled. -SliceSelect option applies to this option. First the ifile's own slice selection is processed. Then, if needed, the -SliceSelect parameters are used to slice except Method is set to 1 ie. average combined slices.

 

-OrderedSubsetOutput (R)
Output the ordered subset file to be used during this reconstruction. The output filename will be aHb.c, where a is number of projections per subset, b is style (either 0 or 1) and c is number of projections. These can be modified and passed back into the R program later through the -OS option if required. If to be reused the file must be placed in the OSProj subdirectory of directory pointed to by IMAGEDIRECTORY environment variable. Default is not to output the ordered subset file.

 

 

-PBDOutput:(none|normal|sparse) (P)
Output the PBD matrix that would be used for this projection. No actual projection is performed if this option is used. Normal output format is a matrix of pixel verses projection bin. Sparse output format is in tuples
pixel projectionbin v
Pixel being the pixel number or matrix column.
Projectionbin being the projection bin number or matrix row.
Value being the probability value of energy from Pixel reaching Projectionbin, scaled by 1000. i.e. Probabilities 0..1 become 0..1000.
This format is especially useful as input to Matlab (or other) package for manipulation as a sparse matrix. Default is none ie. no matrix output and projection occurs.

 

-PBDTotalsSave (R)
Save, at the end of each subiteration, the PBD matrix totals images. ie. probability that counts from pixel where detected somewhere. Output interfile name is ifile_PT_i_s.l, where ifile is input interfile's name, i is the iteration number and s is the subset being used. Default is not to save PBD matrix totals images.

 

-PIRAFunc:func (R)
Apply PIRA smoothing through time slices. Also produces files of fitted values. These are stored in files named filename.Tn.l, where n is number of fitted parameter. Func can be EXP or NONE.
EXP function fitted is .
Default NONE, does not smooth.

 

-PSxWidth:n, -PSzWidth:n (R,P)
These options decide how wide a spread of camera blur you will actually calculate. -CollConst and -CollScale decide the shape of the function. Here you decide what speed/accuracy trade you shall make. Camera blur has a normal distribution and therefore drops off quickly to virtually zero, without ever reaching zero. Doubling PSxWidth or PSzWidth doubles the execution time of R. So use with caution. By default a PSxWidth is 1 and PSzWidth is 0. i.e. Within the slice central pixel and one either side are used for projection, and only one slice is used.

 

-Quiet (R,P,IfInfo,Slice)
Do not report warning messages pertaining to Interfile Format differences. Default is to report all warning messages.

 

-ROIValues:vector (P)
Specify alternative values for the regions of interest in phantom images. e.g. -ROIValues:0,100,200,600. Would give the value of 200 to the third region of interest, etc. Default is to use phantoms default region of interest values. Note: If the Interfile key "[MQU] average count per pixel" is set to 0, no scaling will occur so the regions of interest will literally contain the specified values. Otherwise, values will be scaled to provide required average value.

 

-Reconstruction:file (R)
Output of reconstructions, log files and miscellaneous information goes into files with certain names. Default name for files produced are the base name of the sinogram S , with varied extensions. When specified, file will be used instead of sinograms' basename.

 

-SaveProjections:n (R)
Usually the projections are of no interest. The last n projections may be saved into files NAME_nnn.p, where nnn is the iteration number. By default none are saved. n must be a non-negative integer.

 

-SaveReconstructions:n (R)
Usually the final reconstruction is the best and only one of interest. The last n reconstructions may be saved into files NAME_nnn.r, where nnn is the iteration number. The last reconstruction always goes into file named NAME.r. By default only the last reconstruction is saved. n must be a non-negative integer.

 

-ScatSd:r,-ScatSs:r,-ScatFraction:r,-ScatAVal:r,-ScatBVal:r,-ScatBeta:r (R,P)
The latest in Fourier (de)blurring techniques will be used to remove the affects of scatter from the system. Still in research mode. The value , will be used as an additional hazard rate in computing the weight matrix. i.e. normal weight matrix will be multiplied by k to form a new weight matrix. 1/A refers to the proportion of direct observations from a source subject to high attenuation path length H, while 1/(A-B), a higher fraction, refers to the proportion of direct observations from a location experiencing no attenuation. Normally A-B=1. The normal projection is combined with the scatter projection in proportion, according to -ScatFraction.

Default is not to use scatter aware versions of algorithms.

 

-SliceSelect:From,To,Step,Combine,Method, -ProjSelect:From,To (R Slice)
Select which slices and/or projections to use. From..To specifies the range to be considered. Step the distance between slice selections. Combine the number of slices to be combined from the starting point. Method can be 0 for add or 1 for average slices being combined. e.g. 1,100,10 select 1 every 10th slice starting at 1 finishing at 100. 8,64,4,4 every 4 slices are added to make a single slice from slice 8 through to slice 64. 8,64,4,4,1 every 4 slices are averaged to make a single slice from slice 8 through to slice 64. The projections option is the same, except you can not (currently) choose Step or Combine or Method.

Programs try to apply the slicing to the major data set and when necessary to other data sets. Alternatively you can specify for each interfile the slicing, by using the trailing slice syntax. e.g. fred.r,0,63,2,2,1. When using R this has the added bonus of showing in the log file, slicing used for each interfile.

Default is all slices and all projections.

 

-StartImage:[=]ifile|+pdef|AUTO (R)
The start image is the basis for the reconstruction. It is modified to produce a more correct image. Default action is to generate a best fit from S a polygon gray image. When specified ifile will be loaded and used instead. ifile must be the same dimensions as described by S and specified options.
+pdef can be used to start from built in phantom descriptions. The prepended "=" will cause ifile or pdef to be set to a uniform gray in non zero areas. Note: You may use a phantom file e.g. GRY.PHN, but the dimensions within the header must match those of the desired reconstruction. -SliceSelect option applies to this option. First the ifile's own slice selection is processed. Then, if needed, the -SliceSelect parameters are used to slice.

 

-StatEPSILON:r (R)
The calculation of Chi-squared makes use of this value. See also -NoStats.

 

-Times:vector (R)
Produces reconstruction of each time slice. Times of each slice in seconds are listed e.g. -Times:0,5,10,30. Many options cannot be used in conjunction with multiple time slices. Try them, to find out which ones. Time slice data is assumed to be sequential within the interfile binary. Default is single time slice at time 0.

 

-TransScale:{AUTO|r|ifile} (R)
When S is a transmission sinogram, this option allows you to correctly reconstruct the attenuation map to correct scale. This option is often used in conjunction with the -FanBeam option. Default is not to perform transmission sinogram scaling.

AUTO

Scale will be uniformly set to
.

r

Scale will be uniformly set to r. r must be a non-negative real.

ifile

Scale will be loaded from the Interfile ifile. This allows non-uniform scaling throughout the sinogram. -SliceSelect option applies to this option. First the ifile's own slice selection is processed. Then, if needed, the -SliceSelect parameters are used to slice except Method is set to 1 ie. average combined slices.

 

S is outlined. All projection bins outside the outline are set to . Now all projection bins are scaled according to . When and are both zero no change is made to . If alone is zero .

 

-TransMethod:{BRIAN|MALCOLM} (R)
Perform a transmission data reconstruction. There are two methods. Brian's method is a translation of the data to emission format then reconstruct. Malcolm's method uses the actual transmission data and processes it statistically correctly. Verdict? Brian's is quicker and seems to produce same result. Note: -TransScale must be specified for this option to be relevant. Default is to perform an emission reconstruction.

 

-TransProj (P)
Creates output as produced by a transmission scan. The values will be scaled such that they have a maximum of 1000.0. Default is to perform emission projection.

 

-RadXYmm:rx,ry (R,P)
The collection camera rotates about an ellipse specified by an X and Y radius. A value of 0 is default and causes the X (Y) radius to be taken from the camera width divided by two or the Gridmm size. Any other value will be used as the camera rotation radius length in mm. rx,ry must be non-negative real values in mm.