densnorm(1) General Commands Manual 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 com-
mon 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 propor-
tional to the sum of the mass densities in the specimen, with no addi-
tive 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 trans-
mittance 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 pro-
gram 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 con-
vert 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 insen-
sitive 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 recommen-
dations 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 nor-
malization 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.
OPTIONS
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 -). Options can be abbreviated to
unique letters; the currently valid abbreviations for short names are
shown in parentheses.
-input (-in) OR -InputImageFile File name
Input file with images to be normalized, or whose header con-
tains 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 (-o) 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 (-w) 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 (-im) 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 (-rif) 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 (-rim) 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 (-rie) 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 (-su) 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 (-res) OR -Resubtract
Subtract 32768 off again after normalizing subtracted integers.
-divide (-d) 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 (-l) 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 tak-
ing the log, you can enter "-log 32768" without using the -sub-
tracted option, or "-log 0" with the -subtracted option.
-mode (-mo) 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, 2
for floating point numbers, or 12 for 16-bit floats. The
default is to use the mode of the input file, although the
default mode of floating point output for MRC files is governed
by the value of environment variable IMOD_WRITE_FLOATS_16BIT.
Mode 12 is allowed only if the output format is MRC.
-scale (-sc) 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 tak-
ing 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 (-rev) 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 (-ig) 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 (-e) 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 (-t) 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 (-po) 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 normal-
ization is being done with a tilt angle file.
-minlog (-mi) 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 con-
trast range.
-param (-pa) OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter
file.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
HISTORY
Written by David Mastronarde, 7/16/07
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 densnorm(1)