This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Mon May 27 11:30:01 2019.
NAME:
BACKPROJECT
PURPOSE:
Reconstructs a sinogram into an image using backprojection.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
Result = BACKPROJECT(tomoParams, Sinogram, Angles)
INPUTS:
Sinogram:
The input sinogram, dimensions NX x NANGLES. This should have been
filtered before calling this function.
Angles:
An array of dimensions NANGLES which contains the angle in degrees of
each projection.
OUTPUTS:
This function returns the reconstructed image.
PROCEDURE:
This function simply calls the IDL RIEMANN procedure for each row in the
sinogram, using the ROW and BACKPROJECT keywords. The BILINEAR and CUBIC
keywords are passed from BACKPROJECT to RIEMANN if they are present.
EXAMPLE:
r = backproject(sinogram, angles)
MODIFICATION HISTORY:
Written by: Mark Rivers, May 13, 1998
(See backproject.pro)
NAME:
GRIDREC
PURPOSE:
Performs tomographic reconstruction using the "gridrec" algorithm written
by Bob Marr and Graham Campbell (not sure about authors) at BNL in 1997.
The basic algorithm is based on FFTs. It reconstructs 2 data sets at once,
one in the real part of the FFT and one in the imaginary part.
This routine is 20-40 times faster than BACKPROJECT, and yields virtually
identical reconstructions.
This file uses CALL_EXTERNAL to call GridrecIDL.c which is a thin
wrapper to grid.c,
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
GRIDREC, tomoParams, Sinogram1, Sinogram2, Angles, Image1, Image2
INPUTS:
Sinogram1:
The first input sinogram, dimensions NX x NANGLES.
Sinogram2:
The second input sinogram, dimensions NX x NANGLES.
Angles:
An array of dimensions NANGLES which contains the angle in degrees of
each projection.
KEYWORD PARAMETERS:
CENTER: The column containing the rotation axis. The default is the center
of the sinogram.
OUTPUTS:
Image1:
The reconstructed image from Sinogram1.
Image2:
The reconstructed image from Sinogram2.
Note that the sizes of Image1 and Image2 are controlled by "grid" and will not
be equal NX*NX. RECONSTRUCT_SLICE uses the IDL routine CONGRID to resize the
images to be NX*NX.
PROCEDURE:
This function uses CALL_EXTERNAL to call the shareable library GridrecIDL,
which is written in C.
RESTRICTIONS:
GRIDREC locates the GridrecIDL shareable library via the environment variable
GRIDREC_SHARE. This environment variable must be defined and must contain the
name (typically including the path) to a valid shareable library or DLL.
EXAMPLE:
GRIDREC, s1, s2, angles, image1, image2, center=419
MODIFICATION HISTORY:
Written by: Mark Rivers, March 4, 2000
19-APR-2001 MLR Change units of ANGLES from radians to degrees. Write
documentation header.
(See gridrec.pro)
NAME:
OPTIMIZE_CENTER
PURPOSE:
Finds the best rotation center for tomographic reconstruction using the tomo_recon reconstruction code.
This is done by reconstructing a single slice with a set of rotation centers and measuring the image entropy
for each reconstruction. The optimum rotation center is the one that produces the minimum image entropy.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
MinIndex = optimize_center(Slice, InCenter, Step, NumCenter)
INPUTS:
Slice:
A slice to be reconstructed, [NumPixels, NumProjections]
InCenter:
The rotation center to seach about for the optimum.
This can be thought of as the initial guess of the optimum rotation center
Step:
The step size in pixels for the rotation center array. This can be a floating
point number, i.e. fractional pixels are allowed.
NumCenter:
The number of rotation center positions to use. This should be an odd number,
in which case the InCenter value will be in the middle of the CENTER array.
OUTPUTS:
This function returns the index of the center position that results in the minimum entropy
in the reconstructed image. This index can be used to find the optimum center position,
CENTER[MinIndex], the mimimum entropy value, ENTROPY[MinIndex], and the optimum reconstructed
slice, RECON[*,*,MinIndex].
KEYWORD PARAMETERS:
CENTER:
An output array of dimensions NumCenter. It contains the center positions
used in the optimization. It is computed as:
center = inCenter + (findgen(numCenter) - numCenter/2)*step
ENTROPY:
An output array of dimensions NumCenter. It contains the entropy
of the reconstruction at each center position.
The entropy of a slice is computed as follows:
- H, the histogram of the slice is computed, using 10000 bins from HISTMIN to HISTMAX.
- H is scaled (divided) by the number of pixels in the slice
- The entropy is then computed as the sum of H*log(H), summing over the 10000 elements in H
RECON:
An output float array of reconstructed slices [numPixels, numPixels, numCenter].
HISTMIN:
The minimum reconstructed value to be used when computing the histogram to compute
the entropy.
The default is the half minimum value of the center slice in RECON, i.e. min(RECON[*,*,numCenter/2]) * 0.5
HISTMAX:
The maximum reconstructed value to be used when computing the histogram to compute
the entropy.
The default is the twice maximum value of the center slice in RECON, i.e. max(RECON[*,*,numCenter/2]) * 2.0
PROCEDURE:
This function constructs the CENTER array of rotation centers. It then replicates Slice into a
3-D array [NumPixels, NumCenter, NumProjections].
libtomoRecon.so (Linux) or tomoRecon.dll (Windows), which is written in C++.
;
EXAMPLE:
TOMO_RECON, input, output, center=419
MODIFICATION HISTORY:
Written by: Mark Rivers, August 1, 2012
(See optimize_center.pro)
NAME:
READ_TOMO_DATA
PURPOSE:
This procedure reads a tomography data set from individual Princeton
Instruments .SPE files. It writes a 3-D volume file to disk.
This function is a simple wrapper around TOMO::PREPROCESS.
See the documentation for TOMO::PREPROCESS
for information on the input parameters and other details.
PROCEDURE:
This function simply creates a TOMO object and calls TOMO::PREPROCESS.
EXAMPLE:
The following example will read files Mydata1.SPE through Mydata370.SPE,
using a constant dark current of 50 counts at each pixel. This data set
is assumed to have white field frames in it. The output file will be
Mydata.volume
IDL> READ_TOMO_DATA, 'Mydata', 1, 370, dark=50
; Now read the volume file back into IDL
IDL> vol = READ_TOMO_VOLUME('Mydata.volume')
; Play the volume data as a movie, rotating the sample
IDL> window, 0
IDL> make_movie, vol, min=3000, max=12000
MODIFICATION HISTORY:
Written by: Mark Rivers, March 27, 1999.
3-APR-1999 MLR Changed white field normalization to use weighted average
of white fields before and after, rather than simple
average
4-APR-1999 MLR Changed the default value of threshold from 1.20 to 1.05
Switched to double correlation method of zinger removal
for white field images when possible.
18-MAY-1999 MLR Added missing keyword DOUBLE_THRESHOLD to procedure line
07-JUL-1999 MLR Changed zinger removal for data frames so it is done after
whitefield correction. This makes the identification of
zingers (versus high-frequency structure in the whitefield)
much more robust.
13-SEP-1999 MLR Changed the dark current correction to use a loop, so that
two large arrays are not required at the same time.
08-DEC-1999 MLR Added FIRST_ROW and LAST_ROW keywords for handling very
large data sets.
Added OUTPUT keyword
02-MAR-2000 MLR Added DEBUG keyword to calls to REMOVE_TOMO_ARTIFACTS
large data sets.
02-MAR-2000 MLR Changed the default value of THRESHOLD from 1.05 to 1.25
because the lower threshold was causing significant
blurring of sharp edges. Changed the default value of
DOUBLE_THRESHOLD from 1.02 to 1.05, since it was finding
many more zingers than physically plausible.
02-MAR-2000 MLR Added SWAP_IF_BIG_ENDIAN keyword when opening output file.
22-JAN-2001 MLR Added some default debugging when writing output file
11-APR-2001 MLR Put the original version in the TOMO class library and renamed
the procedure there PREPROCESS rather than READ_TOMO_DATA.
Made this procedure simply create a TOMO object and call
TOMO::PREPROCESS.
(See read_tomo_data.pro)
NAME:
READ_TOMO_VOLUME
PURPOSE:
Reads in 3-D volume files written by WRITE_TOMO_VOLUME or TOMO::WRITE_VOLUME.
This function is a simple wrapper around TOMO::READ_VOLUME.
See the documentation for TOMO::READ_VOLUME
for information on the input parameters and other details.
PROCEDURE:
This function simply creates a TOMO object and calls TOMO::READ_VOLUME.
EXAMPLE:
volume = READ_TOMO_VOLUME('diamond2.volume')
MODIFICATION HISTORY:
Written by: Mark Rivers, May 13, 1998
06-APR-1999 MLR Made file input optional, puts up dialog if it is not
specified
25-JAN-2000 MLR Added /swap_if_big_endian keyword to openr to allow
files to be read on big-endian machines.
23-FEB-2000 MLR Added xrange, yrange, zrange keywords
11-APR-2001 MLR Put the original version in the TOMO class library, made this
function simply create a TOMO object and call TOMO::READ_VOLUME.
(See read_tomo_volume.pro)
NAME:
RECONSTRUCT_SLICE
PURPOSE:
Reconstructs a single slice in a tomography volume array.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
Result = RECONSTRUCT_SLICE(tomoParams, Slice, Volume)
INPUTS:
tomoParams: A tomo_params structure
Slice: The number of the slice to be reconstructed.
Volume: The 3-D volume array from which the slice is extracted
KEYWORD PARAMETERS:
ANGLES:
An array of angles (in degrees) at which each projection was collected.
If this keyword is not specified then the routine assumes that the data was
collected in evenly spaced increments of 180/n_angles.
CENTER:
The rotation centers. If this keyword is not specified then the
center is assumed to be the center pixel of the image
OUTPUTS:
This function returns the reconstructed slice. It is a floating point
array of dimensions NX x NX.
PROCEDURE:
Does the following: extracts the slice, computes the sinogram with
centering and optional center tweaking, removes ring artifacts, filters
with a Shepp-Logan filter and backprojects. It also prints the time
required for each step at the end.
EXAMPLE:
r = reconstruct_slice(tomoParams, 264, volume)
MODIFICATION HISTORY:
Written by: Mark Rivers, May 13, 1998
Many changes over time, see CVS log.
(See reconstruct_slice.pro)
NAME:
RECONSTRUCT_VOLUME
PURPOSE:
This procedure reconstructs a complete 3-D data set (X, Y, Theta) into a
3-D (X, Y, Z) volume. It reads its input from disk and writes its output
back to disk.
This procedure is a simple wrapper around TOMO::RECONSTRUCT_VOLUME().
See the documentation for TOMO::RECONSTRUCT_VOLUME
for information on the input parameters and other details.
EXAMPLE:
reconstruct_volume, 'FOSSIL1', CENTER=329
MODIFICATION HISTORY:
Written by: Mark Rivers, April 23, 1999
30-APR-1999 MLR Fixed bug introduced by new version of sinogram, need
to get size of reconstructed slices after centering
18-MAY-1999 MLR Changed formal parameter _extra to _ref_extra to allow
CENTER keyword value to be returned from sinogram (via
reconstruct_slice).
23-FEB-2000 MLR Pass extra keywords to read_tomo_volume
7-MAR-2000 MLR Added support for GRIDREC reconstruction, which reconstructs
2 slices at once.
2-JAN-2001 MLR Added CENTER keyword. If it is a 2-element array then the
center is interpolated.
11-APR-2001 MLR Put the original version in the TOMO class library, made this
procedure simply create a TOMO object and call
TOMO::RECONSTRUCT_VOLUME.
(See reconstruct_volume.pro)
NAME:
REMOVE_TOMO_ARTIFACTS
PURPOSE:
Removes artifacts from tomography images and sinograms.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
Result = REMOVE_TOMO_ARTIFACTS(Image)
INPUTS:
Image: The input array from which artifacts are to be removed.
KEYWORD PARAMETERS:
IMAGE2:
A second input and output image when doing DOUBLE_CORRELATION
ZINGERS:
Set this keyword to remove zingers from the input image
DOUBLE_CORRELATION:
Set this keyword to remove zingers from the input using double
correlation rather than a spatial detection
RINGS:
Set this keyword to remove ring artifacts from a sinogram
DIFFRACTION:
Set this keyword to removed diffraction artifacts from a sinogram
WIDTH:
Set this keyword to adjust the size of the filter kernal used in the
artifact removal. The default is 9 pixels.
THRESHOLD:
Set this keyword to adjust the threshold used in detecting zingers and
diffraction artifacts. The defaults are 1.2 for /ZINGER and
/DOUBLE_CORRELATION and 0.8 for/DIFFRACTION
DEBUG:
Set this keyword to print debugging information
OUTPUTS:
This function returns an image with the specified artifacts removed.
PROCEDURE:
THIS STILL NEEDS TO BE DOCUMENTED. For now, see the source code.
EXAMPLE:
r = remove_tomo_artifacts(sinogram, /Rings)
MODIFICATION HISTORY:
Written by: Mark Rivers, May 13, 1998
MLR 4/4/99 MLR Added DOUBLE_CORRELATION keyword
MLR 4/5/99 MLR Added /EDGE_TRUNCATE to all calls to SMOOTH so that
smoothing works to the edges of the image
(See remove_tomo_artifacts.pro)
NAME:
SINOGRAM
PURPOSE:
To convert raw tomography data into a sinogram.
CATEGORY:
Tomography
CALLING SEQUENCE:
result = SINOGRAM(Input, Angles)
INPUTS:
Input
An array of raw tomography data. INPUT(I, J) is the intensity at
position I for view angle J. Each row is assumed to contain at least
one air value at each end for normalization.
Angles
An array of the angles of each row of the input. Units are degrees.
COG=cog
This keyword is used to return the measured and fitted
center-of-gravity data for the sinogram. The center-of-gravity data are
very useful for diagnosing problems such as backlash, beam hardening,
detector saturation, etc. COG is dimensioned (n_angles, 2), where
n_angles is the number of angles in the input array. COG(*,0) is the
measured center-of-gravity data. COG(*,1) is the fitted data. The
following command can then be given after the SINOGRAM command
IDL> PLOT, COG(*,0)
IDL> OPLOT, COG(*,1)
to see is the sinogram data are reasonable.
RETURN:
The output array containing the corrected sinogram. It is always of
type FLOAT.
PROCEDURE:
This routine creates a sinogram from raw tomography data. It does the
following:
- Averages the air values for "airPixels" pixels on the left and
right hand sides of the input.
- Logarithmation. output = -log(input/air). The air values are
interpolated between the averaged values for the left and right
hand edges of the image for each row. This step is not performed
if the /FLUORESCENCE keyword is set.
- The measured center-of-gravity is fitted to a sinusoidal curve
of the form Y = A(0) + A(1)*SIN(X + A(2)).
A(0) is the rotation axis
A(1) is the amplitude
A(2) is the phase
The fitting is done using routine CURVE_FIT in the User Library.
The shifting is done using routine POLY_2D which can shift by
fractional pixels.
MODIFICATION HISTORY:
Created 21-OCT-1991 by Mark Rivers.
(See sinogram.pro)
NAME:
TOMO::GET_SETUP
PURPOSE:
This function returns the setup information for a tomography data set
CATEGORY:
Tomography
CALLING SEQUENCE:
setup = TOMO->GET_SETUP()
OUTPUTS:
This function returns a structure of type {TOMO} containing the information
about the tomography dataset. The current definition of the {TOMO}
structure is:
{tomo, $
title: " ", $
operator: " ", $
camera: " ", $
sample: " ", $
comments: ptr_new(), $
image_type: " ", $ ; "RAW", "CORRECTED" or "RECONSTRUCTED"
dark_current: 0., $
center: 0., $
energy: 0., $
x_pixel_size: 0., $
y_pixel_size: 0., $
z_pixel_size: 0., $
scale_factor: 0., $
nx: 0L, $
ny: 0L, $
nz: 0L, $
angles: ptr_new() $
}
This definition is subject to change in the future, but the above fields
will not change, new fields may be added.
EXAMPLE:
IDL> tomo = obj_new('TOMO')
IDL> status = TOMO->READ_SETUP('Sample1.setup')
IDL> setup = TOMO->GET_SETUP()
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 18, 2001
(See tomo__define.pro)
NAME:
TOMO::PREPROCESS
PURPOSE:
This procedure reads a tomography data set from individual Princeton
Instruments .SPE files. It writes a 3-D volume file to disk.
CATEGORY:
Tomography
CALLING SEQUENCE:
TOMO->PREPROCESS, Base_file, First, Last
INPUTS:
Base_file:
The base file name for the data set. The actual file name are assumed
to be of the form Base_file + strtrim(file_number,2) + '.SPE'.
First:
The number of the first file, typically 1.
Last:
The number of the last file
KEYWORD PARAMETERS:
THRESHOLD:
The threshold for zinger removal in normal frames. See documentation
for REMOVE_TOMO_ARTIFACTS for details. Default=1.25
DOUBLE_THRESHOLD:
The threshold for zinger removal in white field frames using double
correlation. Default=1.05
DARK:
The dark current, either a scaler or a 2-D array. If this is a scaler
value then a constant dark current is subtracted from each pixel in
every frame. If this is a 2-D array then it must have the same
dimensions as each frame in the data set. In this case the specified
2-D dark current will be substracted from each frame in the data set.
Note that if the data set contains dark current frames (frame type =
DARK_FIELD) then this keyword is normally not used.
FIRST_ROW:
The starting row (slice) to be processed. The default is 0. This
keyword, together with LAST_ROW below are provided for processing
data sets which are too large to be read into memory in their
entirety. It lets one create multiple volume arrays from a single
data set, for example rows 0-300 in file 1, (FIRST_ROW=0, LAST_ROW=300)
rows 301-600 in file 2, etc.
LAST_ROW:
The ending row (slice) to be processed. The defaults is the last row
in each image. See comments under FIRST_ROW above.
WHITE_FIELD:
The white field value, either a scaler or a 2-D array. If this is a
scaler value then each pixel in each data frame is normalized by this
constant value. If this is a 2-D array then it must have the same
dimensions as each frame in the data set. In this case then each data
frame in the data set is normalized by the specified 2-D array.
Note that if the data set contains white field frames (frame type =
FLAT_FIELD), which is typically the case, then this keyword is
normally not used.
WHITE_AVERAGE:
Set this flag to 1 to process the flat fields by averaging all of them
together. The default (WHITE_AVERAGE=0) is to interpolate flat fields in time.
NOTE: The default value for this flag is 0 for backward compatibility.
However, in general setting WHITE_AVERAGE=1 greatly reduces ring artifacts
compared with the default interpolation method, so it's use is strongly
recommended.
WHITE_SMOOTH:
The size of the smoothing kernal for smoothing the white fields. Set this
value to 2 or more to smooth the white fields before normalization.
Since white fields generally do not have much high frequency content,
smoothing can be used to reduce noise in the normalization.
Default=0 (no smoothing).
OUTPUT:
The name of the output file. The default is Base_file + '.volume'
STATUS_WIDGET:
The widget ID of a text widget used to display the status of the
preprocessing operation. If this is a valid widget ID then
informational messages will be written to this widget.
ABORT_WIDGET
The widget ID of a widget used to abort the preprocessing operation.
If this is a valid widget ID then the "uvalue" of this widget will be
checked periodically. If it is 1 then this routine will clean up and
return immediately.
DEBUG:
A debugging flag. Allowed values are:
0: No informational output
1: Prints each input filename as it is read, and prints limited
information on processing steps
2: Prints detailed information on processing steps
FLIP_DATA
Rotates image data 90 degrees
OUTPUTS:
This function returns a 3-dimensional signed 16-bit integer volume array
of size [NCOLS, NROWS, NANGLES]. The data is the ratio of the input image
to the flat field, multiplied by 10,000. The ratio of the data to the
flat field should be in the range 0 to 1 (with occasional values slightly
greater than 1). Multiplying by 10000 should give sufficient resolution,
since even values with 99% absorption will be stored with a precision of
1%.
RESTRICTIONS:
- There must not be any missing files between the numbers specified by the
First and Last parameters.
- The input files must follow the naming convention Base_file +
strtrim(number,2) + '.SPE', where number varies from First to Last.
- By storing the normalized data as 16-bit integers, there is a
possibility of loss of some information when using a true 16-bit camera.
PROCEDURE:
This function performs the following steps:
- Reads each frame in the data set into a large 3-D data buffer. Stores
a flag for each frame indicating if the frame is a dark current, a
white field or normal data.
Stores the rotation angle at which each frame was collected.
- Subtracts the dark current from each data frame and white field frame,
using dark current images in the data set if present, or the input dark
current if present.
If the data set contains multiple dark current frames, then the
correction is done as follows:
- Use the first dark current for all frames collected before the
first dark current
- Use the last dark current for all frames collected after the last
dark current
- Use the average of the closest preceeding and following dark
currents for all frames collected between two dark currents.
- Removes zingers from white field frames using REMOVE_TOMO_ARTIFACTS with
/DOUBLE_CORRELATION if possible, or /ZINGERS if not.
- Divides each data frame by the white field, using white field images in
the data set, or the input white field if present. If the
data set contains multiple white field frames, and WHITE_AVERAGE=0,
then the correction is done as follows:
- Use the first white field for all frames collected before the
first white field
- Use the last white field for all frames collected after the last
white field
- Use the weighted average of the closest preceeding and following white
fields for all frames collected between two white fields.
If WHITE_AVERAGE=1 then all of the white fields in the data are averaged
before normalizing. This is recommended.
The ratio of each frame to the white field is multiplied by 10,000 to be
able to use 16 bit integers, rather than floats to store the results,
saving a factor of 2 in memory, which is important for these large 3-D
data sets.
- Sorts the rotation angle array, to determine the order in which the
normalized data frames should be written back out to disk in the volume
file.
- Corrects for zingers in the white-field normalized data frames, using
REMOVE_TOMO_ARTIFACTS, /ZINGERS.
- Writes the normalized data frames to a single disk file. The default
file name is Base_file + '.volume'. This file is in little-endian binary
format, with the following data:
- NCOLS (long integer, number of columns in each frame)
- NROWS (long integer, number of rows in each frame)
- NANGLES (long integer, number of frames)
- DATA (short integer array [NCOLS, NROWS, NANGLES]
The volume file can be read back in to IDL with function
READ_TOMO_VOLUME
EXAMPLE:
The following example will read files Mydata1.SPE through Mydata370.SPE,
using a constant dark current of 50 counts at each pixel. This data set
is assumed to have white field frames in it. The output file will be
Mydata.volume
IDL> READ_TOMO_DATA, 'Mydata', 1, 370, dark=50
; Now read the volume file back into IDL
IDL> vol = READ_TOMO_VOLUME('Mydata.volume')
; Play the volume data as a movie, rotating the sample
IDL> window, 0
IDL> make_movie, vol, min=3000, max=12000
MODIFICATION HISTORY:
Written by: Mark Rivers, March 27, 1999.
3-APR-1999 MLR Changed white field normalization to use weighted average
of white fields before and after, rather than simple
average
4-APR-1999 MLR Changed the default value of threshold from 1.20 to 1.05
Switched to double correlation method of zinger removal
for white field images when possible.
18-MAY-1999 MLR Added missing keyword DOUBLE_THRESHOLD to procedure line
07-JUL-1999 MLR Changed zinger removal for data frames so it is done after
whitefield correction. This makes the identification of
zingers (versus high-frequency structure in the whitefield)
much more robust.
13-SEP-1999 MLR Changed the dark current correction to use a loop, so that
two large arrays are not required at the same time.
08-DEC-1999 MLR Added FIRST_ROW and LAST_ROW keywords for handling very
large data sets.
Added OUTPUT keyword
02-MAR-2000 MLR Added DEBUG keyword to calls to REMOVE_TOMO_ARTIFACTS
large data sets.
02-MAR-2000 MLR Changed the default value of THRESHOLD from 1.05 to 1.25
because the lower threshold was causing significant
blurring of sharp edges. Changed the default value of
DOUBLE_THRESHOLD from 1.02 to 1.05, since it was finding
many more zingers than physically plausible.
02-MAR-2000 MLR Added SWAP_IF_BIG_ENDIAN keyword when opening output file.
22-JAN-2001 MLR Added some default debugging when writing output file
11-APR-2001 MLR Changed the name of this routine from READ_TOMO_DATA to
TOMO::PREPROCESS when it was incorporated in the TOMO class
library.
This routine now updates the .SETUP file with the dark current
that was specified when running this procedure.
The output file is now written with TOMO::WRITE_VOLUME rather
than being incrementally written as the data are processed. This
requires more memory, but is necessary to allow use of netCDF
and other file formats.
1-NOV-2001 MLR Added BUFF_ANGLES keyword
20-NOV-2001 MLR Added ABORT_WIDGET and STATUS_WIDGET keywords
25-APR-2002 MLR Added support for reading 3-D .SPE files, created when doing
fast scanning
18-DEC-2005 MLR Added white_average and white_smooth keywords.
Renamed WHITE keyword to WHITE_FIELD
Setting white_average greatly reduces ring artifacts in many cases.
(See tomo__define.pro)
NAME:
TOMO::READ_SETUP
PURPOSE:
This function reads the setup information for a tomography data set from an
ASCII file.
CATEGORY:
Tomography
CALLING SEQUENCE:
result = TOMO->READ_SETUP(File)
INPUTS:
File:
The name of the input file.
OUTPUTS:
This function returns 0 if it was unable to read the file, 1 if it was
successful.
EXAMPLE:
IDL> status = TOMO->READ_SETUP('Sample1.setup')
MODIFICATION HISTORY:
Written by: Mark Rivers, Aug. 2001?
(See tomo__define.pro)
NAME:
TOMO::RECONSTRUCT_VOLUME
PURPOSE:
This procedure reconstructs a complete 3-D data set (X, Y, Theta) into a
3-D (X, Y, Z) volume. It reads its input from disk and writes its output
back to disk.
CATEGORY:
Tomography.
CALLING SEQUENCE:
TOMO->RECONSTRUCT_VOLUME, Base_file
INPUTS:
Base_file:
The base file name. The input file is assumed to be named
base_file+'.volume', and the output file will be named
base_file+'_recon.volume'. The input file is read with
READ_TOMO_VOLUME and the output file is written with WRITE_TOMO_VOLUME.
KEYWORD PARAMETERS:
This procedure accepts all keywords accepted by READ_TOMO_VOLUME and
RECONSTRUCT_SLICE and simply passes them to those routines via keyword
inheritance.
CENTER
This keyword, which is passed to RECONSTRUCT_SLICE can either be a scaler (the
normal case) or a 2-element array. If it is a 2-element array then the
center value passed to RECONSTRUCT_SLICE is interpolated between CENTER[0]
for the first slice of the volume file to CENTER[1] at the last slice of the
volume file. This can be useful if the optimum center varies with slice
depth.
ANGLES
An optional array of angles (in degrees) at which each projection was taken.
This keyword is passed to RECONSTRUCT_SLICE. If this keyword is missing
then RECONSTRUCT_SLICE assumes even spacing from 0 to 180-delta degrees.
SCALE
The scale factor by which the data should be multiplied before writing as
short integers to the output file. The default is 1.e6. Since the
attenuation values are per-pixel, and are typically 0.001, this leads to
integers in the range of 10,000. If there are highly attenuating pixels the
scale factor may need to be decreased to 1-5e5 to avoid integer overflow.
The inverse of the SCALE is stored as the attribute volume:scale_factor
in the netCDF file.
STATUS_WIDGET:
The widget ID of a text widget used to display the status of the
preprocessing operation. If this is a valid widget ID then
informational messages will be written to this widget.
ABORT_WIDGET
The widget ID of a widget used to abort the preprocessing operation.
If this is a valid widget ID then the "uvalue" of this widget will be
checked periodically. If it is 1 then this routine will clean up and
return immediately.
OUTPUTS:
This procedure writes its results to a file base_file+'_recon.volume'
RESTRICTIONS:
This procedure assumes a naming convention for the input and output files.
The output is stored as 16 bit integers to save memory and disk space.
This can reduce the dynamic range of the reconstructed data.
PROCEDURE:
This procedure simply does the following:
- Reads a corrected input volume (X, Y, Theta) which is typically
created with READ_TOMO_DATA
- Calls RECONSTRUCT_SLICE for each row (slice) in the input volume
- Scales the reconstructed data (floating poing) by 10000 and converts
to 16 bit integers
- Writes the reconstructed 3-D volume (X, Y, Z) back to disk with
WRITE_TOMO_VOLUME
EXAMPLE:
reconstruct_volume, 'FOSSIL1', /AUTO_CENTER
MODIFICATION HISTORY:
Written by: Mark Rivers, April 23, 1999
30-APR-1999 MLR Fixed bug introduced by new version of sinogram, need
to get size of reconstructed slices after centering
18-MAY-1999 MLR Changed formal parameter _extra to _ref_extra to allow
CENTER keyword value to be returned from sinogram (via
reconstruct_slice).
23-FEB-2000 MLR Pass extra keywords to read_tomo_volume
7-MAR-2000 MLR Added support for GRIDREC reconstruction, which reconstructs
2 slices at once.
2-JAN-2001 MLR Added CENTER keyword. If it is a 2-element array then the
center is interpolated.
11-APR-2001 MLR Incorporated the previous routine RECONSTRUCT_VOLUME into the
TOMO class library.
This procedure now updates the .SETUP file with the center
value which was used for the reconstruction.
12-APR-2001 MLR Added SCALE and angles keywords since we need to process them
here.
22-NOV-2001 MLR Added STATUS_WIDGET and ABORT_WIDGET keywords
02-APR-2002 MLR Fixed bugs with STATUS_WIDGET and ABORT_WIDGET
11-APR-2002 MLR Fixed bug introduced on 02-APR with center
(See tomo__define.pro)
NAME:
TOMO::WRITE_SETUP
PURPOSE:
This function writes the setup information for a tomography data set to an
ASCII file.
CATEGORY:
Tomography
CALLING SEQUENCE:
result = TOMO->WRITE_SETUP(File)
INPUTS:
File:
The name of the output file.
OUTPUTS:
This function returns 0 if it was unable to write the file, 1 if it was
successful.
EXAMPLE:
IDL> status = TOMO->WRITE_SETUP('Sample1.setup')
MODIFICATION HISTORY:
Written by: Mark Rivers, Aug. 2001?
(See tomo__define.pro)
NAME:
TOMO_FILTER
PURPOSE:
Filters a sinogram before backprojection. A selection of filters is
available.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
Result = TOMO_FILTER(Sinogram, Filter_size, D)
INPUTS:
Sinogram: The unfiltered sinogram. This must be a 2-D array.
OPTIONAL INPUTS:
Filter_size: The half-size of the filter in pixels. The default is NX/4 where
NX is the first dimension of the sinogram.
D: An additional filter parameter. The default is 1.0
KEYWORD PARAMETERS:
FILTER_NAME: A case-insensitive string specifying the filter to be used.
Allowed values are:
'GEN_HAMMING'
'LP_COSINE'
'SHEPP_LOGAN'
'RAMLAK'
'NONE'
The default is 'SHEPP_LOGAN'
OUTPUTS:
This function returns the filtered sinogram.
PROCEDURE:
For each row in the sinogram, this function simply does the following:
Pads the input sinogram
Does a convolution with the appropriate filter
The code for the filters was taken from the IDL tomography demo program
which is included in the IDL distribution. It would be easy to add
additional filters in the future.
EXAMPLE:
f = tomo_filter(sinogram, filter_name='SHEPP_LOGAN')
MODIFICATION HISTORY:
Written by: Mark Rivers, May 13, 1998
25-Nov-2001 MLR Changed the keywords from names of individual filters
(e.g. /SHEPP_LOGAN) to FILTER_NAME
Changed the default filter size from 32 to NX/4
(See tomo_filter.pro)
NAME: TOMO_PARAMS__DEFINE PURPOSE: Defines a structure which controls tomography reconstruction parameters for tomo_recon. This structure is passed directly to the C++ code in the shareable library. MODIFICATION HISTORY: Written by: Mark Rivers, August 1, 2012
(See tomo_params__define.pro)
NAME:
TOMO_RECON
PURPOSE:
Performs tomographic reconstruction using the tomoRecon object from
tomoRecon.cpp and tomoReconIDL.cpp.
tomoRecon uses the "gridrec" algorithm written
by Bob Marr and Graham Campbell (not sure about authors) at BNL in 1997.
The basic algorithm is based on FFTs.
This file uses CALL_EXTERNAL to call tomoReconIDL.cpp which is a thin
wrapper to tomoRecon.cpp.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
tomo_recon, tomoParams, Input, Output
INPUTS:
Input:
An array of normalized projections, dimensions [numPixels, numSlices, numProjections].
This array will be converted to type FLOAT if it is another data type.
OUTPUTS:
Output:
A FLOAT array of reconstructed slices, dimensions [numPixels, numPixels, numSlices].
KEYWORD PARAMETERS:
CREATE:
Set this keyword to 1 to create a new tomoRecon object. This is the default.
Set this keyword to 0 to use an existing tomoRecon object created by a previous
call to this function. Note that all reconstruction parameters except numSlices
and CENTER must be the same when using an existing tomoRecon object.
ANGLES:
An array of dimensions numProjections which contains the angle in degrees of
each projection. The default is numProjections spaced evenly from 0 to
180-angleStep.
WAIT:
Controls whether this procedure waits for the reconstruction to complete (WAIT=1),
or returns immediately to the calling function while the reconstruction continues to run
in its own threads (WAIT=0). Default is WAIT=1.
COMMON BLOCKS:
TOMO_RECON_COMMON:
This common block is used to hold the name of the shareable library that is called from IDL.
PROCEDURE:
This function uses CALL_EXTERNAL to call the shareable library.
libtomoRecon.so (Linux) or tomoRecon.dll (Windows), which is written in C++.
RESTRICTIONS:
TOMO_RECON locates the tomoRecon IDL shareable library first by seeing if the environment variable TOMO_RECON_SHARE exists.
If it does then this must point to the complete path to the shareable library.
On Linux this might be e.g. /home/myaccount/idl_tomography/tomoRecon_linux_x86_64.so.
On Windows it might be C:\idl_tomography\tomoRecon_Win32_x86_64.dll.
If the environment variable does not exist, then it looks for the shareable library in the IDL "path", and the
shareable library must be named: 'tomoRecon_' + !version.os + '_' + !version.arch + '.so' or '.dll'
For example, tomoRecon_Win32_x86_64.dll or tomoRecon_linux_x86_64.so. On Linux this can be done with soft-links to the
actual shareable library file if necessary.
The search of the IDL "path" only works when using the licensed version of IDL.
When using the free IDL Virtual Machine the TOMO_RECON_SHARE environment variable must be defined.
On Windows tomoRecon also needs to be able to find the shareable DLL for the FFTW library.
Unfortunately because this library is not called directly by IDL, but only indirectly by the tomoRecon library,
the location of the FFTW library must be added to your PATH environment variable.
This is done by adding something like the following to your path, C:\idl_tomography\win64dll, where win64dll
is a directory shipped with the GSECARS tomography software.
EXAMPLE:
TOMO_RECON, input, output, center=419
MODIFICATION HISTORY:
Written by: Mark Rivers, August 1, 2012
(See tomo_recon.pro)
NAME:
TOMO_RECON_DELETE
PURPOSE:
Deletes the tomoRecon object created by tomo_recon. This function can be called to explicitly delete the tomoRecon
C++ object. It typically does not need to be called, because object is automatically deleted when tomo_recon is
called again with the create=1 (default) option, or when IDL exits. The overhead of leaving the object in existence is small.
This file uses CALL_EXTERNAL to call tomoReconIDL.cpp which is a thin
wrapper to tomoRecon.cpp.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
tomo_recon_delete
COMMON BLOCKS:
TOMO_RECON_COMMON:
This common block is used to hold the name of the shareable library that is called from IDL.
PROCEDURE:
This function uses CALL_EXTERNAL to call the shareable library.
libtomoRecon.so (Linux) or tomoRecon.dll (Windows), which is written in C++.
EXAMPLE:
TOMO_RECON_DELETE
MODIFICATION HISTORY:
Written by: Mark Rivers, August 1, 2012
(See tomo_recon.pro)
NAME:
TOMO_RECON_POLL
PURPOSE:
Polls the tomoRecon object created by tomo_recon to read the reconstruction status and the
number of slices remaining.
This file uses CALL_EXTERNAL to call tomoReconIDL.cpp which is a thin
wrapper to tomoRecon.cpp.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
tomo_recon_poll, reconComplete, slicesRemaining
OUTPUTS:
reconComplete:
reconComplete=1 if the reconstruction is complete, 0 if it is not yet complete.
slicesRemaining
slicesRemaining is the number of slices remaining to be reconstructed.
COMMON BLOCKS:
TOMO_RECON_COMMON:
This common block is used to hold the name of the shareable library that is called from IDL.
PROCEDURE:
This function uses CALL_EXTERNAL to call the shareable library.
libtomoRecon.so (Linux) or tomoRecon.dll (Windows), which is written in C++.
EXAMPLE:
TOMO_RECON_POLL, reconComplete, slicesRemaining
MODIFICATION HISTORY:
Written by: Mark Rivers, August 1, 2012
(See tomo_recon.pro)
NAME:
WRITE_TOMO_VOLUME
PURPOSE:
Writes 3-D volume files to be read later by READ_TOMO_VOLUME or TOMO::
READ-VOLUME.
This function is a simple wrapper around TOMO::WRITE_VOLUME.
See the documentation for TOMO::WRITE_VOLUME
for more information.
CATEGORY:
Tomography data processing
CALLING SEQUENCE:
WRITE_TOMO_VOLUME, File, Volume
PROCEDURE:
This function simply creates a TOMO object and calls TOMO::WRITE_VOLUME.
EXAMPLE:
WRITE_TOMO_VOLUME, 'diamond2.volume', volume
MODIFICATION HISTORY:
Written by: Mark Rivers, May 13, 1998
26-JAN-2000 MLR Added /swap_if_big_endian keyword to openw to allow
files to be read on big-endian machines.
04-MAR-2001 MLR Added support for netCDF file format. Added NETCDF
and SETUP keywords
11-APR-2001 MLR Put the original version in the TOMO class library, made this
function simply create a TOMO object and call TOMO::WRITE_VOLUME.
(See write_tomo_volume.pro)