imodmop(1)                  General Commands Manual                 imodmop(1)



NAME
       imodmop - extract image data inside of IMOD model contours

SYNOPSIS
       imodmop  [options]  model_file  image_file  image_output_file

DESCRIPTION
       The "mop" in imodmop stands for MOdel Painter; the program can be used
       to color in data inside of model objects.  It will operate on all modes
       of input data, included Fourier transforms and color images in an MRC
       file.  Its output file can be either the same kind of data as the
       input, or an RGB file where the pixels have been colored by the colors
       of the model objects.  In addition, the painted output can be directed
       through Xyzproj to produce projections at a series of tilt angles
       around one axis.  Again, this output can be monochrome or color.  Also,
       there is an option to output a constant value instead of the pixel val-
       ues in the input data, which is useful for making mask volumes.  A sim-
       ilar option will output a different constant for each object, such as
       the object number.

       By default, the program operates only on closed contour objects, but
       open and scattered point objects can also be used.  For open contours,
       it is possible to paint a cylinder of data around each contour by spec-
       ifying the object number and a diameter for the cylinder.  There are
       options for painting either circles or spheres of scattered point
       objects; if the points have individual sizes they will be used as the
       radius for each area painted.  The painting can be padded outside the
       border of an area or restricted from approaching the border, and values
       can be tapered down to the background over these padding regions.

       Contours in a closed contour object may be nested to any level, and
       regions that are topologically inside the surface (odd nested levels)
       will be painted, and enclosed regions that are topologically outside
       (even nested levels) will be cleared (e.g., the holes will be excluded
       from donuts).  An object defined as having its front face inside
       instead of outside will be treated in the reverse fashion, i.e., odd
       levels will be cleared and even levels will be painted.  The painting
       is done in two passes, with outside-facing objects done first, then
       inside facing-ones.  This means that if you have one object inside
       another and you want to paint the region between the two, then you need
       to define the inner object as inside-facing.  However, then you will
       not be able to paint any other objects inside of that, since they will
       be cleared by the painting of the inside-facing object.

       The data need to be scaled for output in two different situations: when
       a color volume is being produced, and when a projection series is being
       produced.  In the first case, scaling can be controlled with the -scale
       option.  In the second case, data are scaled to bytes after projection
       regardless of whether monochrome or color projections are being made.
       The scaling here can be controlled with the -bw option in either case.
       In addition, the differential scaling through the series of angles by
       Xyzproj is controlled with the -constant option.  Some experimenta-
       tion may be needed to get reasonable results.

       If you are modeling in an FFT, you can load the FFT into 3dmod
       either non-mirrored or mirrored.  However, if you load it mirrored (the
       default), then be sure to model only in the right half of the FFT.

