Chimera Commands Index

mask volume-model surf-models options

The mask command extracts a volume data subregion bounded by surfaces (details...). All kinds of surface models can be used, but not surfaces in VRML models. The new data set can be saved to a file using Volume Viewer or the command volume. See also: vop, Icosahedron Surface, Volume Tracer

Volume-model is the model number (preceded by #) of the starting volume data set. A new data set will be generated and opened as a different model.

Surf-models specifies the bounding surface(s) and can be one or more comma-separated model numbers (preceded by #) or the word sel to indicate the currently selected surfaces or surface pieces.


Option keywords for mask can be truncated to unique strings, and their case does not matter. Synonyms for true: True, 1. Synonyms for false: False, 0. A vertical bar "|" designates mutually exclusive options, and default settings are indicated with bold.
axis x,y,z
Projection axis vector (default is along the data Y axis: 0,1,0). This is relevant when the surfaces have holes. The region between surface layers is computed along the specified axis (see algorithm). Vector coordinates x,y,z are relative to the untransformed data. The vector can point in any direction (need not be parallel to the X, Y, or Z axis) and need not be of unit length.
fullmap true|false
Make the masked volume data set have the same dimensions as the original volume data set. Otherwise, the bounds will be set as small as possible to enclose the surfaces, and the masked volume may be smaller.
pad distance
Before computing the masked volume, move the surface by the specified distance along the surface normals. This allows extracting a larger or smaller region than is enclosed by the original surface. Positive or negative values can be used, and the units of length are the same as for the data (generally Å or nm).
slab width|d1,d2
Extract a slab of data around a surface layer. Two additional surfaces, displaced as specified from the existing surface and joined at their edges (if any), are computed but not displayed. Data for voxels between the computed surfaces are retained. If a single value (width) is supplied, the two computed surfaces are offset along the normals of the original surface by ±½(width). Alternatively, two values separated by a comma but no spaces can be used to specify the offsets of the two surfaces independently. Positive or negative values can be used, and the units of length are the same as for the data (generally Å or nm). The basic algorithm applies, except that the original surface is replaced by the pair of computed surfaces.
sandwich true|false
Include only volume voxels lying between two surface layers. Otherwise, the volume projected along the axis beyond a single surface layer will also be included (see algorithm).
invertMask true|false
Include the opposite data, the spatial complement of what would otherwise be included.

Mask Algorithm

The masked volume is computed by looking at intercepts of lines parallel to the projection axis with the surfaces. For a given line, the volume data between the 1st and 2nd, 3rd and 4th, 5th and 6th, ... intercepts are included in the masked volume, while those between the 2nd and 3rd, 4th and 5th, ... are excluded. The intercepts are computed for lines through points on a rectangular grid normal to the projection axis with spacing equal to the minimum grid plane spacing of the volume data set. For each volume voxel, the intercepts of the closest grid line are used to determine inclusion in the masked volume. If there is an odd number of intercept points, then points beyond the final intercept are included in the masked volume unless the sandwich option is used. In the new data set, values outside the masked region are set to zero and those inside are set to the original volume values. The grid points of the calculated volume align exactly with those of the original volume. The bounds are set to minimally enclose the surfaces unless the fullmap option is used. The full size of the original volume data set is used even if only a subregion is being displayed.