PNG Proposed Scientific Visualization Chunks, draft 19961023

File: png-scivis-chunks-19961023.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.

Changes from the 11 October 1996 draft (version 19961011):

Abstract

This document describes some special-purpose chunk types that have been proposed for use in various PNG (Portable Network Graphics) and related multi-image applications. They have not yet been approved for registration by the PNG developers, and therefore are experimental and their format is subject to change. The proposed chunks are "drNG/DrNG", "faLT", "loGE/LoGE", "pcAL", "ttSC", "xxSC", "yySC", and "zzSC".

Table of Contents

1. Introduction

Chunks described here have 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/WD-png.

2. Documentation of registered PNG Sci-Vis chunks

When the first of these chunks is registered, a non-draft version of this document will be created, in which the registered chunk specification will reside, along with the specifications for any subsequently registered chunks from this proposal. The names of the registered chunks will be listed in the "PNG extensions" document.

3. Using Proposed PNG Sci-Vis 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. They are experimental chunks and the format is subject to change. If and when any become registered, the second letter of the chunk name will become uppercase, the "signature" field and it zero-byte terminator will be deleted, and 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 19960914 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.

4. Summary of Proposed Sci-Vis Chunks

This table summarizes some properties of the proposed chunks described in this document.
   Chunk name      Multiple   Ordering
                      OK?     constraints
   
   drNG/DrNG          No      Before IDAT
   faLT               No      Before IDAT
   loGE/LoGE          No      Before IDAT
   ttSC            (used in multi-image format)
   xxSC               No      Before IDAT
   yySC               No      Before IDAT
   zzSC            (used in multi-image format)
   pcAL               No      Before IDAT

5. Proposed PNG Sci-Vis Chunk Specifications

This section provides the detailed specifications for the proposed chunks.

5.1. drNG/DrNG Pixel display range

This chunk can be used when the pixel values do not occupy the full range of possible values, and when bit depth scaling is not appropriate. It can also be used to enhance contrast by scaling to a larger range than the actual range of pixel values. The chunk defines the pixel values that correspond to minimum and maximum intensity, to which the pixel data is to be scaled.

The chunk can be used as a critical chunk, named "DrNG", or as an ancillary chunk, named "drNG". The syntax and function is exactly the same whichever name is used. The critical version should only be used if the image cannot be meaningfully displayed without performing "DrNG" scaling. Decoders not recognizing "DrNG" will not attempt to display the image at all. Encoders are strongly encouraged to scale the image data properly and to use the noncritical version, "drNG", if at all possible.

This chunk's contents are

min_sample  m bytes   Raw sample value corresponding to
                      minimum intensity of the graylevel
                      or red channel, written as a text
                      floating-point value [link to
                      Floating-Point Values in extensions
                      document]

0           1 byte    a zero byte to separate fields

max_sample  n bytes   Raw sample value corresponding to
                      maximum intensity for the graylevel
                      or red channel

(The following entries can be omitted for grayscale images, or for color images where identical values are to be applied to all three color channels)

0          1 byte     a zero byte to separate fields

min_green  m bytes    raw sample value corresponding to
                      minimum green intensity

0          1 byte     a zero byte to separate fields

max_green  m bytes    raw sample value corresponding to
                      maximum green intensity

0          1 byte     a zero byte to separate fields

min_blue   m bytes    raw sample value corresponding to
                      minimum blue intensity

0          1 byte     a zero byte to separate fields

max_blue   m bytes    raw sample value corresponding to
                      maximum blue intensity
If this chunk is present, graylevel or color sample values are to be scaled for display between minimum and maximum intensity by linear interpolation. When the sample value falls outside the range min_value..max_value, it is to be set to min_value or max_value as appropriate. For each graylevel or color sample, the conversion is
ratio := (2^output_bit_depth - 1)/(max_value - min_value)
result := (input_sample - min_value) * ratio
output_sample := LIMIT (0, result, 2^output_bit_depth-1)

