VTK ファイルフォーマット

2020年7月11日

はじめに

VTK ファイルフォーマットについて説明します。

VTK ファイル

VTK ファイルは、形状と属性を含みます。ファイル名の接尾子には ".vtk" が使われます。テキストとバイナリで記述できますが、ここではテキストで記述する場合だけを説明します。以下、全部大文字の語はキーワードで、小文字交じりの語はユーザー指定を意味します。

ヘッダー

ファイルの先頭は以下のように書きます。

# vtk DataFile Version 2.0
Header
ASCII
DATASET UNSTRUCTURED_GRID

1 行目は、ファイルの種類を表わすためのオマジナイです。Header の部分は、任意の文字列を書くことができます。"ASCII" は、全部テキストで書きますよという指定です。"DATASET" の "UNSTRUCTURED_GRID" は、非構造格子のデータですよという意味です。

形状

UNSTRUCTURED_GRID の形状は、以下のような書式で記述します。

POINTS NumPoints DataType
x0 y0 z0 x1 y1 z1 ...

CELLS NumCells DataSize
num0 p00 p01 ... num1 p10 p11 ...

CELL_TYPES NumCells
TypeNum0 TypeNum1 ...

NumPoints は点の数、DataType は "int" や "float" を指定します。NumCells はセルの数、DataSize はそれに続く数値の個数を指定します。numi はセル i を構成する点の数、pi0 pi1 ... はその点です。点の ID は 0 からはじまります。TypeNumi はセル i のセルタイプ番号です。主なセルタイプ番号を以下に示します。

  • 1 : 点
  • 5 : 三角形
  • 9 : 四辺形
  • 10 : 四面体
  • 12 : 六面体
  • 13 : 三角柱
  • 14 : ピラミッド

例を示しましょう。

三角形 triangle.vtk

# vtk DataFile Version 2.0
triangle
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 3 float
0 0 0
1 0 0
1 1 0
CELLS 1 4
3 0 1 2
CELL_TYPES 1
5

四辺形 quad.vtk

# vtk DataFile Version 2.0
quad
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 4 float
0 0 0
1 0 0
1 1 0
0 1 0
CELLS 1 5
4 0 1 2 3
CELL_TYPES 1
9

四面体 tetra.vtk

# vtk DataFile Version 2.0
tetra
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 4 float
0 0 0
1 0 0
1 1 0
0.8 0.2 1
CELLS 1 5
4 0 1 2 3
CELL_TYPES 1
10

六面体 hexahedron.vtk

# vtk DataFile Version 2.0
hexahedron
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 8 float
0 0 0
1 0 0
1 1 0
0 1 0
0 0 1
1 0 1
1 1 1
0 1 1
CELLS 1 9
8 0 1 2 3 4 5 6 7
CELL_TYPES 1
12

三角柱 wedge.vtk

# vtk DataFile Version 2.0
wedge
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 6 float
0 0 0
1 0 0
1 1 0
0 0 1
1 0 1
1 1 1
CELLS 1 7
6 0 1 2 3 4 5
CELL_TYPES 1
13

ピラミッド pyramid.vtk

# vtk DataFile Version 2.0
pyramid
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 5 float
0 0 0
1 0 0
1 1 0
0 1 0
0.5 0.5 1
CELLS 1 6
5 0 1 2 3 4
CELL_TYPES 1
14

属性

属性というのは、要するにシミュレーションデータでいうところの流速やら応力やらのデータのことですが、点とセルでそれぞれ指定できます。

POINT_DATA numPoints
...
CELL_DATA numCells
...

点、セルそれぞれにおいて、スカラーデータとベクトルデータを指定できます。

SCALARS Name DataType
LOOKUP_TABLE default
...
VECTORS Name DataType
...

Name には任意の名前を指定できます (空白を入れるのはダメ)。

例を示しましょう。

スカラーデータ scalar.vtk

# vtk DataFile Version 2.0
scalar
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 4 float
0 0 0
1 0 0
1 1 0
0 1 0
CELLS 1 5
4 0 1 2 3
CELL_TYPES 1
9
POINT_DATA 4
SCALARS point_scalars float
LOOKUP_TABLE default
1
2
3
4
CELL_DATA 1
SCALARS cell_scalars float
LOOKUP_TABLE default
5

ベクトルデータ vector.vtk

