Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

SMOOTHSURF(1)						 	 SMOOTHSURF(1)

NAME
	smoothsurf - to smooth a surface defined by model contours

SYNOPSIS
	smoothsurf [options] input_file output_file

DESCRIPTION
  This program will smooth a surface defined by model contours, adjusting
  the positions of points in each contour as needed.  At each point on the
  surface, it fits a 3-D polynomial to all points within a defined range of
  Z-levels and within a specified distance of the central point.  That
  point's position is then replaced by the fitted position from the
  polynomial.  After this surface smoothing operation, each contour is
  independently smoothed by local fitting to 2-D (ordinary) polynomials.

  The default values for the number of Z levels (sections or slices) and
  for the maximum distance in 3D should give a good starting point for
  smoothing models drawn on tomographic reconstructions.  Increase or
  decrease these two numbers together to increase or decrease the
  smoothing.  Because the default values give a big disparity between the
  total extent in Z versus X and Y (7 versus 30), the Z range should be
  increased more than the distance.  For example, try "-nz 11 -dist 20" and
  "-nz 15 -dist 25" for progressively more smoothing.  If you want to
  experiment more broadly with the parameters, you can try changing the
  balance between these two numbers, as well as omitting the independent
  contour smoothing with "-cont 0".

  For serial section reconstructions, note that the Z scaling is NOT taken
  into account in computing 3D distances, so the maximum distance
  corresponds more closely to distance in the X/Y planes than to true 3D
  distance.  The default parameters may be a good starting point, but here
  it may be appropriate to increase the maximum distance more relative to
  the number of sections (e.g., start with "-dist 25").
  
  Smoothsurf moves only the contours, not the points in any existing
  meshes.  To see the resulting surface, you need to rerun imodmesh.

  Smoothsurf uses the PIP package for input (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 -):

 -input OR -InputFile   File name
    Input model file.

 -output OR -OutputFile   File name
    Output model file.

 -objects OR -ObjectsToSmooth   List of integer ranges
    A list of the objects to smooth (ranges are allowed, e.g. 1,2,5-7).  The
    default is to do all closed-contour objects, and open contours that lie in
    one plane.

 -nz OR -NumberOfSections   Integer
    Number of sections or slices in Z to include in the fit.  Higher numbers
    smooth more.  The default is 7.

 -distance OR -MaximumDistance   Floating point
    Maximum distance from the central point being smoothed, for points to be
    included in fits.  Higher distances smooth more.  The default is 15
    pixels.

 -contorder OR -ContourOrder   Integer
    Order of the polynomials fit to contours to smooth them after smoothing
    the surface, or 0 to omit this smoothing.  Higher orders smooth less.  The
    default is order 2; order 1 (linear) will probably oversmooth and contract
    the contours.

 -surforder OR -SurfaceOrder   Integer
    Order of the polynomials fit to the surface.  Higher orders smooth less. 
    The default is order 3.  Note that a second-order polynomial has 5 terms
    and a third-order has 9 terms.

 -sort OR -SortSurfaces   Integer
    This option controls whether the program uses surface assignments of
    contours to keep from including points from contours that belong to
    different surfaces in a surface fit.  With the default value of 1, the
    program will analyze the object mesh, if any, to sort contours into
    surfaces (see ImodSortSurf(1)).  Enter -1 to have the program use existing
    surface values of the contours, or 0 to ignore surface information.

 -help OR -usage
    Print help output.

  -StandardInput
     Read parameter entries from standard input.


HISTORY
  Written by David Mastronarde, 9/9/97
  6/17/04: Converted to PIP input with default values, fixed bug in contour
  smoothing, made it work properly with pixel sizes in image file header