in which

LIMIT (low, x, high) = MAX (MIN (x, high), low).
In indexed-color images, "output_bit_depth == 8" in this calculation, regardless of the bit depth actully used to store the indices. For other color types, output_bit_depth is the same as the "bit_depth" given in the "IHDR" chunk.

Note that min_value and max_value are permitted to be negative, positive, or zero. The only restriction is that they be different from each other.

Encoders should not use "drNG/DrNG" in lieu of reasonably scaling the samples. For example, if the sample values range from 0 (black) to 1000 (white), it would be an extremely bad idea to use the "drNG" chunk to request the decoder to scale 1000 up to 65535, because a PNG viewer that does not understand "drNG/DrNG" (and, since this is an extension chunk, most viewers will probably not understand "drNG/DrNG") would simply display a very dark rectangle. Instead, multiply your samples by 64, and use "drNG" with max_sample=64000 to request the decoder to do the final adjustment.

If the "tRNS" chunk is present, its value is compared to the unscaled pixel value, prior to applying the "drNG/DrNG" scaling. The "faLT", "gAMA", "cHRM", and alpha conversions, if present, are applied to the scaled sample values.

If present, this chunk must appear before the first "IDAT" chunk. Only one "drNG/DrNG" chunk is permitted in a PNG file.

5.2. drNG/DrNG discussion

The format of the "drNG/DrNG" chunk was last changed 06 April 1996 (Version 19960406). Minor changes to the explanatory material for this chunk were made in version 19960927. The proposed registered name for this chunk is "dRNG/DRNG".

5.3. faLT False-color palette

This chunk is used with grayscale data, where the pixels are to be rendered in a false color according to the grayscale value. The grayscale sample of each pixel serves as a pointer into the false-color palette.

This chunk's contents are a zero-byte-terminated text string (purpose) that names the palette, followed [after a 20-byte signature and its null-byte separator] by a gamma field and a series of false-color palette entries:

   purpose:        n bytes (Latin-1 text)
   separator:      1 byte, null
   signature:     20 bytes ("PNG group 1996-10-23")
   separator:      1 byte, null
   gamma:          4 bytes (file_gamma times 100000)
   index:          2 bytes, range 0 .. (2^bitdepth) -1)
   red:            2 bytes, range 0 .. 65535
   green:          2 bytes, range 0 .. 65535
   blue:           2 bytes, range 0 .. 65535
   
   etc.
The number of entries is determined from the remaining chunk length after the gamma field. This length not divisible by 8 is an error.

The "purpose" identifies the palette, which can permit applications or people to choose the appropriate one when more than one false-color palette 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.

The gamma field gives the value of "file_gamma", times 100000, that is associated with the false-color palette samples.

This chunk can appear for color type 0 or color type 4. If it appears for any other color type, it will be ignored.

The complete 2^bitdepth-entry false-color palette can be built from the chunk data. If the first entry (index value 0) is missing, it will be assumed to be {0, 0, 0} (black). If the last entry (index value 2^bitdepth - 1) is missing, it will be assumed to be {65535, 65535, 65535} (white). The red, green, blue samples for other missing entries are filled in by linearly interpolating between the samples that are present, independently for each of the three color components.

Once the complete false-color palette is established, it is used similarly to PLTE. The first entry in the completed false-color palette is referenced by the grayscale value 0, the second by grayscale value 1, etc.

If the "tRNS" chunk is present, its value is compared to the graylevel, not to the converted false-color of the pixels. If the "bKGD" chunk is present, background pixels will be displayed in the false-color corresponding to the grayscale value found in the "bKGD" chunk. The "cHRM" and alpha conversions, if present, are applied to the color samples in the converted false-color pixels. The "gAMA" chunk is ignored when the "faLT" chunk is processed, and the supplied "file_gamma" value is used instead.

