.\" Copyright (c) 2005 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 H5TOV5D 1 "March 9, 2002" "h5utils" "h5utils"
.SH NAME
h5tov5d \- convert datasets in HDF5 files to Vis5d format
.SH SYNOPSIS
.B h5tov5d
[\fIOPTION\fR]... [\fIHDF5FILE\fR]...
.SH DESCRIPTION
.PP
." Add any additional description here
h5tov5d is a program to generate Vis5d data files from
multidimensional datasets in HDF5 files.  Vis5d is a free volumetric
visualization program capable of displaying 3, 4, or even 5
dimensional datasets (using time for the 4th dimension and different
variables for the 5th dimension).

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 data sets; by default,
.I h5tov5d
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 Vis5d datasets. 4d datasets
are converted into a time series of 3d datasets, with the first
dimension marking the time.  5d datasets are converted into several
variables of time series of 3d datasets, with the first dimension as
the variable index and the second dimension as the time.  Often,
however, you want only a three-dimensional "slice" of four (or more)
dimensional data.  To do this, you specify coordinates in one (or
more) slice dimension(s), via the
.B -xyzt
options.

A typical invocation is of the form
\'h5tov5d foo.h5\', which will output a Vis5d data file foo.v5d
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 h5tov5d.
.TP
.B -v
Verbose output.
.TP
.B -T
Transpose the output dimensions (reverse their order).
.TP
\fB\-o\fR \fIfile\fR
Save the datasets from all of the input files to a single Vis5d
.I file
with each dataset being expressed as a separate Vis5d variable.  In
this way, you can use Vis5d to superimpose and compare the plots from
the different datasets.  The first two dimensions (or three, for 4d
datasets) must be the same for all of the input datasets.

Otherwise, the default behavior is to save each dataset to a separate
Vis5d file, with the .h5 suffix of the input filename replaced by .v5d
in the output filename.
.TP
\fB\-1\fR, \fB\-2\fR, \fB\-4\fR
Use 1 (the default), 2, or 4 bytes to store each data point in the
output file.  Fewer bytes will cause Vis5d to be faster (as well as
requiring 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
will use 4-byte floating-point numbers for an "exact" representation.
In most circumstances,
.B -1
is more than adequate for data visualization purposes.
.TP
\fB\-x\fR \fIix\fR, \fB\-y\fR \fIiy\fR, \fB\-z\fR \fIiz\fR, \fB\-t\fR \fIit\fR
This tells
.I h5tov5d
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.