High-level Functions

Py2VTK natively implements PyEVTK’s API with some minor changes in the order of keyword arguments and some new arguments, most notably the possibility to decide which format to use when writing the file to disk. The options are:

“raw”:
Write the data in bytes. This is space efficient and supported by VTK but means that the ensuing XML files are not valid.
“ascii”:
Write the data in readable ascii characters. This is very inefficient and should only be used for debugging.
“binary”:
Write the data in base64 with the possibility of compressing the data.

When using the latter format, it is possible to compress the data using zlib or lzma.

Functions writing serial VTK XML files

py2vtk.api.serial.imageToVTK(path, start=(0, 0, 0), end=None, origin=(0.0, 0.0, 0.0), spacing=(1.0, 1.0, 1.0), cellData=None, pointData=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True)

Export data values as a rectangular image.

Parameters

pathstr: name of the file without extension where data should be saved.
starttuple, optional: start of this image relative to a global image. Used in the distributed context where each process writes its own vtk file. Default is (0, 0, 0).
endtuple or None, optional: end of this image relative to a global image. Used in the distributed context where each process writes its own vtk file. If None, it will be deduced from the data.
origintuple, optional: grid origin. The default is (0.0, 0.0, 0.0).
spacingtuple, optional: grid spacing. The default is (1.0, 1.0, 1.0).
cellDatadict, optional: dictionary containing arrays with cell centered data. Keys should be the names of the data arrays. Arrays must have the same dimensions in all directions and can contain scalar data ([n,n,n]) or vector data ([n,n,n],[n,n,n],[n,n,n]). The default is None.
pointDatadict, optional: dictionary containing arrays with node centered data. Keys should be the names of the data arrays. Arrays must have same dimension in each direction and they should be equal to the dimensions of the cell data plus one and can contain scalar data ([n+1,n+1,n+1]) or ([n+1,n+1,n+1],[n+1,n+1,n+1],[n+1,n+1,n+1]). The default is None.
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.

Returns

str: Full path to saved file.

Notes

At least, cellData or pointData must be present to infer the dimensions of the image.

py2vtk.api.serial.gridToVTK(path, x, y, z, start=(0, 0, 0), cellData=None, pointData=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True)

Write data values as a rectilinear or structured grid.

Parameters

pathstr: name of the file without extension where data should be saved.
xarray-like: x coordinates of the points.
yarray-like: y coordinates of the points.
zarray-like: z coordinates of the points.
starttuple, optional: start of this grid relative to a global grid. Used in the distributed context where each process writes its own vtk file. Default is (0, 0, 0).
cellDatadict, optional: dictionary containing arrays with cell centered data. Keys should be the names of the data arrays. Arrays must have the same dimensions in all directions and must contain only scalar data.
pointDatadict, optional: dictionary containing arrays with node centered data. Keys should be the names of the data arrays. Arrays must have same dimension in each direction and they should be equal to the dimensions of the cell data plus one and must contain only scalar data.
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.

Returns

str: Full path to saved file.

Notes

Coordinates can be 1D or 3D depending if the grid should be saved as a rectilinear or logically structured grid, respectively. Arrays should contain coordinates of the nodes of the grid. If arrays are 1D, then the grid should be Cartesian, i.e. faces in all cells are orthogonal. If arrays are 3D, then the grid should be logically structured with hexahedral cells. In both cases the arrays dimensions should be equal to the number of nodes of the grid.

py2vtk.api.serial.polyDataToVTK(path, x, y, z, vertices=None, lines=None, strips=None, polys=None, cellData=None, pointData=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True)

Write vertices, lines, strips and polygons as a VTK Polydata

Parameters

pathstr: name of the file without extension where data should be saved.
xarray-like: x coordinates of the points.
yarray-like: y coordinates of the points.
zarray-like: z coordinates of the points.
verticesarray-like or None, optional: 1-D array containing the index of the points which should be saved as vertices.
lines2-tuple of array-likes or list of array-likes or None, optional: If a 2-tuple or array-likes, should be (connectivity, offsets) where connectivity should defines the points associated to each line and offsets should define the index of the last point in each cell (here line). If a list of array-likes, each element in the list should define the points associated to each line.
strips2-tuple of array-likes or list of array-likes or None, optional: If a 2-tuple or array-likes, should be (connectivity, offsets) where connectivity should defines the points associated to each strip and offsets should define the index of the last point in each cell (here strip). If a list of array-likes, each element in the list should define the points associated to each strip.
polys2-tuple of array-likes or list of array-likes or None, optional: If a 2-tuple or array-likes, should be (connectivity, offsets) where connectivity should defines the points associated to each polygon and offsets should define the index of the last point in each cell (here polygon). If a list of array-likes, each element in the list should define the points associated to each polygon.
cellDatadict or 4-tuple of dicts, optional: dictionary containing cell centered data or tuple of 4 dictionaries, one for each cell type (vertices, lines, strips and polys). Keys should be the names of the data arrays. Values should be arrays or 3-tuple of arrays. Arrays must have the same dimensions in all directions and must only contain scalar data.
pointDatadict, optional: dictionary containing node centered data. Keys should be the names of the data arrays. Values should be arrays or 3-tuple of arrays. Arrays must have same dimension in each direction and must contain only scalar data.
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.

