h5topng.1.in

.\" Copyright (c) 2004 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 H5TOPNG 1 "March 9, 2002" "h5utils" "h5utils"
.SH NAME
h5topng \- generate PNG images from 2d slices of HDF5 files
.SH SYNOPSIS
.B h5topng
[\fIOPTION\fR]... [\fIHDF5FILE\fR]...
.SH DESCRIPTION
.PP
.\" Add any additional description here
h5topng is a utility to generate images in PNG (Portable Network Graphics)
format from two-dimensional slices of datasets in HDF5 files.  It is
designed for quick-and-dirty visualization of scientific data, and for
batch processing thereof via shell scripts.

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

For a three- or four-dimensional dataset you must specify coordinates
in one or two slice dimensions, respectively, to get a two-dimensional
slice, via the
.B -xyzt
options.  Yet more options control things like the colormap and
magnification.  Still, the most basic usage is something like
\(aqh5topng foo.h5\(aq, which will output a file foo.png containing an
image from the two-dimensional 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 h5topng.
.TP
.B -v
Verbose output.  This output includes the minimum and maximum values
encountered in the data, which is useful to know for the
.B -mM
options.
.TP
\fB\-o\fR \fIfile\fR
Send PNG output to
.I file
rather than to the filename with .h5 replaced with .png (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 h5topng
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.

Instead of specifying a single index as an argument to these options,
you can also specify a range of indices in a Matlab-like notation:
\fIstart\fR:\fIstep\fR:\fIend\fR or \fIstart\fR:\fIend\fR
(\fIstep\fR defaults to 1).  This loops over that slice index, from
\fIstart\fR to \fIend\fR in steps of \fIstep\fR, producing a
sequence of output PNG files (with the slice index appended to the
filename, before the ".png").
.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\-X\fR \fIscalex\fR, \fB\-Y\fR \fIscaley\fR, \fB\-S\fR \fIscale\fR
Scale the x and y dimensions of the image by
.I scalex
and
.I scaley
respectively.  The
.B -S
option scales both x and y.  The default is to use scale factors of 1.0;
i.e. the image has the same dimensions (in pixels) as the data.  Linear
interpolation is used to fill in the pixels when the scale factors are
not 1.0.
.TP
\fB\-s\fR \fIskewangle\fR
Skew the image by
.I skewangle
(in degrees) to the left or right.  The result is a parallelogram, with
the leftover space in the (square) image filled with either black or white
pixels, depending upon the color map.
.TP
.B -T
Transpose the data (interchange the image axes).  By default,
the first (x) coordinate of the data corresponds to the columns,
and the second (y) coordinate corresponds to the rows; transposition
reverses this convention.
.TP
.B -c \fIcolormap\fR
Use a color map 
.I colormap
rather than the default
.B gray
color map (a grayscale ramp from white to black).
.I colormap
is normally the name of one of the color maps provided with 
.I h5topng
(in the @datadir_val@/h5utils/colormaps directory), or can instead be
the name of a color-map file.

Three useful included color maps are
.B hot
(black-red-yellow-white, useful for intensity data),
.B bluered
(blue-white-red, useful for signed data), and
.B hsv
(a multi-color "rainbow").  If you use the
.B bluered
color map for signed data, you may also want to use the
.B -Z
option so that the center of the color scale (white) corresponds to
zero.

A color-map file is a sequence of whitespace-separated R G B A
quadruples, where each value is in the range 0.0 to 1.0 and indicates
the fraction of red/green/blue/alpha.  (An alpha of 0 is transparent
and of 1 is opaque; this is only used for the \fB\-a\fR option,
below.)  The colors in the color map are linearly interpolated as
necessary to provide a continuous color ramp.
.TP
.B -r
Reverse the ordering of the color map.  You can also accomplish this
by putting a "-" before the colormap name in the 
.B -c
or
.B -a
option.
.TP
.B -Z
Center the color scale on the value zero in the data.
.TP
\fB\-m\fR \fImin\fR, \fB\-M\fR \fImax\fR
Normally, the bottom and top of the color map correspond to the
minimum and maximum values in the data.  Using these options, you
can make the bottom and top of the color map correspond to
.I min
and
.I max
instead.  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
and
.B -R
options.
.TP
.B -R
When multiple files are specified, set the bottom and top of the color
maps according to the minimum and maximum over all the data.  This is
useful to process many files using a consistent color scale, since
otherwise the scale is set for each file individually.
.TP
\fB\-C\fR \fIfile\fR, \fB\-b\fR \fIval\fR
Superimpose contour outlines from the first dataset in the
.I file
HDF5 file on all of the output images.  (If the contour dataset does
not have the same dimensions as the output data, it is peridically
"tiled" over the output.)  You can use the syntax
.I file:dataset
to specify a particular dataset within the file.  The contour outlines
are around a value of
.I val
(defaults to middle of value range in \fIfile\fR).
.TP
\fB\-A\fR \fIfile\fR, \fB\-a\fR \fIcolormap\fR:\fIopacity\fR
Translucently overlay the data from the first dataset in the
.I file
HDF5 file, which should have the same dimensions as the input
dataset, on all of the output images, using the colormap
.I colormap
with opacity (from 0 for completely transparent to 1 for completely opaque)
.I opacity
multiplied by the opacity (alpha) values in the colormap.  (If the
overlay dataset does not have the same dimensions as the output data,
it is peridically "tiled" over the output.)  You can use the syntax
.I file:dataset
to specify a particular dataset within the file.

Some predefined colormaps that work particularly well for this feature
are 
.B yellow
(transparent white to opaque yellow) 
.B gray
(transparent white to opaque black),
.B yarg
(transparent black to opaque white), 
.B green
(transparent white to opaque green), and
.B bluered
(opaque blue to transparent white to opaque red).  You can prepend "-"
to the colormap name to reverse the colormap order.  (See also
\fB\-c\fR, above.)  The default for \fB\-a\fR is yellow:0.3 (yellow
colormap multiplied by 30% opacity).
.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.
.TP
.B -8
Use 8-bit (indexed) color for the PNG output, instead of 24-bit (direct)
color (the default).  (This shrinks the image size slightly, with some
degradation in quality.)  Not supported in conjunction with the \fB\-A\fR
(translucent overlay) option.
.SH BUGS
Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.
.SH AUTHORS
Written by Steven G. Johnson.  Copyright (c) 2004 by the Massachusetts
Institute of Technology.