VTKWrappers Namespace Reference

Namespaces
namespace	internal

Functions
template<int dim>
vtkSmartPointer< vtkDoubleArray >	dealii_point_to_vtk_array (const ::Point< dim > &p)
template<int dim, int spacedim>
void	unstructured_grid_to_dealii_triangulation (const vtkUnstructuredGrid &unstructured_grid, Triangulation< dim, spacedim > &tria, const std::string &material_id_field="", const std::string &boundary_id_field="", const std::string &manifold_id_field="")
template<int dim, int spacedim>
vtkSmartPointer< vtkUnstructuredGrid >	dealii_triangulation_to_unstructured_grid (const Triangulation< dim, spacedim > &tria, const std::string &material_id_field="", const std::string &boundary_id_field="", const std::string &manifold_id_field="")
template<int dim, int spacedim>
void	write_vtk (const std::string &vtk_filename, const Triangulation< dim, spacedim > &tria, const std::string &material_id_field="", const std::string &boundary_id_field="", const std::string &manifold_id_field="")
template<int dim, int spacedim>
void	read_tria (const std::string &vtk_filename, Triangulation< dim, spacedim > &tria, const bool cleanup=true, const double relative_tolerance=0.0, const std::string &material_id_field="", const std::string &boundary_id_field="", const std::string &manifold_id_field="")
void	read_cell_data (const std::string &vtk_filename, const std::string &cell_data_name, Vector< double > &output_vector, const bool cleanup=true, const double relative_tolerance=0.0)
void	read_vertex_data (const std::string &vtk_filename, const std::string &vertex_data_name, Vector< double > &output_vector, const bool cleanup=true, const double relative_tolerance=0.0)
void	read_all_data (const std::string &vtk_filename, Vector< double > &output_vector, const bool cleanup=true, const double relative_tolerance=0.0)
template<int dim, int spacedim>
std::pair< std::unique_ptr< FiniteElement< dim, spacedim > >, std::vector< std::string > >	vtk_to_finite_element (const std::string &vtk_filename)
template<int dim, int spacedim, typename VectorType >
void	data_to_dealii_vector (const Triangulation< dim, spacedim > &serial_tria, const Vector< double > &data, const DoFHandler< dim, spacedim > &dh, VectorType &output_vector)
template<int dim, int spacedim>
void	read_vtk (const std::string &vtk_filename, DoFHandler< dim, spacedim > &dof_handler, Vector< double > &output_vector, std::vector< std::string > &data_names, const bool cleanup=true, const double relative_tolerance=0.0, const std::string &material_id_field="", const std::string &boundary_id_field="", const std::string &manifold_id_field="")

Detailed Description

Interface to the Visualization Toolkit (VTK).

VTK is an open-source, freely available software system for 3D computer graphics, modeling, image processing, volume rendering, scientific visualization, and 2D plotting.

It supports a wide variety of visualization algorithms and advanced modeling techniques, and it takes advantage of both threaded and distributed memory parallel processing for speed and scalability, respectively.

You can learn more about the VTK library at https://vtk.org/

Function Documentation

dealii_point_to_vtk_array()

template<int dim>

vtkSmartPointer< vtkDoubleArray > VTKWrappers::dealii_point_to_vtk_array ( const ::Point< dim > &  p )

inline

Convert from a deal.II Point to a VTK double array.

Template Parameters

dim	Dimension of the point

Parameters

[in]

p

An input deal.II Point<dim>

Returns

A VTK smart pointer to the data array.

unstructured_grid_to_dealii_triangulation()

template<int dim, int spacedim>

void VTKWrappers::unstructured_grid_to_dealii_triangulation	(	const vtkUnstructuredGrid &	unstructured_grid,
		Triangulation< dim, spacedim > &	tria,
		const std::string &	material_id_field = "",
		const std::string &	boundary_id_field = "",
		const std::string &	manifold_id_field = ""
	)

Convert a VTK unstructured grid to a deal.II triangulation.

This function translates the points and cells in unstructured_grid into a serial deal.II Triangulation.

The optional string parameters specify names of VTK cell-data arrays to read and how they are interpreted. Empty names disable reading of the corresponding id data; no default VTK array names are used.

