#include <string.h>
#include "allheaders.h"
#include <setjmp.h>
#include "jpeglib.h"

Data Structures
struct	callback_data

Macros
#define	DEBUG_INFO 0

Functions
static void	jpeg_error_catch_all_1 (j_common_ptr cinfo)

static void	jpeg_error_catch_all_2 (j_common_ptr cinfo)

static l_uint8	jpeg_getc (j_decompress_ptr cinfo)

static boolean	jpeg_comment_callback (j_decompress_ptr cinfo)

PIX *	pixReadJpeg (const char filename, l_int32 cmapflag, l_int32 reduction, l_int32 pnwarn, l_int32 hint)

PIX *	pixReadStreamJpeg (FILE fp, l_int32 cmapflag, l_int32 reduction, l_int32 pnwarn, l_int32 hint)

l_ok	readHeaderJpeg (const char filename, l_int32 pw, l_int32 ph, l_int32 pspp, l_int32 pycck, l_int32 pcmyk)

l_ok	freadHeaderJpeg (FILE fp, l_int32 pw, l_int32 ph, l_int32 pspp, l_int32 pycck, l_int32 pcmyk)

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

l_int32	fgetJpegComment (FILE fp, l_uint8 *pcomment)

l_ok	pixWriteJpeg (const char filename, PIX pix, l_int32 quality, l_int32 progressive)

l_ok	pixWriteStreamJpeg (FILE fp, PIX pixs, l_int32 quality, l_int32 progressive)

PIX *	pixReadMemJpeg (const l_uint8 data, size_t size, l_int32 cmflag, l_int32 reduction, l_int32 pnwarn, l_int32 hint)

l_ok	readHeaderMemJpeg (const l_uint8 data, size_t size, l_int32 pw, l_int32 ph, l_int32 pspp, l_int32 pycck, l_int32 pcmyk)

l_ok	readResolutionMemJpeg (const l_uint8 data, size_t size, l_int32 pxres, l_int32 *pyres)

l_ok	pixWriteMemJpeg (l_uint8 *pdata, size_t psize, PIX *pix, l_int32 quality, l_int32 progressive)

l_ok	pixSetChromaSampling (PIX *pix, l_int32 sampling)

Detailed Description

   Read jpeg from file
         PIX             *pixReadJpeg()  [special top level]
         PIX             *pixReadStreamJpeg()

   Read jpeg metadata from file
         l_int32          readHeaderJpeg()
         l_int32          freadHeaderJpeg()
         l_int32          fgetJpegResolution()
         l_int32          fgetJpegComment()

   Write jpeg to file
         l_int32          pixWriteJpeg()  [special top level]
         l_int32          pixWriteStreamJpeg()

   Read/write to memory
         PIX             *pixReadMemJpeg()
         l_int32          readHeaderMemJpeg()
         l_int32          readResolutionMemJpeg()
         l_int32          pixWriteMemJpeg()

   Setting special flag for chroma sampling on write
         l_int32          pixSetChromaSampling()

   Static system helpers
         static void      jpeg_error_catch_all_1()
         static void      jpeg_error_catch_all_2()
         static l_uint8   jpeg_getc()
         static l_int32   jpeg_comment_callback()

   Documentation: libjpeg.doc can be found, along with all
   source code, at ftp://ftp.uu.net/graphics/jpeg
   Download and untar the file:  jpegsrc.v6b.tar.gz
   A good paper on jpeg can also be found there: wallace.ps.gz

   The functions in libjpeg make it very simple to compress
   and decompress images.  On input (decompression from file),
   3 component color images can be read into either an 8 bpp Pix
   with a colormap or a 32 bpp Pix with RGB components.  For output
   (compression to file), all color Pix, whether 8 bpp with a
   colormap or 32 bpp, are written compressed as a set of three
   8 bpp (rgb) images.

Low-level error handling

   The default behavior of the jpeg library is to call exit.
   This is often undesirable, and the caller should make the
   decision when to abort a process.  To prevent the jpeg library
   from calling exit(), setjmp() has been inserted into all
   readers and writers, and the cinfo struct has been set up so that
   the low-level jpeg library will call a special error handler
   that doesn't exit, instead of the default function error_exit().

   To avoid race conditions and make these functions thread-safe in
   the rare situation where calls to two threads are simultaneously
   failing on bad jpegs, we insert a local copy of the jmp_buf struct
   into the cinfo.client_data field, and use this on longjmp.
   For extracting the jpeg comment, we have the added complication
   that the client_data field must also return the jpeg comment,
   and we use a different error handler.

