Read/write png format from/to file and memory. More...

#include <string.h>
#include "allheaders.h"
#include "png.h"

Defines
#define	DEBUG 0
Functions
PIX *	pixReadStreamPng (FILE *fp)
l_int32	readHeaderPng (const char filename, l_int32 pwidth, l_int32 pheight, l_int32 pbps, l_int32 pspp, l_int32 piscmap)
l_int32	freadHeaderPng (FILE fp, l_int32 pwidth, l_int32 pheight, l_int32 pbps, l_int32 pspp, l_int32 piscmap)
l_int32	sreadHeaderPng (const l_uint8 data, l_int32 pwidth, l_int32 pheight, l_int32 pbps, l_int32 pspp, l_int32 piscmap)
l_int32	fgetPngResolution (FILE fp, l_int32 pxres, l_int32 *pyres)
l_int32	pixWritePng (const char filename, PIX pix, l_float32 gamma)
l_int32	pixWriteStreamPng (FILE fp, PIX pix, l_float32 gamma)
PIX *	pixReadRGBAPng (const char *filename)
l_int32	pixWriteRGBAPng (const char filename, PIX pix)
void	l_pngSetStrip16To8 (l_int32 flag)
void	l_pngSetStripAlpha (l_int32 flag)
void	l_pngSetWriteAlpha (l_int32 flag)
void	l_pngSetZlibCompression (l_int32 val)
PIX *	pixReadMemPng (const l_uint8 *cdata, size_t size)
l_int32	pixWriteMemPng (l_uint8 *pdata, size_t psize, PIX *pix, l_float32 gamma)
Variables
static l_int32	var_PNG_STRIP_16_TO_8 = 1
static l_int32	var_PNG_STRIP_ALPHA = 1
static l_int32	var_PNG_WRITE_ALPHA = 0
static l_int32	var_ZLIB_COMPRESSION = Z_DEFAULT_COMPRESSION
const char *	ImageFileFormatExtensions []

Detailed Description

Read/write png format from/to file and memory.

  Read png from file
        PIX        *pixReadStreamPng()
        l_int32     readHeaderPng()
        l_int32     freadHeaderPng()
        l_int32     sreadHeaderPng()
        l_int32     fgetPngResolution()

  Write png to file
        l_int32     pixWritePng()  [ special top level ]
        l_int32     pixWriteStreamPng()
        
  Read and write of png to/from RGBA pix
        PIX        *pixReadRGBAPng();
        l_int32     pixWriteRGBAPng();

  Setting flags for special modes
        void        l_pngSetStrip16To8()
        void        l_pngSetStripAlpha()
        void        l_pngSetWriteAlpha()
        void        l_pngSetZlibCompression()

  Read/write to memory   [not on windows]
        PIX        *pixReadMemPng()
        l_int32     pixWriteMemPng()

  Documentation: libpng.txt and example.c

  On input (decompression from file), palette color images
  are read into an 8 bpp Pix with a colormap, and 24 bpp
  3 component color images are read into a 32 bpp Pix with
  rgb samples.  On output (compression to file), palette color
  images are written as 8 bpp with the colormap, and 32 bpp
  full color images are written compressed as a 24 bpp,
  3 component color image.

  In the following, we use these abbreviations:
     bps == bit/sample
     spp == samples/pixel
     bpp == bits/pixel of image in Pix (memory)
  where each component is referred to as a "sample".

  There are three special flags for determining the number or
  size of samples retained or written:
  (1) var_PNG_STRIP_16_to_8: default is TRUE.  This strips each
      16 bit sample down to 8 bps:
       - For 16 bps rgb (16 bps, 3 spp) --> 32 bpp rgb Pix
       - For 16 bps gray (16 bps, 1 spp) --> 8 bpp grayscale Pix
  (2) var_PNG_STRIP_ALPHA: default is TRUE.  This does not copy
      the alpha channel to the pix:
       - For 8 bps rgba (8 bps, 4 spp) --> 32 bpp rgb Pix
  (3) var_PNG_WRITE_ALPHA: default is FALSE.  The default generates
      an RGB png file with 3 spp.  If set to TRUE, this generates
      an RGBA png file with 4 spp, and writes the alpha channel.
  These are set with accessors.

  Two convenience functions are included for reading the alpha
  channel (if it exists) into the pix, and for writing out the
  alpha sample of a pix to a png file:
      pixReadRGBAPng()
      pixWriteRGBAPng()
  These use two of the special flags, setting to the non-default
  value before use and resetting to default afterwards.
  In leptonica, we make almost no explicit use of the alpha channel.
      
  Another special flag, var_ZLIB_COMPRESSION, is used to determine
  the compression level.  Default is for standard png compression.
  The zlib compression value can be set [0 ... 9], with
       0     no compression (huge files)
       1     fastest compression
       -1    default compression  (equivalent to 6 in latest version)
       9     best compression
  If not set, we use the default compression in zlib.
  Note that if you are using the defined constants in zlib instead
  of the compression integers given above, you must include zlib.h.

  Note: All special flags use global constants, so if used with
        multi-threaded applications, results can be non-deterministic.

