The SoVolumeMask SoVolumeMask SoVolumeMask node specifies an arbitrary voxel-based region of a volume data set (SoVolumeData SoVolumeData SoVolumeData ). A volume mask is itself a data volume consisting of binary values. Zero values are "false" and non-zero values are "true". A large number of masks may be defined simultaneously, using an SoVolumeMask SoVolumeMask SoVolumeMask node for each one, and mask regions may overlap if desired.
SoVolumeMask SoVolumeMask SoVolumeMask is derived from SoVolumeData SoVolumeData SoVolumeData . Like SoVolumeData SoVolumeData SoVolumeData it accesses its data through an SoVolumeReader SoVolumeReader SoVolumeReader class. I.e. the data may be in a file or in memory (or any data source using a custom volume reader). The mask volume can be any data type, but unsigned byte is currently the most memory efficient representation.
SoVolumeMask SoVolumeMask SoVolumeMask nodes must follow these rules:
Each mask volume must have exactly the same voxel dimensions and tile size value as the data volume it is applied to.
All SoVolumeMask SoVolumeMask SoVolumeMask nodes must be children of an SoVolumeMaskGroup SoVolumeMaskGroup SoVolumeMaskGroup node.
The SoVolumeData SoVolumeData SoVolumeData node and the SoVolumeMaskGroup SoVolumeMaskGroup SoVolumeMaskGroup nodes must be children of an SoMultiDataSeparator SoMultiDataSeparator SoMultiDataSeparator node.
The SoVolumeData SoVolumeData SoVolumeData and associated SoVolumeMask SoVolumeMask SoVolumeMask nodes must each have a different value assigned to their dataSetId field (see SoDataSet SoDataSet SoDataSet ).
![[Warning]](../../images/warning.jpg)
SoVolumeData SoVolumeData SoVolumeData and SoVolumeMask SoVolumeMask SoVolumeMask both have a default value of 1 for the dataSetId field, so some ids must be explicitly set.
Currently SoVolumeMask SoVolumeMask SoVolumeMask nodes only affect volume rendering (SoVolumeRender SoVolumeRender SoVolumeRender ). They do not affect slice rendering or other VolumeViz primitives.
SoVolumeMask SoVolumeMask SoVolumeMask can be used to clip the data volume on a per-voxel basis. But the mask mechanism is much more powerful than that. Each region can have its own transfer function (color map) using SoTransferFunction SoTransferFunction SoTransferFunction nodes. Each region can also have its own draw style (volume rendering, isosurface or boundary) using SoVolumeDataDrawStyle SoVolumeDataDrawStyle SoVolumeDataDrawStyle nodes. Each region, including the original unmasked volume, is only visible if there exists a transfer function (SoTransferFunction SoTransferFunction SoTransferFunction ) with the same id value.
Mask regions:
A single SoVolumeMask SoVolumeMask SoVolumeMask node effectively defines two regions:
False voxels (where the mask voxel = 0), and
True voxels (where is mask voxel != 0).
Because intersecting regions are allowed, two SoVolumeMask SoVolumeMask SoVolumeMask nodes define (up to) four regions:
False (where all masks are 0),
True only in mask 1,
True only in mask 2, and
True in more than one mask (intersection region).
Each additional mask defines one additional region (voxels that are true only in that mask).
In addition, if there exists a transfer function with the same id as the original volume (SoVolumeData SoVolumeData SoVolumeData node), the color value from that transfer function is combined with the color value from the mask region's transfer function.
Transfer functions:
A separate transfer function can be specified for each of these regions using SoTransferFunction SoTransferFunction SoTransferFunction nodes. The transfer function nodes may be placed under the SoVolumeMaskGroup SoVolumeMaskGroup SoVolumeMaskGroup node, but this is not required.
A transfer function is associated with a specific mask (i.e. with the voxels that are true only in that mask), by setting the SoTransferFunction SoTransferFunction SoTransferFunction node's transferFunctionId equal to the mask's dataSetId . If there is no transfer function with the same id as the mask, then that mask is ignored.
A transfer function is associated with all "false" voxels (voxels that do not belong to any mask) by setting its transferFunctionId equal to zero. If there is no transfer function with id = 0, then "false" voxels are not rendered.
A transfer function is associated with all "intersection" voxels (voxels that belong to more than one mask) by setting its transferFunctionId equal to SoVolumeMaskGroup SoVolumeMaskGroup SoVolumeMaskGroup ::TRANSFERFUNCTION_INTERSECTION_ID. If there is no transfer function with this id value, then intersection voxels (if any) are rendered using the default GRAY color map.
Draw Styles:
A separate draw style can be specified for each mask region and for the intersection voxels (but not for false voxels) using SoVolumeDataDrawStyle SoVolumeDataDrawStyle SoVolumeDataDrawStyle nodes:
Unlike transfer functions, a draw style is associated with a mask (voxels that are true only in that mask) by traversal order. In other words, each mask uses the draw style that is current when the mask is traversed. So you need to put SoVolumeDataDrawStyle SoVolumeDataDrawStyle SoVolumeDataDrawStyle nodes under the SoVolumeMaskGroup SoVolumeMaskGroup SoVolumeMaskGroup , alternating draw style, mask, draw style, mask.
A draw style is associated with all "intersection" voxels (voxels that belong to more than one mask) by placing it before the SoVolumeMaskGroup SoVolumeMaskGroup SoVolumeMaskGroup node in the scene graph.