How to avoid subsampling the chroma channels

   When writing, you can avoid subsampling the U,V (chroma)
   channels.  This gives higher quality for the color, which is
   important for some situations.  The default subsampling is 2x2 on
   both channels.  Before writing, call pixSetChromaSampling(pix, 0)
   to prevent chroma subsampling.

How to extract just the luminance channel in reading RGB

   For higher resolution and faster decoding of an RGB image, you
   can extract just the 8 bpp luminance channel, using pixReadJpeg(),
   where you use L_JPEG_READ_LUMINANCE for the hint arg.

How to fail to read if the data is corrupted

   By default, if the low-level jpeg library functions do not abort,
   a pix will be returned, even if the data is corrupted and warnings
   are issued.  In order to be most likely to fail to read when there
   is data corruption, use L_JPEG_FAIL_ON_BAD_DATA in the hint arg.

Compressing to memory and decompressing from memory

   On systems like windows without fmemopen() and open_memstream(),
   we write data to a temp file and read it back for operations
   between pix and compressed-data, such as pixReadMemJpeg() and
   pixWriteMemJpeg().

Vestigial code: parsing the jpeg file for header metadata

   For extracting header metadata, we previously parsed the file, looking
   for specific markers.  This is error-prone because of non-standard
   jpeg files, and we now use readHeaderJpeg() and readHeaderMemJpeg().
   The vestigial code is retained in jpegio_notused.c to help you
   understand a bit about how to parse jpeg markers.  It is not compiled
   into the library.

Definition in file jpegio.c.

Function Documentation

◆ freadHeaderJpeg()

l_ok freadHeaderJpeg	(	FILE *	fp,
		l_int32 *	pw,
		l_int32 *	ph,
		l_int32 *	pspp,
		l_int32 *	pycck,
		l_int32 *	pcmyk
	)

freadHeaderJpeg()

Parameters

[in]	fp	file stream
[out]	pw	[optional]
[out]	ph	[optional]
[out]	pspp	[optional] samples/pixel
[out]	pycck	[optional] 1 if ycck color space; 0 otherwise
[out]	pcmyk	[optional] 1 if cmyk color space; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 549 of file jpegio.c.

References jpeg_error_catch_all_1().

Referenced by readHeaderJpeg(), and readHeaderMemJpeg().

◆ jpeg_comment_callback()

static boolean jpeg_comment_callback ( j_decompress_ptr cinfo )

static

jpeg_comment_callback()

Notes: (1) This is used to read the jpeg comment (JPEG_COM). See the note above the declaration for why it returns a "boolean".

Definition at line 1264 of file jpegio.c.

◆ jpeg_error_catch_all_1()

static void jpeg_error_catch_all_1 ( j_common_ptr cinfo )

static

jpeg_error_catch_all_1()

Notes: (1) The default jpeg error_exit() kills the process, but we never want a call to leptonica to kill a process. If you do want this behavior, remove the calls to these error handlers. (2) This is used where cinfo->client_data holds only jmpbuf.

Definition at line 1210 of file jpegio.c.

Referenced by freadHeaderJpeg(), and pixReadStreamJpeg().

◆ jpeg_error_catch_all_2()

static void jpeg_error_catch_all_2 ( j_common_ptr cinfo )

static

jpeg_error_catch_all_2()

Notes: (1) This is used where cinfo->client_data needs to hold both the jmpbuf and the jpeg comment data. (2) On error, the comment data will be freed by the caller.

Definition at line 1228 of file jpegio.c.

◆ pixReadJpeg()

PIX* pixReadJpeg	(	const char *	filename,
		l_int32	cmapflag,
		l_int32	reduction,
		l_int32 *	pnwarn,
		l_int32	hint
	)

pixReadJpeg()

Parameters

[in]	filename
[in]	cmapflag	0 for no colormap in returned pix; 1 to return an 8 bpp cmapped pix if spp = 3 or 4
[in]	reduction	scaling factor: 1, 2, 4 or 8
[out]	pnwarn	[optional] number of warnings about corrupted data
[in]	hint	a bitwise OR of L_JPEG_* values; 0 for default

Returns: pix, or NULL on error

Notes:
     (1) This is a special function for reading jpeg files.
     (2) Use this if you want the jpeg library to create
         an 8 bpp colormapped image.
     (3) Images reduced by factors of 2, 4 or 8 can be returned
         significantly faster than full resolution images.
     (4) If the jpeg data is bad, the jpeg library will continue
         silently, or return warnings, or attempt to exit.  Depending
         on the severity of the data corruption, there are two possible
         outcomes:
         (a) a possibly damaged pix can be generated, along with zero
             or more warnings, or
         (b) the library will attempt to exit (caught by our error
             handler) and no pix will be returned.
         If a pix is generated with at least one warning of data
         corruption, and if L_JPEG_FAIL_ON_BAD_DATA is included in hint,
         no pix will be returned.
     (5) The possible hint values are given in the enum in imageio.h:
           * L_JPEG_READ_LUMINANCE
           * L_JPEG_FAIL_ON_BAD_DATA
         Default (0) is to do neither.

