.\" Copyright (c) 2002 Massachusetts Institute of Technology
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\" 
.\" The above copyright notice and this permission notice shall be
.\" included in all copies or substantial portions of the Software.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.TH H5TOVTK 1 "March 9, 2002" "h5utils" "h5utils"
.SH NAME
h5tovtk \- convert datasets in HDF5 files to VTK format
.SH SYNOPSIS
.B h5tovtk
[\fIOPTION\fR]... [\fIHDF5FILE\fR]...
.SH DESCRIPTION
.PP
.\" Add any additional description here
h5tovtk is a program to generate VTK data files from multidimensional
datasets in HDF5 files.  VTK, the Visualization ToolKit, is an
open-source, freely available software system for 3D computer
graphics, image processing, and visualization.  VTK itself is a
programming library, but it is also the basis for a number of end-user
graphical visualization programs.

HDF5 is a free, portable binary format and supporting library developed
by the National Center for Supercomputing Applications at the University
of Illinois in Urbana-Champaign.  A single
.I h5
file can contain multiple datasets; by default,
.I h5tovtk
takes the first dataset, but this can be changed via the
.B -d
option, or by using the syntax \fIHDF5FILE:DATASET\fR.

1d/2d/3d datasets are converted into 3d VTK \"structured points\"
datasets.  Normally, a single scalar VTK dataset is output, but
vectors and fields can be output via the
.B -o
option below.

A typical invocation is of the form
\'h5tovtk foo.h5\', which will output a VTK data file foo.vtk
from the data in foo.h5.
.SH OPTIONS
.TP
.B -h
Display help on the command-line options and usage.
.TP
.B -V
Print the version number and copyright info for h5tovtk.
.TP
.B -v
Verbose output.
.TP
\fB\-o\fR \fIfile\fR
Save all the input datasets to a single VTK \fIfile\fR.  If there is
only one dataset, it is output to a VTK scalar dataset; if there are
three datasets, they are output as a VTK vector dataset; all other
numbers of datasets are combined into a VTK field dataset.

Otherwise, the default behavior is to save each dataset to a separate
VTK file, with the .h5 suffix of the input filename replaced by .vtk
in the output filename.

Only three-dimensional datasets may be written to the VTK file.  If
you have a four (or more) dimensional data set, then you must take a
three-dimensional "slice" of the multi-dimensional data.  To do this,
you specify coordinates in one (or more) slice dimension(s), via the
.B -xyzt
options.
.TP
\fB\-1\fR, \fB\-2\fR, \fB\-4\fR
Use 1 , 2, or 4 bytes to store each data point in the
output file.  Fewer bytes require less storage and memory,
but will decrease the resolution in the values.
.B -1
will break up the data values into one of 256 possible values (on a
linear scale from the minimum to the maximum value in your data),
.B -2
will allow 65536 possible values, and
.B -4
(the default) will use 4-byte floating-point numbers for an "exact"
representation.
.TP
.B -a
Output in ASCII format; otherwise, VTK's more compact, but less
readable and somewhat less portable binary format is used.
.TP
.B -n
For binary output (see
.B -a
above), by default the data is written in bigendian byte order, which
is normally the order that VTK expects.  However, some external tools
and a few VTK classes use the native byte ordering instead (which may
not be bigendian), and the
.B -n
option causes
.I h5tovtk
to output binary data in the native ordering.
.TP
\fB\-m\fR \fImin\fR, \fB\-M\fR \fImax\fR
When
.B -1
or
.B -2
are used, the input data are converted to a linear integer scale.
Normally, the bottom and top of this scale correspond to the
minimum and maximum values in the data.  Using the
.B -m
and
.B -M
options, you
can make the bottom and top of the scale correspond to
.I min
and
.I max
instead, respectively.  Data values below or above this range will be
treated as if they were
.I min
or
.I max
respectively.  See also the
.B -Z
option.
.TP
.B -Z
For
.B -1
or
.B -2
output, center the linear integer scale on the value zero in the data.
.TP
.B -r
Invert the output values (map the minimum to the maximum and vice versa).
.TP
\fB\-x\fR \fIix\fR, \fB\-y\fR \fIiy\fR, \fB\-z\fR \fIiz\fR, \fB\-t\fR \fIit\fR
This tells
.I h5tovtk
to use a particular slice of a multi-dimensional dataset.  e.g.
.B -x
uses the subset (with one less dimension) at an x index of
.I ix
(where the indices run from zero to one less than the maximum index in
that direction).  Here, x/y/z correspond to the first/second/third
dimensions of the HDF5 dataset. The \fB\-t\fR option specifies a slice
in the last dimension, whichever that might be.  See also the
.B -0
option to shift the origin of the x/y/z slice coordinates to the
dataset center.
.TP
.B -0
Shift the origin of the x/y/z slice coordinates to the dataset center,
so that e.g. -0 -x 0 (or more compactly -0x0) returns the central x
plane of the dataset instead of the edge x plane.  (\fB\-t\fR
coordinates are not affected.)
.TP
\fB\-d\fR \fIname\fR
Use dataset
.I name
from the input files; otherwise, the first dataset from each file is used.
Alternatively, use the syntax \fIHDF5FILE:DATASET\fR, which allows you
to specify a different dataset for each file.
You can use the
.I h5ls
command (included with hdf5) to find the names of datasets within a file.
.SH BUGS
Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.
.SH AUTHORS
Written by Steven G. Johnson.  Copyright (c) 2005 by the Massachusetts
Institute of Technology.