`vtkmodules.numpy_interface.dataset_adapter`#

This module provides classes that allow Numpy-type access to VTK datasets and arrays. This is best described with some examples.

To normalize a VTK array:

from vtkmodules.vtkImagingCore vtkRTAnalyticSource import vtkmodules.numpy_interface.dataset_adapter as dsa import vtkmodules.numpy_interface.algorithms as algs

rt = vtkRTAnalyticSource() rt.Update() image = dsa.WrapDataObject(rt.GetOutput()) rtdata = image.PointData[‘RTData’] rtmin = algs.min(rtdata) rtmax = algs.max(rtdata) rtnorm = (rtdata - rtmin) / (rtmax - rtmin) image.PointData.append(rtnorm, ‘RTData - normalized’) print image.GetPointData().GetArray(‘RTData - normalized’).GetRange()

To calculate gradient:

grad= algs.gradient(rtnorm)

To access subsets:

grad[0:10] VTKArray([[ 0.10729134, 0.03763443, 0.03136338], [ 0.02754352, 0.03886006, 0.032589 ], [ 0.02248248, 0.04127144, 0.03500038], [ 0.02678365, 0.04357527, 0.03730421], [ 0.01765099, 0.04571581, 0.03944477], [ 0.02344007, 0.04763837, 0.04136734], [ 0.01089381, 0.04929155, 0.04302051], [ 0.01769151, 0.05062952, 0.04435848], [ 0.002764 , 0.05161414, 0.04534309], [ 0.01010841, 0.05221677, 0.04594573]])

grad[:, 0] VTKArray([ 0.10729134, 0.02754352, 0.02248248, …, -0.02748174, -0.02410045, 0.05509736])

All of this functionality is also supported for composite datasets even though their data arrays may be spread across multiple datasets. We have implemented a VTKCompositeDataArray class that handles many Numpy style operators and is supported by all algorithms in the algorithms module.

This module also provides an API to access composite datasets. For example:

from vtkmodules.vtkCommonDataModel import vtkMultiBlockDataSet mb = vtkMultiBlockDataSet() mb.SetBlock(0, image.VTKObject) mb.SetBlock(1e, image.VTKObject) cds = dsa.WrapDataObject(mb) for block in cds: print block

Note that this module implements only the wrappers for datasets and arrays. The classes implement many useful operators. However, to make best use of these classes, take a look at the algorithms module.

Module Contents#

Classes#