• material_id_field: when non-empty, the named VTK cell-data scalar array is read and used to set per-codim-0-cell material_id values in the resulting Triangulation.
• boundary_id_field: when non-empty, the named VTK cell-data scalar array is read and used to set boundary_ids for codim-1 subcells reconstructed from VTK cells whose dimension is smaller than dim.
• manifold_id_field: when non-empty, the named VTK cell-data scalar array is read and used to set manifold_id for both codim-0 cells and appended subcells.

Negative values read from VTK for any of these three fields are interpreted as deal.II defaults to avoid unsigned wrap when mapping onto deal.II types.

Definition at line 256 of file utilities.cc.

dealii_triangulation_to_unstructured_grid()

template<int dim, int spacedim>

vtkSmartPointer< vtkUnstructuredGrid > VTKWrappers::dealii_triangulation_to_unstructured_grid	(	const Triangulation< dim, spacedim > &	tria,
		const std::string &	material_id_field = "",
		const std::string &	boundary_id_field = "",
		const std::string &	manifold_id_field = ""
	)

Convert a serial deal.II triangulation to a VTK unstructured grid.

This function exports the active cells of tria to a newly allocated VTK unstructured grid and returns it.

The optional string parameters specify names of VTK cell-data arrays to create and the export behavior. Empty names disable writing of the corresponding id data; no default VTK array names are used.

• material_id_field: when non-empty, a VTK cell-data scalar array with this name is created and filled with per-codim-0-cell material_id values. Appended subcells receive the material id of the owning codim-0 cell.
• boundary_id_field: when non-empty, a VTK cell-data scalar array with this name is created. Appended codim-1 subcells carry meaningful boundary id values; codim-0 cells receive 0 because boundary ids live on subcells.
• manifold_id_field: when non-empty, a VTK cell-data scalar array with this name is created. Codim-0 cells are written with numbers::flat_manifold_id (i.e. -1) when they have the default manifold; non-flat manifold ids for appended subcells are written alongside boundary ids.

Definition at line 685 of file utilities.cc.

write_vtk()

template<int dim, int spacedim>

void VTKWrappers::write_vtk	(	const std::string &	vtk_filename,
		const Triangulation< dim, spacedim > &	tria,
		const std::string &	material_id_field = "",
		const std::string &	boundary_id_field = "",
		const std::string &	manifold_id_field = ""
	)

Write a serial deal.II triangulation to a VTK file.

This function first converts tria to a VTK unstructured grid through dealii_triangulation_to_unstructured_grid() and then writes it to disk.

The optional string parameters specify names of VTK cell-data arrays to create and fill with deal.II ids. Empty names disable writing of the corresponding id data; no default VTK array names are used:

• material_id_field: when non-empty, write per-codim-0-cell material_id values;
• boundary_id_field: when non-empty, write boundary_id values on appended codim-1 subcells;
• manifold_id_field: when non-empty, write manifold_id values on appended codim-1 subcells and numbers::flat_manifold_id on codim-0 cells.

The output format is selected from the file extension: .vtk for legacy VTK and .vtu for VTK XML.

Definition at line 871 of file utilities.cc.

read_tria()

template<int dim, int spacedim>

void VTKWrappers::read_tria	(	const std::string &	vtk_filename,
		Triangulation< dim, spacedim > &	tria,
		const bool	cleanup = true,
		const double	relative_tolerance = 0.0,
		const std::string &	material_id_field = "",
		const std::string &	boundary_id_field = "",
		const std::string &	manifold_id_field = ""
	)

Read a VTK mesh file and populate a deal.II Triangulation.

This function reads the mesh from the specified VTK file and fills the given Triangulation object. If cleanup is true, overlapping points in the VTK file are merged using VTK's cleaning utilities.

The optional string parameters are forwarded to unstructured_grid_to_dealii_triangulation() and control whether VTK cell-data arrays are interpreted as deal.II ids:

• material_id_field: per-cell material ids for codim-0 cells;
• boundary_id_field: per-subcell boundary ids for codim-1 cells;
• manifold_id_field: manifold ids for both codim-0 and codim-1 cells.

Parameters

vtk_filename	The name of the input VTK file.
tria	The Triangulation object to populate.
material_id_field	Optional VTK cell-data scalar array name to read for material ids. The default empty string disables reading material ids.
boundary_id_field	Optional VTK cell-data scalar array name to read for boundary ids. The default empty string disables reading boundary ids.
manifold_id_field	Optional VTK cell-data scalar array name to read for manifold ids. The default empty string disables reading manifold ids.
cleanup	If true, merge overlapping points in the VTK file (default: true).
relative_tolerance	Relative tolerance used when merging points via VTK's cleaning utilities (default: 0).

