Usage:
vop operation arguments options

The vop command edits volume data to create a new volume data set. The original map is undisplayed and the new map is displayed with the same threshold and color as the original. Map display can be adjusted and the map saved to a file using Volume Viewer or the command volume. See also: mask, sop, Volume Filter, Volume Eraser, Segment Map

Examples:

vop add #1-25 onGrid #0
vop add #1,2,5 onGrid #5 inPlace true
vop add #1,2 boundingGrid false
vop gaussian #3 sd 5
vop subtract #2 #4 modelId #5
vop unbend #0 #1 z 200 200

The operation can be:

• add - add two or more maps
• bin - reduce data size by averaging over cells of multiple grid points
• boxes - extract cubic regions centered on markers
• cover - extend map to cover specified atoms or box
• falloff - smooth the boundaries of masked density
• flatten - scale values to flatten map baseline
• fourier - Fourier transform
• gaussian - Gaussian smoothing or sharpening
• laplacian - Laplacian filtering
• localCorrelation - calculate map-map correlation over a sliding box
• maximum - take the maximum values pointwise from two or more maps
• median - set each value to the median of values in a surrounding box
• minimum - take the minimum values pointwise from two or more maps
• morph - morph (interpolate) between two or more maps
• multiply - multiply values in two or more maps
• new - create empty (zero-valued) map
• ~octant - erase positive octant
• octant - erase all but the positive octant
• permuteAxes - permute axes
• resample - resample on the grid of another map
• ridges - skeletonize; emphasize ridges or filaments in the density
• scale - scale, shift, normalize, and/or cast to a different data value type
• subtract - subtract another map from the first
• threshold - reassign values that are below a specified minimum and/or above a specified maximum
• tile - make a single-plane volume from tiled slices of another volume
• unbend - unbend a map near a path formed by markers/links or atoms/bonds
• unroll - unroll a cylindrical slab into a flat slab
• zFlip - reverse order of Z planes
• zone - zero the values at grid points within or beyond a cutoff distance from specified atoms

• vop add  volume-spec  [ scaleFactors f1,f2,... ] [ onGrid gridmap ] [ boundingGrid true|false ] [ gridStep N | Nx,Ny,Nz ] [ gridSubregion name | i1,j1,k1,i2,j2,k2 | all ] [ valueType value-type ]  general-options

Add two or more maps to create a new map. Option keywords are the same as for vop minimum, vop maximum, and vop multiply:

The scaleFactors keyword specifies a multiplier for each map (default 1.0); as many values as input maps must be supplied, separated by commas but not spaces.

The new map can be created on the grid of another map specified with onGrid, where gridmap is a model number preceded by #. If gridmap is not specified, it defaults to the first in volume-spec (the first of the maps being added). The input maps are resampled on the grid by trilinear interpolation, and the resulting values summed for each grid point. Note resampling causes some loss in resolution (details...). Further options related to gridmap:

• boundingGrid - whether to adjust (extend or shrink) the grid of gridmap to bound the input maps (default true when adding maps without specifying a gridmap, otherwise false)
• gridStep - whether to use the full resolution of gridmap (step size 1, default) or a specified subsample (step size > 1). Step sizes must be integers. If a single number is supplied, it is used along all three axes; if three numbers are supplied (separated by commas but not spaces), they are used along the X, Y, and Z axes, respectively.
• gridSubregion - whether to use the full extents of gridmap (all, default) or a specified subregion. A subregion can be specified by:
  • name previously assigned with volume (see nameRegion) or Volume Viewer (see Named regions)
  • grid indices i1–i2 along the X axis, j1–j2 along the Y axis, and k1–k2 along the Z axis. Grid indices must be integers separated by commas but not spaces.

The value-type defaults to the current type of the onGrid map (if any), otherwise the first in volume-spec, and can be 8-, 16-, or 32-bit signed integer (int8, int16, or int32), 8-, 16-, or 32-bit unsigned integer (uint8, uint16, or uint32), or 32- or 64-bit floating-point (float32 or float64).

If the new map is large, for example a whole tomogram, the command may fail for lack of memory. The whole new map must fit in memory.

Average over cells of multiple grid points in the original map to produce a smaller map. Supplying a single integer N (default 2) indicates partitioning the map into bins of NxNxN grid points and averaging the N³ values per bin to produce a new map with 1/N as many points in each dimension. Cells with different numbers of grid points in each dimension can be specified by supplying three integers N_x,N_y,N_z separated by commas only.

