PNG Proposed pCAL Chunks, draft 19961230

File: png-pCAL-chunk-19961230.txt

Status of this Memo

This document is an informal draft of 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-group/documents/.

Notices

Copyright © 1996 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 a special-purpose chunk type that has been proposed for use in various PNG (Portable Network Graphics) and related multi-image applications. It has not yet been approved for registration by the PNG developers, and therefore are experimental and their format is subject to change. The proposed chunk is pCAL.

Table of Contents

1. Introduction

The chunk described here has been proposed to the PNG development group for use by the scientific visualization community. Their definitions are subject to change until such time as the group formally registers them. No decoder is required or expected to implement these chunks except for experimental or evaluation purposes. Comments on these proposals, and new proposals for additional chunk types, should be sent to the PNG specification maintainers at png-info@uunet.uu.net. The basic PNG specification is available from the W3C archive at http://www.w3.org/pub/WWW/TR/.

2. Using Proposed PNG Chunks

No chunks described in this document have yet been registered by the PNG maintainers. Therefore they have a lower-case letter in the second position of the chunkname, and in some cases the name is different from the proposed registered chunk name. They are experimental chunks and the format is subject to change. If and when any become registered, the chunk name will be changed to its final form. The second letter of the chunk name will become uppercase. The "signature" field and it zero-byte terminator will be deleted. There will be no further change to the format.

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 19961230 of the PNG Proposed Chunks
document.
For those proposed chunks that have a "signature" field, decoders should check to ensure that the signature field is present and that its contents exactly match the specified string.

3. Summary of Proposed pCAL chunk

This table summarizes some properties of the proposed chunks described in this document.
   Proposed        Multiple   Ordering
   chunk name         OK?     constraints
   
   pCAL               No      Before IDAT

4. Proposed PNG pCAL Chunk Specification

This section provides the detailed specifications for the proposed chunk. The "discussion" paragraph will not form a part of the final specification. The "specification" paragraph describes the proposed chunk in its unregistered form.

4.1. Discussion

The proposed name of the registered chunk is "pCAL". The name "pcAL" must be used in test implementations until the chunk is registered. The format of the "pcAL" chunk was last changed in version 19961230) In the previous version, this chunk was called "zsCL". In the 19960925 version, a requirement that all of the parameters for the specified "equation_type" must be present. In the 19961027 version, the form of equation_type 3 was changed. In the 19961226 version, normalization parameters X0 and X1 were added. In the 19961230 version, the format of X0 and X1 was changed to 4-byte integers. The proposed registered name for this chunk is "pCAL".

4.2. pcAL Scale of pixel values

When a PNG file is being used to store physical data other than color 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.

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

1 byte:   null separator

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

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

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.
There is no trailing zero for the final string. 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. A null separator is not required after the final parameter.

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:

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.

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 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 (X1-X0 <= M) and the original sample is in the range [X0..X1]. If (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.

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
The "pcAL" data is not intended to be used by a decoder to affect the way the pixels are displayed. "pcAL" is simply a comment, and could be used, for example, to construct a reference color bar scale beside the image, or to extract the original physical values recorded in the file. Another method should be used if the encoder wants the decoder to modify the sample values for display purposes.

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

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

Editor

End of PNG pCAL chunk proposal. Expires 30 Jun 1997.