API reference

VTKRowData()

The data location of Table columns, usable wherever VTKPointData() etc. are: tbl["a", VTKRowData()] = col when writing, r["a", VTKRowData()] and keys(r, VTKRowData()) when reading.

vtkhdf_grid(filename, points, cells; kwargs...)
vtkhdf_grid(filename, x, [y, [z]]; kwargs...)
vtkhdf_grid(filename, xyz::AbstractArray{T,4}; kwargs...)
vtkhdf_grid(dataset_type, filename, args...; kwargs...)
vtkhdf_grid(dataset_type, filename; kwargs...)

Create a VTKHDF file for one of the grid dataset types. The type is inferred from the arguments (mirroring WriteVTK.jl). The last form — just a VTKUnstructuredGrid()/VTKPolyData() tag and no geometry — creates the file empty, so partitions can be appended one at a time with add_partition:

• UnstructuredGrid: points and cells. points is a 3×N matrix (smaller first dimensions are zero-padded), a vector of point-like objects, or a tuple of coordinate vectors; cells is a vector of MeshCell/VTKPolyhedron.
• PolyData: points plus one or more vectors of MeshCells with PolyData.* cell types (e.g. PolyData.Polys()); each vector must contain a single category. On disk (and for cell data) cells are ordered Vertices, Lines, Polygons, Strips.
• ImageData: 1–3 AbstractRanges (uniform spacing), or vtkhdf_grid(VTKImageData(), filename, dims; origin, spacing, direction, whole_extent).
• RectilinearGrid: 1–3 coordinate AbstractVectors, at least one of which is not a range (or the explicit VTKRectilinearGrid() tag).
• StructuredGrid: a (3, ni, nj, nk) coordinate array, or three (ni, nj, nk) arrays x, y, z.

Data arrays are written with vtk["name"] = data; the location is inferred from the size, or given explicitly as vtk["name", VTKCellData()] = data. Vector and tensor data uses the component-first convention ((3, N) for vectors, like WriteVTK.jl), or a vector of static vectors or tuples. The attribute keyword marks active attributes: vtk["u", VTKPointData(), attribute = :Vectors] = u.

Common keyword arguments:

• temporal::Bool = false: open the file for time-dependent writing with write_timestep.
• compress = false: true (gzip level 6) or an integer level 0-9.
• chunk_size = 0: override the automatic HDF5 chunk length along the append dimension.

All forms support a leading function for the do-block idiom, which closes the file afterwards. When filename has no extension, .vtkhdf is appended. Instead of a filename, (collection, blockname) can be passed to create the dataset as a block of a composite file (see vtkhdf_collection).

vtkhdf_table(filename; temporal = false, compress = false, kwargs...)

Create a VTKHDF Table file. Columns are written with tbl[name] = column where a column is a vector or a (ncomponents, nrows) matrix; all columns must have the same number of rows. For temporal tables, write columns inside write_timestep.

Supports the do-block form vtkhdf_table(fname) do tbl ... end.

vtkhdf_amr(filename; origin, grid_description = :XYZ, compress = false)

Create a VTKHDF OverlappingAMR file. Levels are added with add_level and boxes with add_box:

vtkhdf_amr("amr"; origin = (0, 0, 0)) do amr
    lvl = add_level(amr; spacing = (1.0, 1.0, 1.0))
    add_box(lvl, (0, 4, 0, 4, 0, 4); celldata = ("ρ" => ρ,))
end

Temporal AMR is not supported.

vtkhdf_htg(filename; dimensions, branch_factor = 2, kwargs...)

Create a VTKHDF HyperTreeGrid file. dimensions is the number of coordinate points per direction. The number of trees is the product of max(nᵢ - 1, 1) over the directions, so a direction with a single coordinate contributes no trees. Pieces (partitions) are appended with add_piece.

Optional keywords: transposed_root_indexing::Bool, interface_normals_name, interface_intercepts_name.

