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.0.2 imodmop(1)