# vtk DataFile Version 2.0
vector
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 4 float
0 0 0
1 0 0
1 1 0
0 1 0
CELLS 1 5
4 0 1 2 3
CELL_TYPES 1
9
POINT_DATA 4
VECTORS point_vectors float
1 1 0
-1 1 0
-1 -1 0
1 -1 0
CELL_DATA 1
VECTORS cell_vectors float
1 1 0

構造格子

構造格子を表すための DATASET の種類として "STRUCTURED_POINTS" と "STRUCTURED_GRID" があります。点の間隔が均一の場合は "STRUCTURED_POINTS" が使えます。

DATASET STRUCTURED_POINTS
DIMENSIONS nx ny nz
ORIGIN x0 y0 z0
SPACING dx dy dz

nx, ny, nz は点の数、x0, y0, z0 は原点の座標、dx, dy, dz は点と点の間の広さです。

セル値も扱えますが、nx, ny, nz は点の数なので、セルの分割数で考えるにはそれぞれ 1 を足す必要があります。セル値を書き込む場合、ループは z, y, x で回します ((0, 0, 0), (1, 0, 0), ... という順番で書き込む)。

点の間隔が均一でない場合は "STRUCTURED_GRID" が使えます。

DATASET STRUCTURED_GRID
DIMENSIONS nx ny nz
POINTS NumPoints DataType
x0 y0 z0 x1 y1 z1 ...

XML フォーマット

上記の古い (legacy) フォーマットとは別に、XML 形式のものもあります。たとえば、上述の triangle.vtk、quad.vtk を XML フォーマットで書くと、次のようになります。

triangle.vtu

<VTKFile type="UnstructuredGrid" version="1.0">
<UnstructuredGrid>
<Piece NumberOfPoints="3" NumberOfCells="1">
<Points>
<DataArray type="Float32" NumberOfComponents="3" format="ascii">
0 0 0
1 0 0
1 1 0
</DataArray>
</Points>
<Cells>
<DataArray type="Int64" Name="offsets" format="ascii">
3
</DataArray>
<DataArray type="Int64" Name="connectivity" format="ascii">
0 1 2
</DataArray>
<DataArray type="UInt8" Name="types" format="ascii">
5
</DataArray>
</Cells>
</Piece>
</UnstructuredGrid>
</VTKFile>

quad.vtu

<VTKFile type="UnstructuredGrid" version="1.0">
<UnstructuredGrid>
<Piece NumberOfPoints="4" NumberOfCells="1">
<Points>
<DataArray type="Float32" NumberOfComponents="3" format="ascii">
0 0 0
1 0 0
1 1 0
0 1 0
</DataArray>
</Points>
<Cells>
<DataArray type="Int64" Name="offsets" format="ascii">
4
</DataArray>
<DataArray type="Int64" Name="connectivity" format="ascii">
0 1 2 3
</DataArray>
<DataArray type="UInt8" Name="types" format="ascii">
9
</DataArray>
</Cells>
</Piece>
</UnstructuredGrid>
</VTKFile>

XML フォーマットの場合、データのタイプにより拡張子が変わります。UnstructuredGrid は .vtu、StructuedGrid は .vts など。上記の例で、Cells の DataArray "offsets" の値は、セルごとのデータの最後の位置で、たとえば六面体データの場合は、8, 16, 24, ... となります。

legacy における STRUCTURED_POINTS に相当するものは ImageData (.vti) です。

grid.vti

<VTKFile type="ImageData" version="1.0">
<ImageData WholeExtent="0 10 0 10 0 10" Origin="0 0 0" Spacing="0.1 0.1 0.1">
<Piece Extent="0 10 0 10 0 10">
</Piece>
</ImageData>
</VTKFile>

WholeExtent は DIMENSIONS に対応するもので、x, y, z それぞれの節点のインデックスの範囲を指定しています (11 節点必要なら 0 と 10 を指定する)。

StructuredGrid は次のようになる。

grid.vts

<VTKFile type="StructuredGrid" version="1.0">
<StructuredGrid WholeExtent="0 1 0 1 0 1">
<Piece Extent="0 1 0 1 0 1">
<Points>
<DataArray type="Float32" NumberOfComponents="3" format="ascii">
0 0 0
1 0 0
0 1 0
1 1 0
0 0 1
1 0 1
0 1 1
1 1 1
</DataArray>
</Points>
</Piece>
</StructuredGrid>
</VTKFile>

