Allows datasets with arbitrary storage layouts to be used with VTK. More...

#include <vtkMappedUnstructuredGrid.h>

Inheritance diagram for vtkMappedUnstructuredGrid< Implementation, CellIterator >:

Collaboration diagram for vtkMappedUnstructuredGrid< Implementation, CellIterator >:

Public Types
typedef vtkTypeTemplate < vtkMappedUnstructuredGrid < Implementation, CellIterator > , vtkUnstructuredGridBase >	Superclass
typedef Implementation	ImplementationType
typedef CellIterator	CellIteratorType
Public Member Functions
void	PrintSelf (ostream &os, vtkIndent indent)
void	CopyStructure (vtkDataSet *pd)
void	ShallowCopy (vtkDataObject *src)
vtkIdType	GetNumberOfCells ()
vtkCell *	GetCell (vtkIdType cellId)
void	GetCell (vtkIdType cellId, vtkGenericCell *cell)
int	GetCellType (vtkIdType cellId)
void	GetCellPoints (vtkIdType cellId, vtkIdList *ptIds)
vtkCellIterator *	NewCellIterator ()
void	GetPointCells (vtkIdType ptId, vtkIdList *cellIds)
int	GetMaxCellSize ()
void	GetIdsOfCellsOfType (int type, vtkIdTypeArray *array)
int	IsHomogeneous ()
void	Allocate (vtkIdType numCells, int extSize=1000)
vtkIdType	InsertNextCell (int type, vtkIdList *ptIds)
vtkIdType	InsertNextCell (int type, vtkIdType npts, vtkIdType *ptIds)
vtkIdType	InsertNextCell (int type, vtkIdType npts, vtkIdType ptIds, vtkIdType nfaces, vtkIdType faces)
void	ReplaceCell (vtkIdType cellId, int npts, vtkIdType *pts)
unsigned long	GetMTime ()
void	SetImplementation (ImplementationType *impl)
ImplementationType *	GetImplementation ()
Protected Types
typedef vtkMappedUnstructuredGrid < Implementation, CellIterator >	ThisType
Protected Member Functions
	vtkMappedUnstructuredGrid ()
	~vtkMappedUnstructuredGrid ()
Protected Attributes
vtkSmartPointer < ImplementationType >	Impl

Detailed Description

template<class Implementation, class CellIterator = vtkMappedUnstructuredGridCellIterator<Implementation>>
class vtkMappedUnstructuredGrid< Implementation, CellIterator >

Allows datasets with arbitrary storage layouts to be used with VTK.

This class fulfills the vtkUnstructuredGridBase API while delegating to a arbitrary implementation of the dataset topology. The purpose of vtkMappedUnstructuredGrid is to allow external data structures to be used directly in a VTK pipeline, e.g. for in-situ analysis of a running simulation.

When introducing an external data structure into VTK, there are 3 principle components of the dataset to consider:

Points
Cells (topology)
Point/Cell attributes

Points and attributes can be handled by subclassing vtkMappedDataArray and implementing that interface to adapt the external data structures into VTK. The vtkMappedDataArray subclasses can then be used as the vtkPoints's Data member (for points/nodes) or added directly to vtkPointData, vtkCellData, or vtkFieldData for attribute information. Filters used in the pipeline will need to be modified to remove calls to vtkDataArray::GetVoidPointer and use vtkTypedDataArrayIterators instead. See vtkDataArrayIteratorMacro.h for a (relatively) simple way to write processing algorithms that will use efficient raw memory accesses for standard VTK data arrays and safe iterators for non-standard data arrays in a single templated implementation.

Introducing an arbitrary topology implementation into VTK requires the use of the vtkMappedUnstructuredGrid class. Unlike the data array counterpart, the mapped unstructured grid is not subclassed, but rather takes an adaptor class as a template argument. This is to allow cheap shallow copies of the data by passing the reference-counted implementation object to new instances of vtkMappedUnstructuredGrid.

The implementation class should derive from vtkObject (for reference counting) and implement the usual vtkObject API requirements, such as a static New() method and PrintSelf function. The following methods must also be implemented:

vtkIdType GetNumberOfCells()
int GetCellType(vtkIdType cellId)
void GetCellPoints(vtkIdType cellId, vtkIdList *ptIds)
void GetPointCells(vtkIdType ptId, vtkIdList *cellIds)
int GetMaxCellSize()
void GetIdsOfCellsOfType(int type, vtkIdTypeArray *array)
int IsHomogeneous()
void Allocate(vtkIdType numCells, int extSize = 1000)
vtkIdType InsertNextCell(int type, vtkIdList *ptIds)
vtkIdType InsertNextCell(int type, vtkIdType npts, vtkIdType *ptIds)
vtkIdType InsertNextCell(int type, vtkIdType npts, vtkIdType *ptIds, vtkIdType nfaces, vtkIdType *faces)
void ReplaceCell(vtkIdType cellId, int npts, vtkIdType *pts)

These methods should provide the same functionality as defined in vtkUnstructuredGrid. See that class's documentation for more information.

Note that since the implementation class is used as a compile-time template parameter in vtkMappedUnstructuredGrid, the above methods do not need be virtuals. The compiler will statically bind the calls, making dynamic vtable lookups unneccessary and giving a slight performance boost.

Adapting a filter or algorithm to safely traverse the vtkMappedUnstructuredGrid's topology requires removing calls the following implementation-dependent vtkUnstructuredGrid methods:

vtkUnstructuredGrid::GetCellTypesArray()
vtkUnstructuredGrid::GetCellLocationsArray()
vtkUnstructuredGrid::GetCellLinks()
vtkUnstructuredGrid::GetCells() Access to the values returned by these methods should be replaced by the equivalent random-access lookup methods in the vtkUnstructuredGridBase API, or use vtkCellIterator (see vtkDataSet::NewCellIterator) for sequential access.

A custom vtkCellIterator implementation may be specified for a particular vtkMappedUnstructuredGrid as the second template parameter. By default, vtkMappedUnstructuredGridCellIterator will be used, which increments an internal cell id counter and performs random-access lookup as-needed. More efficient implementations may be used with data structures better suited for sequential access, see vtkUnstructuredGridCellIterator for an example.

A set of four macros are provided to generate a concrete subclass of vtkMappedUnstructuredGrid with a specified implementation, cell iterator, and export declaration. They are:

vtkMakeMappedUnstructuredGrid(_className, _impl)
- Create a subclass of vtkMappedUnstructuredGrid using _impl implemenation that is named _className.
vtkMakeMappedUnstructuredGridWithIter(_className, _impl, _cIter)
- Create a subclass of vtkMappedUnstructuredGrid using _impl implemenation and _cIter vtkCellIterator that is named _className.
vtkMakeExportedMappedUnstructuredGrid(_className, _impl, _exportDecl)
- Create a subclass of vtkMappedUnstructuredGrid using _impl implemenation that is named _className. _exportDecl is used to decorate the class declaration.
vtkMakeExportedMappedUnstructuredGridWithIter(_className, _impl, _cIter, _exportDecl)
- Create a subclass of vtkMappedUnstructuredGrid using _impl implemenation and _cIter vtkCellIterator that is named _className. _exportDecl is used to decorate the class declaration.

To instantiate a vtkMappedUnstructuredGrid subclass created by the above macro, the follow pattern is encouraged:

 MyGrid.h:
 ----------------------------------------------------------------------
 class MyGridImplementation : public vtkObject
 {
 public:
   ... (vtkObject required API) ...
   ... (vtkMappedUnstructuredGrid Implementation required API) ...
   void SetImplementationDetails(...raw data from external source...);
 };

 vtkMakeMappedUnstructuredGrid(MyGrid, MyGridImplementation)

 SomeSource.cxx
 ----------------------------------------------------------------------
 vtkNew<MyGrid> grid;
 grid->GetImplementation()->SetImplementationDetails(...);
 /* grid is now ready to use. */

The vtkCPExodusIIElementBlock class provides an example of vtkMappedUnstructuredGrid usage, adapting the Exodus II data structures for the VTK pipeline.

Definition at line 154 of file vtkMappedUnstructuredGrid.h.