Chimera Commands Index

Usage:
volume model-spec options

Volume is the command-line implementation of many features in Volume Viewer, a tool for visualizing volume data. Model-spec can be a specific model number or range of model numbers (preceded by #), 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. 

Examples:

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
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).

← General Display Options

show
Display the volume model.
hide
Undisplay the volume model.
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.
Separate sets of level, color, brightness, and transparency information are maintained for the surface/mesh and solid styles of a volume model; switching to solid from surface or mesh (or vice versa) restores any previous assignments for that style. See also: surface and mesh display options, solid display options
level threshold-level
Place a threshold for mapping data values to the display.
color threshold-color
Assign threshold color. The threshold-color can be any color name that specifies a single color (with any spaces stripped) or a numerical specification of the form R,G,B or R,G,B,A. In numerical specifications, each value ranges from 0.0 to 1.0: R, G, and B are red, green, and blue color components, respectively, and A is opacity (1–transparency). The default color is an opaque medium gray (0.7,0.7,0.7,1.0) for surface and mesh displays, white for solid.
Multiple level and color specifications can be included in a single command. If a color is specified but no levels, the color applies to all existing levels and becomes the default color for the volume model. If levels are given but no color, the model's current default color is used for the levels, and all old levels are removed. If one color and one or more levels are given, that color applies to all levels but does not become the default color. Otherwise, if multiple levels and colors are given, there must be an equal number of each. Levels and colors are paired in the order given, but they do not need to be interleaved; only the ordering of each type of specification (levels or colors) is significant.
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).
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) or a numerical specification of the form R,G,B. In numerical specifications, R, G, and B are red, green, and blue color components, respectively, each ranging from 0.0 to 1.0. The default color is white.

← Sampling and Size

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 step sizes turns off their automatic adjustment (see limitVoxelCount).
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.
The remaining options in this section apply to all volume models, regardless of which are specified:
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 32.0). 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.

← Dimensions and Scale

region full|all|name|i1,j1,k1,i2,j2,k2
Show the full data set (specified with full or 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 data origin at coordinates x,y,z (numbers separated by commas but not spaces).
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.
symmetry type[,subtype]
Assign the specified symmetry to the data set. This information is retained in files saved in Chimera map format and can be used by the sym command. If subtype is supplied, it should be separated from type by only a comma (no spaces). If subtype is omitted, the default value for that type will be used.

Currently the only type is icos (icosahedral), with subtype options:

← Saving to a File

save file
Write the current display region of the data to a file in MRC (default), NetCDF, or Chimera map format. The desired format can be indicated with the corresponding filename suffix .mrc, .nc, .cmap, or .cmp (overridden by saveFormat). The output pathname/filename file cannot contain spaces. However, specifying file as browse or browser will raise a dialog for saving the file. The output file header will include information for converting between grid indices and Cartesian coordinates, such as the origin and scale. If zoning is in effect, data will be written out for a region enclosing the zone, with values outside the zone set to zero.
saveFormat mrc|netcdf|cmap
Specify the save format as MRC (default), NetCDF, or Chimera map; the keywords are the corresponding filename prefixes. This option overrides any filename suffix supplied with save.

When Chimera map format is saved:

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: 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.

← Surface and Mesh Display 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 4j, 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.

← Solid Display Options

The solid display style shows data as a semitransparent solid.

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.
useColormap true|false
Whether to use a colormap for solid displays, in which data values are divided into a specified number of ranges and each range is mapped to a particular color and transparency. A colormap allows faster updates after changes in display settings. With some hardware, however, the updates may still be slow.
colormapSize N
How many ranges to use when useColormap is set to true (default 256). Smaller values result in coarser divisions and more abrupt gradations of color. If N is too high for the graphics hardware, an error message may result, or (depending on the GL implementation) the model may simply fail to appear. The hardware-determined maximum is typically 256 or 65356.
use2dTextures true|false
Whether to use 2D (default) or 3D texture mapping for solid displays. These give similar but not equivalent visual results. The 3D texture mapping method is not supported by some computer hardware. If 3D texture mapping is chosen but not supported by the computer hardware, an empty red outline box will be shown. If the hardware does support 3D texture mapping but the texture is too large, an empty yellow outline box will be shown. The 2D texture mapping method requires three times as much texture memory as the 3D method but has the advantage of working on all platforms.
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 (applies to solid displays with 2D texture mapping). Without this correction, the apparent brightness and transparency 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 31/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
When using 2D texture mapping, reuse a single 2D texture 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 (in two dimensions for 2D texture mapping, all three dimensions for 3D texture mapping). Turning interpolation off may yield a pixelated appearance but speed up rendering, depending on the graphics hardware.

See also: open, modeldisplay, mask, sym, meshmol, Volume Viewer