     H5TOPNG(1)                        h5utils                        H5TOPNG(1)
     h5utils                                                             h5utils

                                    March 9, 2002

     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-dimensional data set, the xy slice at z index zero is
          extracted by default, but other slices can be extracted using the -xyz
          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
          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
               This tells h5topng to use a particular slice of a two- or three-
               dimensional dataset.  e.g.  -x causes a yz plane 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).  The default behaviour is
               equivalent to -z 0.  See also the -0 option to shift the origin
               of the slice coordinates to the dataset center.

          -0   Shift the origin of the slice coordinates to the dataset center,
               so that e.g. -0 -x 0 (or more compactly -0x0) returns the central

                                        - 1 -         Formatted:  March 20, 2002

     H5TOPNG(1)                        h5utils                        H5TOPNG(1)
     h5utils                                                             h5utils

                                    March 9, 2002

               x plane of the dataset instead of the edge x plane.

          -X scalex, -Y scaley, -S scale
               Scale the x and y dimensions 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, no
               transposition is done.

          -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
               /opt/h5utils/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.)  The colors in the color map
               are linearly interpolated as necessary to provide an 8-bit color
               palette.

          -r   Reverse the ordering of the color map.

          -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

                                        - 2 -         Formatted:  March 20, 2002

     H5TOPNG(1)                        h5utils                        H5TOPNG(1)
     h5utils                                                             h5utils

                                    March 9, 2002

               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, which should have the same dimensions as the input
               dataset, on all of the output images.  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).

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

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

     AUTHORS
          Written by Steven G. Johnson.  Copyright (c) 1999, 2000, 2001, 2002 by
          the Massachusetts Institute of Technology.

                                        - 3 -         Formatted:  March 20, 2002