Note that the "gAMA" and other values must be selected so that the grayscale image is meaningfully displayed when the "faLT" chunk is unrecognized or ignored.

If this chunk does appear, it must precede the first "IDAT" chunk. There can be only one "faLT" chunk in a PNG datastream.

5.4. faLT discussion

Format last changed in version 19961023 of this document (October 1996). The name has been changed from "faLS" to "faLT" to distinguish the versions; the proposed name of the registered chunk is "fALS". The "signature" field and its null separator will not be included in the registered chunk.

5.5. loGE/LoGE Logarithmic encoding

The "loGE/LoGE" chunk is used to decode image data whose grayscale or color samples have been logarithmically encoded.

The chunk can be used as a critical chunk, named "LoGE", or as an ancillary chunk, named "loGE". The syntax and function is exactly the same whichever name is used. The critical version should only be used if the image cannot be meaningfully displayed without performing "LoGE" scaling. Decoders not recognizing "LoGE" will not attempt to display the image at all. Encoders are strongly encouraged to include a "gAMA" chunk that permits a meaningful if not completely accurate display, and use the noncritical version, "loGE", if at all possible.

The "loGE/LoGE" chunk's contents are

P0             n0 bytes    (First parameter, a real number
                           written as a text floating-point
                           value [link to Floating-Point
                           Values in extensions document]
Null separator: 1 byte

P1             n1 bytes    (Second parameter)

Null separator: 1 byte

P2             n2 bytes    (Third parameter)

There is no trailing zero for the final string.

The scaling algorithm is

normalized_sample_value := input_sample/(2^input_bitdepth-1)
scaled_value := P0 + P1 * P2^normalized_sample_value
output_sample := LIMIT (0, scaled_value, 2^output_bitdepth-1)

in which 

LIMIT (low, x, high) = MAX (MIN (x, high), low).
For color_types 0 and 4, the normalized sample value is the grayscale value of the pixel normalized to the range [0.0:1.0] by dividing it by the maximum value for the input bit depth, using floating point arithmetic.

For color_types 2, 3, and 6, the scaling algorithm is applied independently to each of the color samples similarly normalized to [0.0:1.0].

The alpha channel, if present, is not affected by the "loGE/LoGE" transformation. Alpha compositing is done in the normal manner, with the transformed pixels forming the foreground image [link to Decoders: Alpha Processing in core spec]

Pure logarithmic data can be expressed with

P0 := 0
P1 := min_val
P2 := max_val/min_val
In which the range [min_val..max_val] includes the minimum and maximum values appearing in the source data. When the image is decoded using the "loGE/LoGE" data, the gamma calculation for the decoded samples should be done as though the "file_gamma" were 1.0, regardless of the contents of the "gAMA" chunk.

It is advisable to include a "gAMA" chunk with logarithmic data, in case a viewer does not use the "loGE" data to decode it. A value of gamma should be chosen that allows the image to be displayed as well as it can be with a viewer that supports "gAMA" but not "loGE".

You can select a value of gamma (also called "file_gamma") by eye as described in [link to Gamma Tutorial: General Gamma Handling in core spec], or you can calculate one as follows:

If the maximum value of the logarithmically decoded pixels can reasonably be displayed as white on the monitor, then specifying a value of gamma given by

gamma := LN( LN(0.2) / LN(max_val/min_val) + 1) / LN(0.2)
(in which LN() is the natural logarithm function)
causes the two values max_val and 0.2*max_val to be reproduced at correct brightness on screen - these can be thought of as white and mid-grey. Tones between white and mid-grey will be a bit too bright, ones darker than mid-grey will be increasingly too dark, but it's a reasonable approximation for viewable display. A max_val/min_val ratio of 64 gives a gamma of about 0.3, a max_val/min_val of 1000 gives a gamma of about 0.165, so a viewer assuming a default gamma of 0.45 is going to give a bright, washed-out image for any log-encoded image.

In cases where the maximum sample value is many times brighter than scene white (i.e. the image is encoded to retain specular highlight information), the formula above doesn't apply, but there's probably no way of getting such an image to display reasonably anyway with a viewer that doesn't understand "loGE".

If present, the "loGE/LoGE" chunk must appear before the first "IDAT" chunk. Only one instance of the "loGE/LoGE" chunk is permitted in a PNG datastream.

5.6. loGE/LoGE Discussion

The format of the "loGE" chunk was last changed 06 April 1996 (Version 19960406). There have been no changes to any part of the specification for this chunk since then. The proposed registered name for this chunk is "lOGE/LOGE". If the chunk becomes registered, the specification will appear in the Scientific Visualization Chunks document.

5.7. 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 between pixel values and actual physical values. The "pcAL" data might be used to construct a reference color bar beside the image. It is not expected to affect the way the image is 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 an equation type and a set of parameters for the equation:

purpose:        n bytes (Latin-1 text)

separator:      1 byte, null

signature:     20 bytes ("PNG group 1996-10-11")

separator:      1 byte, null

Equation type   1 byte   (0 for linear scaling,
                          1 for base-e exponential scaling,
                          2 for arbitrary-base exponential
                            scaling,
                          3 for hypberbolic scaling)

N               1 byte   (Number of parameters)

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

Null separator: 1 byte

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

Null separator: 1 byte

P1             p1 bytes  (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 last parameter.

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 the "xxSC" and "yySC" chunks, to permit a decoder to select an appropriate set of chunks based on the contents of their "purpose" fields.

The scaling algorithm is


if equation_type == 0 then
scaled_value := P0 + P1 * normalized_sample_value

else if equation_type == 1 then
scaled_value := P0 + P1 * EXP(P2 * normalized_sample_value)

else if equation_type == 2 then
scaled_value := P0 + P1 * P2^normalized_sample_value

else if equation_type == 3 then
scaled_value := P0 + P1*SINH((normalized_sample_value - P2)/P3)
in which For color_types 0 and 4, the normalized sample value is the grayscale sample value of the pixel normalized to the range [0.0:1.0] by dividing it by the maximum value for the bit depth, using floating point arithmetic.

For color_types 2, 3, and 6, the scaling algorithm is applied independently to each of the color sample values similarly normalized to [0.0:1.0].

Pure logarithmic data can be expressed either with

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. The "drNG/DrNG" or "loGE/LoGE" chunk 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.

5.8. pcAL Discussion

The format of the "pcAL" chunk was last changed in version 19960914) 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. The proposed registered name for this chunk is "pCAL".

5.9. ttSC Physical time scale

This is like "xxSC" chunk except that it gives the scale and offset in the frame-to-frame direction, which would normally be the physical time scale. It would be meaningless in a PNG stream, but in a multi-image format it could be used at the top level, to provide the physical scale (rather than the display frame rate) in the frame-to-frame direction.

5.10. ttSC discussion

This is a new proposed chunk, 16 August 1996 (Version 19960816). The chunk name was changed from "tsCL" to "ttSC" in the 19961011 version because the "purpose" and "signature" fields were added. The proposed registered name for this chunk is "tSCL".

5.11. xxSC X-Scale of image subject

This chunk relates the actual dimension of the image subject in the "x" (width) direction to the column position of a pixel. It provides some additional capability beyond that available in the "sCAL" [link to sCAL in PNG extensions document] chunk, which does not provide for an offset, and does not provide for different units in the width and height directions. The latter could be useful, for example, in racing photo-finish "streak" images, where one of the dimensions is time and the other is length. The chunk does not affect the image display, but could be used to construct scaled axes adjacent to the image.

The "xxSC" chunk's contents are

purpose:        n bytes (Latin-1 text)

separator:      1 byte, null

signature:     20 bytes ("PNG group 1996-10-11")

separator:      1 byte, null

Xunit          xu bytes  (Latin-1 symbol or description of
                         the width unit, eg. milliseconds,
                         degrees West Longitude,  etc).
                         A zero-length string can be used if
                         the data is dimensionless.

Null separator: 1 byte

Xoffset        xo bytes  X offset, a real number written as a
                         text floating-point value [link to
                         Floating-Point Values in PNG
                         extensions document] This is the
                         physical value of "x" corresponding
                         to the left edge of the image.

Null separator: 1 byte


Xscale         xs bytes  X scale, the x-distance corresponding
                         to the width of a pixel.  Must be
                         non-zero.
There is no trailing zero for the final string.

The scaling algorithm for finding the physical x-value of the middle of a pixel is


physical_x_value := Xoffset + Xscale * (column_number + 0.5)

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

5.12. xxSC discussion

New chunk, 16 August 1996 (Version 19960816). This chunk was formerly included in the "xySC" chunk and was called "xSCL" in the 19960914 version. The chunk name was changed in the 19961011 version because the "purpose" and "signature" fields were added. The proposed registered name for this chunk is "xSCL".

5.13. yySC Y-Scale of image subject

This chunk is similar to the "xxSC" chunk. It relates the actual dimension of the image subject in the "y" (height) direction to the row position of a pixel, positive downward from the top.

The "yySC" chunk's contents are

purpose:        n bytes (Latin-1 text)

separator:      1 byte, null

signature:     20 bytes ("PNG group 1996-10-11")

separator:      1 byte, null

Yunit          yu bytes  (Latin-1 symbol or description of
                         the width unit, eg. milliseconds,
                         degrees North Latitude, etc).
                         A zero-length string can be used if
                         the data is dimensionless.

Null separator: 1 byte

Yoffset        yo bytes  Y offset, a real number written as a
                         text floating-point value [link to
                         Floating-Point Values in extensions
                         document] This is the physical value
                         of "y" corresponding to the top
                         edge of the image.

Null separator: 1 byte

Yscale         ys bytes  Y scale, the y-distance corresponding
                         to the height of a pixel.  Must be
                         non-zero.  The positive direction is
                         downward.
There is no trailing zero for the final string.

The scaling algorithm for finding the physical y-value of the middle of a pixel is


physical_y_value := Yoffset + Yscale * (row_number + 0.5)

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

5.14. yySC discussion

New chunk, 16 August 1996 (Version 19960816). This chunk was formerly included in the "xySC" chunk and was called "ySCL" in the 19960914 version. The chunk name was changed in the 19961011 version because the "purpose" and "signature" fields were added. The proposed registered name for this chunk is "ySCL".

5.15. zzSC Z scale

This is like "xxSC" chunk except that it gives the z-scale and offset in the thickness direction, when a series of images are considered to be layers of voxels (tomographic slices). It would be meaningless in a PNG stream, but in a multi-image format it could be used to provide the physical dimension in the frame-to-frame direction, or when images are grouped as in a composite frame, to give the dimension in the plane-to-plane direction within the group.

5.16. zzSC discussion

New chunk, 16 August 1996 (Version 19960816). This chunk was was called "zsCA" in the 19960914 version. The chunk name was changed in the 19961011 version because the "purpose" and "signature" fields were added. The proposed registered name for this chunk is "zSCL".

6. Security considerations

Security considerations are addressed in the basic PNG specification, http://www.w3.org/pub/WWW/TR/WD-png.

The same precautions taken when displaying "tEXt" data should be taken when displaying the text contained in the "unit" strings of the "xxSC" and "pcAL" chunks and the "purpose" string of various chunks. Viewers should not display these strings directly without first checking for the presence of nonprintable characters, and for the <ESC> character in particular.

No known additional security hazards are posed by the chunks described here.

7. Credits

Contributors

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

Editor

End of PNG Sci-Vis Chunks Specification. Expires 23 Apr 1997.