Usage:
volume model-spec options

Volume is the command-line implementation of many features in Volume Viewer, a tool for visualizing volume data. See also: open, vop, vseries, mask, molmap, topography, measure, scolor, sym, fitmap, meshmol, Volume Viewer

Model-spec can be a specific model number or range of model numbers (preceded by #), or simply # or the word all to indicate all volume models. Several of the sampling and size options apply to all volume models, regardless of which are specified.

Option keywords for volume can be truncated to unique strings, and their case does not matter. Specifications of true (synonyms t, yes, y, on, 1) and false (synonyms f, no, n, off, 0) are also case-independent. A vertical bar “|” designates mutually exclusive options, and factory default settings are indicated with bold (different defaults can be saved from Volume Viewer, however).

volume #0 style mesh level 0.8 color red level 1.2 color 0,.5,.8
volume #2 level 10,0 level 100,1 level 400,1 color hotpink style solid
vol all hide

General Display Options
Sampling and Size Options
Dimension and Scale Options
Planes Options
File-Saving Options
Surface and Mesh Display Options
Solid Display Options

← General Display Options     (Usage: volume model-spec options)

• show
Display the volume model.

• hide
Undisplay the volume model.

• toggle
Of the specified volume models, show those that are hidden and hide those that are shown.

• style surface | mesh | solid
Designate the style of display: the surface and mesh modes depict isosurfaces (contour surfaces), while the solid mode shows data as a semitransparent solid.

• level threshold-level
Place a threshold for mapping data values to the display. See the video mini-example.

• For surface and mesh displays, threshold-level is a single number, the contour level of the surface. This corresponds to horizontal placement on a histogram in the graphical interface. To adjust the threshold level automatically so that the contour encloses a specified spatial volume, see the encloseVolume and fastEncloseVolume options.
• For solid displays, threshold-level consists of two numbers separated by a comma (no spaces). The first number indicates a data value and the second number indicates an intensity ranging from 0.0 to 1.0. These correspond to horizontal and vertical placement, respectively, on a histogram in the graphical interface.

• rmsLevel threshold-level
• sdLevel threshold-level
Same as level, except with threshold-level specified in units of root-mean-square (RMS) deviations from zero or standard deviations (SD) from the mean, respectively, calculated for the current display region and step size. See also: measure mapStats, vop scale

• color threshold-color
Assign threshold color. The threshold-color can be any color name that specifies a single color (with any spaces stripped). The default color is an opaque medium gray (0.7,0.7,0.7,1.0) for surface and mesh displays, white for solid. See also: scolor

• encloseVolume volume
Automatically set surface or mesh threshold level to enclose the specified volume in distance units cubed (e.g., ų if the grid spacing is expressed in Å). Multiple volume models can be specified in the same command to make their isosurfaces enclose the same spatial volume. The level is determined by an iterative procedure. In each iteration, the density value midway between the upper and lower bounds is tested. If the resulting enclosed volume is larger (smaller) than the target, that midpoint value becomes the new lower (upper) bound. In the first iteration, the upper and lower bounds are the maximum and minimum values in the map. Iteration stops when the actual enclosed volume differs from the target by less than 0.001 of the target or 30 iterations have been performed. The fastEncloseVolume option is similar but uses a noniterative approximation. See also: measure volume, vseries align

• fastEncloseVolume volume
Automatically set surface or mesh threshold level to enclose the specified volume in distance units cubed (e.g., ų if the grid spacing is expressed in Å). Multiple volume models can be specified in the same command to make their isosurfaces enclose the same spatial volume. The number of grid points to enclose is estimated by dividing the target volume by the volume of one grid cell, and then the level corresponding to that number of points is estimated by sorting the data values into 10,000 bins of equal width and identifying the value bin that attains (cumulatively) that number of points. The encloseVolume option is similar but uses an iterative procedure with increased accuracy at the cost of increased computation time. See also: measure volume, vseries align

• brightness value
Brightness scales the intensity of the color of the display. Values can range from 0.01 to 10.0, where 1.0 (the default) produces no change relative to the specified colors.

• transparency value
Transparency values range from 0.0 (fully opaque) to 1.0 (fully transparent).

• For surface and mesh displays, transparency is the fraction of light transmitted from behind the surface or a line of mesh (default 0.0). By default, these objects are dimmed as they are made more transparent (see dimTransparency.)
• For solid displays, this transparency setting further modulates initial transparencies obtained from the transfer function in a way that compensates for the thickness of the display (details). Values range from 0.0 (no modulation) to 1.0, default 0.5. By default, more transparent voxels are made dimmer (see dimTransparentVoxels).

• showOutlineBox true | false
Outline the bounding box of the current display region.

• outlineBoxRgb outline-color
Assign a color to the outline box. The outline-color can be any color name that specifies a single color (with any spaces stripped). Any transparency in the color will be ignored. The default color is white.

← Sampling and Size Options     (Usage: volume model-spec options)

• step N | Nx,Ny,Nz
Step values indicate sampling density; a step of 1 means all data points are used to generate the display, while 2 means every other data point is taken along each axis. Step sizes must be integers. If a single number is supplied, it is used in all three directions; if three numbers are supplied (separated by commas but not spaces), they are used in the X, Y, and Z directions, respectively. Changing a step value will change the data size limit for automatic step adjustment (see voxelLimit).

• limitVoxelCount true | false
Automatically adjust step size so that no more than the specified voxel limit is displayed.

• voxelLimit limit
Set the maximum number of Mvoxels to be displayed (default 1.0) when limitVoxelCount is set to true.

• showOnOpen true | false
Automatically display a data set when it is opened if it does not exceed a specified size.

• voxelLimitForOpen size
Set the data size limit in Mvoxels below which data should be automatically displayed when opened (default 256.0) when showOnOpen is set to true.

• showPlane true | false
Initially display just a single plane (normal to the Z axis) of a data set if it exceeds a specified size.

• voxelLimitForPlane size
Set the data size limit in Mvoxels above which a single plane of the data should be initially displayed (default 256.0) when showPlane is set to true.

• dataCacheSize size
Set how much memory in Mb should be dedicated to volume data (default 512). A cache can improve performance, since accessing cached data is faster than reading it from disk. The least recently displayed data values are purged to maintain the specified size. The data cache only accounts for approximately 1/3 to 1/2 of the memory used in viewing volume data, as additional memory is occupied by surfaces and color arrays.

← Dimension and Scale Options     (Usage: volume model-spec options)

• region all | name | i1,j1,k1,i2,j2,k2
Show the full data set (specified with all), or the data region previously assigned name, or the data region with 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.

• nameRegion name
Assign name to the currently displayed region.

• origin x,y,z
Place the grid origin at coordinates x,y,z (numbers separated by commas but not spaces).

• originIndex i,j,k
Place the coordinate origin (0,0,0) at grid indices i,j,k (numbers separated by commas but not spaces). Fractional and negative values are allowed, as the origin is not required to coincide with a grid point or even to fall within the grid.

• voxelSize S | Sx,Sy,Sz
Voxel size indicates the scale of the data set, the spacing of points in units of distance. If a single number is supplied, it is used in all three directions; if three numbers are supplied (separated by commas but not spaces), they are used in the X, Y, and Z directions, respectively. The grid is anchored at the coordinate origin (originIndex remains unchanged).

• symmetry sym-type
Assign the specified symmetry to the volume data set. This information is retained in files saved in Chimera map format and can be used by other commands such as sym and fitmap. For automatic symmetry detection and assignment, see the command measure symmetry. Specifications of sym-type are case-independent, and most types have additional sub-options or parameters:

• symmetry of model #N - use biomt information from a molecule model or the symmetry assignment of another volume model
  • Example: #4
• cage model polygon symmetry #N,pM or #N,pnM - place copies at equivalent positions relative to each M-sided polygon in the cage model with ID number N. The pM form places one copy per M-sided polygon, whereas pnM places M copies per M-sided polygon using CM symmetry about the center of the M-sided polygon nearest the original copy.
  • Examples: #2,p6 or #2,pn5
• cyclic symmetry Cn around axis and center
  • Example: C3
• dihedral symmetry Dn around axis and center
  • Example: d7
• tetrahedral symmetry T[,orientation] around center
  • Example: t,z3
  where orientation can be:
  • 222 (default) - with two-fold symmetry axes along the X, Y, and Z axes, a three-fold along axis (1,1,1)
  • z3 - a three-fold symmetry axis along Z, another three-fold axis in the YZ plane such that rotation about the X axis by ~110° is a symmetry operation (EMAN convention)
• octahedral symmetry O around center
• icosahedral symmetry I[,orientation] around center
  • Example: i,n25
  where orientation can be:
  • 222 (default) - with two-fold symmetry axes along the X, Y, and Z axes
  • 2n5 - with two-fold symmetry along X and 5-fold along Z
  • n25 - with two-fold symmetry along Y and 5-fold along Z
  • 2n3 - with two-fold symmetry along X and 3-fold along Z
  • 222r - same as 222 except rotated 90° about Z
  • 2n5r - same as 2n5 except rotated 180° about Y
  • n25r - same as n25 except rotated 180° about X
  • 2n3r - same as 2n3 except rotated 180° about Y
• helical symmetry H,rise,angle,n[,offset] around axis and center
  • Example: h,43.5,21,6,-2
  where rise is the translation along the axis per subunit, angle is the rotation in degrees per subunit, and n is how many copies total (including the original) the resulting segment of infinite helix should contain. The integer offset (default 0) allows extending the helix in both directions. The example above would give n = 6 copies total, with two copies in the negative axis direction, one at the identity position, and three in the positive axis direction.
• translational symmetry shift,n,distance along axis – or – shift,n,x,y,z
  • Example: shift,3,26.7
  where n is how many copies total (including the original) the result should contain. The translation can be expressed as a distance along the axis or as a vector x,y,z in the reference coordinate system.
• the product of symmetry groups, each specified as described above and separated by * to indicate multiplying each symmetry matrix of one group with each symmetry matrix of another; can be generalized to multiple symmetry groups (not just two)
  • Example: c2*h,42,21,9,-4

• axis axis
Specify axis of symmetry (default z), where axis can be:

• x - X-axis
• y - Y-axis
• z - Z-axis
• x,y,z (three values separated by commas only) - an arbitrary vector in the reference coordinate system
• 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.

• center center
Specify center of symmetry in physical coordinates (default 0,0,0), where center can be:

• x,y,z (three values separated by commas only) - an arbitrary point in the reference coordinate system
• an atom-spec of any combination of atoms and surface pieces. The center of the bounding sphere of the specified items will be used.

This option is overridden by centerIndex.

• centerIndex [ i | i,j,k ]
Specify center of symmetry in grid coordinates, given as a single value or three values separated by commas only. Fractional and negative values can be used. If a single value is given, it is used as the grid coordinate along all three axes. This option overrides center.

• coordinateSystem N
Specify a reference model by model number N preceded by #. The reference coordinate system is used for interpreting specifications of axis and center of symmetry.

← Planes Options     (Usage: volume model-spec options)

• planes axis,start[,end[,increment[,depth]]]
Sequentially display slabs depth planes thick along the specified data axis (x,y, or z) starting from index start and repositioning the slab by increment grid units per frame until the index at the next frame would exceed end. The indices refer to the first displayed plane along the axis. If no end is supplied, only a single slab will be shown. The default increment and depth are both 1. Only planes that are multiples of the step size will be shown, and the depth refers to the number of planes shown rather than a grid index range. Although an increment smaller than the step size can be specified, at each frame the grid index will be rounded down to a multiple of the step size, resulting in the same plane being displayed in more than one frame. To avoid this, change the step size to 1 beforehand or specify start, end and increment values consistent with the current step size. The start, end, increment, and depth parameters can be floating-point numbers. For example, an increment of 0.25 with step size 1 will show each plane for 4 frames. See the video mini-example. See also: vop tile

• expandSinglePlane true | false
Expand a single-plane display along its perpendicular axis to the full thickness of the data. This option does not apply to orthogonal planes.

• orthoplanes xyz | xy | yz | xz | off [ positionPlanes i,j,k ]
Display planes perpendicular to the X, Y, and/or Z data axes within the current region. If only a single plane is shown beforehand, it will be expanded to define the region. The positionPlanes option specifies plane locations along the axes by integer grid indices (default 0,0,0 or the lowest indices in the current region). Orthogonal planes automatically use the solid display style, opaque color mode, and an outline, although these can be overriden with the corresponding command options. Turning orthogonal planes off restores the auto8 color mode.

• boxFaces true | false
Display orthogonal planes as the six box faces of the current region. If only a single plane is shown beforehand, it will be expanded to define the region. Box-face planes automatically use the solid display style, opaque color mode, and an outline, although these can be overriden with the corresponding command options. Turning box-face planes off restores the auto8 color mode.

← File-Saving Options     (Usage: volume model-spec options)

• save filename [ append true|false ] [ saveStep N | Nx,Ny,Nz ] [ saveRegion all | name | i1,j1,k1,i2,j2,k2 ] [ maskZone true|false ] [ baseIndex M ]
Write the data to a file in MRC (default), NetCDF, Chimera map, BRIX, or IMAGIC format. The desired format can be indicated with the corresponding filename suffix: .mrc, .nc, .cmap or .cmp, .brix, or for IMAGIC, .hed or .img, which will save both (the two files together describe a single map). The saveFormat designation overrides the suffix if they conflict. For Chimera map format only, append true can be used to append the data to an existing file instead of overwriting it.

The output pathname filename cannot contain spaces. However, specifying filename as browse or browser will raise a dialog for saving the file. Multiple data sets can be written to multiple files by including a %d integer format specification in filename:

volume #2,3,7 save data%d.mrc
volume #2,3,7 save data%03d.mrc

The first example would generate the files data1.mrc, data2.mrc, and data3.mrc, while the second would instead use names like data001.mrc. Successive integers starting with baseIndex M (default 1) will be used in the new names regardless of the volume model numbers. If the format specification is incorrect, filename will be interpreted as the name of a single file. Only the Chimera map format can accommodate multiple data sets in a single file.

The output file header will include information for converting between grid indices and Cartesian coordinates, such as the origin and scale.

• saveStep indicates whether to write 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.
• saveRegion indicates whether to write the full extents of the data or a specified subregion. The full extents are specified by all, while a subregion can be specified by name (previously assigned) or by 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. If the saveRegion option is not supplied, the currently displayed subregion will be written. In this context, a zone is not considered a subregion.
• If maskZone is true and zoning is in effect (using Surface Zone or the Zone feature in Volume Viewer), data will be written out for a region enclosing the zone, with values outside the zone set to zero.

• saveFormat mrc | netcdf | cmap | dsn6 | imagic
Specify the save format as MRC (default), NetCDF, Chimera map, BRIX, or IMAGIC; the keywords are the same as the corresponding filename prefixes. This option overrides any filename suffix supplied with save.

When Chimera map format is saved:

• multiple data sets can be saved to a single file (multiple models can be specified)
• the data layout can be controlled with chunkShapes
• the file can be compressed with compress
• the file will include any symmetry assignment

• chunkShapes order
Control data layout when saving Chimera map format. Layout affects the efficiency of later reading the data, primarily a concern for very large data sets (hundreds of Mb). The order can be one or more of the following, separated by commas but not spaces:

• zyx (default)
• zxy
• yxz
• yzx
• xzy
• xyz

Data are written in blocks of up to 64 Kb. The blocks are shaped according to the specified order: smallest along the first axis and largest along the third. Data planes are read from a file with different efficiencies depending on their orientations and the layout. For example, from data written in the default order (zyx), XY planes will be read the most efficiently and YZ planes the least efficiently. When multiple orders are specified, multiple copies of the data are written to the same file. When the file is read, the most efficient copy available will be used. Saving a file with an order ending in "z" can be very slow because one Z-plane is written at a time.

• compress true | false
Compress the file when saving Chimera map format. Most useful for volume masks (values 0/1), as other data sets tend to be noisy and compress very little, if at all.

• dumpHeader true | false
Write the file header contents (if any) of a map read from MRC or CCP4 format to the Reply Log.

← Surface and Mesh Display Options     (Usage: volume model-spec options)

The surface and mesh display styles both depict isosurfaces.

• surfaceSmoothing true | false
Whether to smooth surface and mesh displays. Smoothing entails moving each vertex a specified fraction of the way toward the average position of its neighbors a specified number of times.

• smoothingIterations N
How many iterations of smoothing to perform (default 2) when surfaceSmoothing is set to true. Each vertex is moved once per iteration.

• smoothingFactor f
How far to move each vertex when surfaceSmoothing is set to true. In each iteration, each vertex is moved a fraction f (ranging from 0.0 to 1.0, default 0.3) of the way toward the average position of the vertices connected to it by triangle edges.

• subdivideSurface true | false
Whether to subdivide each triangle in surface and mesh displays into four smaller triangles a specified number of times. A triangle is subdivided by connecting the midpoints of its edges. Subdivision can help to produce smoother surfaces when combined with the surfaceSmoothing option.

• subdivisionLevels j
How many times to subdivide triangles when subdivideSurface is set to true. The number of triangles is increased by a factor of 4^j, where j is a positive integer (default 1).

• smoothLines true | false
Turn on anti-aliasing to smooth lines in mesh displays. Mesh lines with transparency > 0.0 can only be smoothed when dimTransparency is true. A side effect of OpenGL anti-aliasing is that dense meshes look brighter from some viewpoints and darker from others, depending on the order in which the lines were drawn.

• squareMesh true | false
Display only a subset of the lines in the triangular mesh. Lines in the square mesh show the intersection of the XY, YZ, and XZ grid planes with the contour surface.

• lineThickness width
Set pixel linewidth used in mesh displays. The width must be a positive integer (default 1).

• dimTransparency true | false
Decrease the brightness of surface and mesh displays as their transparency is increased. When dimming is on, OpenGL (alpha,1–alpha) blending is used instead of (1,1–alpha) blending.

• meshLighting true | false
Make the inside of a mesh-enclosed volume dimmer than the outside by varying the brightness according to the angle between each surface point normal and the line of sight. Brightness is maximal when the outward-facing normal is parallel to the line of sight and pointing at the user (see more on the definition of "outward" under flipNormals). When this option is off, brightness is uniform regardless of the angle between the normal and the line of sight.

• twoSidedLighting true | false
Light both sides of surface displays. Otherwise, only the outside of a surface-enclosed volume will be lit (see more on the definition of "outside" under flipNormals). The brightness of each lit side varies according to the angle between a surface point normal and the line of sight; brightness is maximal when the normal is parallel to the line of sight.

• flipNormals true | false
Affects surface displays when twoSidedLighting is set to false, mesh displays when meshLighting is set to true. When flipNormals is true, the side toward larger or more positive values is treated as the outside for negative thresholds and the side toward smaller or more negative values is treated as the outside for positive thresholds (appropriate for data in which the sign is meaningful, such as electrostatic potential). When flipNormals is false, the side toward smaller or more negative data values is always treated as the outside.

• capFaces true | false
Cover the faces of the volume data box where high values would be exposed.

← Solid Display Options     (Usage: volume model-spec options)

The solid display style shows data as a semitransparent solid.

• colorMode cmode
Specify color pixel format (OpenGL texture format). Possible values of cmode combine a string describing the types of information:

• rgba - multiple colors and transparency
• rgb - multiple colors, opaque
• la - luminance (single color) and transparency
• l - luminance (single color), opaque
• auto - set the mode based on the current display

with a number of bits: 4, 8, 12, 16. For example, the default cmode is auto8.

• projectionMode pmode
Specify projection mode for memory-efficient display of large data sets such as tomograms. Possible values of pmode:

• auto (default)
• 2d-x
• 2d-y
• 2d-z
• 2d-xyz
• 3d

Displaying just the planes perpendicular to one data axis (2d-x, 2d-y, or 2d-z) uses less memory than automatically switching to those along the data axis most perpendicular to the screen at a given time (2d-xyz). The auto setting uses 2d-z for volumes with X or Y dimensions at least 4 times greater than Z, otherwise 2d-xyz. The 3d option (3D texture mapping) uses planes perpendicular to the current line of sight, which may not lie along any data axis. If this option is chosen but not supported by the computer hardware, an empty red outline box will be shown; if it is supported but the texture is too large, an empty yellow outline box will be shown.

• maximumIntensityProjection true | false
At each pixel, display the the most intense color value underlying the pixel along the line of sight. The maximum intensities of the red, green, and blue color components are determined separately, and transparency is ignored. This option can be useful for enhancing detail. Unphysical effects can result, but are usually not very noticeable; examples include the disappearance of a dim spot when it passes in front of a brighter spot and the simulation of a single spot when the maximal values of different color components under the same pixel actually come from different spots.

• dimTransparentVoxels true | false
Scale voxel brightness in solid displays by a factor of (1–transparency). Otherwise, increasing the transparency also makes a volume appear brighter, because less light is blocked.

• btCorrection true | false
Correct brightness and transparency for the viewing angle. Without this correction, the apparent brightness and transparency of solid displays (in projection modes other than 3d) will depend on the viewing angle relative to the data axes. For a cube-shaped volume with equal resolution in the X, Y, and Z dimensions, the brightness drops and the transparency increases by a factor of 3^1/2 (approximately 1.7) as the viewing angle is changed from along any axis to along the cube diagonal. The brightness correction remedies this, but doubles rendering time.

• minimalTextureMemory true | false
Reuse a single 2D texture for solid displays (in projection modes other than 3d) instead of allocating separate textures for every plane of the data. This is useful for viewing large data sets that would otherwise fail to display, but can degrade interactive response.

• linearInterpolation true | false
Linearly interpolate brightness and transparency between voxels in solid displays. Turning interpolation off may yield a pixelated appearance but speed up rendering, depending on the graphics hardware.