README.md 5.76 KB
Newer Older
Praetorius, Simon's avatar
Praetorius, Simon committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Dune-Vtk
File reader and writer for the VTK Format

## Summary
Provides structured and unstructured file writers for the VTK XML File Formats 
that can be opened in the popular ParaView visualization application. Additionally
a file reader is provided to import VTK files into Dune grid and data objects.

## Usage
The VTK writer works similar to the dune-grid `VTKWriter`. It needs to be bound 
to a GridView and then data can be added to the points or cells in the grid.
Points are not necessarily grid vertices, but any coordinates places inside the 
grid cells, so the data must be provided as GridViewFunction to allow the local
evaluation in arbitrary local coordinates.

```c++
Grid grid = ...;
Simip's avatar
Simip committed
18
VtkWriter<typename Grid::LeafGridView> vtkWriter(grid.leafGridView(), Vtk::ASCII);
Praetorius, Simon's avatar
Praetorius, Simon committed
19
20
21
22
23
24
25
26

auto fct = makeAnalyticGridViewFunction([](auto const& x) {
  return std::sin(x[0]);
});

vtkWriter.addPointData(fct, "u_points");
vtkWriter.addCellData(fct, "u_cells");

Simip's avatar
Simip committed
27
vtkWriter.write("filename.vtu");
Praetorius, Simon's avatar
Praetorius, Simon committed
28
29
30
31
32
33
34
35
```

See also the `src/` directory for more examples.

## Comparison with Dune::VTKWriter
In Dune-Grid there is a VTK writer available, that is a bit different from the
proposed one. A comparions:

Praetorius, Simon's avatar
Praetorius, Simon committed
36
| **Property**       | **Dune-Grid** | **Dune-Vtk** |
Praetorius, Simon's avatar
Praetorius, Simon committed
37
38
39
| ------------------ | :-----------: | :----------: |
| VTK version        | 0.1           | 1.0          |
| UnstructuredGrid   | **x**         | **x**        |
Praetorius, Simon's avatar
Praetorius, Simon committed
40
| PolyData           | (1d)          | -            |
Praetorius, Simon's avatar
Praetorius, Simon committed
41
42
43
44
45
46
47
48
49
50
| StructuredGrid     | -             | **x**        |
| RectilinearGrid    | -             | **x**        |
| ImageData          | -             | **x**        |
| ASCII              | **x**         | **x**        |
| BASE64             | **x**         | -            |
| APPENDED_RAW       | **x**         | **x**        |
| APPENDED_BASE64    | **x**         | -            |
| BASE64_COMPRESSED  | -             | -            |
| APPEDED_COMPRESSED | -             | **x**        |
| Parallel files     | **x**         | **x**        |
Praetorius, Simon's avatar
Praetorius, Simon committed
51
52
53
54
| Conforming Data    | **x**         | **x**        |
| NonConforming Data | **x**         | **x**        |
| Quadratic Data     | -             | **x**        |
| Subdivided Data    | **x**         | -            |
Simip's avatar
Simip committed
55
56
| Sequence (PVD)     | **x**         | **x**        |
| Timeseries         | -             | x            |
Praetorius, Simon's avatar
Praetorius, Simon committed
57

Simip's avatar
Simip committed
58
59
## Writers and Readers
Dune-Vtk provides nearly all file formats specified in VTK + 2 time series formats: PVD and VTK-Timeseries.
Praetorius, Simon's avatar
Praetorius, Simon committed
60

Simip's avatar
Simip committed
61
62
### VtkUnstructuredGridWriter
Implements a VTK file format for unstructured grids with arbitrary element types in 1d, 2d, and 3d. Coordinates are specified explicitly and a connectivity table + element types are specified for all grid elements (of codim 0). Can be used with all Dune grid types.
Praetorius, Simon's avatar
Praetorius, Simon committed
63

Simip's avatar
Simip committed
64
65
### VtkStructuredGridWriter
Implements a writer for grid composed of cube elements (lines, pixels, voxels) with local numbering similar to Dunes `cube(d)` numbering. The coordinates of the vertices can be arbitrary but the connectivity is implicitly given and equals that of `Dune::YaspGrid` or `Dune::SPGrid`. Might be chosen as writer for a transformed structured grid, using, e.g., a `GeometryGrid` meta-grid. See `src/geometrygrid.cc` for an example.
Praetorius, Simon's avatar
Praetorius, Simon committed
66

Simip's avatar
Simip committed
67
68
### VtkRectilinearGridWriter
Rectilinear grids are tensor-product grids with given coordinates along the x, y, and z axes. Therefore, the grid must allow to extract these 1d coordinates and a specialization for a `StructuredDataCollector` must be provided, that implements the `ordinates()` function. By default, it assumes constant grid spacing starting from a lower left corner. For `YaspGrid` a specialization is implemented if the coordinates type is `TensorProductCoordinates`. See `src/structuredgridwriter.cc` for an example.
Praetorius, Simon's avatar
Praetorius, Simon committed
69

Simip's avatar
Simip committed
70
71
### VtkImageDataWriter
The *most structured* grid is composed of axis-parallel cube elements with constant size along each axis. The is implemented in the VtkImageDataWriter. A specialization of the `StructuredDataCollector` must implement `origin()` for the lower left corner, `wholeExtent()` for the range of cell numbers along each axis in the global grid, `extent()` for the range in the local grid, and `spacing()` for the constant grid spacing in each direction.
Praetorius, Simon's avatar
Praetorius, Simon committed
72

Simip's avatar
Simip committed
73
74
### PvdWriter
A sequence writer, i.e. a collection of timestep files, in the ParaView Data (PVD) format. Supports all VtkWriters for the timestep output. In each timestep a collection (.pvd) file is created.
Praetorius, Simon's avatar
Praetorius, Simon committed
75

Simip's avatar
Simip committed
76
77
78
79
80
81
82
83
84
**TODO:**

- Just append the new timestep to the file instead of recreating it.

### VtkTimseriesWriter
A timeseries is a collection of timesteps stored in one file, instead of separate files for each timestep value. Since in the `Vtk::APPENDED` mode, the data is written as binary blocks in the appended section of the file and references by an offset in the XML DataArray attributes, it allows to reuse written data. An example of usage is when the grid points and cells do not change over time, but just the point-/cell-data. Then, the grid is written only once and the data is just appended.

Timeseries file are create a bit differently from other Vtk file. There, in the first write the grid points and cells are stored in a separate file, and in each timestep just the data is written also to temporary files. When you need the timeseries file, these stored temporaries are collected and combined to one VTK file. Thus, only the minimum amount of data is written in each timestep. The intermediate files are stored, by default, in a `/tmp` folder, with (hopefully) fast write access.

Simip's avatar
Simip committed
85
86
87
88
**Limitations:**

- Maximum 1000 timesteps can be written. This is a limitation of VTK.

Simip's avatar
Simip committed
89
90
91
92
93
94
95
96
**TODO:**

- Allow to specify the `/tmp` folder by the user.

### VtkReader
Read in unstructured grid files (.vtu files) and create a new grid, using a GridFactory.

**TODO:**
Praetorius, Simon's avatar
Praetorius, Simon committed
97

Simip's avatar
Simip committed
98
99
- Provide an interface to read the points-/cell-data from the file
- Extent the implementation to other file formats