imodmop

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 (-zm) 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. However, the pixel spacing and origin
 information in whatever image file is provided must match those
 of the volume on which the model was generated.
 -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 or 12 for 32-bit or 16-bit floating point values.
 Changing the mode to 2 or 12 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 output 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 mak-
 ing a mask, or when using -color or -project. The default mode
 of floating point output for MRC files is governed by the value
 of environment variable IMOD_WRITE_FLOATS_16BIT. Mode 12 is
 allowed only if the output format is MRC.
 -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.
 -ztaper (-zt) OR -TaperInZOverPad
 Do tapering over the padding distance in Z as well as in X and
 Y. This option is allowed only with tapering inside, i.e., with
 a negative entry for -pad. The distance in Z is 0.5 for points
 in a contour with no overlapping contours at adjacent Z values,
 1.5 if an adjacent Z value has the last overlapping contour in
 that direction, etc.
 -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 5.2.0 imodmop(1)