Definition at line 214 of file jpegio.c.

References fopenReadStream(), and pixReadStreamJpeg().

◆ pixReadMemJpeg()

PIX* pixReadMemJpeg	(	const l_uint8 *	data,
		size_t	size,
		l_int32	cmflag,
		l_int32	reduction,
		l_int32 *	pnwarn,
		l_int32	hint
	)

pixReadMemJpeg()

Parameters

[in]	data	const; jpeg-encoded
[in]	size	of data
[in]	cmflag	colormap flag 0 means return RGB image if color; 1 means create a colormap and return an 8 bpp colormapped image if color
[in]	reduction	scaling factor: 1, 2, 4 or 8
[out]	pnwarn	[optional] number of warnings
[in]	hint	a bitwise OR of L_JPEG_* values; 0 for default

Returns: pix, or NULL on error

Notes:
     (1) The size byte of data must be a null character.
     (2) The only hint flag so far is L_JPEG_READ_LUMINANCE,
         given in the enum in imageio.h.
     (3) See pixReadJpeg() for usage.

Definition at line 991 of file jpegio.c.

References fopenReadFromMemory(), and pixReadStreamJpeg().

◆ pixReadStreamJpeg()

PIX* pixReadStreamJpeg	(	FILE *	fp,
		l_int32	cmapflag,
		l_int32	reduction,
		l_int32 *	pnwarn,
		l_int32	hint
	)

pixReadStreamJpeg()

Parameters

[in]	fp	file stream
[in]	cmapflag	0 for no colormap in returned pix; 1 to return an 8 bpp cmapped pix if spp = 3 or 4
[in]	reduction	scaling factor: 1, 2, 4 or 8
[out]	pnwarn	[optional] number of warnings
[in]	hint	a bitwise OR of L_JPEG_* values; 0 for default

Returns: pix, or NULL on error

Usage: see pixReadJpeg

Notes:
     (1) The jpeg comment, if it exists, is not stored in the pix.

Definition at line 270 of file jpegio.c.

References jpeg_error_catch_all_1(), L_JPEG_READ_LUMINANCE, pixCreate(), and pixDestroy().

Referenced by pixReadJpeg(), and pixReadMemJpeg().

◆ pixSetChromaSampling()

l_ok pixSetChromaSampling	(	PIX *	pix,
		l_int32	sampling
	)

pixSetChromaSampling()

Parameters

[in]	pix
[in]	sampling	1 for subsampling; 0 for no subsampling

Returns: 0 if OK, 1 on error

Notes:
     (1) The default is for 2x2 chroma subsampling because the files are
         considerably smaller and the appearance is typically satisfactory.
         To get full resolution output in the chroma channels for
         jpeg writing, call this with sampling == 0.

Definition at line 1182 of file jpegio.c.

◆ pixWriteJpeg()

l_ok pixWriteJpeg	(	const char *	filename,
		PIX *	pix,
		l_int32	quality,
		l_int32	progressive
	)

pixWriteJpeg()

Parameters

[in]	filename
[in]	pix	any depth; cmap is OK
[in]	quality	1 - 100; 75 is default
[in]	progressive	0 for baseline sequential; 1 for progressive

Returns: 0 if OK; 1 on error

Definition at line 732 of file jpegio.c.

References fopenWriteStream(), and pixWriteStreamJpeg().

◆ pixWriteMemJpeg()

l_ok pixWriteMemJpeg	(	l_uint8 **	pdata,
		size_t *	psize,
		PIX *	pix,
		l_int32	quality,
		l_int32	progressive
	)

pixWriteMemJpeg()

Parameters

[out]	pdata	data of jpeg compressed image
[out]	psize	size of returned data
[in]	pix	any depth; cmap is OK
[in]	quality	1 - 100; 75 is default value; 0 is also default
[in]	progressive	0 for baseline sequential; 1 for progressive

Returns: 0 if OK, 1 on error

Notes:
     (1) See pixWriteStreamJpeg() for usage.  This version writes to
         memory instead of to a file stream.

Definition at line 1121 of file jpegio.c.

References fopenWriteWinTempfile(), l_binaryReadStream(), and pixWriteStreamJpeg().

◆ pixWriteStreamJpeg()

