Ubuntu Manpage: h5topng - generate PNG images from 2d slices of HDF5 files

NAME

       h5topng - generate PNG images from 2d slices of HDF5 files

SYNOPSIS

       h5topng [OPTION]... [HDF5FILE]...

DESCRIPTION

       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  h5  file  can  contain  multiple data sets; by default, h5topng takes the first
       dataset,  but  this  can  be  changed  via  the  -d  option,  or  by  using   the   syntax
       HDF5FILE:DATASET.

       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 -xyzt options.  Yet more
       options  control  things like the colormap and magnification.  Still, the most basic usage
       is something like ´h5topng foo.h5´, which will output a file foo.png containing  an  image
       from the two-dimensional data in foo.h5.

OPTIONS

-h Display help on the command-line options and usage.

-V Print the version number and copyright info for h5topng.

-v Verbose output. This output includes the minimum and maximum values encountered in
the data, which is useful to know for the -mM options.

-o file
Send PNG output to file rather than to the filename with .h5 replaced with .png
(the default).

-x ix, -y iy, -z iz, -t it
This tells h5topng to use a particular slice of a multi-dimensional dataset. e.g.
-x causes a yz plane (of a 3d dataset) to be used, at an x index of 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 -t
option specifies a slice in the last dimension, whichever that might be. See also
the -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: start:step:end or start:end
(step defaults to 1). This loops over that slice index, from start to end in steps
of step, producing a sequence of output PNG files (with the slice index appended to
the filename, before the ".png").

-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. (-t coordinates are not affected.)

-X scalex, -Y scaley, -S scale
Scale the x and y dimensions of the image by scalex and scaley respectively. The
-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.

-s skewangle
Skew the image by 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.

-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.

-c colormap
Use a color map colormap rather than the default gray color map (a grayscale ramp
from white to black). colormap is normally the name of one of the color maps
provided with h5topng (in the /usr/share/h5utils/colormaps directory), or can
instead be the name of a color-map file.

Three useful included color maps are hot (black-red-yellow-white, useful for
intensity data), bluered (blue-white-red, useful for signed data), and hsv (a
multi-color "rainbow"). If you use the bluered color map for signed data, you may
also want to use the -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 -a option, below.) The colors in the color map are linearly
interpolated as necessary to provide a continuous color ramp.

-r Reverse the ordering of the color map. You can also accomplish this by putting a
"-" before the colormap name in the -c or -a option.

-Z Center the color scale on the value zero in the data.

-m min, -M max
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 min and max instead. Data values below or above this range
will be treated as if they were min or max respectively. See also the -Z and -R
options.

-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.

-C file, -b val
Superimpose contour outlines from the first dataset in the 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 file:dataset to specify a particular dataset within the file. The contour
outlines are around a value of val (defaults to middle of value range in file).

-A file, -a colormap:opacity
Translucently overlay the data from the first dataset in the file HDF5 file, which
should have the same dimensions as the input dataset, on all of the output images,
using the colormap colormap with opacity (from 0 for completely transparent to 1
for completely opaque) 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
file:dataset to specify a particular dataset within the file.

Some predefined colormaps that work particularly well for this feature are yellow
(transparent white to opaque yellow) gray (transparent white to opaque black), yarg
(transparent black to opaque white), green (transparent white to opaque green), and
bluered (opaque blue to transparent white to opaque red). You can prepend "-" to
the colormap name to reverse the colormap order. (See also -c, above.) The
default for -a is yellow:0.3 (yellow colormap multiplied by 30% opacity).

-d name
Use dataset name from the input files; otherwise, the first dataset from each file
is used. Alternatively, use the syntax HDF5FILE:DATASET, which allows you to
specify a different dataset for each file. You can use the h5ls command (included
with hdf5) to find the names of datasets within a file.

-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 -A (translucent overlay) option.

BUGS

       Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.

AUTHORS

       Written  by  Steven  G.  Johnson.   Copyright  (c)  2004 by the Massachusetts Institute of
       Technology.