`ArrayAssociation`	Easy access to vtkDataObject.AttributeTypes
`VTKObjectWrapper`	Superclass for classes that wrap VTK objects with Python objects. This class holds a reference to the wrapped VTK object. It also forwards unresolved methods to the underlying object by overloading __get__attr.
`VTKArrayMetaClass`
`VTKArray`	This is a sub-class of numpy ndarray that stores a reference to a vtk array as well as the owning dataset. The numpy array and vtk array should point to the same memory location.
`VTKNoneArrayMetaClass`
`VTKNoneArray`	VTKNoneArray is used to represent a “void” array. An instance of this class (NoneArray) is returned instead of None when an array that doesn’t exist in a DataSetAttributes is requested. All operations on the NoneArray return NoneArray. The main reason for this is to support operations in parallel where one of the processes may be working on an empty dataset. In such cases, the process is still expected to evaluate a whole expression because some of the functions may perform bulk MPI communication. None cannot be used in these instances because it cannot properly override operators such as add, sub etc. This is the main raison d’etre for VTKNoneArray.
`VTKCompositeDataArrayMetaClass`
`VTKCompositeDataArray`	This class manages a set of arrays of the same name contained within a composite dataset. Its main purpose is to provide a Numpy-type interface to composite data arrays which are naturally nothing but a collection of vtkDataArrays. A VTKCompositeDataArray makes such a collection appear as a single Numpy array and support all array operations that this module and the associated algorithm module support. Note that this is not a subclass of a Numpy array and as such cannot be passed to native Numpy functions. Instead VTK modules should be used to process composite arrays.
`DataSetAttributes`	This is a python friendly wrapper of vtkDataSetAttributes. It returns VTKArrays. It also provides the dictionary interface. Note that the stored array should have a shape that matches the number of elements. E.g. for a PointData, narray.shape[0] should be equal to dataset.GetNumberOfPoints()
`CompositeDataSetAttributes`	This is a python friendly wrapper for vtkDataSetAttributes for composite datasets. Since composite datasets themselves don’t have attribute data, but the attribute data is associated with the leaf nodes in the composite dataset, this class simulates a DataSetAttributes interface by taking a union of DataSetAttributes associated with all leaf nodes.
`CompositeDataIterator`	Wrapper for a vtkCompositeDataIterator class to satisfy the python iterator protocol. This iterator iterates over non-empty leaf nodes. To iterate over empty or non-leaf nodes, use the vtkCompositeDataIterator directly.
`MultiCompositeDataIterator`	Iterator that can be used to iterate over multiple composite datasets together. This iterator works only with arrays that were copied from an original using CopyStructured. The most common use case is to use CopyStructure, then iterate over input and output together while creating output datasets from corresponding input datasets.
`DataObject`	A wrapper for vtkDataObject that makes it easier to access FielData arrays as VTKArrays
`Table`	A wrapper for vtkTable that makes it easier to access RowData array as VTKArrays
`HyperTreeGrid`	A wrapper for vtkHyperTreeGrid that makes it easier to access CellData arrays as VTKArrays.
`CompositeDataSet`	A wrapper for vtkCompositeData and subclasses that makes it easier to access Point/Cell/Field data as VTKCompositeDataArrays. It also provides a Python type iterator.
`DataSet`	This is a python friendly wrapper of a vtkDataSet that defines a few useful properties.
`PointSet`	This is a python friendly wrapper of a vtkPointSet that defines a few useful properties.
`PolyData`	This is a python friendly wrapper of a vtkPolyData that defines a few useful properties.
`UnstructuredGrid`	This is a python friendly wrapper of a vtkUnstructuredGrid that defines a few useful properties.
`Graph`	This is a python friendly wrapper of a vtkGraph that defines a few useful properties.
`Molecule`	This is a python friendly wrapper of a vtkMolecule that defines a few useful properties.

Functions#

`_override_numpy`	Register an array_function implementation for VTKCompositeDataArray objects.
`reshape_append_ones`	Returns a list with the two arguments, any of them may be processed. If the arguments are numpy.ndarrays, append 1s to the shape of the array with the smallest number of dimensions until the arrays have the same number of dimensions. Does nothing if the arguments are not ndarrays or the arrays have the same number of dimensions.
`vtkDataArrayToVTKArray`	Given a vtkDataArray and a dataset owning it, returns a VTKArray.
`numpyTovtkDataArray`	Given a numpy array or a VTKArray and a name, returns a vtkDataArray. The resulting vtkDataArray will store a reference to the numpy array: the numpy array is released only when the vtkDataArray is destroyed.
`_make_tensor_array_contiguous`
`_metaclass`	For compatibility between python 2 and python 3.
`WrapDataObject`	Returns a Numpy friendly wrapper of a vtkDataObject.

Data#

`NUMPY_MAJOR_VERSION`
`COMPOSITE_OVERRIDE`
`NoneArray`

API#

vtkmodules.numpy_interface.dataset_adapter.NUMPY_MAJOR_VERSION#: ‘int(…)’

vtkmodules.numpy_interface.dataset_adapter.COMPOSITE_OVERRIDE#: None

vtkmodules.numpy_interface.dataset_adapter._override_numpy(numpy_function)#: Register an array_function implementation for VTKCompositeDataArray objects.