See also: segment

For each marker or atom in atom-spec, extract a surrounding cube of data. The edge length of each cube can be specified in physical units of length with size or in grid units with isize. If useMarkerSize is true, the diameter of its central marker or atom is used as the edge length or added to the size value if also given (default d = 0.0). The isize option facilitates getting the same-sized cubes for each marker, except where a marker is too close to the edge of the density map to obtain a cube of the requested size. If size is used instead, rounding may yield edges that differ slightly in grid dimensions.

Extend a map to cover specified atoms or to fill a rectangular box, using map symmetries and periodicity. The output dimensions can be specified as:

• atomBox spanning the specified atoms plus any extra pad in each dimension (d is in units of physical distance, default 5.0)
• box or just individual dimensions x, y, and/or z in the X,Y,Z coordinate system of the input map
• fbox or just individual dimensions fx etc. in fractional coordinates where 0.0-1.0 spans each dimension of the input map
• ibox or just individual dimensions ix etc. in grid indices of the input map. The input map's grid indices start at 0.

Unspecified dimensions will be kept the same as the input map. The output grid will have the same spacing and alignment as the grid of the input map. The cellSize option specifies unit cell dimensions in grid units along the X, Y, and Z axes. The default unit cell dimensions correspond to the full size of the map, or for CCP4 and MRC maps, are taken from the header. The useSymmetry option indicates whether to use any symmetries associated with the map (default true); if false, only unit cell periodicity will be used. Map symmetries are read from the CCP4 or MRC file header, or can be assigned manually with the symmetry option of volume or automatically with measure symmetry.

Values from symmetry copies are determined by trilinear interpolation (with potential loss in resolution, see details). Where symmetries and periodicity give multiple copies of the input map overlapping a grid point, the average value will be assigned. The maximum difference between values from different copies at a grid point will be reported in the Reply Log. If there are grid points not covered by symmetry or unit cell periodicity, a message will be sent to the Reply Log and status line, and the points will be assigned values of 0.0. To ensure complete coverage by symmetry copies, the asymmetric unit of the map should extend far enough that its symmetry copies overlap by a non-zero amount. For example, if the unit cell is 100 grid points wide and there is two-fold symmetry along the X axis, the asymmetric unit would need to contain at least 52 grid points along the X axis. If it contains only 50, the two symmetric copies will not overlap, and values in the space between the copies cannnot be determined because the current code cannot interpolate between different copies of the map. If it contains 51, the two copies will have a single plane of grid points in common. Although that would be sufficient with exact arithmetic, the copies still might not overlap given the rounding errors inherent in computer calculations.

Smooth the boundaries of a masked map by replacing the value at each grid point outside the boundary with the average of the values of its six nearest neighbors, for M iterations (default 10). All grid points with values of zero before the first iteration are taken to be outside the boundary, thus assigned a new value at each iteration. Thanks to Greg Pintilie for the initial implementation.

If the method is multiply, scale data values by factor (a*i + b*j + c*k + d) where i,j,k are the grid indices and a,b,c,d are calculated to zero out the first moments of the resulting map (make its mass balance at the center of the grid). If the method is divide, data values are divided by the factor (a*i + b*j + c*k + d), which is a least-squares fit to the map data values. For both methods, the a,b,c,d coefficients are scaled to make (a*i + b*j +c*k + d) equal to 1 at the center of the map. If a fitregion is specified, the calculation of the a,b,c,d coefficients uses only the data values in the specified region, while the scaling operation applies to the entire map or the part specified by the subregion general option. The fitregion can be the full extents of the data (all, default) or a subregion specified by:

• name previously assigned with volume (see nameRegion) or Volume Viewer (see Named regions)
• grid indices i1–i2 along the X axis, j1–j2 along the Y axis, and k1–k2 along the Z axis. Grid indices must be integers separated by commas but not spaces.

Calculate the 3D Fourier transform. If phase is false (default), generate a magnitude map; if phase is true, generate a map of phase values (–π to π) instead.

