densmatch(1)                General Commands Manual               densmatch(1)



NAME
       densmatch - Scale densities in one volume to match another volume or to
       have a given mean/SD

SYNOPSIS
       densmatch  [options]  Reference_file  File_to_scale  [Output_file]

DESCRIPTION
       Densmatch scales the density values in one volume so that its mean and
       standard deviation match that of another volume or match a given mean
       and SD.  To determine the mean and S.D. for each volume, by default it
       samples up to 1000000 pixels in the central eighth of each volume (cen-
       tral half in X, Y, and Z).  There are options to control the region
       sampled or to use all pixels instead of sampling.  The program can
       write the scaled values either to a new file or back into the file of
       the volume being scaled.  THE LATTER WILL DESTROY THE ORIGINAL VALUES
       IN THAT FILE.

OPTIONS
       Densmatch uses the PIP package for input (see the manual page for
       pip) and can still take sequential input interactively, but with no
       options.  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 paren-
       theses.

       -reference (-ref) OR -ReferenceFile      File name
              Input file with reference volume (the one being matched to).
              This file can be entered on the command line as the first non-
              option argument.

       -scaled (-s) OR -ScaledFile    File name
              Input file with volume to be scaled to match.  This file can be
              entered on the command line as the second non-option argument,
              or as the first non-option argument if -target is entered
              instead of a reference file.

       -output (-ou) OR -OutputFile   File name
              Output file for the scaled volume.  This file can be entered on
              the command line as the third non-option argument, or the second
              non-option argument if -target is entered instead of a reference
              file.  If this file is omitted, the program will write the
              scaled values back to the input file.

       -target (-t) OR -TargetMeanAndSD    Two floats
              Mean and standard deviation to scale the volume to (the one
              entered with -scaled).  The reference file is not entered in
              this case.  If you have a byte or integer image file and you
              want to scale to a small target SD value (such as 1, as opposed
              to 40), then you need to change the mode of the output file to
              floating point.

       -mode (-m) OR -ModeToOutput    Integer
              The storage mode of the output file; 0 for byte, 1 for 16-bit
              signed integer, 6 for 16-bit unsigned integer, or 2 for 32-bit
              floating point.  The default is the mode of the input file.
              This entry is allowed only when writing to a new output file.

       -report (-rep) OR -ReportOnly
              Report scaling factors without writing scaled data to file.  The
              program will report two numbers, a factor to multiply by then a
              constant to add; these numbers can be supplied to the -multadd
              option of Newstack.

       -xminmax (-x) OR -XMinAndMax   Two integers
              Starting and ending X coordinates of region to analyze for mean
              and SD in reference volume.  An ending X of 0 will be converted
              to NX - 1, so 0,0 can be entered to use the full extent in X.
              The default is NX/4, 3*NX/4, where NX is the size of the scaled
              volume in X.  X, Y, and Z coordinates are numbered from 0.

       -yminmax (-y) OR -YMinAndMax   Two integers
              Starting and ending Y coordinates of region to analyze in refer-
              ence volume.  An ending Y of 0 will be converted to NY - 1.  The
              default is NY/4, 3*NY/4, where NY is the size of the scaled vol-
              ume in Y.

       -zminmax (-z) OR -ZMinAndMax   Two integers
              Starting and ending Z values of region to analyze in reference
              volume.  An ending Z of 0 will be converted to NZ - 1. The
              default is NZ/4, 3*NZ/4, where NZ is the number of slices in the
              scaled volume.

       -all (-a) OR -UseAllPixels
              Compute mean and SD from all pixels in the files, not from a
              sample of pixels.  With this option, it is not necessary or
              allowed to enter any minimum and maximum coordinates.  Use this
              option to get an exact match to target values for small volumes
              (say, several megapixels).  For larger volumes, use "-xm 0,0 -ym
              0,0 -zm 0,0" instead to sample the entire volume, unless you
              really need a precise match; with sampling, the SD will be accu-
              rate to within about 0.2%.

       -offset (-of) OR -OffsetRefToScaledXYZ   Three integers
              Displacement of the volume being scaled relative to the refer-
              ence volume in X, Y, and Z; namely, the amount to add to a pixel
              coordinate in the reference volume to obtain the coordinate of
              the corresponding pixel in the file being scaled.

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

       -StandardInput
              Read parameter entries from standard input.

INTERACTIVE INPUT
       If there are no command-line arguments, Densmatch takes sequential
       input the old way, with the following entries:

       Name of the first volume, the one whose densities are being matched

       Name of the second volume, the one being scaled

       Name of an output file, or a blank line to have the scaled values writ-
       ten back into the second file.

HISTORY
       Written by David Mastronarde, November 1995
       Converted to PIP input, added reporting option, 8/23/04
       Added options for target, mode, and all pixels, increased sample size
       by 10, 2/11/15

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.11.0                        densmatch(1)