Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

DENSNORM(1)							   DENSNORM(1)

NAME
  densnorm - Normalize densities in an image file

SYNOPSIS
  densnorm [options] [Input_file] [Output_file]

DESCRIPTION
  Densnorm can normalize images by dividing by the incident illumination, an
  operation usually referred to as mass normalization.  It can take the log of
  normalized data, or simply take the log of the input data.  It can also
  output weighting factors that can be supplied to Tilt to provide a
  relative normalization of the data, thus avoiding the need to write a
  normalized file.

  Mass normalization is done in order to bring different images to a common
  scale so that they all represent projections of the same structure.  That
  way, images at different angles will be appropriately weighted in a
  backprojection.  A relative normalization, where images are just adjusted for
  different exposures, is sufficient for this purpose.  An absolute
  normalization is useful if one wants images that are proportional to the sum
  of the mass densities in the specimen, with no additive constants.  Absolute
  normalization requires information about the image intensity that would be
  produced by the unattenuated beam.  With this information, the program can
  compute a transmittance value, I/I0, where I is the image intensity at each
  pixel and I0 is the intensity produced by the unattenuated beam.

  The treatment of transmittance values depends on whether the log is going to
  be taken of the data.  This choice would depend on the source of contrast.
  For stained samples where amplitude contrast dominates, the projected mass
  density should be proportion to the negative of the log of the
  transmittance.  In this case, taking the log of the transmittance is
  appropriate and will result in negative values, where 0 corresponds to 0
  projected mass.  When phase contrast dominates, it seems that the amount of
  attenuation of the beam should be proportional to the linear sum of mass
  densities.  Here, it should be appropriate not to take the log.  Thus, when
  the log is not being taken, the program will express the densities as
  attenuations by taking one minus the transmittance (1 - I/I0).  These
  attenuations will also be negative numbers, with 0 corresponding to 0 mass.
  In either case, you can convert the negative values to positive ones, but
  this will reverse the contrast of the data and make density appear white.

  Standard R-weighted backprojection as implemented in Tilt is insensitive
  to the mean value of images, and there is no value in having an absolute
  normalization.  On the other hand, having density values where 0 means 0
  mass is potentially important for algebraic reconstruction techniques, where
  it is possible to constrain values to be all positive or all negative.
  These considerations motivate the following recommendations for various
  cases:

  1) R-weighted back projection when taking the log: Do not bother to normalize
  the data; it should have no effect.

  2) R-weighted back projection when not taking the log: A relative
  normalization is sufficient; use this program either to normalize the data
  or to compute weighting factors to pass to Tilt.

  3) Algebraic technique without zero constraints, and taking the log:
  Normalization is unnecessary but use this program to take the log before
  starting the reconstruction procedure.

  4) Algebraic technique without zero constraints, and without taking the
  log: A relative normalization is sufficient; as in 2), either normalize the
  data or pass weighting factors to Tilt (assuming Tilt will be involved
  in the algebraic technique).

  5) Algebraic technique with zero constraints, and taking the log: An
  absolute normalization is needed, using reference image data; take the log
  after normalizing.

  6) Algebraic technique with zero constraints, and without taking the log: An
  absolute normalization is needed.

  Densnorm uses the PIP package for input exclusively (see the manual page for
  pip).  The following options can be specified either as command line
  arguments (with the -) or one per line in a command file or parameter file
  (without the -):

 -input OR -InputImageFile   File name
    Input file with images to be normalized, or whose header contains the
    exposure data needed for scaling.  This entry is optional unless an output
    image file is entered.  If the option is not entered and there is a
    non-option argument, the latter will be used as the input file.

 -output OR -OutputImageFile   File name
    Output file for normalized images.  If this option is not entered, the
    second non-option argument will be used for this output file.

 -weight OR -WeightOutputFile   File name
    Output file with weighting factors that can be supplied to Tilt, which
    can be either relative factors with a mean of 1 or factors that would
    convert each image to transmittances.

 -images OR -ImagesWithExposures   File name
    Image file with exposure information in header.  Use this option to
    specify a raw stack if the images to be normalized no longer have exposure
    data in their header, such as would occur with montages.

 -rifile OR -ReferenceImageFile   File name
    File with a reference image of the blank beam.  If the mean value and the
    exposure for a reference image is known, then the exposure value for each
    image can be used to scale the data to transmittances.

 -rimean OR -MeanOfReferenceImage   Floating point
    Mean value of a reference image, which can be used for absolute
    normalization to transmittances.  This option and the reference image file
    cannot both be entered.

 -riexp OR -ExposureOfReferenceImage   Floating point
    Exposure time or electron dose of a reference image, which can be combined
    with the exposure values for each view to achieve absolute normalization. 
    If this option is entered together with a reference image file, the given
    value supercedes the exposure value in the header of the reference image,
    if any.

 -subtracted OR -SubtractedIntegers
    One of the ways of storing data from a 16-bit camera into the signed
    integer mode, 1, is to subtract 32768.  Use this option to indicate that
    this occurred, and to have 32768 added back before normalization.

 -resub OR -Resubtract
    Subtract 32768 off again after normalizing subtracted integers.

 -divide OR -DivideBy2
    Divide by 2 after normalizing subtracted integers.  This option and
    -resubtract are relevant only if the data were subtracted integers, a
    relative normalization is being done, the mode of the output file is 1,
    and logs are not being taken.  If there are values above 0 in the input
    file, one or the other option is needed to avoid truncating these values.

 -log OR -LogOfOutput   Floating point
    Take log of output values after adding the given value.  If the data have
    had 32768 subtracted from them, and you are just taking the log, you can
    enter "-log 32768" without using the -subtracted option, or "-log 0" with
    the -subtracted option.

 -mode OR -ModeOfOutput   Integer
    Mode of output file: 0 for bytes (almost certainly useless), 1 for signed
    16-bit integers, 6 for unsigned 16-bit integers, or 2 for floating point
    numbers.  The default is to use the mode of the input file.

 -scale OR -ScalingFactor   Floating point
    Factor for scaling the output after data are normalized and the log is
    taken.  If the mode of the output is 2, the default scale factor is 1
    regardless of whether the log is being taken.  The scale is also 1 if
    there is relative normalization without taking logs.  Otherwise, the scale
    factor for logarithms is 5000, +/-10000, or +/-50 for modes 1, 6, or 0;
    the scale for absolute linear normalizations is 25000, -50000, or -250 for
    modes 1, 6, or 0.  Negative scaling is needed to fit absolute normalized
    data into the unsigned modes.

 -reverse OR -ReverseContrast
    Reverse contrast from input data by using negative scaling.  With positive
    scaling, the values produced by the program will have the same contrast
    polarity as the input, with density dark, but absolute normalization will
    produce negative numbers.

 -ignore OR -IgnoreExposures
    Use this option if you just want to take the logarithm of the input images
    without normalizing by exposure data in image file header.

 -expfile OR -ExposureFile   File name
    File with an exposure value for each image, one per line.  These can be
    either electron doses, or exposure times if the beam intensity was
    constant.

 -tiltfile OR -TiltFile   File name
    File with tilt angles, one per line.  If this option is entered, the
    program will compute normalization factors by assuming that the exposures
    were inversely proportional to the cosine of the tilt angle, possibly
    raised to a power as specified by -power.

 -power OR -CosinePowerInverse   Integer
    When varying the exposure by the inverse of the cosine of the tilt angle,
    SerialEM has an option to moderate the amount of exposure change by taking
    this inverse to 1/2, 1/3, 1/4 or 1/5 power.  Use this option to specify
    the selected power if normalization is being done with a tilt angle file.

 -minlog OR -MinimumLogFactor   Floating point
    Minimum fraction of dynamic range to allow when taking the log.  Before
    taking the log, small values will be truncated at this fraction times the
    difference between the maximum and minimum of the input file.  The default
    is 0.001, the same value that is used in Tilt to prevent small values
    from dominating the contrast range.

 -param OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.


HISTORY
  Written by David Mastronarde, 7/16/07