nad_eed_3d(1)                                                    nad_eed_3d(1)



NAME
       nad_eed_3d - Nonlinear anisotropic diffusion, edge enhancing, in 3D

SYNOPSIS
       nad_eed_3d  [options]  input_file  output_file

DESCRIPTION
       nad_eed_3d is Frangakis and Hegerl's 3D anisotropic diffusion program
       with edge-enhancing diffusion only (see Frangakis, A., and Hegerl, R.,
       2001.  "Noise reduction in electron tomographic reconstructions using
       nonlinear anisotropic diffusion." J. Struct. Biol. 135: 239-205).  In
       addition to options to control the algorithm itself, this version pro-
       vides some options to make it easier to explore the effects of differ-
       ent parameters.

       The program requires ~36 times as much memory as the number of voxels
       in the input file.  To process a large volume, place the command line
       needed to run the program into a command file and use chunksetup to
       obtain command files to process the volume in chunks.  Determine the
       maximum number of megabytes of memory that you want this processing to
       require, and divide by 36 to obtain the value to enter with the -m
       option to chunksetup.  See the example below.

       Finding the right parameters for anisotropic diffusion can be diffi-
       cult.  To adjust parameters, first clip out a small subvolume, e.g.,
       100x100x30 pixels, with typical features of interest.  One strategy is
       to look at a restricted range of iterations, such as 5-10 or possibly
       5-15, and find the K value that gives the desired result.  A very wide
       range of K needs to be explored, perhaps from .02 to 5 times the stan-
       dard deviation of the data.  For typical byte data this might be a
       range of 0.4 to 100.  The range should thus be explored in two stages.
       In the first stage, you might try K values of 0.4, 1.6, 6.4, 26, 102,
       then look at the results as described below.  When you see that the
       desired K value falls in one of these intervals, then try 5 K values to
       fill in the interval with finer steps, such as 2.4, 3.2, 4.0, 4.8, and
       5.6 for the interval from 1.6 and 6.4.  Once you have chosen your
       parameters, you can process the whole volume.

       The eTomo program contains an interface for extracting a subvolume,
       testing different K values and iteration numbers, and running the dif-
       fusion on a full volume.  From the File menu, select "New Parallel Pro-
       cess" then press the "Nonlinear Anisotropic Diffusion" button.

OPTIONS
       -k value
              The K value (sometimes referred to as lambda).  The ratio of the
              local image gradient to K is used to determine whether density
              will diffuse isotropically or primarily in the direction of
              least density variation (along edges).  Lower K values will pre-
              serve more edges; higher K values will give more isotropic
              smoothing.

       -n value
              The number of iterations.  The higher the number of iterations,
              the smoother the result.

       -i list
              A list of iterations at which output should be written to a file
              (ranges such as 1-3,5,8 or allowed).  If such a list is entered,
              the -n option is ignored.  By default, the entire volume will be
              written at each listed iteration, with the filename out-
              file_file-nnn, where output_file is the name entered on the
              command line, and nnn is the number of iterations, with leading
              zeros as needed to give three digits.  However, if the -o option
              is entered, a single slice will be written at each of the speci-
              fied iterations, all into the same output file.

       -o value
              Single slice to output (numbered from 1).  This option is useful
              when adjusting parameters if you can judge the performance by
              looking at just one slice.  It will not make the program do the
              computation on only one slice; it will still operate on the
              whole input volume.

       -m value
              Mode for output file: 0 for byte, 1 for integer, 2 for real, or
              6 for unsigned integer.  By default, the output file will have
              the same mode as the input file.  This works for byte data
              because densities will never become more extreme than in the
              original volume.  However, if you have byte input data with a
              low dynamic range, you may need to specify real output to avoid
              seeing discrete density levels in the smoothed regions.

       -s value
              Sigma value for smoothing or averaging the structure tensor,
              which might give a more accurate estimate of the direction of an
              edge.  The default is 0 for no smoothing.

       -t value
              The time step.  The product of the time step and the number of
              iterations determines the amount of diffusion.  The diffusion
              will run faster with a higher time step but may become unstable.

       -P     Print process ID to standard error.

EXAMPLES
       To get a set of volumes, one at every third iteration, enter:
          nad_eed_3d -i 3,6,9,12,15,18,21 -k 1.2 tomo.rec tomo.nad

       This will produce tomo.nad-003, tomo.nad-006, etc.  They can be visual-
       ized with:
          3dmod tomo.nad-*

       To get a single file with one slice, say slice 16, from every iteration
       from 5 to 15, enter:
          nad_eed_3d -i 5-15 -k 1.2 -o 16 tomo.rec tomo.nad-1.2

       To get a series of such files at different K values, just repeat the
       above command, or (under tcsh) enter:
          foreach i (0.6 0.8 1.0 1.2 1.4 1.6)
          nad_eed_3d -i 5-15 -k $i -o 16 tomo.rec tomo.nad-$i
          end

       This will produce tomo.nad-0.6, tomo.nad-0.8, etc., which can be visu-
       alized with:
          3dmod tomo.nad-*.*

       If your file is large (e.g., > 10 megavoxels), and you have determined
       your optimal parameters, say 15 iterations with a K of 1.3, then pre-
       pare a command file, e.g., nad.com, with the line:
          $nad_eed_3d -k 1.3 -n 15 INPUTFILE OUTPUTFILE
       (Do not indent the line; the $ must be the first character on the line.
       Also, do not substitute your input and output files, the command file
       really should say INPUTFILE and OUTPUTFILE.)

       Then enter:
          chunksetup -m 10 nad.com tomo.rec tomo.nad

       If you are doing more than 8 iterations, you should increase the over-
       lap between chunks by adding the option "-p #" where "#" is the number
       of iterations; this will reduce the effects of cutting the volume into
       chunks to a minor level.  Overlap of 4 times the number of iterations
       is needed to eliminate these effects but this could increase chunk
       sizes substantially.

       The Chunksetup command with option "-m 10" will produce command files
       in which each run of the program will require less than 360 MB of mem-
       ory (use a different amount to allow for more memory).  On a single
       processor machine, run these with:
          subm nad-all

       If multiple machines or processors are available, run in parallel with:
          processchunks list_of_machines nad
       or just
          processchunks # nad
       to run with # processors on the local machine.

FILES
       If an output file already exists, it will be made a backup file by
       adding ~ to its name.

AUTHORS
       Achilleas Frangakis and Reiner Hegerl (IMOD modifications by David Mas-
       tronarde).  The program is copyright Max-Planck-Institut for Biochem-
       istry, Martinsried, Germany.

SEE ALSO
       chunksetup, processchunks, 3dmod

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                       nad_eed_3d(1)