vtkmodules.numpy_interface.dataset_adapter.reshape_append_ones(a1, a2)#: Returns a list with the two arguments, any of them may be processed. If the arguments are numpy.ndarrays, append 1s to the shape of the array with the smallest number of dimensions until the arrays have the same number of dimensions. Does nothing if the arguments are not ndarrays or the arrays have the same number of dimensions.

class vtkmodules.numpy_interface.dataset_adapter.ArrayAssociation#

Easy access to vtkDataObject.AttributeTypes

POINT#: None

CELL#: None

FIELD#: None

ROW#: None

class vtkmodules.numpy_interface.dataset_adapter.VTKObjectWrapper(vtkobject)#

Bases: object

Superclass for classes that wrap VTK objects with Python objects. This class holds a reference to the wrapped VTK object. It also forwards unresolved methods to the underlying object by overloading __get__attr.

Initialization

__getattr__(name)#: Forwards unknown attribute requests to VTK object.

vtkmodules.numpy_interface.dataset_adapter.vtkDataArrayToVTKArray(array, dataset=None)#: Given a vtkDataArray and a dataset owning it, returns a VTKArray.

vtkmodules.numpy_interface.dataset_adapter.numpyTovtkDataArray(array, name='numpy_array', array_type=None)#: Given a numpy array or a VTKArray and a name, returns a vtkDataArray. The resulting vtkDataArray will store a reference to the numpy array: the numpy array is released only when the vtkDataArray is destroyed.

vtkmodules.numpy_interface.dataset_adapter._make_tensor_array_contiguous(array)#

vtkmodules.numpy_interface.dataset_adapter._metaclass(mcs)#: For compatibility between python 2 and python 3.

class vtkmodules.numpy_interface.dataset_adapter.VTKArrayMetaClass#

Bases: type

__new__(name, parent, attr)#

We overwrite numerical/comparison operators because we might need to reshape one of the arrays to perform the operation without broadcast errors. For instance:

An array G of shape (n,3) resulted from computing the gradient on a scalar array S of shape (n,) cannot be added together without reshaping. G + expand_dims(S,1) works, G + S gives an error: ValueError: operands could not be broadcast together with shapes (n,3) (n,)

This metaclass overwrites operators such that it computes this reshape operation automatically by appending 1s to the dimensions of the array with fewer dimensions.

class vtkmodules.numpy_interface.dataset_adapter.VTKArray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)#

Bases: numpy.ndarray

This is a sub-class of numpy ndarray that stores a reference to a vtk array as well as the owning dataset. The numpy array and vtk array should point to the same memory location.

Initialization

_numeric_op(other, attr_name)#: Used to implement numpy-style numerical operations such as add, mul, etc.

_reverse_numeric_op(other, attr_name)#: Used to implement numpy-style numerical operations such as add, mul, etc.

__new__(input_array, array=None, dataset=None)#

__array_finalize__(obj)#

__getattr__(name)#: Forwards unknown attribute requests to VTK array.

__array_wrap__(out_arr, context=None, return_scalar=False)#

property DataSet#: Get the dataset this array is associated with. The reference to the dataset is held through a vtkWeakReference to ensure it doesn’t prevent the dataset from being collected if necessary.

class vtkmodules.numpy_interface.dataset_adapter.VTKNoneArrayMetaClass#

Bases: type

__new__(name, parent, attr)#: Simplify the implementation of the numeric/logical sequence API.

class vtkmodules.numpy_interface.dataset_adapter.VTKNoneArray#

Bases: object

VTKNoneArray is used to represent a “void” array. An instance of this class (NoneArray) is returned instead of None when an array that doesn’t exist in a DataSetAttributes is requested. All operations on the NoneArray return NoneArray. The main reason for this is to support operations in parallel where one of the processes may be working on an empty dataset. In such cases, the process is still expected to evaluate a whole expression because some of the functions may perform bulk MPI communication. None cannot be used in these instances because it cannot properly override operators such as add, sub etc. This is the main raison d’etre for VTKNoneArray.

