VTK/Image Stencil Improvements
Some of the VTK image filters can operate through a "stencil", which is represented by the special data class vtkImageStencilData. This class stores a binary image mask via run-length encoding. This encoding is used for the sake of speed and low memory usage. Stencils have existed in VTK since VTK 4, but are not supported by many filters, and more importantly, were never fully moved over to the VTK 5 pipeline executives. The goal of this project is correct the shortcomings of the stencils.
Description of vtkImageStencilData
The purpose of vtkImageStencilData is to store a binary image mask. It does so via run-length encoding, where the runs alternate between zero (black) and unity (white). This run-length encoding was chosen for two reasons:
- Compactness -- image masks are usually very sparse
- Efficiency -- the run lengths can be traversed very fast
The traversal of the stencil can easily be driven by an iterator (but unfortunately, such an iterator has not been written). Random-access of voxel values in the stencil is O(n) where n is the number of run-lengths in the row being accessed. It could be made to be O(log(n)) but since n is typically less than four, there would be little advantage in doing so.
In the current implementation, stencils are strictly binary, but they could be extended to be multi-value to allow them to be used as labels. This would require the addition of a scalar array to vtkImageStencilData.
The superclass of vtkImageStencilData is vtkObjectData, instead of vtkDataSet. This means that, unlike other kinds of VTK data, a vtkImageStencilData cannot be abstractly represented as a collection of points and cells.
Status as of VTK 5.6
As of VTK 5.6, the support for stencils is unchanged as compared to VTK 4.2. Only a small number of classes can use stencils:
- vtkImageStencil - combine two images via a stencil
- vtkImageBlend - apply a stencil while blending images
- vtkImageReslice - ignore all out-of-stencil voxels, set them to the background color
- vtkImageAccumulate - generate a histogram of only the voxels in the stencil
Stencils can be created in the following ways:
- vtkImageToImageStencil - threshold an image to create a stencil
- vtkImplicitFunctionToImageStencil - generate stencil from an implicit function
- vtkPolyDataToImageStencil - generate stencil from a surface mesh
The vtkImageStencilData class also has methods for doing in-place binary addition and subtraction of stencils, but there are no filters for performing these operations, hence they cannot be pipelined.
There is currently no way to load stencils from disk or save them to disk, except through conversion to and from vtkImageData. The stencil is stored as a sequence of run-lengths for each row of an image, which is a very compact, but this compactness is lost if the stencil is converted into an image.
