densnorm(1)                                                        densnorm(1)

       densnorm - Normalize densities in an image file

       densnorm  [options]  [Input_file]  [Output_file]

       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.

       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

       -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

       -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, or 2
              for floating point numbers.  The default is to use the mode of
              the input file.

       -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

       -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

       -help (-h) OR -usage
              Print help output

              Read parameter entries from standard input.

       Written by David Mastronarde, 7/16/07

       Email bug reports to mast at colorado dot edu.

BL3DEMC                              4.7.3                         densnorm(1)