Man Linux: Main Page and Category List


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


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


       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.


       -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

              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

       -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

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


       Send bug reports to S. G. Johnson,


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