png-scivis-19970127
Mon Jan 27 17:08:27 EST 1997




PNG-GROUP-DRAFT                                    PNG Development Group
PNG-Sci-Vis                                   png-list@dworkin.wustl.edu
                                                             27 Jan 1997


         PNG Scientific Visualization Chunks, Version 19970127

File: draft-png-scivis-19970127.txt

Status of this Memo

      **************************************************************
            DRAFT. This is document is written as though already
      approved, and is posted only for the edification of people who
      are voting on the pcal-19961230 proposal.  Do not use this
      document for implementation purposes.  It will be superseded
      tomorrow one way or the other.  EXPIRES  28 Jan 1997.
      **************************************************************

   This document is a specification by the PNG development group.

   Comments on this document can be sent to the PNG specification
   maintainers at

      png-info@uunet.uu.net

   or at

      png-list@dworkin.wustl.edu.

   Distribution of this memo is unlimited.

   At present, the latest version of this document is available on the
   World Wide Web from

      ftp://swrinde.nde.swri.edu/pub/png/documents/.















PNG Development Group        Informational                      [Page 1]

PNG-GROUP             PNG Sci-Vis Chunks 19970127            27 Jan 1997


Notices

   Copyright (c) 1997 Thomas Boutell

   Permission is granted to copy and distribute this document for any
   purpose and without charge, provided that the copyright notice and
   this notice are preserved, and that any substantive changes or
   deletions from the original are clearly marked.

Abstract

   This document describes some special-purpose chunk types, of
   particular interest to the scientific visualization community, that
   have been registered for use in various PNG (Portable Network
   Graphics) and related multi-image applications.  The chunks that have
   been registered to date are: "pCAL".

Table of Contents

   1. Introduction ................................................... 2
   2. Summary of Proposed Sci-Vis Chunks ............................. 2
   3.  pCAL Calibration of pixel values .............................. 2

1. Introduction

   The chunks described here were registered by the PNG development
   group as public chunks for use by the scientific visualization
   community.  The format of these chunks has been "frozen" and is not
   subject to change.  No general-purpose decoder is required or
   expected to implement these chunks.  Comments on these chunk
   specifications, and new proposals for additional chunk types, should
   be sent to the PNG specification maintainers at png-
   info@uunet.uu.net.  or png-group@w3.org.  The basic PNG specification
   is available from the PNG ftp archive at
   <URL:ftp://swrinde.nde.swri.edu/pub/png/documents/:gt;.

2. Summary of Proposed Sci-Vis Chunks

   This table summarizes some properties of the proposed chunks
   described in this document.

      Proposed        Multiple   Ordering
      chunk name         OK?     constraints

      pCAL               No      Before IDAT




3.  pCAL Calibration of pixel values

   When a PNG file is being used to store physical data other than color


PNG Development Group        Informational                      [Page 2]

PNG-GROUP             PNG Sci-Vis Chunks 19970127            27 Jan 1997


   values, such as a two-dimensional temperature field, the "pCAL" chunk
   can be used to record the relationship (mapping) between stored pixel
   samples, original samples, and actual physical values.  The "pCAL"
   data might be used to construct a reference color bar beside the
   image, or to extract the original physical data values from the file.
   It is not expected to affect the way the pixels are displayed.
   Another method should be used if the encoder wants the decoder to
   modify the sample values for display purposes.

   The "pCAL" chunk's contents are are a zero-byte-terminated text
   string (purpose) that names the equation, followed by original sample
   limits "X0" and "X1", an equation type, and a set of parameters for
   the equation:

      n bytes:  purpose (Latin-1 text)

      1 byte:   null separator

      4 bytes:  X0 (signed integer) Lower limit of original
                sample range.  This original sample value is
                mapped to the stored sample value 0.

      4 bytes:  X1 (signed integer) Upper limit of original
                sample range.  This original sample value is
                mapped to the stored sample value
                (2^sample_depth - 1).  Must not equal X0.

      1 byte:   Equation type (unsigned integer).
           0:   Linear mapping
           1:   Base-e exponential mapping
           2:   Arbitrary-base exponential mapping
           3:   Hypberbolic mapping

      1 byte:   N (unsigned integer), number of parameters.

      u bytes:  Unit (Latin-1 string).  Symbol or description of
                the unit, eg. K, Population Density, MPa, etc).
                A zero-length string can be used if the data is
                dimensionless.

      1 byte:   null separator

      p0 bytes: P0 (ASCII text).  First parameter, a real number
                written as a text floating-point value [link to
                Floating-Point Values in PNG extensions document]

      1 byte:   null separator

      p1 bytes: P1 (ASCII text).  Second parameter.

      etc.



PNG Development Group        Informational                      [Page 3]

