densnorm(1) densnorm(1)NAMEdensnorm - Normalize densities in an image fileSYNOPSISdensnorm [options] [Input_file] [Output_file]DESCRIPTIONDensnorm 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.OPTIONSDensnorm 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-InputImageFileFilenameInput 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-OutputImageFileFilenameOutput 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-WeightOutputFileFilenameOutput 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-ImagesWithExposuresFilenameImage 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-ReferenceImageFileFilenameFile 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-MeanOfReferenceImageFloatingpointMean 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-ExposureOfReferenceImageFloatingpointExposure 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-SubtractedIntegersOne 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-ResubtractSubtract 32768 off again after normalizing subtracted integers.-divide(-d)OR-DivideBy2Divide 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-LogOfOutputFloatingpointTake 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-ModeOfOutputIntegerMode 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-ScalingFactorFloatingpointFactor 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-ReverseContrastReverse 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-IgnoreExposuresUse 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-ExposureFileFilenameFile 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-TiltFileFilenameFile 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-CosinePowerInverseIntegerWhen 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-MinimumLogFactorFloatingpointMinimum 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-ParameterFileParameterfileRead parameter entries as keyword-value pairs from a parameter file.-help(-h)OR-usagePrint help output-StandardInputRead parameter entries from standard input.HISTORYWritten by David Mastronarde, 7/16/07BUGSEmail bug reports to mast at colorado dot edu. BL3DEMC 4.7.3 densnorm(1)