pack4png: Code

VERSION 1.1, JULY 06, 2003

Author: Theo Pavlidis

1. Overview

This page describes the source code of version 1.1 of pack4png.

2. Available zip files

There are four files: Header files copied from the PNG library. You need those to compile the p4pApp code. You will also need to download from the PNG site the full library in order to enable p4pApp to link and run. (See Section 3.2 below.) Archive size is 57KB. Source files for the pack4png library (see Section 3.1 below). These files can be used to build a DLL. Archive size is 17KB. Source files for an interactive Microsoft Windows application p4pApp that lets you read and display images, apply the pack4png transformation, observe the results and save the packed image (see Section 3.2 below) Archive size is 38KB.

The easy way to try pack4png: A ready executable (p4pApp.exe) and a DLL (p4p.dll) plus online documentation (p4pAppDocumentation.htm). Extracting these files and placing them in the same directory lets you try pack4png with minimal effort. (The porting has been made succesfully to a Windows ME machine.) Archive size is 104KB.

There is also a mirror site: .

3. Code Description

3.1. The pack4png Library (p4p)

The software has been set up as an MFC project (named p4p) to produce a DLL. If you have a different computing environment you may not want all those files. There are four key files:

  • HistAnalArray.h and HistAnalArray.cpp that implement a class CHistAnalArray that does all the essential work.
  • pack4png.h and pack4png.cpp that provide the public interface. In contrast to the (0.0) version, these are now trivial programs with all the work done inside the class CHistAnalArray.

The DLL has the following public interface (and two other similar functions that you can find from pack4png.h):

extern "C" __declspec(dllimport) int pack4png1(
			long hist[],	        // input: histogram
			int levels,	            // input: usually 256
			int  compression	//  input: should be  in the range 1-9 or 11-19
			int pxmap[]	        // output: new pixel values in terms of old

The function pack4png1() accepts as input an intensity histogram for a particular color that has been computed over an image (or a region of an image), the number of levels per pixel (usually 256), and a quality parameter. The output is the array pxmap[] that maps old pixel values to new ones. The function returns the number of zones found (i.e. number of distinct values in the pxmap array). Returns of 0 or -1 indicate errors.

The value of compression%10 is the minimum number of level crossings of the histogram that are required to define a zone (see the paper for details). Minimum value is clearly 1 (minimum compression). The maximum value equals the number of levels used (9 in this imprementation). compression/10 determines whether anti-aliasing intensities should be kept (if the value is 0) or not.(Again, see the paper for details) The latter strategy produces even higher compression. If all this seems too confusing, think of compression as having a range of 1-19 which is close to what is happening. For images that fit well the model under which this method has been developed the value of compression%10 has little effect.

It is possible to pass information about whether the image is color (rather than gray) by adding 1000 to the value of compression and whether we are confident that the image is a good candidate for space domain compression (rather than JPEG) by adding 100 to the value of compression. Such information is used in heuristic post-procesing and it may be omitted in future versions.

Note: Earlier drafts used the term quality to describe the effect of changes in the strategy of the algorithm specified in the third argument of the function. However image quality is quite subjective and in this draft the third argument is called compression.

A corresponding set of functions have been added that do the packing when a 6x6x6 global color table is expected to be used.

extern "C" __declspec(dllimport) int pack4gct1(
			long hist[],	        // input: histogram
			int levels,	            // input: usually 256
			int  compression	//  input: should be  in the range 1-9 or 11-19
			int pxmap[]	        // output: new pixel values in terms of old

3.2. The pack4png Windows Application (p4pApp)

The software has been set up as an MFC project (named p4pApp) to produce an executable file. The application has the usual Microsoft Windows Document/View structure and look with a toolbar. It reads a PNG file, displays it, lets the user select the parameters, and produces another PNG file. In order to use this code you also need to have the PNG code library lpng125 or later as well as the zlib. You may download both by going to libpng site. (If you are not familiar with PNG you should also look at the PNG Home Page). Once you install these libraries you should edit the local.h file (it contains definitions that depend on the local system) and you are ready to build the executable. For convenience, on this site contains copies of the definition files of the PNG library that are needed to compile this application.

The following information is for those who are adventurous. Besides the libpng files and the Microsoft application Document and View files, the key files of p4pApp are

  • CPix.h and CPix.cpp that implement a simple class CPix that provides the "glue" between pack4png and the png library. It has only three member functions: ReadPix(), WritePix() and InvokeP4P().
  • pngcall.h and pngcall.cpp that provide calling routines to the PNG library. The routines do not meet the full PNG standard. The reading routine does not handle palletted images or images with an alpha channel. If you have you own interface you may discard these programs and modify the CPix functions ReadPix() and WritePix() to call your own PNG code.
  • CPixEx.h and CPixEx.cpp that implement a class CPixEx based on CPix that provides all the essential functions for the interactive aspects of the application.
  • local.h that was discussed above.

There is a user's manual for the application.

4. How to build a Batch Application

It is easy to build a batch application using pack4png that does not depend on the Microsoft Windows environment. The main program can be as simple as the one shown below (initialization and error checking not included):

	char *InputFileName, *OutputlFieName;
        int compression; // meaningful values 1-19
        CPix pix;
        pix.ReadPix(InputFileName);    // reads a PNG file
        pix.InvokeP4P(compression);   // calls pack4png
        pix.WritePix(OutputlFieName); // writes a PNG file

In order to build it you need to add files CPix.h, CPix.cpp, pngcall.h, pngcall.cpp (from the p4pApp project), pack4png.h (from the p4p project) and define the compiler flag BATCH_P4P. You also need to have the PNG code library lpng125 or later as well as the zlib.

(See Section 3.2. above.)

Main pack4png page