PNG Proposed pCAL Chunks, draft 19961226

File: png-pCAL-chunk-19961226.txt

Status of this Memo

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

png-info@uunet.uu.net

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-group/documents/.

Notices

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

Table of Contents

• 1. Introduction
• 2. Using Proposed PNG Chunks
• 3. Summary of Proposed pCAL chunk
• 4. Proposed PNG pCAL Chunk Specification
  • 4.1. Discussion
  • 4.2. pcAL Scale of pixel values

1. Introduction

2. Using Proposed PNG Chunks

Whenever you use any of these unregistered chunks you should also include a "tEXt" chunk describing it, for example:

tEXtComment\0
This file contains a pcAL chunk written according to the
format given in Version 19961226 of the PNG Proposed Chunks
document.

3. Summary of Proposed pCAL chunk

   Proposed        Multiple   Ordering
   chunk name         OK?     constraints
   
   pCAL               No      Before IDAT

4. Proposed PNG pCAL Chunk Specification

4.1. Discussion

4.2. pcAL Scale of pixel values

The "pcAL" chunk's contents are are a zero-byte-terminated text string (purpose) that names the equation, followed (after the 20-byte signature and its null-byte separator) 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

20 bytes: signature ("PNG group 1996-12-27")

1 byte:   null separator

x0 bytes: X0 (ASCII text) Lower limit of original sample
          range, a real number written as a text
          floating-point number.  This original sample
          value is mapped to the stored sample value 0.

1 byte:   null separator

x1 bytes: X1 (ASCII text) Upper limit of original sample
          range, a real number written as a text
          floating-point number.  This original sample
          value is mapped to the stored sample value M,
          where M is 2^sample_depth - 1.

1 byte:   null separator

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

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.

The "purpose" identifies the equation, which can permit applications or people to choose the appropriate one when more than one scaling equation is stored in a multiple-image 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 is 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 integers in the range [0..M], where "M==2^sample_depth-1", to the original samples, which are 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.

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

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

• 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) )
  

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

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

For color_types 2, 3, and 6, the mapping algorithms are applied independently to each of the color sample values.

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

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.

Contributors

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

Editor

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