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