home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / source / thesource6.dms / thesource6.adf / Source / Compression / hcompress.lha / hcompress / doc / hcompress.man < prev    next >
Encoding:
Text File  |  1992-04-22  |  17.8 KB  |  529 lines
  1.  
  2.  
  3.  
  4. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      hcompress, hdecompress, fcompress,  fdecompress  -  compress
  10.      and decompress images
  11.  
  12. SYNOPSIS
  13.      hcomp -v -i raw|net|fits|hhh -s scale  -r  rows  -c  columns
  14.           [ datafile [ headerfile ] ]
  15.  
  16.      hdecomp -v -s -o raw|net|fits|hhh
  17.  
  18.      hcompress -s scale -k -r files...  [ options ] files...
  19.  
  20.      fcompress -s scale -k -r files...  [ options ] files...
  21.  
  22.      hdecompress  -s  -u  -k  -r  -o  raw|net|fits|hhh   files...
  23.           [ options ] files...
  24.  
  25.      fdecompress  -s  -u  -k  -r  -o  raw|net|fits|hhh   files...
  26.           [ options ] files...
  27.  
  28. DESCRIPTION
  29.      hcompress  is  an  image  compression  package  written   to
  30.      compress the Space Telescope Science Institute (STScI) Digi-
  31.      tized Sky Survey images.  It is well-suited to the  compres-
  32.      sion of astronomical images, which generally consist of flat
  33.      sky sprinkled with point sources (stars) and the  occasional
  34.      extended source (galaxies and nebulae).  Briefly, the method
  35.      used is:
  36.  
  37.      (1)  a wavelet transform  called  the  H-transform  (a  Haar
  38.           transform generalized to two dimensions), followed by
  39.  
  40.      (2)  quantization that discards noise  in  the  image  while
  41.           retaining the signal on all scales, followed by
  42.  
  43.      (3)  quadtree coding of the quantized coefficients.
  44.  
  45.      The technique gives very good compression  for  astronomical
  46.      images  and  is fast, requiring about 4 seconds for compres-
  47.      sion or decompression of a 512x512 image on a Sun  SPARCsta-
  48.      tion  1.   The  calculations  are  carried out using integer
  49.      arithmetic and are entirely reversible.   Consequently,  the
  50.      program  can  be  used for either lossy or lossless compres-
  51.      sion, with no special approach needed for the lossless  case
  52.      (e.g. there is no need for a file of residuals.)
  53.  
  54.      These programs can compress 2-byte integer images in a small
  55.      variety  of  input  formats.  The resulting compressed image
  56.      file is machine-independent and may be  transferred  between
  57.      computers with binary FTP.
  58.  
  59.      The executable programs hcomp  and  hdecomp  are  the  basic
  60.  
  61.  
  62.  
  63. Sun Release 4.1    Last change: 20 April 1992                   1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  71.  
  72.  
  73.  
  74.      tools  for  compression  and decompression of images.  Users
  75.      with images in FITS format will generally find it easier  to
  76.      use  the fcompress and fdecompress scripts, while users with
  77.      images in the IRAF and  STSDAS  hhh/hhd  file  formats  will
  78.      prefer  the hcompress and hdecompress scripts.  (FITS is the
  79.      Flexible Image Transport  System,  which  is  the  universal
  80.      standard  for  astronomical  data.   IRAF  is  a widely used
  81.      astronomical data analysis system; STSDAS is  a  package  of
  82.      IRAF  tasks designed for Hubble Space Telescope data.) Those
  83.      who  wish  to  use  this  compression  software   for   non-
  84.      astronomical  images will probably find these scripts inade-
  85.      quate and are encouraged to create their own  scripts  using
  86.      these  as  a  model.  It also would be rather easy to modify
  87.      the source code so that 8-bit images can be used as input.
  88.  
  89.      In Unix these programs and scripts can be installed in  some
  90.      directory found in your path using the make install command.
  91.      In VMS it is necessary to define  symbols  pointing  to  the
  92.      directory  and the programs by executing the @hcompinit com-
  93.      mand file.
  94.  
  95.      To compress a 2-byte integer image in FITS format,
  96.  
  97.           fcompress -s scale image.fits
  98.  
  99.      produces an output file named image.fits.H (or  image.fits_H
  100.      in   VMS)   with  the  compressed  image.   The  input  file
  101.      image.fits is not removed unless the -r option is specified.
  102.      To decompress this image,
  103.  
  104.           fdecompress image.fits.H
  105.  
  106.      will create a FITS file called image.fits.
  107.  
  108.      The -s scale option determines the  amount  of  compression.
  109.      Scale  =  0  or  1  leads  to lossless compression, i.e. the
  110.      decompressed image has exactly the same pixel values as  the
  111.      original image.  If scale > 1 then the compression is lossy:
  112.      the decompressed image will not be exactly the same  as  the
  113.      original.   For astronomical images, lossless compression is
  114.      generally rather ineffective because the images have a  good
  115.      deal of noise, which is inherently incompressible.  However,
  116.      if some of this noise is discarded then the images  compress
  117.      very  well.   The  scale  factor  determines how much of the
  118.      noise is discarded.  We have found that setting scale  to  2
  119.      times  sigma, the RMS noise in the image, usually results in
  120.      compression by about a factor of  10  (i.e.  the  compressed
  121.      image  requires  about  1.5  bits/pixel),  while producing a
  122.      decompressed image that is nearly indistinguishable from the
  123.      original.    In   fact,   the  RMS  difference  between  the
  124.      decompressed image and the original image will be only about
  125.      1/2 sigma.  Our experiments indicate that this level of loss
  126.  
  127.  
  128.  
  129. Sun Release 4.1    Last change: 20 April 1992                   2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  137.  
  138.  
  139.  
  140.      has no noticeable effect on either the visual appearance  of
  141.      the  image  or  on  quantitative analysis of the image (e.g.
  142.      measurements of positions and brightnesses of stars are  not
  143.      adversely affected.)
  144.  
  145.      Using a larger value for scale results in higher compression
  146.      at the cost of larger differences between the compressed and
  147.      original images.  A rough rule of thumb  is  that  if  scale
  148.      equals  N  sigma,  then the image will compress to about 3/N
  149.      bits/pixel, and the RMS difference between the original  and
  150.      the  compressed  image  will be about N/4 sigma.  This crude
  151.      relationship is inaccurate both for  very  high  compression
  152.      ratios  and  for  lossless compression, but it does at least
  153.      give an indication of  what  to  expect  of  the  compressed
  154.      images.
  155.  
  156.      For images in which the noise varies  from  pixel  to  pixel
  157.      (e.g.  CCD  images,  where  the noise is larger for brighter
  158.      pixels), the appropriate value for scale  is  determined  by
  159.      the  RMS  noise  level in the sky regions of the image.  For
  160.      images that are essentially noiseless, any lossy compression
  161.      is  noticeable  under  sufficiently  close inspection of the
  162.      image, but some loss is nonetheless acceptable  for  typical
  163.      applications.   Note  that  the  quantization scheme used in
  164.      hcompress is not designed to give images that appear as much
  165.      like  the  original as possible to the human eye, but rather
  166.      is designed to produce images that are as similar as  possi-
  167.      ble  to the original under quantitative analysis.  Thus, our
  168.      emphasis is on discarding noise without affecting the signal
  169.      rather  than  on discarding components of the image that are
  170.      not very noticeable to the eye (as may be done, for example,
  171.      by  JPEG  compression.)  The resulting compression scheme is
  172.      not ideal for typical terrestrial images (though it is still
  173.      a  reasonably  good method for those images), but we believe
  174.      it is close to optimal for astronomical images.
  175.  
  176.  
  177. OPTIONS
  178.      hcomp -v -i raw|net|fits|hhh -s scale  -r  rows  -c  columns
  179.           [ datafile [ headerfile ] ]
  180.  
  181.      hcomp reads an  image  from  the  standard  input  (or  from
  182.      datafile   and   headerfile   if  specified)  and  writes  a
  183.      compressed image to the standard output.
  184.  
  185.           -v   Verbose. A description of the input file  and  the
  186.                compression  achieved  is  written to the standard
  187.                error output.
  188.  
  189.           -i raw|net|fits|hhh
  190.                Input format. Choices are:
  191.  
  192.  
  193.  
  194.  
  195. Sun Release 4.1    Last change: 20 April 1992                   3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  203.  
  204.  
  205.  
  206.                raw  Pixel  values  have  2  bytes   in   machine-
  207.                     dependent  order,  i.e.  no  byte swapping is
  208.                     done on input.  This is the default format if
  209.                     none is specified.
  210.  
  211.                net  Pixel values have 2 bytes in "network" order:
  212.                     high  byte  first,  then  low  byte  for each
  213.                     pixel.  Byte-swapping is  done  on  input  if
  214.                     needed.   Note  that  this is the same as raw
  215.                     format on some machines (e.g.  Suns)  but  is
  216.                     different  on  others (e.g. VAXes).  Files in
  217.                     net  format  can  be  transferred  from   one
  218.                     machine  to another without modification, but
  219.                     files in raw format cannot.
  220.  
  221.                fits FITS (Flexible Image Transport System) format
  222.                     image.   Header  gives image size.  Bytes are
  223.                     in network order.  FITS format is the univer-
  224.                     sal  standard  for  transport of astronomical
  225.                     images.
  226.  
  227.                hhh  FITS-type header (but without  padding  lines
  228.                     making  header  multiple  of 2880 bytes) in a
  229.                     file  named  rootname.xxh,  with  the   pixel
  230.                     values  (bytes in machine-dependent order) in
  231.                     a  different  file  named  rootname.xxd.   No
  232.                     byte-swapping is done on input.
  233.  
  234.           -s scale
  235.                Scale factor.  Non-negative  integer  that  deter-
  236.                mines the amount of compression.  Default is scale
  237.                = 1024, which could be  wildly  inappropriate  for
  238.                your  images.  Use scale = 0 for lossless compres-
  239.                sion.  See the discussion above for more  informa-
  240.                tion.
  241.  
  242.           -r   Pixels/row.  This is the quickly varying dimension
  243.                in  the file, i.e. the order of pixels in the file
  244.                is all pixels from  first  row,  all  pixels  from
  245.                second  row, etc.  Note that the size of the image
  246.                can be specified this way only  for  raw  and  net
  247.                format  images; fits and hhh format images include
  248.                a header giving the size of  the  image.   Default
  249.                value is 256.
  250.  
  251.           -c   Pixels/column.  This is the slowly varying  dimen-
  252.                sion in the file.  Default value is 256.
  253.  
  254.           datafile
  255.                Input data file.  If not specified  the  input  is
  256.                read from stdin.
  257.  
  258.  
  259.  
  260.  
  261. Sun Release 4.1    Last change: 20 April 1992                   4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  269.  
  270.  
  271.  
  272.           headerfile
  273.                Input header file.  This  is  only  specified  for
  274.                format  hhh,  in  which the header and data are in
  275.                separate files.  It is also possible to  concaten-
  276.                ate  the  header and data files into stdin for hhh
  277.                format images.
  278.  
  279.      hdecomp -v -s -o raw|net|fits|hhh
  280.  
  281.      hdecomp reads a compressed image from the standard input and
  282.      writes a decompressed image to the standard output.
  283.  
  284.           -v   Verbose. A description of the output file is writ-
  285.                ten to the standard error output.
  286.  
  287.           -s   Smoothing  flag.    At   high   compressions   the
  288.                decompressed image begins to appear blocky because
  289.                of the way information is discarded.  This blocki-
  290.                ness  is  greatly reduced, producing more pleasing
  291.                images,  if  the  -s  flag  is  specified   during
  292.                decompression.  Default is no smoothing.
  293.  
  294.           -o raw|net|fits|hhh
  295.                Output format.  Default is fits  for  input  files
  296.                that  were  in  FITS  format  and is raw for other
  297.                input file formats.  Note that this means that  an
  298.                image that was originally in net format is not, by
  299.                default, decompressed to the same  format.   Other
  300.                input  formats  are  properly  decompressed to the
  301.                same format on output.
  302.  
  303.      hcompress -s scale -k -r files...  [ options ] files...
  304.  
  305.      hcompress compresses one or more images in hhh input format.
  306.  
  307.           -s scale
  308.                Scale factor.  Default in  script  is  666.   Note
  309.                that  this is different than the default in hcomp.
  310.                You can modify the  script  to  insert  a  typical
  311.                value for your images as the default.
  312.  
  313.           -k   Keep original files after compression (default).
  314.  
  315.           -r   Remove original files after compression.  Only the
  316.                data  file  (hhd)  is  removed, the header file is
  317.                retained in any case.
  318.  
  319.           files...
  320.                One or more hhh/hhd  format  images  to  compress.
  321.                Wild  cards  may  be  used.  The names of the data
  322.                files (not the header files) should be  specified.
  323.                Note  that  one  can  mix  options and file names;
  324.  
  325.  
  326.  
  327. Sun Release 4.1    Last change: 20 April 1992                   5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  335.  
  336.  
  337.  
  338.                options apply only to files that  follow  them  on
  339.                the command line.  For example, the removal of the
  340.                original images may be turned on and off using the
  341.                -r  and -k flags.  If infile.xxd is the name of an
  342.                original image data file, the resulting compressed
  343.                image   is   in  a  file  named  infile.xxd.H  (or
  344.                infile.xxd_H in VMS.)
  345.  
  346.      fcompress -s scale -k -r files...  [ options ] files...
  347.  
  348.      fcompress compresses one or more images in fits  input  for-
  349.      mat.
  350.  
  351.           -s scale
  352.                Scale  factor.   As  for  hcompress,  the   script
  353.                default value is 666.
  354.  
  355.           -k   Keep original files after compression (default).
  356.  
  357.           -r   Remove original files after compression.
  358.  
  359.           files...
  360.                One or more FITS format images  to  compress.   If
  361.                infile is the name of an input FITS file, then the
  362.                resulting compressed image  is  in  a  file  named
  363.                infile.H (or infile_H in VMS.)
  364.  
  365.      hdecompress  -u  -s  -k  -r  -o  raw|net|fits|hhh   files...
  366.           [ options ] files...
  367.  
  368.      fdecompress  -u  -s  -k  -r  -o  raw|net|fits|hhh   files...
  369.           [ options ] files...
  370.  
  371.      These programs  decompress  one  or  more  compressed  image
  372.      files.   hdecompress  and  fdecompress are actually the same
  373.      program; the two  different  names  are  provided  for  con-
  374.      sistency  with  the  two compression programs, hcompress and
  375.      fcompress.
  376.  
  377.           -u   Disable smoothing (default).
  378.  
  379.           -s   Enable smoothing.
  380.  
  381.           -k   Keep compressed  image  file  after  decompression
  382.                (default).
  383.  
  384.           -r   Remove compressed image file after decompression.
  385.  
  386.           -o raw|net|fits|hhh
  387.                Output format.  Default is fits for  files  origi-
  388.                nally  in  FITS  format,  and raw for other files.
  389.                Note that raw format output  is  correct  for  hhh
  390.  
  391.  
  392.  
  393. Sun Release 4.1    Last change: 20 April 1992                   6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  401.  
  402.  
  403.  
  404.                format data files.
  405.  
  406.           files...
  407.                Names of files to decompress.  The .H extension is
  408.                added  to  the  end  of  the filename if it is not
  409.                explicitly specified.  (In VMS the filenames  must
  410.                already have _H on the end of the file extension.)
  411.                For an input  compressed  image  in  infile.H  (or
  412.                infile_H  in VMS) the output decompressed image is
  413.                in infile.
  414.  
  415. BUGS
  416.      Current input formats include  only  16  bit,  2-dimensional
  417.      images,  though the extension to other formats and to higher
  418.      dimensions would be straightforward.
  419.  
  420.      FITS extensions such as multiple groups and group parameters
  421.      are not accepted.
  422.  
  423.      FITS header lines are not compressed when they are  included
  424.      in the compressed image file.  This can significantly affect
  425.      the  compression  achieved  for  small  images  with   large
  426.      headers.   It does have the advantage that the header can be
  427.      easily examined to determined the contents of the file.
  428.  
  429.      If a highly inappropriate value is specified for  the  scale
  430.      factor, the image is vastly overcompressed and much informa-
  431.      tion is lost.  The compression program ought to estimate the
  432.      range  of  plausible scale factors from the image statistics
  433.      and issue a warning of  the  user-supplied  value  does  not
  434.      appear reasonable.  It would also be useful to have the pro-
  435.      gram make a good guess for the scale factor  if  it  is  not
  436.      specified.
  437.  
  438.      If the wrong size is given (using the -r and -c  parameters)
  439.      for  a  raw or net format image, the compression program may
  440.      fail to read the entire image.  No error message  is  issued
  441.      if the image is actually bigger than the specified size.
  442.  
  443.      On VAXes running VMS, the decompressed image  file  may  not
  444.      have the same record format as the original image.  This can
  445.      cause problems if the software reading the image requires it
  446.      to have special characteristics (e.g. fixed record lengths.)
  447.      The modify program, included with the VMS command files, can
  448.      be  used to change the decompressed image files so that they
  449.      have fixed record lengths, but it uses  an  unsupported  VMS
  450.      system  routine,  SYS$MODIFY, to make the modification so it
  451.      is at best a makeshift solution.
  452.  
  453. AUTHOR
  454.      Richard L. White, Space Telescope Science Institute
  455.  
  456.  
  457.  
  458.  
  459. Sun Release 4.1    Last change: 20 April 1992                   7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. HCOMPRESS(1)             USER COMMANDS               HCOMPRESS(1)
  467.  
  468.  
  469.  
  470.      Problems, suggestions, gripes, and praise to rlw@stsci.edu
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525. Sun Release 4.1    Last change: 20 April 1992                   8
  526.  
  527.  
  528.  
  529.