Provided by: h5utils_1.13.1-3build1_amd64 bug

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.