VTK/Image Stencil Improvements
The VTK imaging pipeline support the idea of a "stencil," which is a selection region that can have any shape, 2D or 3D. The stencil is represented by the special data class vtkImageStencilData, which stores a binary image mask via run-length encoding. 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. Ideally, all image filters that have the same output data type as their input data type should support stencilling.
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.
Summary of Proposed Improvements
New classes:
- vtkImageStencilAlgorithm - fully upgrade stencils to the VTK 5 pipeline
- vtkImageStencilMerge - merge stencils via binary operations
- vtkROIStencilSource - create stencils of various simple shapes
- vtkLassooStencilSource - create stencils from contours
- vtkImageStencilToImage - convert a stencil into a binary mask image
- vtkImageStencilIterator - an iterator for image stencils
Improved classes:
- vtkPolyDataToImageStencil - make it work with 2D contours, instead of just 3D surfaces
There are several other items that would be nice to have, if people can volunteer the time:
- Stencil support for more filters, e.g. vtkImageMathematics
- Readers/writers for stencils
- Support for label values in stencils
Current Status (Nov 13, 2010)
vtkImageStencilAlgorithm
Done. But the vtkImageStencilSource class needs some cleanup:
- InformationInput needs to become a VTK-5 style input.
- Default WholeExtent is still an issue, it is inconsistent between subclasses.
vtkImageStencilMerge
Not started.
vtkROIStencilSource
Done. Support for boxes, ellipses, and cylinders in X, Y, and Z orientations.
vtkLassooStencilSource
Done. Support for polygonal and spline contours in X, Y, and Z orientations. Contours can be stacked, with a different contour for each slice.
vtkImageStencilIterator
Done. It is not a subclass of vtkImageIterator, though, because vtkImageIterator needs some improvement.
vtkPolyDataToImageStencil
Done. Supports 2D contours in the XY plane. Uses new polygon rasterization code in vtkLassooStencilSource. It could still be made much more efficient and flexible, e.g.:
- The cutting code could be replaced with faster code from vtkClipClosedSurface.
- It could support slicing in any direction, like vtkLassooStencilSource.