PNG-GROUP             PNG Sci-Vis Chunks 19970127            27 Jan 1997


   There is no null separator after the final parameter.  All of the
   parameters for the specified "equation_type" must be present.  If
   some future private "equation_type" should be defined with a variable
   number of parameters, the number of parameters specified by "N" must
   be present.

   The "purpose" identifies the equation, which can permit applications
   or people to choose the appropriate one when more than one "pCAL"
   chunk is present (this could occur in a multiple-image file, but not
   in a PNG file).  The "purpose" string must follow the format of a
   "tEXt" keyword, i.e.  1-79 printable Latin-1 characters.  One way the
   "purpose" field could be used s to identify the system of units. A
   "purpose" string such as "SI" or "English" could be used in the
   "pCAL" chunk as well as in other chunk types, to permit a decoder to
   select an appropriate set of chunks based on the contents of their
   "purpose" fields.

   The "pCAL" chunk defines two mappings:

       * A mapping from the stored samples, which are unsigned integers
         in the range [0..M], where "M==2^sample_depth-1", to the
         original samples, which are signed integers.  "X0" and "X1",
         together with the "sample_depth" for the image, define this
         mapping.
       * A mapping from the original samples to the physical values,
         which are usually real numbers.  The remaining "pCAL" chunk
         parameters define this mapping.
       * Encoders will usually set "X0 = 0" and "X1 = M" to indicate
         that the stored samples are equal to the original samples.
         Note that "X0" is not constrained to be less than "X1", and
         neither is constrained to be positive, but they must be
         different from each other.

   The mapping algorithms are

      original_sample :=
         (stored_sample * (X1 - X0) + M/2) / M + X0

   using integer arithmetic, where (a / b) means (integer(floor(real(a)
   / real(b)))).  Note that this is the same as the "/" operator in the
   C programming language when "a" and "b" are nonnegative, but not
   necessarily when "a" or "b" is negative.












PNG Development Group        Informational                      [Page 4]

PNG-GROUP             PNG Sci-Vis Chunks 19970127            27 Jan 1997


      if equation_type == 0 then
      physical_value := P0 + P1 * original_sample/(X1-X0)

      else if equation_type == 1 then
      physical_value :=
          P0 + P1 * EXP(P2 * original_sample/(X1-X0))

      else if equation_type == 2 then
      physical_value := P0 + P1 * P2^(original_sample/(X1-X0))

      else if equation_type == 3 then
      physical_value :=
          P0 + P1*SINH(P2*(original_sample - P3)/(X1-X0))

   using floating point arithmetic, in which

       * EXP(x) is the exponential function, e^x, in which "e" is the
         base of natural logarithms (approximately 2.718282)
       * SINH(x) is the hyperbolic sine of x,

            SINH(x) = 0.5 * ( EXP(x) - EXP(-x) )

   To map an original sample to a stored sample, the function is:

      stored_sample :=
          ((original_sample - X0) * M + (X1 - X0) / 2) / (X1 - X0)

          (limited to the range [0..M])

   This mapping is lossless and reversible when (ABS(X1-X0) <= M) and
   the original sample is in the range [X0..X1].  If (ABS(X1-X0) > M)
   then there can be no lossless reversible mapping, but the functions
   provide the best integer approximations to floating-point affine
   transformations.

   For color_types 2, 3, and 6, the mapping algorithms are applied
   independently to each of the color sample values.  In the case of
   color type 3 (indexed color), the mapping refers to the RGB samples
   and not to the index values.

   Linear data can be expressed with equation_type 1.

   Pure logarithmic data can be expressed either with

      X0 =: 0                           X0 := 0
      X1 =: M                           X1 := M
      Equation_type =: 1                Equation_type := 2
      N  =: 3                or with    N  := 3
      P0 =: 0                           P0 := 0
      P1 =: min                         P1 := min
      P2 =: LOGe(max/min)               P2 := max/min



PNG Development Group        Informational                      [Page 5]

PNG-GROUP             PNG Sci-Vis Chunks 19970127            27 Jan 1997


   If present, the "pCAL" chunk must appear before the first "IDAT"
   chunk.  Only one instance of the "pCAL" chunk is permitted in a PNG
   stream.

   Using equation type 3, floating point data in the range {-v0..v1} can
   be reduced (with loss) to a set of integer samples such that the
   resolution of the stored data is roughly proportional to its
   magnitude.  For example, floating point data ranging from -10^31 to
   10^31 (the usual range of floating point numbers on 32-bit machines)
   can be represented with

      X0 =: 0
      X1 =: 65536
      Equation_type =: 3
      N  =: 4
      P0 =: 0.0
      P1 =: 1.0e-30
      P2 =: 280.0
      P3 =: 32767.0

   The resolution near zero is about 10^-33, while the resolution around
   +/-10^31 is about 10^28.  Everywhere the resolution is about 0.4
   percent of the magnitude.

   Implementations should use double precision arithmetic (or take other
   precautions) while performing the mappings for equation types 1, 2,
   and 3, to prevent overflow of intermediate results when the parameter
   "P1" is small and the exponential or power functions are large.

Contributors

   Names of contributors not already listed in the PNG specification are
   presented in alphabetical order:

       * John Bowler, jbowler@acm.org
       * Todd French, tfrench@sandia.gov

Editor

       * Glenn Randers-Pehrson, glennrp@arl.mil or randeg@alumni.rpi.edu

   End of PNG Scientific Visualization Chunks Specification.  Expires 28
   January 1997.











PNG Development Group        Informational                      [Page 6]