Definition in file pngio.c.

Define Documentation

#define DEBUG 0

Definition at line 123 of file pngio.c.

Function Documentation

PIX* pixReadStreamPng ( FILE * fp )

pixReadStreamPng()

Input: stream Return: pix, or null on error

Notes: (1) If called from pixReadStream(), the stream is positioned at the beginning of the file. (2) To do sequential reads of png format images from a stream, use pixReadStreamPng()

Definition at line 143 of file pngio.c.

References PixColormap::array, COLOR_BLUE, COLOR_GREEN, COLOR_RED, ERROR_PTR, L_ALPHA_CHANNEL, L_WARNING, NULL, pixcmapAddColor(), pixcmapCreate(), pixCreate(), pixGetData(), pixGetWpl(), pixInvert(), pixSetColormap(), pixSetText(), pixSetXRes(), pixSetYRes(), PROCNAME, SET_DATA_BYTE, Pix::text, var_PNG_STRIP_16_TO_8, var_PNG_STRIP_ALPHA, and x0.

Referenced by pixaReadStream(), and pixReadStream().

l_int32 readHeaderPng	(	const char *	filename,
		l_int32 *	pwidth,
		l_int32 *	pheight,
		l_int32 *	pbps,
		l_int32 *	pspp,
		l_int32 *	piscmap
	)

readHeaderPng()

Input: filename &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error

Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.

Definition at line 346 of file pngio.c.

References ERROR_INT, fopenReadStream(), freadHeaderPng(), NULL, and PROCNAME.

Referenced by pixReadHeader().

l_int32 freadHeaderPng	(	FILE *	fp,
		l_int32 *	pwidth,
		l_int32 *	pheight,
		l_int32 *	pbps,
		l_int32 *	pspp,
		l_int32 *	piscmap
	)

freadHeaderPng()

Input: stream &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error

Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.

Definition at line 385 of file pngio.c.

References CALLOC, ERROR_INT, fnbytesInFile(), FREE, PixMemoryStore::nbytes, NULL, PROCNAME, and sreadHeaderPng().

Referenced by readHeaderPng().

l_int32 sreadHeaderPng	(	const l_uint8 *	data,
		l_int32 *	pwidth,
		l_int32 *	pheight,
		l_int32 *	pbps,
		l_int32 *	pspp,
		l_int32 *	piscmap
	)

sreadHeaderPng()

Input: data &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error

Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.

Definition at line 430 of file pngio.c.

References convertOnLittleEnd16(), convertOnLittleEnd32(), ERROR_INT, and PROCNAME.

Referenced by freadHeaderPng(), and pixReadHeaderMem().

l_int32 fgetPngResolution	(	FILE *	fp,
		l_int32 *	pxres,
		l_int32 *	pyres
	)

Definition at line 497 of file pngio.c.

References ERROR_INT, NULL, and PROCNAME.

l_int32 pixWritePng	(	const char *	filename,
		PIX *	pix,
		l_float32	gamma
	)

pixWritePng()

Input: filename pix gamma Return: 0 if OK; 1 on error

Notes: (1) Special version for writing png with a specified gamma. When using pixWrite(), no field is given for gamma.

Definition at line 561 of file pngio.c.

References ERROR_INT, fopenWriteStream(), NULL, pixWriteStreamPng(), and PROCNAME.

Referenced by pixWriteRGBAPng().

l_int32 pixWriteStreamPng	(	FILE *	fp,
		PIX *	pix,
		l_float32	gamma
	)

pixWriteStreamPng()

Input: stream pix gamma (use 0.0 if gamma is not defined) Return: 0 if OK; 1 on error

Notes: (1) If called from pixWriteStream(), the stream is positioned at the beginning of the file. (2) To do sequential writes of png format images to a stream, use pixWriteStreamPng() directly. (3) gamma is an optional png chunk. If no gamma value is to be placed into the file, use gamma = 0.0. Otherwise, if gamma > 0.0, its value is written into the header. (4) The use of gamma in png is highly problematic. For an illuminating discussion, see: http://hsivonen.iki.fi/png-gamma/ (5) What is the effect/meaning of gamma in the png file? This gamma, which we can call the 'source' gamma, is the inverse of the gamma that was used in enhance.c to brighten or darken images. The 'source' gamma is supposed to indicate the intensity mapping that was done at the time the image was captured. Display programs typically apply a 'display' gamma of 2.2 to the output, which is intended to linearize the intensity based on the response of thermionic tubes (CRTs). Flat panel LCDs have typically been designed to give a similar response as CRTs (call it "backward compatibility"). The 'display' gamma is in some sense the inverse of the 'source' gamma. jpeg encoders attached to scanners and cameras will lighten the pixels, applying a gamma corresponding to approximately a square-root relation of output vs input: output = input^(gamma) where gamma is often set near 0.4545 (1/gamma is 2.2). This is stored in the image file. Then if the display program reads the gamma, it will apply a display gamma, typically about 2.2; the product is 1.0, and the display program produces a linear output. This works because the dark colors were appropriately boosted by the scanner, as described by the 'source' gamma, so they should not be further boosted by the display program. (6) As an example, with xv and display, if no gamma is stored, the program acts as if gamma were 0.4545, multiplies this by 2.2, and does a linear rendering. Taking this as a baseline brightness, if the stored gamma is: > 0.4545, the image is rendered lighter than baseline < 0.4545, the image is rendered darker than baseline In contrast, gqview seems to ignore the gamma chunk in png. (7) The only valid pixel depths in leptonica are 1, 2, 4, 8, 16 and 32. However, it is possible, and in some cases desirable, to write out a png file using an rgb pix that has 24 bpp. For example, the open source xpdf SplashBitmap class generates 24 bpp rgb images. Consequently, we anble writing 24 bpp pix. To generate such a pix, you can make a 24 bpp pix without data and assign the data array to the pix; e.g., pix = pixCreateHeader(w, h, 24); pixSetData(pix, rgbdata); See pixConvert32To24() for an example, where we get rgbdata from the 32 bpp pix. Caution: do not call pixSetPadBits(), because the alignment is wrong and you may erase part of the last pixel on each line.