Definition at line 886 of file utilities.cc.

read_cell_data()

void VTKWrappers::read_cell_data	(	const std::string &	vtk_filename,
		const std::string &	cell_data_name,
		Vector< double > &	output_vector,
		const bool	cleanup = true,
		const double	relative_tolerance = 0.0
	)

Read cell data (scalar or vector) from a VTK file and store it in the output vector.

This function reads the specified cell data array (scalar or vector) from the given VTK file and stores it in the provided output vector. For vector data, all components are stored in row-major order (cell0_comp0, cell0_comp1, ..., cell1_comp0, ...).

Parameters

vtk_filename	The name of the input VTK file.
cell_data_name	The name of the cell data array to read.
output_vector	The vector to store the cell data values.
cleanup	If true, merge overlapping points in the VTK file (default: true).
relative_tolerance	Relative tolerance used when merging points via VTK's cleaning utilities (default: 0).

Definition at line 903 of file utilities.cc.

read_vertex_data()

void VTKWrappers::read_vertex_data	(	const std::string &	vtk_filename,
		const std::string &	vertex_data_name,
		Vector< double > &	output_vector,
		const bool	cleanup = true,
		const double	relative_tolerance = 0.0
	)

Read vertex data from a VTK file and store it in the output vector.

This function reads the specified vertex data array (scalar or vector) from the given VTK file and stores it in the provided output vector.

For vector data, all components are stored in row-major order (vertex0_comp0, vertex0_comp1, ..., vertex1_comp0, ...).

Parameters

vtk_filename	The name of the input VTK file.
vertex_data_name	The name of the vertex data array to read.
output_vector	The vector to store the vertex data values.
cleanup	If true, merge overlapping points in the VTK file (default: true).
relative_tolerance	Relative tolerance used when merging points via VTK's cleaning utilities (default: 0).

Definition at line 927 of file utilities.cc.

read_all_data()

void VTKWrappers::read_all_data	(	const std::string &	vtk_filename,
		Vector< double > &	output_vector,
		const bool	cleanup = true,
		const double	relative_tolerance = 0.0
	)

Read all field data from a VTK file and store it in the output vector.

This function reads all field data arrays (scalar or vector, cell or point data) from the given VTK file and stores it in the provided output vector.

The data is output in the following way:

• first all vertex data (point data) in the order they are found in the VTK file, with all components stored in row-major order (vertex0_comp0, vertex0_comp1, ..., vertex1_comp0, ...)
• then all cell data (cell data) in the order they are found in the VTK file, with all components stored in row-major order (cell0_comp0, cell0_comp1, ...).

This is equivalent to calling read_vertex_data() for each vertex data field, and then read_cell_data() for each cell data field, and concatenating the resulting vectors in a single long vector.

Parameters

vtk_filename	The name of the input VTK file.
output_vector	The vector to store the vertex data values.
cleanup	If true, merge overlapping points in the VTK file (default: true).
relative_tolerance	Relative tolerance used when merging points via VTK's cleaning utilities (default: 0).

Definition at line 951 of file utilities.cc.

vtk_to_finite_element()

template<int dim, int spacedim>

std::pair< std::unique_ptr< FiniteElement< dim, spacedim > >, std::vector< std::string > > VTKWrappers::vtk_to_finite_element

(

const std::string &

vtk_filename

)

Create a FiniteElement representation for data stored in a VTK file.

This function inspects the specified VTK file and builds a FiniteElement (typically an FESystem) that can store the data fields contained in the file. It returns a pair consisting of a std::unique_ptr to the constructed FiniteElement and a vector of field names corresponding to the VTK data arrays.

Only meshes with a single cell type are supported (either all quads/hexes or all triangles/tetrahedra). Mixed meshes are not supported. The mesh type is inferred from the first cell encountered in the VTK file.

Mapping rules:

• Vertex data (VTK point data):
  • quad/hex meshes: represented by FE_Q(1) blocks;
  • simplex meshes: represented by FE_SimplexP(1) blocks.

• Cell data (VTK cell data):

  • quad/hex meshes: represented by FE_DGQ(0) blocks;
  • simplex meshes: represented by FE_SimplexDGP(0) blocks.

  Vector-valued cell or vertex data are represented as an FESystem of the scalar cell element repeated for each component.

