CLIP(1) CLIP(1)
NAME
clip - command line image processing for mrc files.
SYNOPSIS
clip [process] [options] [input files...] [output file]
DESCRIPTION
The processes that clip can do are listed below. One and only one pro-
cess must be selected on the command line. Only the first three or
four letters of the process name have to be entered.
average (avg)
Average several images together.
brighten
Brighten image by scaling intensities.
color Add false color to image.
contrast
Adjust contrast by scaling intensities.
correlation
Do a auto/cross correlation.
diffusion
Do 2d anisotropic diffusion.
gradient
Calculate a gradient as in 3dmod image processing.
graham Apply Graham filter as in 3dmod image processing.
info Print header information to stdout.
fft Calculate a fft or inverse fft transform.
filter Calculate a bandpass filter.
flip[xyz]
Flip an image by x y or z.
joinrgb
Join images from 3 byte files into one RGB file.
laplacian
Apply Laplacian filter as in 3dmod image processing.
median Apply median filter.
prewitt
Apply Prewitt filter as in 3dmod image processing.
resize Box out image to a new size.
rotx Rotate a volume by -90 degrees about X axis.
shadow Adjust darkness of image by scaling intensities.
sharpen
Sharpen image as in 3dmod image processing.
smooth Smooth image as in 3dmod image processing.
sobel Apply Sobel filter as in 3dmod image processing.
splitrgb
Split an RGB file into 3 byte files.
stats Print min, max, location of max and std. dev.
Options
These options are available to most processes.
-v View output data file using 3dmod.
-2d Use 2d instead of 3d (default) processes if a 2d process exists.
Each input file is considered a stack of 2D images to be pro-
cessed. For most processes, this will change only the way that
the -iz option is interpreted.
-3d Use 3d process. Each input file is considered a volume to be
processed.
-a Append data to output file. Append and overwrite are not avail-
able for processing modes that do not take standard input and
output size and centering options.
-ov <section>
Overwrite output starting at section number section. Range is
from 0 (first section) to z size - 1 (last section).
-p <value>
Image coordinates with no image data are padded with the given
value. The default is the mean value of the input image.
-c[xyz] <value>
Adjust the center of input image. Default is center of first
input file. The -cx option will center the x coordinate on the
given value, the -cy option will center the y coordinate on the
given value and the -cz option will center the z coordinate on
the given value.
-ix <value>
-iy <value>
-iz <value>
Sets the size of input image. The default is the size of the
first input file. The -ix option sets the x input size, the -iy
option sets the y input size. The -iz option sets the z input
size, or specifies a list of Z values if the -2d option is
included. In the latter case, the value is interpreted as a
comma-separated list of ranges. Commas indicate individual sec-
tion numbers and dashes (or minus symbol) indicate a range of
sections.
-ox <value>
-oy <value>
-oz <value>
Size of output file. Default is same as input size, options -a
and -ov overide these setting. The -ox option sets the x output
size, the -oy options sets the y output size and the -oz option
sets the z output size.
Selected options
The following options are valid for selected processes:
-s Switch, use depends on process.
-m <mode>
Output modes: 'byte', 'short', 'float', 'complex', 'ushort',
'rgb', or 0-4, 6, or 16. 0 = byte, 1 = short, 2 = float, 3 =
complex short, 4 = complex float, 6 = unsigned short, 16 = rgb.
-h <level>
Level for high pass filter. Range is (0.0 - 0.71 / pixel). The
default value is 0.
-k <value>
K threshold value for anisotropic diffusion; the default is 2.0.
-l <level>
Has multiple uses: 1) Level for low pass filter. Range is (0.0 -
0.71 / pixel). The default value is 1.0. 2) Sigma of Gaussian
kernel for smoothing; the default is to use the standard kernel
shown below. 3) With diffusion, this specifies the lambda value
or step size; the default is 0.2.
-cc <value>
Specifies type of edge stopping function for diffusion: 1 for
exponential function, 2 for rational function, 3 for Tukey
biweight. The default is 2.
-n <value>
Input number. Use depends on process: threshold for averaging,
scaling factor for brightness/contrast/shadow, padding for cor-
relations, iterations for smoothing or anisotropic diffusion,
size for median filter.
-r <value>
Red value; Range is (0.0 - 1.0) Default is 1.0.
-g <value>
Green value; Range is (0.0 - 1.0) Default is 1.0.
-b <value>
Blue value; Range is (0.0 - 1.0) Default is 1.0.
PROCESSES
A brief discription of each process is given below.
average
(avg) Average images together. Average 3d version: Average
will add all of the input files together slice by slice and then
divide the results by the number of input files. All input
images must be the same size. (Standard options for input and
output size not implemented.) Average 2d version: Averages
slices from the input file together, use the -n option to set a
threshold such that pixels below threshold are not included in
the average. Standard options are available.
brightness
contrast
shadow Increase or decrease image brightness, contrast, or darkness.
These options scale the image intensity by the value entered
with the -n option, with intensity fixed at one point. With
brightness, intensity is fixed at the minimum so scaling up
increasing brightness. With contrast, intensity is fixed at the
mean; with shadow, intensity is fixed at the maximum so dark
parts are scaled more. Scaling values less then 1 will decrease
the chosen property, values greater then 1 increase it. With
the -2d option, the min, max, or mean are taken from the indi-
vidual sections.
color Colorize a black and white image. Color 3d version: reads in a
whole mrc file as byte data and then scales the image to a color
ramp that starts at black and goes to the -r, -g, and -b values
given on the command line. The default color values are 1.0.
Standard options for input and output size are not implemented.
Color 2d version: reads in data slice by slice without scaling
it to bytes, the scales the image to a color ramp using the -r,
-g, and -b values. The size of these values may need to be
adjusted to get output data within the desired range (0-255).
Standard options are available.
correlation
Calculate auto or cross correlation functions. 3d correlation
takes 1 or 2 volumes and does an auto or cross correlation
respectively. If the volumes are fourier transforms, the output
file will be a fourier transform. 2d correlation takes 1 or 2
slices for input and does an auto or cross correlation respec-
tively. Select the slices with the -iz option. Input files in
this case may not be fourier transforms. All other input types
are automatically padded, fft transformed, correlated and
inverse fft transformed. One or two input files can be given
and one output file needs to be given. Input is automatically
padded with the mean value unless the option -p option is given
to change the pad value. The -n option selects the type of
padding: '-n 0' selects no padding; '-n 1' selects padding with
mean value. (default) Float is the only output mode supported.
Input sizes must fit fft dimensions.
diffusion
Apply 2D anisotropic diffusion to individual slices, using the
simple Perona and Malik diffusion technique. The gradients in
this method are simply pixel-to-pixel differences. The ratio
between these pixel-to-pixel differences and the threshold K
determines how much diffusion is allowed between pixels. The
number of iterations is specified with the -n option (default
5). The edge stopping function is selected with the -cc option
and can be 1 for the exponential function, 2 for the rational
function, or 3 for the Tukey biweight function (default 2). The
K value for controlling the edge stopping function is entered
with the -k option. For byte data, start with values on the
order of 1; the rational edge function may require lower values
and the Tukey biweight may require larger values. The effect of
the value scales proportional to the range of the data. The
step size, lambda, is specified with the -l option; the default
is 0.2, which should be small enough to give stable results.
These computations correspond to those done in the image pro-
cessing window in 3dmod, but better results will generally by
obtained with nad_eed_3d.
fft Calculate a Fast Fourier Transform. fft does either a forward
or inverse fft, depending on the input data type. The output
for a forward transformation is complex float. The input sizes
must be a multiple of two, and must have no prime factors
greater than 19. Both 2D and 3D output match the format of the
fft output by fftrans, in which no data is duplicated and the
center is shifted to x = 0, y = ny/2. Older fft files produced
by clip, in which the data were replicated to the left of the Y
axis, will still be accepted as input. Input size and centering
options can be used for the forward transform, and output size
and mode can be set for the inverse transform.
filter High and/or low pass filtering in frequency space (2D only).
Filters an fft or an image using the -l and -h options. An fft
and inverse fft is automatically done if needed. The units for
-l and -h are cycles/pixel so they range from 0 to 0.5. Every-
thing higher than -l and lower then -h is filtered. The attenu-
ation will be 0.5 at the given frequency; the filter factor is
the product of 1/(1+(r/l)**3) if -l is entered and
1/(1+(h/r)**3) if -h is entered, where r is the radius in
cycles/pixel.
flip The flip command is just the root of several types of image
transformations. The flipx and flipy commands will each create
a new file where each slice is the mirror image of the input
slice around the x or y axis. The flipz command will invert the
order of slices (mirror around the x/y plane). The flipxy,
flipyz, flipzx commands will flip the xy, yz or zx indices and
change the size of the output file to match. No input size or
centering, or output size or mode options will be applied. All
of these options invert the handedness of the structures in the
image file.
gradient
graham
prewitt
sobel These options apply simple 2D filters to the input image, using
the same same method as for the respective entry in the 3dmod
image processing dialog. The prewitt and sobel filters seem to
be the most useful.
info Print information about an image. All header information in the
mrc file is printed to standard output. If the file is not an
mrc file the information is still printed with a warning that
the file is not an mrc file.
joinrgb
Combine 3 input files containing red, green, and blue informa-
tion into one RGB file. The 3 input files must all be byte mode
and their names must be entered in the order red, green, and
blue, followed by the output file name. The -r, -g, and -b
options can be used to scale the components (default scaling is
1). No other options except -v will work with this process.
median Apply a median filter by replacing each pixel with the median of
the values in a block of neighboring pixels. The size of the
block is given by the -n option; its default is 3. The default
is to do a 3D filter (thus taking the median in cubes of data),
but the -2d option can be used to apply a 2D filter that consid-
ers only the pixels in one section. Note that an even size will
offset the data by half a pixel.
resize Cut out or pad an image to a new size without doing any other
operations. Resize 3d cuts out an image of size ix, iy, iz,
centered around cx, cy, and cz. The output size of the file is
ox, oy, and oz. The default input size is the size of the input
file, the default center is the center of the input file and the
default output size is the same as the input size. The default
padding is the average value of the input file; the padding can
be changed with the -p option. Resize 2d cuts out a list of
slices specified by the
rotx Rotate an image volume by -90 degrees about the X axis. This
rotation is preferable to flipyz because it preserves the hand-
edness of structures. The origin and tilt angles in the header
will be modified to retain the coordinate system of the original
volume, as is done by Rotatevol.
sharpen
smooth
laplacian
These options will filter images by convolving with a simple 3x3
or larger kernel, using the same method as for the respective
entry in the 3dmod image processing dialog. The smoothing fil-
ter is the most useful; by default, its kernel is
1 2 1
2 4 2
1 2 1
However, a Gaussian kernel can be used for smoothing instead if
a standard deviation (sigma) is entered with the -l option. The
kernel will be 3x3 for sigma up to 1.0, 5x5 for sigma up to 2.0,
and 7x7 for higher sigma values.
splitrgb
Output the 3 color channels of an RGB file into three separate
files, so that other operations can be performed on them (such
as transformations). With this process, the output file name
will be used as a root for three filenames ending in .r, .g, and
.b. No options except -v will work with this process.
stat Calculate stats on a file. A table is printed with the Min, Max
and Std. Deviation. The location of the maximum is also
printed. The location is calculated by doing a quadratic fit to
the maximum value. The -s option is used to report the location
for a cross-correlation.
HISTORY
Originally most processes loaded all data into memory unless the -2d
option was given, and the -2d option did not provide for any output
padding. Work in Jan 2005 fixed this so that only 3D correlation and
FFTs and 3D color load the whole volume; everything else does slice-by-
slice processing, with proper handling of output padding and appending
regardless of whether -2d or -3d is selected. Rotation, translation,
and zoom were not well-implemented and were abandoned.
AUTHORS
Jim Kremer
David Mastronarde
The anisotropic diffusion is based on a program by Alejandro Cantarero
SEE ALSO
3dmod, newstack, rotatevol, matchvol, fftrans
BUGS
There are not checks for the validity of all input values, and some
nonsensical mode conversions are allowed. Disk-based 3D FFTs (invoked
with -s) do not work.
Email bug reports to mast at colorado dot edu.
BL3DEMC 3.11.2 CLIP(1)