Definition at line 651 of file pngio.c.

References PixColormap::array, CALLOC, COLOR_BLUE, COLOR_GREEN, COLOR_RED, ERROR_INT, FREE, GET_DATA_BYTE, L_ALPHA_CHANNEL, NULL, pixcmapGetCount(), pixcmapToArrays(), pixDestroy(), pixEndianByteSwap(), pixEndianByteSwapNew(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetHeight(), pixGetText(), pixGetWidth(), pixGetWpl(), pixGetXRes(), pixGetYRes(), pixInvert(), PROCNAME, var_PNG_WRITE_ALPHA, var_ZLIB_COMPRESSION, and x0.

Referenced by pixaWriteStream(), pixWritePng(), and pixWriteStream().

PIX* pixReadRGBAPng ( const char * filename )

pixReadRGBAPng()

Input: filename (of png file) Return: pix, or null on error

Notes: (1) Wrapper to keep the alpha channel of a png, if it exists. (2) The default behavior of pix read functions is to ignore the alpha channel. (3) This always leaves alpha stripping in the same mode as when this function begins. So if alpha stripping is in default mode, this disables it, reads the file (including the alpha channel), and resets back to stripping. Otherwise, it leaves stripping disabled.

Definition at line 894 of file pngio.c.

References ERROR_PTR, FALSE, findFileFormat(), IFF_PNG, ImageFileFormatExtensions, L_ERROR, L_ERROR_STRING, l_pngSetStripAlpha(), NULL, pixRead(), PROCNAME, and var_PNG_STRIP_ALPHA.

l_int32 pixWriteRGBAPng	(	const char *	filename,
		PIX *	pix
	)

pixWriteRGBAPng()

Input: filename pix (rgba) Return: 0 if OK, 1 on error

Notes: (1) Wrapper to write the alpha sample of a 32 bpp pix to a png file in rgba format. (2) The default behavior of pix write to png is to ignore the alpha sample. (3) This always leaves alpha writing in the same mode as when this function begins. So if alpha writing is in default mode, this enables it, writes out a rgba png file that includes the alpha channel, and resets to default. Otherwise, it leaves alpha writing enabled.

Definition at line 943 of file pngio.c.

References ERROR_INT, IFF_PNG, l_pngSetWriteAlpha(), pixWrite(), pixWritePng(), PROCNAME, TRUE, and var_PNG_WRITE_ALPHA.

Referenced by main().

void l_pngSetStrip16To8 ( l_int32 flag )

l_pngSetStrip16To8()

Input: flag (1 for stripping 16 bpp to 8 bpp; 0 for leaving 16 bpp) Return: void

Definition at line 976 of file pngio.c.

References var_PNG_STRIP_16_TO_8.

Referenced by main().

void l_pngSetStripAlpha ( l_int32 flag )

l_pngSetStripAlpha()

Input: flag (1 for stripping alpha channel on read; 0 for leaving it) Return: void

Definition at line 989 of file pngio.c.

References var_PNG_STRIP_ALPHA.

Referenced by main(), and pixReadRGBAPng().

void l_pngSetWriteAlpha ( l_int32 flag )

l_pngSetWriteAlpha()

Input: flag (1 for writing alpha channel; 0 for just writing rgb) Return: void

Definition at line 1002 of file pngio.c.

References var_PNG_WRITE_ALPHA.

Referenced by main(), and pixWriteRGBAPng().

void l_pngSetZlibCompression ( l_int32 val )

l_pngSetZlibCompression()

Input: val (zlib compression value) Return: void

Notes: (1) Valid zlib compression values are in the interval [0 ... 9], where, as defined in zlib.h: 0 Z_NO_COMPRESSION 1 Z_BEST_SPEED (poorest compression) 9 Z_BEST_COMPRESSION For the default value, use either of these: 6 Z_DEFAULT_COMPRESSION -1 (resolves to Z_DEFAULT_COMPRESSION) (2) If you use the defined constants in zlib.h instead of the compression integers given above, you must include zlib.h.

Definition at line 1027 of file pngio.c.

References L_ERROR, PROCNAME, and var_ZLIB_COMPRESSION.