__getitem__(index)#

_op(other, op)#: Used to implement numpy-style numerical operations such as add, mul, etc.

astype(dtype)#: Implements numpy array’s astype method.

property shape: Tuple[int, ...]#: Return a tuple representing the shape of the none array.

vtkmodules.numpy_interface.dataset_adapter.NoneArray#: ‘VTKNoneArray(…)’

class vtkmodules.numpy_interface.dataset_adapter.VTKCompositeDataArrayMetaClass#

Bases: type

__new__(name, parent, attr)#: Simplify the implementation of the numeric/logical sequence API.

class vtkmodules.numpy_interface.dataset_adapter.VTKCompositeDataArray(arrays=[], dataset=None, name=None, association=None)#

Bases: object

This class manages a set of arrays of the same name contained within a composite dataset. Its main purpose is to provide a Numpy-type interface to composite data arrays which are naturally nothing but a collection of vtkDataArrays. A VTKCompositeDataArray makes such a collection appear as a single Numpy array and support all array operations that this module and the associated algorithm module support. Note that this is not a subclass of a Numpy array and as such cannot be passed to native Numpy functions. Instead VTK modules should be used to process composite arrays.

Initialization

Construct a composite array given a container of arrays, a dataset, name and association. It is sufficient to define a container of arrays to define a composite array. It is also possible to initialize an array by defining the dataset, name and array association. In that case, the underlying arrays will be created lazily when they are needed. It is recommended to use the latter method when initializing from an existing composite dataset.

__init_from_composite()#

GetSize()#: Returns the number of elements in the array.

size#: ‘property(…)’

GetArrays()#: Returns the internal container of VTKArrays. If necessary, this will populate the array list from a composite dataset.

Arrays#: ‘property(…)’

__setitem__(index, value) → None#: Setter overwritten to defer indexing to underlying VTKArrays. For the most part, this will behave like Numpy.

__getitem__(index) → Union[List, vtkmodules.numpy_interface.dataset_adapter.VTKCompositeDataArray, numpy.ndarray]#: Getter overwritten to refer indexing to underlying VTKArrays. For the most part, this will behave like Numpy.

_global_to_local_id(global_index, total_size, offsets)#: Returns the chunk index and the local index of the chunk from the global index

_slice_intersection(global_slice, chunk_offset, chunk_size, total_length)#: Returns a local slice into the chunk for the global_slice, or None if no overlap. Handles both positive and negative steps.

_numeric_op(other, op)#: Used to implement numpy-style numerical operations such as add, mul, etc.

_reverse_numeric_op(other, op)#: Used to implement numpy-style numerical operations such as add, mul, etc.

__str__()#

astype(dtype)#: Implements numpy array’s as array method.

property shape: Tuple[int, ...]#: Return a tuple representing the shape of the composite array.

__len__() → int#: Return the total number of elements in the composite array.

__contains__(item) → bool#: Check if the item exists in any of the non-null sub-arrays.

__reversed__() → Generator[numpy.ndarray, None, None]#: Iterate over all subarrays in the composite array in backward order.

__iter__() → Generator[numpy.ndarray, None, None]#: Iterate over all subarrays in the composite array in forward order.

__array__(dtype=None, copy=None) → numpy.ndarray#: Convert the composite array into a single NumPy array.

__array_function__(func, types, args, kwargs)#: Implements Numpy dispatch mechanism. Functions registered in COMPOSITE_OVERRIDE are captured here. See: https://numpy.org/doc/stable/user/basics.interoperability.html#the-array-function-protocol

__array_ufunc__(ufunc, method, *inputs, **kwargs)#: Handles Numpy functions calls that takes a fixed number of specific inputs and outputs.

class vtkmodules.numpy_interface.dataset_adapter.DataSetAttributes(vtkobject, dataset, association)#

Bases: vtkmodules.numpy_interface.dataset_adapter.VTKObjectWrapper