Perform Gaussian filtering, where σ is one standard deviation of the 3D Gaussian function in physical units such as Å (default 1.0). Different standard deviations along X,Y,Z can be specified as three values separated by commas only. Gaussian filtering (invert false, default) attenuates high frequencies to smooth the map. Using invert true instead amplifies the high frequencies to sharpen the map. Sharpening with σ values smaller than the pixel size is most useful; larger values overemphasize high frequencies, in effect amplifying noise. The value-type defaults to the current type and can be 8-, 16-, or 32-bit signed integer (int8, int16, or int32), 8-, 16-, or 32-bit unsigned integer (uint8, uint16, or uint32), or 32- or 64-bit floating-point (float32 or float64).

Perform Laplacian filtering.

Calculate the correlation between two maps over a sliding box of NxNxN grid points, generating a new map by assigning the correlation value to the box center. The sliding box is based on the grid of the first map, and N = 5 grid units by default. If the grids of the two input maps do not coincide, the values of the second map will be interpolated. The subtractMean option specifies subtracting the mean of the values in the window from each value in the window before calculating the correlation. The output map will be N–1 smaller in each dimension than the first map. It will be opened as model number M, or if not specified, the lowest unused model number.

Set each value to the maximum at that point in two or more input maps. See vop add for descriptions of the options.

Smooth the data by setting each value to the median of the values in a box centered at that point. Values at points for which the surrounding box extends outside the data are simply set to zero. Box dimensions are specified in grid units with binSize and must be odd integers. Supplying a single integer N (default 3) indicates a box size of NxNxN grid points. Boxes with different numbers of grid points in each dimension can be specified by supplying three integers N_x,N_y,N_z separated by commas only. The iterations option indicates how many cycles of smoothing to perform (default 1).

Set each value to the minimum at that point in two or more input maps. See vop add for descriptions of the options.

Morph between two or more maps (this is the command-line implementation of Morph Map, except that more than two maps can be handled). For a reasonable result, the input maps should have the same grids: dimensions, spacing, and numbers of points. Note vop resample can be used to make a copy of one map that has the same grid as another. A morphing fraction of 0.0 corresponds to the first map and a fraction of 1.0 corresponds to the last, with intermediate maps evenly spaced within that range. There is smooth interpolation between each adjacent pair of maps. See the video mini-example.

The morph display will proceed from start-fraction (default 0.0) in steps of increment (default 0.04) for N frames (default 25). By default (playDirection 1), the initial direction of play is from low to high fractions. If the number of frames and step increment are more than needed to reach the playRange bounds (default is the entire range: 0.0,1.0), the morph display will “bounce” back and forth. The scaleFactors keyword specifies a multiplier for each map (default 1.0); as many values as input maps must be supplied. The constantVolume option specifies adjusting the threshold (contour level) automatically to keep the enclosed volume constant. The addMode option specifies treating the second map as a delta to be added to the first instead of linearly interpolating between the two. It is not recommended for inputs of >2 maps. The hideOriginalMaps option specifies hiding the input maps. The interpolateColors option only applies when the maps have the same number of coloring thresholds (contour levels for surface/mesh display, coloring control nodes for solid display).

The morph is created as a new map (volume) model. However, if the modelId of an existing morph map is given, the new calculation will reuse the memory already allocated to that map, and the size of the input maps must match that of the existing map. The vop morph settings are not retained, however, and must be specified anew in the command.

See also: morph, vseries, movie-related commands, the ParM filament tutorial at the Chimera website

Multiply the values pointwise in two or more maps. This is used to apply a mask (values 0,1) to a map. See vop add for descriptions of the options.

Create an “empty” zero-valued map named map-name with the specified size (number of grid points along each axis, default 100), gridSpacing in physical distance units (default 1.0 along each axis), origin coordinates (default 0.0,0.0,0.0), and cellAngles (default 90,90,90°). Grid size and spacing can each be given as a single value to apply to all three axes or as three values separated by commas only. If map-name includes spaces, it must be enclosed in quotation marks. The value-type defaults to float32 and can be 8-, 16-, or 32-bit signed integer (int8, int16, or int32), 8-, 16-, or 32-bit unsigned integer (uint8, uint16, or uint32), or 32- or 64-bit floating-point (float32 or float64). The modelId option assigns model number N to the new map; the default is the lowest unused model number.

Erase values inside the positive octant (all grid points with X,Y,Z coordinates greater than the center). The center can be specified in physical units (such as Å) with center or in grid units with iCenter. The default is the center of the volume data box. The coordinates should be separated by commas but not spaces, and the values can be fractional. iCenter overrides center if both are given. The values in the erased regions will be set to value (default 0). A different value may improve contour surface appearance; for example, large negative values produce flatter surfaces where an octant has been cut away from a map of positive values.

