CLIP(1) CLIP(1)NAMEclip - command line image processing for mrc files.SYNOPSISclip process [options] input_files... [output_file]DESCRIPTIONThe 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.addAdd several images together.average(avg)Average several images together.brightenBrighten image by scaling intensities.colorAdd false color to image.contrastAdjust contrast by scaling intensities.correlationDo a auto/cross correlation.diffusionDo 2d anisotropic diffusion.divideDivide one image volume by another or by a single image.gradientCalculate a gradient as in 3dmod image processing.grahamApply Graham filter as in 3dmod image processing.infoPrint header information to stdout.fftCalculate a FFT or inverse FFT transform.filterCalculate a bandpass filter.flip[xyz]Flip an image by x y or z.histogramPrint histogram of values.joinrgbJoin images from 3 byte files into one RGB file.laplacianApply Laplacian filter as in 3dmod image processing.medianApply median filter.multiplyMultiply one image volume by another or by a single image.prewittApply Prewitt filter as in 3dmod image processing.quadrantCorrect disparities between quadrants in images from 4-port readout camera.resizeBox out image to a new size.rotxRotate a volume by -90 degrees about X axis.shadowAdjust darkness of image by scaling intensities.sharpenSharpen image as in 3dmod image processing.smoothSmooth image as in 3dmod image processing.sobelApply Sobel filter as in 3dmod image processing.splitrgbSplit an RGB file into 3 byte files.statsPrint min, max, mean, standard deviation, and location of min and max.standevCompute the standard deviation of a set of images.subtractSubtract one image volume from another.truncateLimit pixel values at low or high end, or both.unpackUnpack 4-bit values packed into bytes, with optional scaling by reference.unwrapUndo wraparound of values in integer data.varianceCompute the variance of a set of images.OptionsThese options are available to most processes.-vView output data file using 3dmod.-2dUse 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-izoption is interpreted.-3dUse 3d process. Each input file is considered a volume to be processed.-aAppend 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.-ovsectionOverwrite output starting at section numbersection.Range is from 0 (first section) to z size - 1 (last section) unless the-1option is entered to number sections from 1.-pvalueImage coordinates with no image data are padded with the givenvalue.The default is the mean value of the input image.-c[xyz]valueAdjust the center of input image. Default is center of first input file. The-cxoption will center the x coordinate on the givenvalue,the-cyoption will center the y coordinate on the givenvalueandthe-czoption will center the z coordinate on the givenvalue.-ixvalue-iyvalue-izvalueSets the size of input image. The default is the size of the first input file. The-ixoption sets the x input size, the-iyoption sets the y input size. The-izoption sets the z input size, or specifies a list of Z values if the-2doption is included. In the latter case, thevalueis interpreted as a comma-separated list of ranges. Commas indicate individual sec- tion numbers and dashes (or minus symbol) indicate a range of sections.-xvalue,value-yvalue,valueThese options are an alternative way of specifying the size and center of the input image. The two values are the starting and ending coordinates, numbered from 0 (i.e., the first pixel in an image is (0, 0)). The-xoption sets the X coordinates, and neither-cxnor-ixmay be entered with it. The-yoption sets the Y coordinates, and neither-cynor-iymay be entered with it. These coordinates are not constrained to lie within the volume; regions outside the volume will be filled with the padding value.-oxvalue-oyvalue-ozvalueSize of output file. Default is same as input size, options-aand-ovoverride these setting. The-oxoption sets the x out- put size, the-oyoptions sets the y output size and the-ozoption sets the z output size.-1Z values are numbered from 1 instead of 0, the default. This option affects the interpretation of lists of Z values entered with-izwhen the-2doption is given, and the interpretation of the Z value entered with the-ozand-czoptions. When running "clip stat", slices will be referred to as views instead and numbered from 1 with this option.SelectedoptionsThe following options are valid for selected processes:-sSwitch, use depends on process.-mmodeOutput modes: "byte", "ubyte", "sbyte", "short", "float", "com- plex", "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. "byte" will produce byte output that is signed or unsigned depending on the default for this version of IMOD and the value of the environment variable WRITE_MODE0_SIGNED. Use "ubyte" or "sbyte" to force unsigned or signed byte output regardless of other settings. Unsigned output is needed to work with versions of IMOD before IMOD 4.2.23; signed output may be needed for compatibility with external software that has fol- lowed recent documentation of the MRC format. Regardless of the representation in the file, bytes are read into IMOD programs as unsigned with a range of 0 to 255.-hlevelHas five uses: 1) Level for high pass filter. Range is (0.0 - 0.71 / pixel). The default value is 0. 2) High level for image truncation; the default is no truncation. 3) Width of area ana- lyzed in quadrant correction. 4) Upper limit for histogram out- put. 5) Threshold above which values will be truncated With 4-bit unpacking.-kvalueK threshold value for anisotropic diffusion; the default is 2.0.-llevelHas 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. 4) With statistics, sets the number of slices over which to determine outliers in the min and max values. 5) When using "add" or taking an average, standard deviation, or variance, sets a factor for scaling the output values. 5) With image truncation, sets the low level for trunca- tion (default is no truncation). 6) With quadrant correction, sets a base to be added to values for scaling. 7) Lower limit for histogram output. 8) When truncating values from 4-bit unpacking, sets the value to assign to a pixel above the trunca- tion threshold.-ccvalueSpecifies type of edge stopping function for diffusion: 1 for exponential function, 2 for rational function, 3 for Tukey biweight. The default is 2.-nvalueInput 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, criterion for determining outliers in statistics, value to add when undoing wraparound, number of images to analyze together for quadrant correction, bin size for histogram output, scaling for multiply, divide, and unpacking 4-bit values and applying a gain reference.-rvalueRed value; Range is (0.0 - 1.0) Default is 1.0.-gvalueGreen value; Range is (0.0 - 1.0) Default is 1.0.-bvalueBlue value; Range is (0.0 - 1.0) Default is 1.0.-PfileName of piece list file, in order to have coordinates in statis- tics converted to position in a montage displayed with adjusted overlap. The overlap in the display is assumed to be zero, unless overlap is specified with the-Ooption.-Ovalue,valueOverlap values in X and Y to be used when printing coordinates corresponding to positions in a displayed montage. Negative values correspond to spaces between the displayed pieces.PROCESSESA brief description of each process is given below.addAdd image volumes together. All of the input files (there must be at least two) are added together slice by slice. All input images must be the same size. Standard input and output options are available. The output values can be scaled with-land the output mode can be changed.average(avg) Average images together. If more than one input file is given, it adds all of the input files together slice by slice and then divides the sum by the number of input files. All input images must be the same size. Standard input and output options are available. With one input file, it averages the 2D slices to produce one output slice. In this case, use the-noption to set a threshold such that pixels below threshold are not included in the average. Standard input options are avail- able but output cannot be resized. In either case, the output values can be scaled with-land the output mode can be changed. As of IMOD 4.2.15, the distinction between 2D and 3D averaging is controlled by the number of input files and not by the-2dversus-3doptions.brightnesscontrastshadowIncrease or decrease image brightness, contrast, or darkness. These options scale the image intensity by the value entered with the-noption, with intensity fixed at one point. Withbrightness,intensity is fixed at the minimum so scaling up increasing brightness. Withcontrast,intensity is fixed at the mean; withshadow,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-2doption, the min, max, or mean are taken from the indi- vidual sections.colorColorize 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-bvalues 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-bvalues. The size of these values may need to be adjusted to get output data within the desired range (0-255). Standard options are available.correlationCalculate 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-izoption. 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-poption is given to change the pad value. The-noption 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 have dimensions that fit the requirements for an FFT: the size in X must be a multiple of two, and for versions on older architectures not using the FFTW library, no size can have a prime factor greater than 19.diffusionApply 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-noption (default 5). The edge stopping function is selected with the-ccoption 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-koption. 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-loption; 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.fftCalculate 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. For a forward transfor, the input size in X must be a multiple of two, and for versions on older architectures not using the FFTW library, no size can have a prime factor 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 before IMOD 3.5, in which the data were replicated to the left of the Y axis, are no longer accepted as input as of IMOD 4.6.25. Input size and cen- tering options can be used for the forward transform, and output size and mode can be set for the inverse transform.filterHigh 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. The input sizes must be a multiple of two, and must have no prime factors greater than 19.flipThe 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, or flipzx commands will exchange x and y coordinates, y and z, or z and x coordinates, respectively. and also change the size of the output file to match (e.g., with flipyz, the sizes in y and z are exchanged). 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. Use the rotx command instead of flipyz to reorient a vol- ume without changing handedness.gradientgrahamprewittsobelThese options apply simple 2D filters to the input image, using the same method as for the respective entry in the 3dmod image processing dialog. Theprewittandsobelfilters seem to be the most useful.infoPrint 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.histogramPrint a histogram of pixel values from the selected region of selected slices. This function operates differently depending on the type of data. For byte, integer, or RGB data, a full histogram is built of all values. For byte or RGB data, counts are then printed for all values between the min and the max val- ues encountered. For integer data, counts are combined into bins, if necessary, to give around 256 bins. For floating point or complex data, values are counted directly in 256 bins between the min and max in the image file header, then bins are output between the min and max values actually encountered. This behavior can be changed by entering a bin size with the-noption (the entry is rounded to the nearest integer for data with integer values). You can also enter-land-hwith the lower and upper limits of the histogram to build (for floating point or complex values) or the limits of the range to output (for integer-valued data). Only values with the given limits are counted in the histogram; values outside the range are ignored. With integer-valued data, the last bin may have fewer counts because it represents a smaller range of values than the rest.joinrgbCombine 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-boptions can be used to scale the components (default scaling is 1). The-aoption can be used to append to an existing color file of the same size in X and Y. No other options except-vwill work with this process.medianApply 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-noption; its default is 3. The default is to do a 3D filter (thus taking the median in cubes of data), but the-2doption 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.multiplydivideMultiply or divide the first input file by the second input file. Use "multiply" to apply a mask to a volume, such as one produced by Imodmop. The files must be the same size in X and Y, and they must either be the same size in Z or the second file must be a single image. Standard input and output options can be used. The first input file may be any mode. The second input file must have a single "data channel" (i.e., byte, inte- ger, or float) unless either a) the first input file is complex, in which case the second file can be either a single-channel or a complex file, or b) the output mode is float, in which case the second input file is converted to a single channel of float data. The-noption can be used to set a factor for scaling the output, and the mode can be changed to preserve resulting values outside the range of the input mode.quadrantAnalyze and correct for differences between quadrants in images from 4-port-readout cameras. The boundary between quadrants must be in the exact image center in X and Y. By default, the program analyzes and corrects each section separately by finding the mean in areas adjacent to the boundary that are 20 pixels wide and extend parallel to the boundary from the center out to within 5% of the image edge. Scaling factors are computed that do the best job of equalizing these means across the boundaries. There are four options that affect this behavior: 1) The-izoption can specify a list of sections to correct; all other sections are simply copied to the output file. This option allows you to run the correction on subsets of the data with different parameter settings if necessary. 2) The-noption sets the number of images to analyze together. The sections are considered in successive groups of this size. An overall mean is obtained from the average of the boundary areas, and a single scaling is computed and applied to all the sections in the group. Enter any number larger than the number of sections in the file to have all images analyzed together. 3) The-loption sets a base amount to add to the data. By default, the program will add a base if necessary to avoid ana- lyzing negative mean values from boundary areas, but this may not work well. If you have data from FEI software that have had 32768 subtracted, you must enter "-l 32768" to have the correc- tion work correctly. 4) The-hoption sets the width of the boundary areas. The output file will have the same dimensions as the input file; options for selecting subareas are ignored. Extra header data are copied over to the output file. The-moption can be used to change the mode of the output.resizeCut 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-izoption.rotxRotate 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.sharpensmoothlaplacianThese 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-loption. The kernel will be 3x3 for sigma up to 1.0, 5x5 for sigma up to 2.0, and 7x7 for higher sigma values.splitrgbOutput 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. A subset in Z may be extracted from the file, where the-izentry is interpreted as usual depending on whether-2dis specified. No other options except-vwill work with this pro- cess.standevvarianceCompute standard deviation or variance of a set of volumes or a set of images in a stack. These operations work the same as the "average" option, so if the same options are given, the results should be usable together for statistical tests, such as with Subimstat. If more than one input file is given, it computes the statistics for each pixel from all of the input files and outputs a volume. All input images must be the same size and mode. Standard input and output options are available in this case. With one input file, it computes the statistics for each pixel in X/Y across the slices and produces one output slice. Just as with averaging, use the-noption to set a threshold such that pixels below threshold are not included in the statis- tic. Standard input options are available but output cannot be resized in this case. For both cases, if a scaling factor is entered with the-loption, then standard deviations will be scaled by this factor but variances will be scaled by the square of the factor. to prevent saturation with byte input data, you will generally need either to scale the output appropriately or to change the output mode to floating point.statsCalculate stats on a file. A table is printed with the minimum, maximum, mean and standard deviation. The locations of the max and min are also printed. The locations are calculated by doing a quadratic fit around the extreme value. If the-soption is given, the location of the max is adjusted by half the image size, which may be appropriate for a cross-correlation. Other- wise, if statistics are done on a subarea, the location is adjusted to give the coordinates in the full image. If either the-lor the-noption is given, min and max values will be analyzed for outliers by comparing the min or max value for a slice with the respective values for nearby slices or for all slices. The comparison is by the ratio of the distance of a value from the median, to the median of such distances. The criterion for this ratio is set with the-noption and has a default of 2.24; use higher values to have fewer slices marked as outliers. The number of nearby slices used for comparison is set with the-loption; otherwise the comparison is with the values for all slices. Each outlier is marked with a star, and at the end the slices with outlier values are listed.subtractSubtract the second input file from the first one. Both files must be the same size and mode, but standard input and output options are available. There is no provision for scaling, but the mode of the output can be changed, .e.g., to preserve nega- tive values.truncateTruncate pixel values at a lower or upper limit, or both. Enter the lower limit with-land the upper limit with-h.If the-soption is given, values beyond the limit will be replaced by the image mean. Standard input and output options can be used.unpackUnpacks 4-bit data that have been packed into a byte mode file with half the actual size in X. The low-order 4 bits are assumed to be the first of the two pixel values, going from left to right. If only one input file is given, the data are not scaled and will range from 0 to 15. If two input files are given, the second is assumed to be a file to multiply by (i.e., a gain reference file). It must be mode 2 (floating point) and its size must match the first input file, and be twice the X size of the first input file. In this case, data are scaled by 16, by default. The-noption can be used to set a different scaling factor. Values can be truncated at a level entered with the-hoption. Values above that level will be set to that level by default, or to a different value entered with the-loption. (The mean of the data are not yet known, so that cannot be used.) The-moption can be used to set a different output mode, and all input and output size and centering options can be used. However, input size and position in X are specified with the half-size coordinates of the input file, whereas an output size is relative to the full-size coordinates of the output file. For example, "-ix 100" and "-ox 200" would both produce 200 pixels of output in X.unwrapAdd the value specified by the-noption (32768 by default for signed integer data) and adjust any values that are now out of range for the input data mode by adding or subtracting 65536. This process can be used to recover data that wrapped around when they were saved as integers. Two examples of wraparound are: 1) Unsigned data that went higher that 32767 but were saved as signed integers, in which the values above 32767 now appear as large negative numbers. 2) Data with negative values that had 32768 subtracted before saving, in which the negative values became large positive ones (this has been seen with FEI acquisi- tion software). In case 1, the default value to add (32768) is appropriate but the data then need to be saved as unsigned (mode 6) or as floating point. In case 2, the default value is appro- priate as long as the original data did not range higher than 32767; if they did, then you need to determine a different value to add, such as a small number just sufficient to bring the originally negative numbers above 0. This process will also work with unsigned input data but a-nentry is required. Stan- dard input and output options can be used.HISTORYOriginally 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.AUTHORSJim Kremer David Mastronarde The anisotropic diffusion is based on a program by Alejandro CantareroSEEALSO3dmod, newstack, rotatevol, matchvol, fftrans, subim- stat(1), imodmopBUGSThere are not checks for the validity of all input values, and some nonsensical mode conversions are allowed. The extended header is not copied over to the output file, except by the quadrant process. Email bug reports to mast at colorado dot edu. BL3DEMC 4.7.3 CLIP(1)