OPTIONS
       Imodmop uses the PIP package for input (see the manual page for
       pip).  Options can be specified either as command line arguments
       (with the -) or one per line in a command file (without the -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -xminmax (-x) OR -XMinAndMax   Two integers
              Starting and ending X index coordinates to extract into the out-
              put volume (numbered from 0).  The default is to produce an out-
              put volume the same size as the input.  The X and Y range of the
              output cannot be modified if the input is a Fourier transform.

       -yminmax (-y) OR -YMinAndMax   Two integers
              Starting and ending Y index coordinates to extract into the out-
              put volume (numbered from 0).

       -zminmax (-z) OR -ZMinAndMax   Two integers
              Starting and ending Z slices to extract into the output volume
              (numbered from 0).

       -border (-bo) OR -BorderAroundObjects    Integer
              Use this option to extract just the volume necessary to contain
              all of the objects being painted, with the given border added in
              X and Y.  For tubular lines, the radius of the tube is taken
              into account in determining the limits to extract in X and Y and
              Z. For scattered points, the radius of each point is taken into
              account in determining limits to extract in all 3 dimensions.
              If padding is specified with the -pad option, the padding is
              added only if it is positive.  If Z limits are entered with the
              -zminmax option, then they supercede the Z limits computed from
              the objects with this option; this is the way to get extra
              slices in Z.  This option cannot be used with -xminmax or -ymin-
              max.

       -invert (-i) OR -InvertPaintedArea
              Paint outside model contours instead of inside.  This is accom-
              plished by painting inside the contours, then subtracting the
              painted volume from the original volume.  This option cannot be
              used when making colored data because the color is not defined
              outside of model objects.

       -reverse (-rev) OR -ReverseContrast
              Reverse the contrast by subtracting each value from the file
              maximum before painting.  The intensity range being operated on
              thus ranges from 0 to the original max minus the min.  For color
              input data, each channel is subtracted from 255.  FFT input data
              may not be reversed.

       -thresh (-th) OR -Threshold    Floating point
              Set values below the given threshold to zero.  If contrast is
              being reversed, the threshold will be converted to the appropri-
              ate value to use after the reversal, so a value in the original
              data can be used.

       -fv OR -FillValue    Floating point
              Value with which to fill the background pixels that are not
              painted with image data.  This is a value on the same scale as
              the values in the input volume, before any reversal of contrast.
              If you enter a value and also select contrast reversal, the
              value is subtracted from the file maximum before being tested
              for whether it fits in the range for the data mode.  The default
              is 0.

       -fc OR -FillColor    Three floats
              Relative values for scaling the value for background fill into a
              red, green, and blue components for color output.  The values
              should be between 0 and 1.  The default is 1,1,1.

       -mask (-ma) OR -MaskValue      Floating point
              With this option, the given value will be used to generate out-
              put instead of the value in the input data.  In the simplest
              case, you can make a mask volume that consists of zeros and ones
              by using "-mask 1".  You can use the -invert option to produce
              the mask value outside the painted regions and 0 inside.  A mask
              can be tapered with the -pad and -taper options.  When creating
              a mask file, either with this option or the -label option, a
              byte file will be output as unsigned so that the values in the
              file will equal the mask values.  Also, the input slices will
              not be read, which means that the input image file can be just a
              copy of an MRC file header, such as is created with the IMOD
              program copyheader.

       -label (-l) OR -LabelMaskList       List of integer ranges
              A set of object-specific mask values that allows the regions
              inside different objects to be labeled by the different values.
              There must be as many numbers in the list as objects included
              for consideration (i.e., either the total number of model
              objects, or the number entered with the -objects option).  Enter
              "/" to use the default, which is the object number for each
              object.  The mask values must fit into the output file data type
              and not be indistinguishable from the fill value in the output
              file.  This option cannot be entered with -mask.

       -retain (-ret) OR -RetainOutsideMask
              Outside of areas painted with mask values, retain the existing
              image data by copying values from the input to the output.  This
              option, which can be used only when masking, allows mask output
              to be added to an existing mask output file.

       -mode (-mo) OR -ModeToOutput   Integer
              Mode for output file: 0 for bytes, 1 or 6 for signed or unsigned
              integers, or 2 for real values.  Changing the mode to 2 is
              essential if you want to make a mask with a value of 1 and
              tapering over padded regions.  You may also need to change out-
              put mode if you are inserting fill or mask values outside the
              range of the input mode.  You cannot change the mode of FFT
              input data, of RGB input data unless making a mask, or when
              using -color or -project.

       -pad (-pa) OR -PaddingSize     Floating point
              This option will extend the painted region outside of the model
              feature with a positive padding value, or eliminate pixels just
              inside the boundary of the model feature with a negative padding
              value.  For a contour nested inside of another contour, the
              sense of the padding is reversed, with a positive padding
              extending the painted area inside, and a negative padding elimi-
              nating painted pixels outside.  For spheres, the padding size is
              essentially added to the sphere radius.  For tubular contours,
              adding padding is the same as entering a different tube diame-
              ter, unless tapering is being used.

       -taper (-ta) OR -TaperOverPad       Integer
              With this option, values will be tapered down to the background
              value over a padding region.  Enter 1 for a taper that is linear
              with distance, or 2 for a Gaussian that falls to 0.05 at the end
              of the tapering distance.

       -objects (-o) OR -ObjectsToDo       List of integer ranges
              Paint only for the given list of objects.  The default is to do
              all closed contour objects, all scattered point objects if
              -2dscat or -3dscat is entered, and any open contour objects
              listed with -tube.

       -2dscat (-2) OR -2DScatteredPoints
              Paint scattered point objects, but paint only a circle in the Z
              plane of each point.  This would be useful for 2D FFTs.

       -3dscat (-3) OR -3DScatteredPoints
              Paint scattered point objects with each point treated as a
              sphere.  Options -2dscat and -3dscat are mutually exclusive.

       -tube (-tu) OR -TubeObjects    List of integer ranges
              List of open contour objects for which to paint a cyclinder of a
              particular diameter around each contour.

       -diam (-d) OR -DiameterForTubes     Floating point
              Diameter for open contour objects being painted as tubes.  Enter
              either 1 value, or 1 value per listed object.

       -planar (-pl) OR -PlanarTubes
              With this open, open contours identified as being painted as
              tubes will be painted in 2D only.  For each segment of the con-
              tour that lies in one Z plane, pixels will be extracted in that
              Z plane only.  If there is only one point in the contour, a cir-
              cle will be painted around the point, which will not happen
              without this option.

       -allsec (-al) OR -AllSectionObjects      List of integer ranges
              List of closed contour or scattered point objects to paint on
              all sections.  For example, a cylinder will be painted for each
              sphere regardless of its Z location.

       -color (-col) OR -ColorOutput
              Produce RGB output colored by model object colors.  This option
              is available only with byte, integer, or floating point input.

       -scale (-s) OR -ScalingMinMax       Two floats
              Minimum and maximum values for scaling to bytes, when a color
              volume is being produced.  The default is to scale the min and
              max of the file to 0 and 255 for input data modes other than
              bytes, but to leave bytes unscaled.  This entry should produce
              the same scaling as the -s option to 3dmod.

       -project (-pr) OR -ProjectTiltSeries     Three floats
              Produce projection series with given starting, ending, and
              increment angles.  Projection is done with xyzproj, then data
              are read back in and and scaled to bytes.  When color output is
              being produced, each painted color channel is output separately
              and projected separately, then read back in and combined into
              one RGB mode file.  Only byte, integer, or real data may be pro-
              jected.

       -axis (-ax) OR -AxisToTiltAround    Text string
              Axis to tilt around for projections (X, Y, or Z; default is Y)

       -constant (-con) OR -ConstantScaling
              When projecting with Xyzproj, scale all projections by the
              same amount instead of dividing them by the number of pixels
              along the projection ray at the particular angle.  This will
              give more even intensities through the projection series for
              nearly spherical compact objects embedded in the black back-
              ground.

       -bw OR -BlackAndWhite     Two integers
              Black/white values for scaling projections to bytes.  By
              default, the projections are scaled so that their min and max
              values map to 0 and 255.  With this option, scaled values below
              the black level are set to 0, ones above the white level are set
              to 255, and values in between are remapped to 0 to 255.  The
              result is similar to reading the default scaled data into 3dmod
              and setting the black and white sliders to these values.

       -tempdir (-te) OR -TemporaryDirectory    Text string
              Directory for temporary files when projecting

       -keep (-k) OR -KeepTempFiles
              Keep intermediate files when projecting.  2 or 6 intermediate
              files are produced, depending on whether color output is being
              generated.  The temporary volume files are named imod-
              mop.rec0.pid (and imodmop.rec1.pid and imodmop.rec2.pid for
              green and blue channels of color output), where pid is the
              process ID.  The temporary projection files are named imod-
              mop.xyz0.pid, etc.

       -fast (-fa) OR -FastLegacyMethod
              Paint closed contours using scan contours, the method used prior
              to IMOD 4.2.15.  This was about 10 times faster but was not com-
              pletely accurate at identifying the pixels within contours, par-
              ticularly if they were the contours small or convoluted.

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

       -StandardInput
              Read parameter entries from standard input


AUTHORS
       David Mastronarde
       Based on imodmop and imodcmopp by James Kremer.

SEE ALSO
       3dmod, xyzproj

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.11.0                          imodmop(1)