上述のスカラーデータ scalar.vtk とベクトルデータ vector.vtk の XML 版は次のようになります。

scalar.vtu

<VTKFile type="UnstructuredGrid" version="1.0">
<UnstructuredGrid>
<Piece NumberOfPoints="4" NumberOfCells="1">
<Points>
<DataArray type="Float32" NumberOfComponents="3" format="ascii">
0 0 0
1 0 0
1 1 0
0 1 0
</DataArray>
</Points>
<Cells>
<DataArray type="Int64" Name="offsets" format="ascii">
4
</DataArray>
<DataArray type="Int64" Name="connectivity" format="ascii">
0 1 2 3
</DataArray>
<DataArray type="UInt8" Name="types" format="ascii">
9
</DataArray>
</Cells>
<PointData">
<DataArray type="Float32" Name="point_scalars" format="ascii">
1
2
3
4
</DataArray>
</PointData>
<CellData">
<DataArray type="Float32" Name="cell_scalars" format="ascii">
5
</DataArray>
</CellData>
</Piece>
</UnstructuredGrid>
</VTKFile>

vector.vtu

<VTKFile type="UnstructuredGrid" version="1.0">
<UnstructuredGrid>
<Piece NumberOfPoints="4" NumberOfCells="1">
<Points>
<DataArray type="Float32" NumberOfComponents="3" format="ascii">
0 0 0
1 0 0
1 1 0
0 1 0
</DataArray>
</Points>
<Cells>
<DataArray type="Int64" Name="offsets" format="ascii">
4
</DataArray>
<DataArray type="Int64" Name="connectivity" format="ascii">
0 1 2 3
</DataArray>
<DataArray type="UInt8" Name="types" format="ascii">
9
</DataArray>
</Cells>
<PointData>
<DataArray type="Float32" Name="point_vectors" NumberOfComponents="3" format="ascii">
1 1 0
-1 1 0
-1 -1 0
1 -1 0
</DataArray>
</PointData>
<CellData>
<DataArray type="Float32" Name="cell_vectors" NumberOfComponents="3" format="ascii">
1 1 0
</DataArray>
</CellData>
</Piece>
</UnstructuredGrid>
</VTKFile>

並列版

XML フォーマットには並列版というものがあります。UnstructuredGrid の並列版の拡張子は .pvtu で、次のように書きます。

multi.pvtu

<VTKFile type="PUnstructuredGrid" version="1.0">
<PUnstructuredGrid>
<PPoints>
<DataArray type="Float32" NumberOfComponents="3" format="ascii"/>
</PPoints>
<Piece Source="file_0.vtu"/>
<Piece Source="file_1.vtu"/>
<PCellData>
<DataArray type="Float32" Name="cell_scalars" NumberOfComponents="3" format="ascii"/>
</PCellData>
</PUnstructuredGrid>
</VTKFile>

Piece 要素の Source で別の .vtu ファイルを指定しています。セル値が必要な場合は、PCellData 要素と PDataArray で必要なものを指定しておきます。

マルチブロック

複数のデータを組み合わせたマルチブロックというデータセット (vtkMultiBlockDataSet、拡張子 .vtm) もあります。

multi.vtm

<VTKFile type="vtkMultiBlockDataSet" version="1.0">
<vtkMultiBlockDataSet>
<DataSet index="0" name="file_0" file="file_0.vtu"/>
<DataSet index="1" name="file_1" file="file_1.vtu"/>
<Block index="2" name="block">
<DataSet index="0" name="file_2" file="file_2.vti"/>
<DataSet index="1" name="file_3" file="file_3.vti"/>
</Block>
</vtkMultiBlockDataSet>
</VTKFile>

外部のファイルを指定しているところは並列版に似ていますが、別のタイプのデータを混在させたり、Block で階層構造を作ったりできます。

時系列データの時刻の指定

ParaView 5.6.0 以降

以下のような JSON 形式でファイルと時刻の対応を記述する。

files.vti.series

{
    "file-series-version" : "1.0",
    "files" : [
        { "name" : "file_0.vti", "time" : 0 },
        { "name" : "file_1.vti", "time" : 0.5 },
        { "name" : "file_2.vti", "time" : 1 }
    ]
}

ファイルの名前は、vti のセットなら "*.vti.series"、vtu のセットなら "*.vtu.series" といったようにする。このファイルを ParaView で直接開けばよい。