Provided by: h5utils_1.12.1-2_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.