Returns

str: Full path to saved file.

Notes

While Vtk PolyData does support cell-centered data, the way it does is not intuitive as the cell are numbered globally across each cell type and ordered in the following way: verts, lines, polys and strips. On top of that, for what is still a mistery to me, cell data written in base64 is read improperly (despite being written properly) and shows wrong results in paraview and when read using the python vtk library. For this reason, when provided with cell-centered data, this function will enforce ‘raw’ as the appended format and ‘ascii’ as the direct format.

Warns

UserWarning: If cellData is not None and the appended or direct format is binary.

py2vtk.api.serial.pointsToVTK(path, x, y, z, data=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True)

Export points and associated data as an unstructured grid.

Parameters

pathstr: name of the file without extension where data should be saved.
xarray-like: x coordinates of the points.
yarray-like: y coordinates of the points.
zarray-like: z coordinates of the points.
datadict, optional: dictionary with variables associated to each point. Keys should be the names of the variable stored in each array. All arrays must have the same number of elements.
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.

Returns

str: Full path to saved file.

py2vtk.api.serial.linesToVTK(path, x, y, z, cellData=None, pointData=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True)

Export line segments that joint 2 points and associated data.

Parameters

pathstr: name of the file without extension where data should be saved.
xarray-like: x coordinates of the points in lines.
yarray-like: y coordinates of the points in lines.
zarray-like: z coordinates of the points in lines.
cellDatadict, optional: dictionary with variables associated to each line. Keys should be the names of the variable stored in each array. All arrays must have the same number of elements.
pointDatadict, optional: dictionary containing node centered data. Keys should be the names of the variable stored in each array. All arrays must have the same number of elements.
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.

Returns

str: Full path to saved file.

Notes

x, y, z are 1D arrays with coordinates of the vertex of the lines. It is assumed that each line is defined by two points, then the length of the arrays should be equal to 2 * number of lines.

py2vtk.api.serial.unstructuredGridToVTK(path, x, y, z, connectivity, offsets, cell_types, faces=None, faceoffsets=None, cellData=None, pointData=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True, check_cells=True)

Export unstructured grid and associated data.

Parameters

pathstr: name of the file without extension where data should be saved.
xarray-like: x coordinates of the vertices.
yarray-like: y coordinates of the vertices.
zarray-like: z coordinates of the vertices.
connectivityarray-like: 1D array that defines the vertices associated to each element. Together with offset define the connectivity or topology of the grid. It is assumed that vertices in an element are listed consecutively.
offsetsarray-like: 1D array with the index of the last vertex of each element in the connectivity array. It should have length nelem, where nelem is the number of cells or elements in the grid.
cell_typesarray_like: 1D array with an integer that defines the cell type of each element in the grid. It should have size nelem. This should be assigned from evtk.vtk.VtkXXXX.tid, where XXXX represent the type of cell. Please check the VTK file format specification or py2vtk.core.vtkcells for allowed cell types.
facesarray_like or None, optional: 1D integer array describing the faces of polyhedric cells. This is only required and used if there are polyhedra in the grid (cell id 42). When used it is expected to be formatted in the following way for each polyhedron: Number of faces, Number of points in face 0, first point of face 0, … and so on.
faceoffsetsarray_like or None, optional: 1D integer array with the index of the last vertex of each polyhedron in the faces array.
cellDatadict, optional: dictionary containing cell centered data. Keys should be the names of the variable stored in each array. Values should be arrays or 3-tuple of arrays. All arrays must have the same number of elements.
pointDatadict, optional: dictionary containing node centered data. Keys should be the names of the variable stored in each array. Values should be arrays or 3-tuple of arrays. All arrays must have the same number of elements.
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array. Values should be arrays or 3-tuple of arrays.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.
check_cellsBool, default=True: If True, checks cell_types and offsets to ensure that the types are correct and the number of points in each cell is coherent with their type. The understood cell types are listed in py2vtk.core.vtkcells.py.

Returns

str: Full path to saved file.

py2vtk.api.serial.cylinderToVTK(path, x0, y0, z0, z1, radius, nlayers, npilars=16, cellData=None, pointData=None, fieldData=None, direct_format='ascii', appended_format='raw', compression=False, compressor='zlib', append=True)

Export cylinder as VTK unstructured grid.

Parameters

