.\" Copyright (c) 1999-2009 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 H5TOTXT 1 "March 9, 2002" "h5utils" "h5utils"
.SH NAME
h5totxt \- generate comma-delimited text from 2d slices of HDF5 files
.SH SYNOPSIS
.B h5totxt
[\fIOPTION\fR]... [\fIHDF5FILE\fR]...
.SH DESCRIPTION
.PP
.\" Add any additional description here
h5totxt is a utility to generate comma-delimited text (and similar
formats) from one-, two-, or more-dimensional slices of numeric
datasets in HDF5 files.  This way, the data can easily be imported
into spreadsheets and similar programs for analysis and visualization.

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 h5totxt
takes the first dataset, but this can be changed via the
.B -d
option, or by using the syntax \fIHDF5FILE:DATASET\fR.

By default, the entire dataset is dumped to the output.  in row-major
order.  For 3d datasets, this corresponds to a sequence of yz slices,
in order of increasing x, separated by blank lines.  If
.B -T
is specified, outputs in the transposed (column-major) order instead

Often, however, you want only a one- or two-dimensional slice of
multi-dimensional data.  To do this, you specify coordinates in one or
more slice dimensions, via the
.B -xyzt
options.

The most basic usage is something like \(aqh5totxt foo.h5\(aq, which will
output comma-delimited text to stdout 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 h5totxt.
.TP
.B -v
Verbose output.
.TP
\fB\-o\fR \fIfile\fR
Send text output to
.I file
rather than to stdout (the default).
.TP
\fB\-s\fR \fIsep\fR
Use the string
.I sep
to separate columns of the output rather than a comma (the default).
.TP
\fB\-x\fR \fIix\fR, \fB\-y\fR \fIiy\fR, \fB\-z\fR \fIiz\fR, \fB\-t\fR \fIit\fR
This tells
.I h5totxt
to use a particular slice of a multi-dimensional dataset.  e.g.
.B -x
causes a yz plane (of a 3d dataset) to be used, 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
.B -T
Transpose the data (interchange the dimension ordering).  By default, no
transposition is done.
.TP
\fB\-.\fR \fInumdigits\fR
Output
.I numdigits
digits after the decimal point (defaults to 16).
.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.