l_ok pixWriteStreamJpeg	(	FILE *	fp,
		PIX *	pixs,
		l_int32	quality,
		l_int32	progressive
	)

pixWriteStreamJpeg()

Parameters

[in]	fp	file stream
[in]	pixs	any depth; cmap is OK
[in]	quality	1 - 100; 75 is default value; 0 is also default
[in]	progressive	0 for baseline sequential; 1 for progressive

Returns: 0 if OK, 1 on error

Notes:
     (1) Progressive encoding gives better compression, at the
         expense of slower encoding and decoding.
     (2) Standard chroma subsampling is 2x2 on both the U and V
         channels.  For highest quality, use no subsampling; this
         option is set by pixSetChromaSampling(pix, 0).
     (3) The only valid pixel depths in leptonica are 1, 2, 4, 8, 16
         and 32 bpp.  However, it is possible, and in some cases desirable,
         to write out a jpeg file using an rgb pix that has 24 bpp.
         This can be created by appending the raster data for a 24 bpp
         image (with proper scanline padding) directly to a 24 bpp
         pix that was created without a data array.
     (4) There are two compression paths in this function:
         * Grayscale image, no colormap: compress as 8 bpp image.
         * rgb full color image: copy each line into the color
           line buffer, and compress as three 8 bpp images.
     (5) Under the covers, the jpeg library transforms rgb to a
         luminance-chromaticity triple, each component of which is
         also 8 bits, and compresses that.  It uses 2 Huffman tables,
         a higher resolution one (with more quantization levels)
         for luminosity and a lower resolution one for the chromas.

Definition at line 793 of file jpegio.c.

References pixGetDimensions().

Referenced by pixWriteJpeg(), and pixWriteMemJpeg().

◆ readHeaderJpeg()

l_ok readHeaderJpeg	(	const char *	filename,
		l_int32 *	pw,
		l_int32 *	ph,
		l_int32 *	pspp,
		l_int32 *	pycck,
		l_int32 *	pcmyk
	)

readHeaderJpeg()

Parameters

[in]	filename
[out]	pw	[optional]
[out]	ph	[optional]
[out]	pspp	[optional] samples/pixel
[out]	pycck	[optional] 1 if ycck color space; 0 otherwise
[out]	pcmyk	[optional] 1 if cmyk color space; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 507 of file jpegio.c.

References fopenReadStream(), and freadHeaderJpeg().

◆ readHeaderMemJpeg()

l_ok readHeaderMemJpeg	(	const l_uint8 *	data,
		size_t	size,
		l_int32 *	pw,
		l_int32 *	ph,
		l_int32 *	pspp,
		l_int32 *	pycck,
		l_int32 *	pcmyk
	)

readHeaderMemJpeg()

Parameters

[in]	data	const; jpeg-encoded
[in]	size	of data
[out]	pw	[optional] width
[out]	ph	[optional] height
[out]	pspp	[optional] samples/pixel
[out]	pycck	[optional] 1 if ycck color space; 0 otherwise
[out]	pcmyk	[optional] 1 if cmyk color space; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 1038 of file jpegio.c.

References fopenReadFromMemory(), and freadHeaderJpeg().

Referenced by l_generateJpegDataMem().

◆ readResolutionMemJpeg()

l_ok readResolutionMemJpeg	(	const l_uint8 *	data,
		size_t	size,
		l_int32 *	pxres,
		l_int32 *	pyres
	)

readResolutionMemJpeg()

Parameters

[in]	data	const; jpeg-encoded
[in]	size	of data
[out]	pxres	[optional]
[out]	pyres	[optional]

Returns: 0 if OK, 1 on error

Definition at line 1079 of file jpegio.c.

References fopenReadFromMemory().

Referenced by l_generateJpegDataMem().

Data Structures

Macros

Functions

Detailed Description

Low-level error handling

How to avoid subsampling the chroma channels

How to extract just the luminance channel in reading RGB

How to fail to read if the data is corrupted

Compressing to memory and decompressing from memory

Vestigial code: parsing the jpeg file for header metadata

Function Documentation

◆ freadHeaderJpeg()

◆ jpeg_comment_callback()

◆ jpeg_error_catch_all_1()

◆ jpeg_error_catch_all_2()

◆ pixReadJpeg()

◆ pixReadMemJpeg()

◆ pixReadStreamJpeg()

◆ pixSetChromaSampling()

◆ pixWriteJpeg()

◆ pixWriteMemJpeg()

◆ pixWriteStreamJpeg()

◆ readHeaderJpeg()

◆ readHeaderMemJpeg()

◆ readResolutionMemJpeg()