pathstr: name of the file without extension where data should be saved.
x0float: x-center of the cylinder.
y0float: y-center of the cylinder.
z0float: lower end of the cylinder.
z1float: upper end of the cylinder.
radiusfloat: radius of the cylinder.
nlayersint: Number of layers in z direction to divide the cylinder.
npilarsint, optional: Number of points around the diameter of the cylinder. Higher value gives higher resolution to represent the curved shape. The default is 16.
cellDatadict, optional: dictionary containing cell centered data. Keys should be the names of the variable stored in each array. Arrays should have number of elements equal to ncells = npilars * nlayers.
pointDatadict, optional: dictionary containing node centered data. Keys should be the names of the variable stored in each array. Arrays should have number of elements equal to npoints = npilars * (nlayers + 1).
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.
direct_formatstr in {‘ascii’, ‘binary’}, default=’ascii’: how the data that isn’t appended will be encoded. If 'ascii', the data will be human readable, if 'binary' it will use base 64 and can be compressed. See compressor argument.
appended_formatstr in {‘raw’, ‘binary’}, default=’raw’: how that appended data will be encoded. If 'raw', raw binary data will be written to file. This is space efficient and supported by vtk but isn’t valid XML. If 'binary', data will be encoded using base64 and can be compressed. See compressor argument.
compressionBool or int, default=False: compression level of the binary data. Can be True, False or any integer in [-1, 9] included. If True, compression will be set to -1 and use the default value of the compressor.
compressor: str in {‘zlib’, ‘lzma’}, default=’zlib’: compression library to use for the binary data.
appendbool, default=True: Whether to write the data in appended mode or not.

Returns

str: Full path to saved file.

Notes

This function only export vertical shapes for now. However, it should be easy to rotate the cylinder to represent other orientations.

Functions writing parallel VTK XML files

Note

Despite being called parllel VTK files, this file format is expected to be written in serial. As such, the following functions are serial.

py2vtk.api.parallel.writeParallelVTKImageData(path, starts, ends, sources, dimension=None, origin=(0.0, 0.0, 0.0), spacing=(1.0, 1.0, 1.0), ghostlevel=0, cellData=None, pointData=None, fieldData=None, format='binary')

Writes a parallel vtk file from grid-like data: VTKStructuredGrid or VTKRectilinearGrid

Parameters

pathstr: name of the file without extension.
startslist: list of 3-tuple representing where each source file starts in each dimension.
endslist: list of 3-tuple representing where each source file ends in each dimension
dimensiontuple or None, optional: dimension of the image.
sourcelist: list of the relative paths of the source files where the actual data is found.
origintuple, optional: grid origin. The default is (0.0, 0.0, 0.0).
spacingtuple, optional: grid spacing. The default is (1.0, 1.0, 1.0).
ghostlevelint, default=0: Number of cells which are shared between neighbouring files.
pointDatadict: dictionnary containing the information about the arrays containing node centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
cellData :: dictionnary containing the information about the arrays containing cell centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.

py2vtk.api.parallel.writeParallelVTKGrid(path, coordsDtype, starts, ends, sources, dimension=None, ghostlevel=0, cellData=None, pointData=None, fieldData=None, format='binary')

Writes a parallel vtk file from grid-like data: VTKStructuredGrid or VTKRectilinearGrid

Parameters

pathstr: name of the file without extension.
coordsDtypenumpy.dtype: the dtype of the coordinates.
startslist: list of 3-tuple representing where each source file starts in each dimension.
endslist: list of 3-tuple representing where each source file ends in each dimension
sourcelist: list of the relative paths of the source files where the actual data is found.
ghostlevelint, default=0: Number of cells which are shared between neighbouring files.
pointDatadict: dictionnary containing the information about the arrays containing node centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
cellData :: dictionnary containing the information about the arrays containing cell centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.

py2vtk.api.parallel.writeParallelVTKPolyData(path, coordsDtype, sources, ghostlevel=0, cellData=None, pointData=None, fieldData=None, format='binary')

Writes a parallel VTK PolyData.

Parameters

pathstr: name of the file without extension.
coordsDtypenumpy.dtype: the dtype of the coordinates.
sourcelist: list of the relative paths of the source files where the actual data is found.
ghostlevelint, default=0: Number of cells which are shared between neighbouring files.
pointDatadict: dictionnary containing the information about the arrays containing node centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
cellData :: dictionnary containing the information about the arrays containing cell centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.

py2vtk.api.parallel.writeParallelVTKUnstructuredGrid(path, coordsDtype, sources, ghostlevel=0, cellData=None, pointData=None, fieldData=None, format='binary')

Writes a parallel VTK Unstructured Grid

Parameters

pathstr: name of the file without extension.
coordsdtypedtype: dtype of the coordinates.
sourcelist: list of the relative paths of the source files where the actual data is found
ghostlevelint, optional: Number of ghost-levels by which the extents in the individual source files overlap.
pointDatadict: dictionnary containing the information about the arrays containing node centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
cellData :: dictionnary containing the information about the arrays containing cell centered data. Keys shoud be the names of the arrays. Values are (dtype, number of components)
fieldDatadict, optional: dictionary with variables associated with the field. Keys should be the names of the variable stored in each array.