|
PIX * | pixReadStreamPng (FILE *fp) |
|
l_ok | readHeaderPng (const char *filename, l_int32 *pw, l_int32 *ph, l_int32 *pbps, l_int32 *pspp, l_int32 *piscmap) |
|
l_ok | freadHeaderPng (FILE *fp, l_int32 *pw, l_int32 *ph, l_int32 *pbps, l_int32 *pspp, l_int32 *piscmap) |
|
l_ok | readHeaderMemPng (const l_uint8 *data, size_t size, l_int32 *pw, l_int32 *ph, l_int32 *pbps, l_int32 *pspp, l_int32 *piscmap) |
|
l_int32 | fgetPngResolution (FILE *fp, l_int32 *pxres, l_int32 *pyres) |
|
l_ok | isPngInterlaced (const char *filename, l_int32 *pinterlaced) |
|
l_ok | fgetPngColormapInfo (FILE *fp, PIXCMAP **pcmap, l_int32 *ptransparency) |
|
l_ok | pixWritePng (const char *filename, PIX *pix, l_float32 gamma) |
|
l_ok | pixWriteStreamPng (FILE *fp, PIX *pix, l_float32 gamma) |
|
l_ok | pixSetZlibCompression (PIX *pix, l_int32 compval) |
|
void | l_pngSetReadStrip16To8 (l_int32 flag) |
|
static void | memio_png_write_data (png_structp png_ptr, png_bytep data, png_size_t length) |
|
static void | memio_png_flush (MEMIODATA *pthing) |
|
static void | memio_png_read_data (png_structp png_ptr, png_bytep outBytes, png_size_t byteCountToRead) |
|
static void | memio_free (MEMIODATA *pthing) |
|
PIX * | pixReadMemPng (const l_uint8 *filedata, size_t filesize) |
|
l_ok | pixWriteMemPng (l_uint8 **pfiledata, size_t *pfilesize, PIX *pix, l_float32 gamma) |
|
Reading png through stream
PIX *pixReadStreamPng()
Reading png header
l_int32 readHeaderPng()
l_int32 freadHeaderPng()
l_int32 readHeaderMemPng()
Reading png metadata
l_int32 fgetPngResolution()
l_int32 isPngInterlaced()
l_int32 fgetPngColormapInfo()
Writing png through stream
l_int32 pixWritePng() [ special top level ]
l_int32 pixWriteStreamPng()
l_int32 pixSetZlibCompression()
Set flag for special read mode
void l_pngSetReadStrip16To8()
Low-level memio utility (thanks to T. D. Hintz)
static void memio_png_write_data()
static void memio_png_flush()
static void memio_png_read_data()
static void memio_free()
Reading png from memory
PIX *pixReadMemPng()
Writing png to memory
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".
For reading and writing rgb and rgba images, we read and write
alpha if it exists (spp == 4) and do not read or write if
it doesn't (spp == 3). The alpha component can be 'removed'
simply by setting spp to 3. In leptonica, we make relatively
little explicit use of the alpha sample. Note that the alpha
sample in the image is also called "alpha transparency",
"alpha component" and "alpha layer."
To change the zlib compression level, use pixSetZlibCompression()
before writing the file. The 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
Note that if you are using the defined constants in zlib instead
of the compression integers given above, you must include zlib.h.
There is global for determining the size of retained samples:
var_PNG_STRIP_16_to_8
and a function l_pngSetReadStrip16To8() for setting it.
The default is TRUE, which causes pixRead() to strip 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
If the variable is set to FALSE, the 16 bit gray samples
are saved when read; the 16 bit rgb samples return an error.
Note: results can be non-deterministic if used with
multi-threaded applications.
Thanks to a memory buffering utility contributed by T. D. Hintz,
encoding png directly into memory (and decoding from memory)
is now enabled without the use of any temp files. Unlike with webp,
it is necessary to preserve the stream interface to enable writing
pixa to memory. So there are two independent but very similar
implementations of png reading and writing.
Definition in file pngio.c.
l_ok pixWriteStreamPng |
( |
FILE * |
fp, |
|
|
PIX * |
pix, |
|
|
l_float32 |
gamma |
|
) |
| |
pixWriteStreamPng()
- Parameters
-
[in] | fp | file stream |
[in] | pix | |
[in] | gamma | use 0.0 if gamma is not defined |
- Returns
- 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 enable 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.
(8) If the pix has a colormap, it is written to file. In most
situations, the alpha component is 255 for each colormap entry,
which is opaque and indicates that it should be ignored.
However, if any alpha component is not 255, it is assumed that
the alpha values are valid, and they are written to the png
file in a tRNS segment. On readback, the tRNS segment is
identified, and the colormapped image with alpha is converted
to a 4 spp rgba image.
Definition at line 1072 of file pngio.c.
Referenced by pixaWriteStream(), and pixWritePng().