Temporal HyperTreeGrid writing is not supported.

vtkhdf_collection(filename) -> collection
vtkhdf_multiblock(filename) -> collection

Create a composite VTKHDF file: a PartitionedDataSetCollection, or a MultiBlockDataSet for vtkhdf_multiblock. Blocks are created with the usual constructors, passing (collection, name) instead of a filename, e.g. vtkhdf_grid(col, "mesh", points, cells). They behave like standalone files, temporal writing included, except that all temporal blocks must share the same time values. The block hierarchy is defined with add_node and add_block_ref; add_empty_block creates a type-less block.

Supports the do-block form. Closing the collection closes all blocks.

vtkhdf_multiblock(filename)

Shorthand for vtkhdf_collection(filename; multiblock = true); see vtkhdf_collection.

vtk["name"] = data
vtk["name", loc] = data
vtk["name", loc, attribute = :Scalars] = data

Write a data array. Without a location the location is inferred from the array size; loc (VTKPointData(), VTKCellData(), VTKFieldData(), VTKRowData()) gives it explicitly. attribute (:Scalars, :Vectors, ...) marks the array as the location's active attribute. See the manual's Data arrays for the accepted array shapes.

write_timestep(f::Function, vtk, t::Real; geometry...)

Write one time step with time value t to a temporal VTKHDF file. Data arrays are written inside the do-block with the same vtk[name] = data syntax used for static files.

With no geometry keyword arguments, the previous step's geometry is reused and stored only once. Passing new geometry (points/cells for unstructured grids, x/y/z for rectilinear grids, points for structured grids) appends it; this step and later ones then use it.

The set of data arrays (names, element types, component counts) must be the same for every step; it is fixed by the first step.

vtk = vtkhdf_grid("sim", points, cells; temporal = true)
for (t, u) in timesteps
    write_timestep(vtk, t) do frame
        frame["u"] = u
    end
end
close(vtk)

add_partition(vtk, points, cells; pointdata = (), celldata = ())        # UnstructuredGrid
add_partition(vtk, points, cellvecs...; pointdata = (), celldata = ())  # PolyData

Append one partition of geometry (and optionally its data) to an unstructured grid or poly data file (usually one created without geometry, via vtkhdf_grid(VTKUnstructuredGrid(), filename) / vtkhdf_grid(VTKPolyData(), filename)). For PolyData, pass one homogeneous cell vector per category, as in the constructor. For temporal files this must be called inside write_timestep (all partitions of a step must be supplied when its geometry changes); a file created without geometry can also add its initial partitions before the first step.

pointdata/celldata are iterables of name => data pairs whose lengths are validated against this partition. Alternatively, data for all partitions of a step can be written afterwards with vtk[name] = data using the concatenated arrays.

add_level(amr; spacing) -> level

Append a refinement level (Level0, Level1, ...) with the given cell spacing to an OverlappingAMR file.

add_box(level, (imin, imax, jmin, jmax, kmin, kmax); pointdata = (), celldata = (), fielddata = ())

Append one AMR box (inclusive cell extents) to a level. Data arrays are serialized per box, in the order boxes are added; sizes are validated against the box extents (imax - imin + 1 cells and imax - imin + 2 points per direction). Data can alternatively be written for a whole level at once with level[name, VTKCellData()] = data after adding its boxes.

add_piece(
    htg; descriptors, depth_per_tree, tree_ids,
    number_of_cells_per_tree_depth, xcoordinates, ycoordinates,
    zcoordinates, mask = nothing, celldata = ()
)

Append one piece (partition) to a HyperTreeGrid file:

• descriptors::AbstractVector{Bool}: refinement bits for each tree in turn, level by level within the tree (each tree's deepest level carries no bits); bit-packed MSB-first on disk. Each refined cell must have exactly branch_factor^dim cells on the next level.
• depth_per_tree, tree_ids: depth and id of each tree in the piece.
• number_of_cells_per_tree_depth: cells per depth, tree by tree (sum(depth_per_tree) entries); its total is the piece's cell count.
• x/y/zcoordinates: tree coordinates for this piece (lengths matching dimensions).
• mask: optional AbstractVector{Bool} of length equal to the cell count, in descriptor cell order; refined cells cannot be masked.
• celldata: iterable of name => array pairs (HyperTreeGrids have no point data).

add_node(col_or_node, name) -> node

Create a group node in the Assembly hierarchy of a composite file (under the root assembly, or nested under another node).

add_block_ref(col_or_node, block)

Reference a block from the Assembly hierarchy (a soft link named after the block). A block may be referenced from several nodes.

add_empty_block(col, name) -> block

Add a block with no dataset type to a composite file (a placeholder allowed by the spec). The returned handle can be referenced from the Assembly with add_block_ref.

vtkhdf_open(filename) -> reader
vtkhdf_open(f::Function, filename)

Open a VTKHDF file for reading. Returns a VTKHDFReader for simple datasets or a VTKHDFCollectionReader for composite files (PartitionedDataSetCollection/MultiBlockDataSet); the reader must be closed (the do-block form does so automatically).

Data arrays are read by indexing (the location is found automatically, or passed explicitly): r["u"], r["u", VTKCellData()]. Geometry is read with read_points, read_cells and read_coordinates. Temporal files are read one step at a time via read_timestep.

See the manual for the full reading API (much of which — nsteps, time_values, grid_info, ... — is public but not exported).

read_timestep(r, i) -> step

A view of time step i (1-based) of a temporal file. The step supports the same data and geometry access as a static reader — step["u"], read_points(step), read_cells(step), ... — plus time_value. It holds no resources of its own (the parent reader must stay open).

read_points(r_or_step)

Point coordinates: a 3 × N matrix for UnstructuredGrid/PolyData, a (3, ni, nj, nk) array for StructuredGrid.

read_cells(r_or_step)

The cells of an UnstructuredGrid (a vector of MeshCell/VTKPolyhedron with 1-based connectivity into read_points), or of a PolyData (a NamedTuple (; vertices, lines, polygons, strips) of MeshCell vectors). Multi-partition files are concatenated with point ids rebased; see partition_ranges for the partition structure.

read_coordinates(r_or_step) -> (x, y, z)

The coordinate vectors of a RectilinearGrid.

r["name"]
r["name", loc]

Read a data array by name from a reader or a time step. Without a location the dataset's locations are searched (an ambiguous name throws); loc reads from that location only. Values come back as plain arrays in the writing shape convention (see Data arrays).

keys(r, loc) -> Vector{String}

Names of the data arrays stored at loc (VTKPointData(), VTKCellData(), VTKFieldData(), VTKRowData()); works on readers and time steps.

keys(col) -> Vector{String}

The block names of a composite file, ordered by the Index attribute for PartitionedDataSetCollection and by creation order for MultiBlockDataSet. Blocks are opened by indexing: col["mesh"].

col[name] -> block reader

Open block name of a composite file. Typed blocks return a reader with the full reading API; type-less placeholder blocks return a handle whose dataset_type is nothing. Block readers share the collection's file handle and are invalidated when the collection is closed.

dataset_type(r) -> String

The VTKHDF dataset type of an open reader (the Type attribute), e.g. "UnstructuredGrid". For composite files, "PartitionedDataSetCollection" or "MultiBlockDataSet"; for an empty (type-less) composite block, nothing.

file_version(r) -> (major, minor)

The VTKHDF specification version of the file (the Version attribute).

is_temporal(r) -> Bool

Whether the file contains time-dependent data (a Steps group). Temporal data is read step by step with read_timestep.

nsteps(r) -> Int

Number of time steps in a temporal file (is_temporal).

time_values(r) -> Vector{Float64}

The time value of every step of a temporal file.

time_value(step) -> Float64

The time value of a step obtained from read_timestep.

grid_info(r) -> NamedTuple

The metadata attributes stored at the dataset root, per dataset type:

• ImageData: (; dims, origin, spacing, direction, whole_extent)
• RectilinearGrid, StructuredGrid: (; dims, whole_extent)
• OverlappingAMR: (; origin, grid_description)
• HyperTreeGrid: (; dimensions, branch_factor, transposed_root_indexing)

UnstructuredGrid and PolyData store no such attributes and have no grid_info method.

npoints(r_or_step) -> Int

Total number of points (UnstructuredGrid, PolyData, ImageData, RectilinearGrid, StructuredGrid; also amr_level handles).

ncells(r_or_step) -> Int

Total number of cells (UnstructuredGrid, PolyData, ImageData, RectilinearGrid, StructuredGrid, HyperTreeGrid; also amr_level handles).

nrows(r_or_step) -> Int

Number of rows of a Table (for a temporal table: of one time step).

npartitions(r_or_step) -> Int

Number of geometry partitions (UnstructuredGrid, PolyData).

partition_ranges(r_or_step) -> NamedTuple

The index ranges of each partition into the concatenated point/cell data arrays. For UnstructuredGrid: (; points, cells), each a vector with one range per partition. For PolyData additionally cells_by_category: per partition, a (; vertices, lines, polygons, strips) NamedTuple of ranges into the cell-data arrays (on disk, PolyData cell data is partition-major with the categories in that order inside each partition). For an amr_level handle: (; points, cells) with one range per AMR box.

active_attributes(r, loc) -> Dict{Symbol, String}

The active-attribute roles (:Scalars, :Vectors, ...) defined for the data-array group at loc, mapping role to array name. Both spec encodings are understood: group attributes (PointData attribute "Vectors" => "u") take precedence; per-array Attribute attributes (spec 2.6, matched case-insensitively) fill in roles the group does not define.

data_attributes(r, name, loc) -> Vector{Symbol}

All active-attribute roles resolved to the array name at loc (see active_attributes).

read_assembly(col) -> AssemblyTreeNode

The Assembly hierarchy of a composite file as a tree. Each node has name, children::Vector{AssemblyTreeNode} (nested assembly nodes) and blocks::Vector{String} (names of the blocks referenced from this node), both in creation order. The root node is named "Assembly".

nlevels(r) -> Int

Number of refinement levels of an OverlappingAMR file.

amr_level(r, l) -> level

The refinement level l of an OverlappingAMR file, with l the on-disk level number in 0:nlevels(r)-1 (Level0 is the coarsest). The level supports level_info, keys(level, loc), data reading by indexing (level["ρ"], level["ρ", VTKCellData()] — arrays are concatenated over the level's boxes) and partition_ranges with one point/cell range per box.

level_info(level) -> (; spacing, boxes)

Spacing and AMR boxes (inclusive cell extents (imin, imax, jmin, jmax, kmin, kmax)) of an amr_level.

npieces(r) -> Int

Number of pieces (partitions) of a HyperTreeGrid file.

htg_piece(r, p) -> NamedTuple

Piece p (1-based) of a HyperTreeGrid file, as the exact inverse of add_piece: a NamedTuple with descriptors::Vector{Bool}, tree_ids, depth_per_tree, number_of_cells_per_tree_depth, xcoordinates/ycoordinates/zcoordinates, mask::Union{Nothing, Vector{Bool}} and celldata::Dict{String, Any} (this piece's slice of every cell-data array).

VTKHDF

Write and read VTK data in the VTKHDF file format (HDF5-based, spec version 2.x). Supports static and temporal data for all basic VTK dataset types and composite datasets.

Main entry points for writing: vtkhdf_grid, vtkhdf_table, vtkhdf_amr, vtkhdf_htg, vtkhdf_collection, vtkhdf_multiblock and write_timestep; for reading: vtkhdf_open and read_timestep.