Erase values outside the positive octant. Options are as described for vop ~octant above.

Permute grid axes to the specified order, which can be any of the 6 ordered combinations of x, y, and z. The original order is xyz.

Resample values on the grid of another map specified with onGrid, where gridmap is a model number preceded by #. Values on the grid are obtained by trilinear interpolation of the input map. The other arguments are as described above for vop add. Note resampling causes some loss in resolution (details...).

Skeletonize map(s) by tracing along high-density grid points to identify ridges or filamentous structures in the density. At each grid point, the value is compared to the values of all the points in the surrounding 3x3x3 box, and the count of how many directions (up to 13) along which the value is a local maximum is assigned as that point's value in the new map. The level keyword indicates a minimum value in the original map below which to automatically set the new value to 0, essentially ignoring those points in the skeletonization. The default minimum is the lowest display threshold (contour level) in the original map. Viewing the new skeleton map with a threshold of 6-10 highlights ridgelike features in the original map.

See also: Volume Tracer

Shift values by adding a constant (default 0.0), scale values by a multiplicative factor f (default 1.0), and/or cast them to a different data value type. When values are both shifted and scaled, the shift is applied first. Two normalization options calculate a scaling factor from the data:

• rms - scale values to make new-rms = ((∑x²)/N)^½ where x is each value and N is the total number of values
• sd - first shift values so that the mean is 0.0, then scale values to make new-std-dev = ((∑x²)/N)^½

If a factor f is also specified, it is applied last. The value-type defaults to the current type and can be 8-, 16-, or 32-bit signed integer (int8, int16, or int32), 8-, 16-, or 32-bit unsigned integer (uint8, uint16, or uint32), or 32- or 64-bit floating-point (float32 or float64).

See also: measure mapStats

Subtract the values of othermap from map, both specified by model number preceded by #. The scaleFactors keyword specifies multipliers f1 and f2 for map and othermap, respectively; two values must be supplied, separated by a comma but not spaces. Alternatively, the minRMS option can be used to scale othermap automatically to minimize the root-mean-square sum of the resulting (subtracted) values at grid points within the lowest contour of othermap.

The new map can be created on the grid of another map specified with onGrid, where gridmap is a model number preceded by #. If gridmap is not specified, it defaults to map. The input maps are resampled on the grid by trilinear interpolation, and the resulting values subtracted for each grid point. Note resampling causes some loss in resolution (details...).

The remaining arguments are as described above for vop add, except that boundingGrid always defaults to false. When subtraction from an unsigned-integer map could give negative numbers, the valueType option should be used to specify a signed data type for the result.

Replace all values that are below a mininum value (min) with newmin (default equal to min), and/or replace all values that are above a maximum value (max) with newmax (default equal to max).

Create a single-plane volume by tiling slices of a specified volume perpendicular to the specified axis (default z). The spacing of slices (default 1 grid unit) is given with the pstep keyword. The trim keyword indicates each slice should be trimmed on all four edges by i grid units (default 0). The slices are arranged into a single plane with number of rows r and number of columns c. If neither the number of rows nor the number of columns is supplied, they are computed to produce as near a square tiling as possible. If one or the other is supplied, the remaining parameter is adjusted to accommodate the total number of slices. The fillOrder setting (default ulh) specifies the tiling pattern, including the starting corner, the tiling direction (horizontal or vertical), and whether to reverse the order of slices. The first two characters specify the corner for the first tile, the first character being u for upper or l for lower and the second being l for left or r for right. These directions are defined with the specified axis pointing at the viewer and the remaining two axes pointing up and right. The third character is h for horizontal tiling or v for vertical tiling. The optional fourth character r indicates that the order of the slices should be reversed. The resulting volume data set has the same origin and orientation of axes as the original volume, and grid size 1 along the specified axis.

See also: segment sliceimage, topography, tile

Unbend a map near a path formed by markers/links or equivalently, atoms/bonds. The path-spec should be an atom-spec that specifies a single chain of atoms (markers) connected by bonds (links). The path will be mapped to the Z axis of the result. The new-y parameter defines what axis in the existing volume will be mapped to the Y axis of the result, and can be given as:

• x - X-axis
• y - Y-axis
• z - Z-axis
• x,y,z (three values separated by commas only) - an arbitrary vector
• an atom-spec of exactly two atoms (not necessarily bonded or in the same model) or one bond. A bond can only be specified by selecting it and using the word selected, sel, or picked; any atoms also selected at the time will be ignored.

The xsize and ysize parameters give the X and Y dimensions of the new map in physical units (typically Å). The gridSpacing s is the separation between grid points in the new map (default is the minimum spacing along the three axes of the input map). A cubic spline is placed through the path points and the input volume is interpolated on planes perpendicular to the splined path.

See also: segment sliceimage

Unroll a hollow cylindrical section of the map into a flat slab. The cylinder axis can be given as:

• x - X-axis
• y - Y-axis
• z (default) - Z-axis
• x,y,z (three values separated by commas only) - an arbitrary vector
• an atom-spec of exactly two atoms (not necessarily bonded or in the same model) or one bond. A bond can only be specified by selecting it and using the word selected, sel, or picked; any atoms also selected at the time will be ignored.

Cylinder axis and center (default 0,0,0) coordinates are interpreted in the coordinate system of the input map, unless another reference model is specified with coordinateSystem. The dimensions of the cylindrical slab are given in physical units of length, typically Å: length d (default is the map extent parallel to the cylinder axis) and inner and outer radii r1 and r2 (defaults are 90% of the smallest radius and 110% of the largest radius of the displayed isosurface, respectively, given the cylinder center and axis direction). The flattening is done by interpolating values from the original map on a cylindrical grid of points, then unwrapping the cylindrical grid into a rectangular grid. The cylinder radial direction becomes the X-axis of the new map, circumference the Y-axis, and cylinder axis direction the Z-axis. The gridSpacing s is the requested separation of grid points along each axis in the new map (default is the minimum spacing along the three axes of the input map). The actual spacing may be slightly different because the dimensions of the new map may not be an exact multiple of the requested value; the number of grid divisions along each axis is chosen to give spacing as close as possible to the requested value without being smaller.

Reverse the order of the Z planes.

Set the values of grid points farther than radius Å from any atom in atom-spec (those beyond the zone) to zero, or if invert is true, set the values of grid points within the zone to zero. If minimalBounds is true, make the resulting map as small as possible while enclosing the zone; otherwise, the dimensions will be the same as for the input map. If bondPointSpacing s is specified, use points along bonds in addition to the atoms to define the zone. The points along the bonds will be placed s × (bond radius) apart. Link radii in Volume Tracer are equivalent to bond radii, except when a link radius is 0.0, the corresponding bond radius is 1.0.

See also: the Zone feature in Volume Viewer

modelId  N
Open the new data set as model number N (an integer, optionally preceded by #). The default is the lowest unused number.

step  N | Nx,Ny,Nz
Whether to use the full resolution of the data (step size 1, default) or a specified subsample (step size > 1). Step sizes must be integers. A step size of 1 indicates all data points, 2 indicates every other data point, 3 every third point, etc. If a single number is supplied, it is used along all three axes; if three numbers are supplied (separated by commas but not spaces), they are used along the X, Y, and Z axes, respectively.

subregion  name | i1,j1,k1,i2,j2,k2 | all
Whether to use the full extents of the data (all, default) or a specified subregion. A subregion can be specified by:

• name previously assigned with volume (see nameRegion) or Volume Viewer (see Named regions)
• grid indices i1–i2 along the X axis, j1–j2 along the Y axis, and k1–k2 along the Z axis. Grid indices must be integers separated by commas but not spaces.

inPlace true|false
Whether to overwrite the existing data set in Chimera instead of creating a new one. Not all operations accept this option. Regardless of this setting, the existing data will only be overwritten if it was created in Chimera (for example with a previous vop command) rather than read from a file. In the case of map addition, the model to overwrite is the gridmap (the model whose grid will be used for the result).

Resampling and loss of resolution. There is some loss of resolution with resampling a map on a different grid with trilinear interpolation. The effect is similar to smoothing. The amount of reduction in resolution depends on the initial resolution, the initial and final grid spacing, the “bumpiness” of the data, and the shift between the grids. For example, starting with a 6-Å resolution map with 2-Å spacing from molmap and resampling on a grid (with the same spacing) shifted by 1 Å reduced resolution to approximately 7.7 Å. Starting with a 6-Å resolution map with 1-Å spacing and resampling on a grid shifted by 0.5 Å reduced resolution to approximately 6.4 Å.