Parameters

vtk_filename

The path to the input VTK file.

Definition at line 1007 of file utilities.cc.

data_to_dealii_vector()

template<int dim, int spacedim, typename VectorType >

void VTKWrappers::data_to_dealii_vector	(	const Triangulation< dim, spacedim > &	serial_tria,
		const Vector< double > &	data,
		const DoFHandler< dim, spacedim > &	dh,
		VectorType &	output_vector
	)

Translate a vtk data file (obtained through read_all_data() above) to a dealii vector type, associated with the given DoFHandler object.

Prerequisites:

• The input triangulation must be a serial triangulation, obtained through read_tria() above.
• The DoFHandler must have been initialized with the finite element obtained through the vtk_to_finite_element() method, and degrees of freedom must have been already distributed.
• The triangulation associated with the DoFHandler does not need to be same as the input triangulation, but it must be obtained from it. It may be, for example, a parallel::fullydistributed::Triangulation obtained by distributing the serial triangulation.
• The input data must refer to the serial triangulation (obtained through the read_vtk() method), and must have been obtained by calling the read_all_data() method above.

The DoFHandler object may be serial or parallel, and you may renumber it to your liking before calling this method. An example usage is the following:

// Read serial triangulation from VTK file Triangulation<dim, spacedim>
serial_tria; VTKWrappers::read_tria(vtk_filename, serial_tria);
 
// Read all data from VTK file Vector<double> serial_data;
VTKWrappers::read_all_data(vtk_filename, serial_data);
 
// Read finite element from VTK file auto [fe, data_names] =
VTKWrappers::vtk_to_finite_element<dim, spacedim>(vtk_filename);
 
// Split serial triangulation into a parallel one
parallel::fullydistributed::Triangulation<dim, spacedim> parallel_tria;
parallel_tria.copy_triangulation(serial_tria); // use default partitioner
 
// Setup DoFHandler on parallel triangulation DoFHandler<dim, spacedim>
dof_handler(parallel_tria); dof_handler.distribute_dofs(*fe); // Optionally
renumber dofs here
...
// Map serial data to distributed vector
LinearAlgebra::distributed::Vector<double> distributed_data;
VTKWrappers::data_to_dealii_vector( serial_tria, serial_data, dof_handler,
distributed_data);

This function exists to allow manipulation of the DoFHandler (e.g., through block wise renumbering) before mapping the (serial) data to (a possibly distributed) vector.

Template Parameters

dim
spacedim
VectorType

Parameters

serial_tria
data
dh
output_vector

read_vtk()

template<int dim, int spacedim>

void VTKWrappers::read_vtk	(	const std::string &	vtk_filename,
		DoFHandler< dim, spacedim > &	dof_handler,
		Vector< double > &	output_vector,
		std::vector< std::string > &	data_names,
		const bool	cleanup = true,
		const double	relative_tolerance = 0.0,
		const std::string &	material_id_field = "",
		const std::string &	boundary_id_field = "",
		const std::string &	manifold_id_field = ""
	)

Read a VTK mesh and all data fields into a DoFHandler and output vector.

This function reads the mesh from the specified VTK file, populates the Triangulation associated to the given DoFHandler, and queries all cell and vertex data fields. For each data field, a suitable FESystem is constructed (using FE_DGQ for cell data and FE_Q for vertex data, with the correct number of components). DoFs are distributed and renumbered block-wise. All data is read into the output_vector, and the names of the fields are stored in data_names.

Parameters

vtk_filename	The name of the input VTK file.
dof_handler	The DoFHandler to distribute DoFs on the mesh.
output_vector	The vector to store all data field values.
data_names	The vector to store the names of all data fields found in the VTK file.
material_id_field	Optional VTK cell-data scalar array name to read for material ids when reconstructing the Triangulation. The default empty string disables reading material ids.
boundary_id_field	Optional VTK cell-data scalar array name to read for boundary ids when reconstructing the Triangulation. The default empty string disables reading boundary ids.
manifold_id_field	Optional VTK cell-data scalar array name to read for manifold ids when reconstructing the Triangulation. The default empty string disables reading manifold ids.
cleanup	If true, merge overlapping points in the VTK file (default: true).
relative_tolerance	Relative tolerance used when merging points via VTK's cleaning utilities (default: 0).

Definition at line 1138 of file utilities.cc.