CARS Tomography Routines

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.


List of Routines


Routine Descriptions

BACKPROJECT

[Next Routine] [List of Routines]
 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)


GRIDREC

[Previous Routine] [Next Routine] [List of Routines]
 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)


OPTIMIZE_CENTER

[Previous Routine] [Next Routine] [List of Routines]
 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)


READ_TOMO_DATA

[Previous Routine] [Next Routine] [List of Routines]
 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)


READ_TOMO_VOLUME

[Previous Routine] [Next Routine] [List of Routines]
 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)


RECONSTRUCT_SLICE

[Previous Routine] [Next Routine] [List of Routines]
 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)


RECONSTRUCT_VOLUME

[Previous Routine] [Next Routine] [List of Routines]
 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)


REMOVE_TOMO_ARTIFACTS

[Previous Routine] [Next Routine] [List of Routines]
 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)


SINOGRAM

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO::GET_SETUP

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO::PREPROCESS

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO::READ_SETUP

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO::RECONSTRUCT_VOLUME

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO::WRITE_SETUP

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO_FILTER

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO_PARAMS__DEFINE

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO_RECON

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO_RECON_DELETE

[Previous Routine] [Next Routine] [List of Routines]
 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)


TOMO_RECON_POLL

[Previous Routine] [Next Routine] [List of Routines]
 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)


WRITE_TOMO_VOLUME

[Previous Routine] [List of Routines]
 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)