This is a python friendly wrapper of vtkDataSetAttributes. It returns VTKArrays. It also provides the dictionary interface. Note that the stored array should have a shape that matches the number of elements. E.g. for a PointData, narray.shape[0] should be equal to dataset.GetNumberOfPoints()

Initialization

__getitem__(idx)#: Implements the [] operator. Accepts an array name or index.

GetArray(idx)#: Given an index or name, returns a VTKArray.

keys()#: Returns the names of the arrays as a list.

values()#: Returns the arrays as a list.

PassData(other)#: A wrapper for vtkDataSet.PassData.

append(narray, name)#

Appends narray to the dataset attributes.

If narray is a scalar, create an array with this scalar for each element. If narray is an array with a size not matching the array association (e.g. size should be equal to GetNumberOfPoints() for PointData), copy the input narray for each element. This is intended to ease initialization, typically using same 3d vector for each element. In any case, be careful about memory explosion.

class vtkmodules.numpy_interface.dataset_adapter.CompositeDataSetAttributes(dataset, association)#

This is a python friendly wrapper for vtkDataSetAttributes for composite datasets. Since composite datasets themselves don’t have attribute data, but the attribute data is associated with the leaf nodes in the composite dataset, this class simulates a DataSetAttributes interface by taking a union of DataSetAttributes associated with all leaf nodes.

Initialization

__determine_arraynames()#

keys()#: Returns the names of the arrays as a list.

__getitem__(idx)#: Implements the [] operator. Accepts an array name.

append(narray, name)#: Appends a new array to the composite dataset attributes.

GetArray(idx)#: Given a name, returns a VTKCompositeArray.

PassData(other)#: Emulate PassData for composite datasets.

class vtkmodules.numpy_interface.dataset_adapter.CompositeDataIterator(cds)#

Bases: object

Wrapper for a vtkCompositeDataIterator class to satisfy the python iterator protocol. This iterator iterates over non-empty leaf nodes. To iterate over empty or non-leaf nodes, use the vtkCompositeDataIterator directly.

Initialization

__iter__()#

__next__()#

next()#

__getattr__(name)#: Returns attributes from the vtkCompositeDataIterator.

class vtkmodules.numpy_interface.dataset_adapter.MultiCompositeDataIterator(cds)#

Bases: vtkmodules.numpy_interface.dataset_adapter.CompositeDataIterator

Iterator that can be used to iterate over multiple composite datasets together. This iterator works only with arrays that were copied from an original using CopyStructured. The most common use case is to use CopyStructure, then iterate over input and output together while creating output datasets from corresponding input datasets.

Initialization

__next__()#

next()#

