GitHub

ReadVTK.jl

With ReadVTK.jl you can read in data from VTK XML files in Julia. It aims to complement the excellent package WriteVTK.jl.

Note: ReadVTK was mainly motivated by wanting to write proper tests for Trixi2Vtk.jl. A lot of useful features are still missing (see What does not work), and community contributions to improve this package are welcome!

Usage

First, load the package with

using ReadVTK

Open a VTK file by creating a VTKFile object and passing the filename to the constructor:

vtk = VTKFile(get_example_file("celldata_appended_binary_compressed.vtu"))

To retrieve information about the cell data, use

cell_data = get_cell_data(vtk)

The return object of type VTKCellData allows access to the individual VTKDataArrays using a dictionary-like syntax:

element_ids = cell_data["element_ids"]

Finally, the actual data can be obtained by executing

data = get_data(element_ids)

Full example including REPL output:

julia> using ReadVTK

julia> vtk = VTKFile(get_example_file("celldata_appended_binary_compressed.vtu"))
VTKFile("celldata_appended_binary_compressed.vtu", <XMLDocument>, "UnstructuredGrid", "1.0.0", "LittleEndian", "vtkZLibDataCompressor", <appended_data>, 4434, 3085)

julia> cell_data = get_cell_data(vtk)
VTKData()

julia> element_ids = cell_data["element_ids"]
VTKDataArray("element_ids")

julia> data = get_data(element_ids)
3085-element reinterpret(Int64, ::Vector{UInt8}):
    1
    2
    3
    ⋮
 3083
 3084
 3085

After modifications to the read VTK data, one can write back using WriteVTK.jl but must first convert cell objects using to_meshcells. Continuing from the REPL code above:

julia> using WriteVTK

julia> points = get_points(vtk); cells = to_meshcells(get_cells(vtk));

julia> vtk_grid("celldata_appended_binary_compressed_new.vtu", points, cells) do vtk
         vtk["element_ids"] = data
       end
1-element Vector{String}:
 "celldata_appended_binary_compressed_new.vtu"

Further example VTK files can be found in the ReadVTK_examples repository.

What works

  • Reading in VTK XML files of type UnstructuredGrid, StructuredGrid, RectilinearGrid,ImageData, PUnstructuredGrid, PStructuredGrid, PRectilinearGrid,PImageData, or PolyData
  • Extracting cell or point data
  • Extracting field data
  • Extracting point coordinates
  • Extracting information about cell types
  • Only for ImageData,PImageData files: get origin, spacing, and extent information
  • Only for RectilinearGrid,PRectiLinearGrid files: get 1D coordinate vectors
  • Only for StructuredGrid,PStructuredGrid files: get coordinate arrays
  • Reading PolyData files containing vortices, lines, and/or polygons
  • Reading PVD files
  • Reading ParaView VTK files that are in-line binary (experimental, only UnstructuredGrid type tested)

What does not work

  • Reading VTK files not stored in the VTK XML format
  • Reading VTK files of other type than what is listed under What works above
  • Multiblock files
  • Different byte orders in file and host system
  • Probably reading from VTK files that were not created by WriteVTK.jl will fail, specifically since
    • compressed data is assumed to be stored as a single block
    • appended data is assumed to be stored as raw
    • header_type is hardcoded to UInt64
  • Extracting primitives from PolyData files other than vortices, lines, and/or polygons
  • Likely anything else that is not specifically mentioned under What works

Development

Helpful resources for working with (i.e., reading and writing) VTK XML files:

  • VTK file format documentation (incomplete!) as a PDF
  • VTK XML formats wiki article
  • Blog post on encoding binary data
  • Mailing list message on encoding binary data

We use JuliaFormatter.jl to keep a consistent code formatting. If you have installed JuliaFormatter.jl, just run

using JuliaFormatter; format(".")

in the top-level directory of ReadVTK.jl to update the formatting.

Authors

ReadVTK is maintained by the Trixi authors. Its principal developers are Michael Schlottke-Lakemper (University of Stuttgart, Germany) and Hendrik Ranocha (Johannes Gutenberg University Mainz, Germany).

Further contributions to ReadVTK have been made by the following people:

License and contributing

ReadVTK is licensed under the MIT license (see License). Since ReadVTK is an open-source project, we are very happy to accept contributions from the community. Please refer to Contributing for more details. To get in touch with the developers, join us on Trixi's Slack workspace or create an issue.

Acknowledgments

This package would not exist without the nice work of Juan Ignacio Polanco and his cleanly written and well-documented package WriteVTK.jl.