class vtkmodules.numpy_interface.dataset_adapter.DataObject(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.VTKObjectWrapper

A wrapper for vtkDataObject that makes it easier to access FielData arrays as VTKArrays

Initialization

GetAttributes(type)#: Returns the attributes specified by the type as a DataSetAttributes instance.

HasAttributes(type)#: Returns if current object support this attributes type

GetFieldData()#: Returns the field data as a DataSetAttributes instance.

FieldData#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.Table(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataObject

A wrapper for vtkTable that makes it easier to access RowData array as VTKArrays

Initialization

GetRowData()#: Returns the row data as a DataSetAttributes instance.

HasAttributes(type)#: Returns if current object support this attributes type

RowData#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.HyperTreeGrid(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataObject

A wrapper for vtkHyperTreeGrid that makes it easier to access CellData arrays as VTKArrays.

Initialization

GetCellData()#: Returns the cell data as DataSetAttributes instance.

HasAttributes(type)#: Returns if current object support this attributes type

CellData#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.CompositeDataSet(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataObject

A wrapper for vtkCompositeData and subclasses that makes it easier to access Point/Cell/Field data as VTKCompositeDataArrays. It also provides a Python type iterator.

Initialization

__iter__()#: Creates an iterator for the contained datasets.

GetNumberOfElements(assoc)#: Returns the total number of cells or points depending on the value of assoc which can be ArrayAssociation.POINT or ArrayAssociation.CELL.

GetNumberOfPoints()#: Returns the total number of points of all datasets in the composite dataset. Note that this traverses the whole composite dataset every time and should not be called repeatedly for large composite datasets.

GetNumberOfCells()#: Returns the total number of cells of all datasets in the composite dataset. Note that this traverses the whole composite dataset every time and should not be called repeatedly for large composite datasets.

GetAttributes(type)#: Returns the attributes specified by the type as a CompositeDataSetAttributes instance.

HasAttributes(type)#: Returns true if every leaves of current composite object support this attributes type

GetPointData()#: Returns the point data as a CompositeDataSetAttributes instance.

GetCellData()#: Returns the cell data as a CompositeDataSetAttributes instance.

GetFieldData()#: “Returns the field data as a CompositeDataSetAttributes instance.”

GetGlobalData()#: Returns the global data (field data of the root) as a DataSetAttributes instance.

GetPoints()#: Returns the points as a VTKCompositeDataArray instance.

PointData#: ‘property(…)’

CellData#: ‘property(…)’

FieldData#: ‘property(…)’

GlobalData#: ‘property(…)’

Points#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.DataSet(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataObject

This is a python friendly wrapper of a vtkDataSet that defines a few useful properties.

Initialization

GetPointData()#: Returns the point data as a DataSetAttributes instance.

GetCellData()#: Returns the cell data as a DataSetAttributes instance.

HasAttributes(type)#: Returns if current object support this attributes type

PointData#: ‘property(…)’

CellData#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.PointSet(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataSet

This is a python friendly wrapper of a vtkPointSet that defines a few useful properties.

Initialization

GetPoints()#: Returns the points as a VTKArray instance. Returns None if the dataset has implicit points.

SetPoints(pts)#: Given a VTKArray instance, sets the points of the dataset.

Points#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.PolyData(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.PointSet

This is a python friendly wrapper of a vtkPolyData that defines a few useful properties.

Initialization

GetPolygons()#: Returns the polys as a VTKArray instance.

Polygons#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.UnstructuredGrid(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.PointSet

This is a python friendly wrapper of a vtkUnstructuredGrid that defines a few useful properties.

Initialization

GetCellTypes()#: Returns the cell types as a VTKArray instance.

GetCellLocations()#: Returns the cell locations as a VTKArray instance.

GetCells()#: Returns the cells as a VTKArray instance.

SetCells(cellTypes, cellLocations, cells)#: Given cellTypes, cellLocations, cells as VTKArrays, populates the unstructured grid data structures.

CellTypes#: ‘property(…)’

CellLocations#: ‘property(…)’

Cells#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.Graph(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataObject

This is a python friendly wrapper of a vtkGraph that defines a few useful properties.

Initialization

GetVertexData()#: Returns the vertex data as a DataSetAttributes instance.

GetEdgeData()#: Returns the edge data as a DataSetAttributes instance.

VertexData#: ‘property(…)’

EdgeData#: ‘property(…)’

class vtkmodules.numpy_interface.dataset_adapter.Molecule(vtkobject)#

Bases: vtkmodules.numpy_interface.dataset_adapter.DataObject

This is a python friendly wrapper of a vtkMolecule that defines a few useful properties.

Initialization

GetAtomData()#: Returns the atom data as a DataSetAttributes instance.

GetBondData()#: Returns the bond data as a DataSetAttributes instance.

AtomData#: ‘property(…)’

BondData#: ‘property(…)’

vtkmodules.numpy_interface.dataset_adapter.WrapDataObject(ds)#: Returns a Numpy friendly wrapper of a vtkDataObject.

vtkmodules.numpy_interface.dataset_adapter#

Module Contents#

Classes#

Functions#

Data#

API#

`vtkmodules.numpy_interface.dataset_adapter`#