iflJFIF(3) Image Format Library C++ Reference Manual iflJFIF(3)NAMEiflJFIF - a JFIF formatted image file
HEADER FILE
#include <ifl/iflJFIF.h>
DESCRIPTION
This IFL format provides support for reading and writing image files with
the JFIF format, Version 4. This software is based in part on the work of
the Independent JPEG Group. This format implements JPEG image compression
and decompression. JPEG is intended for compressing "real-world" scenes;
cartoons and other non-realistic images are not its strong suit. JPEG is
lossy, meaning that the output image is not necessarily identical to the
input image. Hence you must not use JPEG if you have to have identical
output bits. However, on typical images of real-world scenes, very good
compression levels can be obtained with no visible change, and amazingly
high compression levels are possible if you can tolerate a low-quality
image. For more details, see the references, or just experiment with
various compression settings. JFIF implements JPEG baseline and
extended-sequential compression processes. Provision is made for
supporting all variants of these processes, although some uncommon
parameter settings aren't implemented yet. For legal reasons, the
arithmetic-coding process is not implemented. At present no provision is
made for supporting the progressive, hierarchical, or lossless processes
defined in the standard.
This format is always of type iflUChar and can be one of three color
models: iflMinBlack, iflRGB or iflCMYK. Its order is always
iflInterleaved and the orientation is iflUpperLeftOrigin. Its page size
is forced to be the size of the image. Hence this format is not tiled. So
even if one is just reading or writing a small portion of the image, the
entire image will be read or written. If you wish to have tiled JPEG
compressed data use the iflTIFF format.
A number of tag values are available to set/query encoding/decoding
parameters with the getItem() and setItem() methods. Normally for
creating or reading images in general use, the default values of these
parametrs are quite sufficient and one would not need to use these
methods.
While encoding, i.e. creating a JPEG file, iflJFIFcompressionQuality can
be used to set/query the compression quality; iflJFIFgrayScaleEncoding
can be used to create a monochrome JPEG file from a color input.
iflJFIFenableOptHuffTab can be used to enable optimization of entropy
encoding parameters. Advanced users can use iflJFIFrestartInterval to
emit a restart marker after a specified number of MCU rows or blocks; can
use iflJFIFsmoothingFactor to smooth the input to eliminate dithering
noise. Absolute wizards can use iflJFIFqTable to specify their own
quantization tables; siflJFIFsamplingFactors can be used to set/get the
horizontal and vertical sampling factors of the different components. The
"wizard" switches are intended for experimentation with JPEG. If you
don't know what you are doing, don't use them. You can easily produce
Page 1
iflJFIF(3) Image Format Library C++ Reference Manual iflJFIF(3)
files with worse image quality and/or poorer compression than you'll get
from the default settings. Furthermore, these switches should not be used
when making files intended for general use, because not all JPEG
implementations will support unusual JPEG parameter settings.
While decoding advanced users can use iflJFIFblockSmoothing to perform
cross block smoothing; iflJFIFgrayScaleDecoding can be used to force
gray-scale output even if JPEG file is color.
The environment variable JPEGMEM can be used to set the limit for amount
of memory to use in processing large images. Value is in thousands of
bytes, or millions of bytes if "M" is attached to the number. For
example, setting JPEGMEM to 4m selects 4000000 bytes. If you get an
"insufficient memory" error, try specifying a smaller memory value, even
0 to use the absolute minimum space. For most cases you would not need to
set JPEGMEM.
The default extension for image files in the JFIF format is '.jpg'. When
you create a file with that extension IFL will assume you want the JFIF
format, unless you override it with the iflFormat parameter.
TAG VALUES FOR GET ITEM
The followng tag values are supported with getItem():
iflJFIFcompressionQuality
iflStatus getItem(iflJFIFcompressionQuality, int* val)
This function returns the value of the quality factor used in encoding or
creating the JFIF image file. The "quality factor" is the amount by which
quantization tables are scaled to adjust image quality.
iflJFIFrestartInterval
iflStatus getItem(iflJFIFrestartInterval, int* val)
This function returns the value of the restart interval used in encoding
or creating the JFIF image file. This is the interval at which a JPEG
restart marker is emitted. This interval is either in number of MCU rows
or blocks.
iflJFIFqTable
iflStatus getItem(iflJFIFqTable, char** qtablefile)
This function returns the filename from which the custom quantization
tables were read. These are tables used in encoding or creating the JFIF
image file. If default tables were used, NULL is returned.
iflJFIFsamplingFactors
Page 2
iflJFIF(3) Image Format Library C++ Reference Manual iflJFIF(3)
iflStatus getItem(iflJFIFsamplingFactors,
* horiz, int* vert, int ch)
The horizontal and vertical sampling factors used (in encoding or
creating the JFIF image file) for channel ch are returned in horiz and
vert.
iflJFIFsmoothingFactor
iflStatus getItem(iflJFIFsmoothingFactor, int* val)
This function returns the value of the smoothing factor, used to
eliminate dithering noise while encoding or creating the JFIF image file.
The value ranging from 0 to 100, indicates the strength of smoothing.
Zero means no smoothing.
iflJFIFblockSmoothing
iflStatus getItem(iflJFIFblockSmoothing, int* on)
This function returns TRUE if cross-block smoothing (a decoding
parameter) is enabled; FALSE otherwise.
iflJFIFgrayScaleDecoding
iflStatus getItem(iflJFIFgrayScaleDecoding, int* on)
This function returns TRUE if grayscale decoding is enabled i.e.a color
file is read as a monochrome image; FALSE otherwise.
iflJFIFgrayScaleEncoding
iflStatus getItem(iflJFIFgrayScaleEncoding, int* on)
This function returns TRUE if grayscale encoding is enabled i.e.a
monochrome JFIF file is created from a color input; FALSE otherwise.
iflJFIFenableOptHuffTab
iflStatus getItem(iflJFIFenableOptHuffTab, int* on)
This function returns TRUE if optimization of entropy encoding parameters
is enabled; FALSE otherwise.
TAG VALUES FOR SET ITEM
The followng tag values are supported with setItem():
iflJFIFblockSmoothing
iflStatus setItem(iflJFIFblockSmoothing, int on)
Page 3
iflJFIF(3) Image Format Library C++ Reference Manual iflJFIF(3)
This function can be used to enable cross-block smoothing while decoding
or reading a JFIF image file, by setting on = TRUE. This is quite
memory-intensive and only seems to improve the image at very low quality
settings (compression quality of 10 to 20 or so). At normal quality
settings it may make things worse. By default cross-block smoothing is
disabled, on = FALSE. This functionality is meant for advanced users with
some knowledge of JPEG.
iflJFIFgrayScaleDecoding
iflStatus setItem(iflJFIFgrayScaleDecoding, int on)
This function can be used to force a JFIF color file to be read as a
monochrome image (i.e. iflRGB color space is converted to iflMinBlack),
by setting on = TRUE.
iflJFIFgrayScaleEncoding
iflStatus setItem(iflJFIFgrayScaleEncoding, int on)
This method can be used to enable creation of a monochrome JFIF image
file from a color (ilRGB) input, by setting on = TRUE. By default this
functionality is disabled and a color input produces a color output. This
functionality is meant for advanced users with some knowledge of JPEG.
iflJFIFenableOptHuffTab
iflStatus setItem(iflJFIFenableOptHuffTab, int on)
This method can be used to enable optimization of entropy encoding
parameters, used while encoding or creating a JFIF image file, by setting
on = TRUE. By default this optimization is not enabled and default
encoding parameters are used. Enabling the optimization usually makes
the JPEG file a little smaller, but the compression runs somewhat slower
and needs much more memory. Image quality and speed of decompression are
unaffected by enabling optimization.
iflJFIFcompressionQuality
iflStatus setItem(iflJFIFcompressionQuality, int val)
This function sets the quality factor used in encoding or creating a JFIF
image file to val. val can range from 0 (worst) to 100 (best), default is
75. The quality factor lets you trade off compressed file size against
quality of the reconstructed image: the higher the quality setting, the
larger the JPEG file, and the closer the output image will be to the
original input. Normally you want to use the lowest quality setting
(smallest file) that decompresses into something visually
indistinguishable from the original image. For this purpose the quality
setting should be between 50 and 95; the default of 75 is often about
right. If you see defects at 75, then go up 5 or 10 counts at a time
until you are happy with the output image; The optimal setting will vary
Page 4
iflJFIF(3) Image Format Library C++ Reference Manual iflJFIF(3)
from one image to another.
iflJFIFqTable
iflStatus setItem(iflJFIFqTable, char* qtablefile)
This function can be used to set the quantization tables to be used in
the encoding process to those in the file qtablefile. The file should
contain one to four tables (64 values each) as plain text. Comments
preceded by '#' may be included in the file. The tables are implicitly
numbered 0,1,etc. If a non-zero quality factor is also specified, the
values in the file are scaled according to a quality scaling curve. If
qtablefile = NULL, default tables are used. This function is meant for
wizards with indepth knowledge of JPEG.
iflJFIFrestartInterval
iflStatus setItem(iflJFIFrestartInterval, int val, int inRows)
This function is used to set the restart interval used in encoding or
creating the JFIF image file. If inRows = TRUE then a JPEG restart marker
is emitted every val MCU rows; else if inRows = FALSE, a JPEG restart
marker is emitted every val MCU blocks. The restart option inserts extra
markers that allow a JPEG decoder to resynchronize after a transmission
error. Without restart markers, any damage to a compressed file will
usually ruin the image from the point of the error to the end of the
image; with restart markers, the damage is usually confined to the
portion of the image up to the next restart marker. Of course, the
restart markers occupy extra space. We recommend val = 1 for images that
will be transmitted across unreliable networks such as Usenet. By default
no extra markers (val = 0) are emitted. This functionality is meant for
advanced users with some knowledge of JPEG.
iflJFIFsamplingFactors
iflStatus setItem(iflJFIFsamplingFactors,
int horiz, int vert, int ch)
This function can be used to set the JPEG sampling factors used in
creating a JFIF image file. The horizontal and vertical sampling for
channel ch are set to horiz and vert. This function is meant for wizards
with indepth knowledge of JPEG.
iflJFIFsmoothingFactor
iflStatus setItem(iflJFIFsmoothingFactor, int val)
This function sets the smoothing factor, useful in eliminating dithering
noise, to val. This is used while encoding or creating a JFIF image file.
val can range from 0 to 100, indicating the strength of smooting; 0, the
default means no smoothing. This smoothing option filters the input to
eliminate fine-scale noise. This is often useful when converting GIF
Page 5
iflJFIF(3) Image Format Library C++ Reference Manual iflJFIF(3)
files to JPEG: a moderate smoothing factor of 10 to 50 gets rid of
dithering patterns in the input file, resulting in a smaller JPEG file
and a better-looking image. Too large a smoothing factor will visibly
blur the image, however. This functionality is meant for advanced users
with some knowledge of JPEG.
SEE ALSO
iflFile, ilFileImg
The best short technical introduction to the JPEG compression algorithm
is: Wallace, Gregory K. "The JPEG Still Picture Compression Standard",
Communications of the ACM, April 1991 (vol. 34 no. 4), pp. 30-44.
(Adjacent articles in that issue discuss MPEG motion picture compression,
applications of JPEG, and related topics.) If you don't have the CACM
issue handy, a PostScript file containing a revised version of the
article is available at ftp.uu.net, graphics/jpeg/wallace.ps.Z. The file
(actually a preprint for an article to appear in IEEE Trans. Consumer
Electronics) omits the sample images that appeared in CACM, but it
includes corrections and some added material. Note: the Wallace article
is copyright ACM and IEEE, and it may not be used for commercial
purposes.
A somewhat less technical, more leisurely introduction to JPEG can be
found in "The Data Compression Book" by Mark Nelson, published by M&T
Books (Redwood City, CA), 1991, ISBN 1-55851-216-0. This book provides
good explanations and example C code for a multitude of compression
methods including JPEG. It is an excellent source if you are comfortable
reading C code but don't know much about data compression in general
A new textbook about JPEG is "JPEG Still Image Data Compression Standard"
by William B. Pennebaker and Joan L. Mitchell, published by Van Nostrand
Reinhold, 1993, ISBN 0-442-01272-1. This book includes the complete text
of the ISO JPEG standards (DIS 10918-1 and draft DIS 10918-2).
In the US, copies of the JPEG standard itself may be ordered from ANSI
Sales at (212) 642-4900.
The JPEG standard does not specify all details of an interchangeable file
format. For the omitted details the "JFIF" conventions, revision 1.02 is
followed. A copy of the JFIF spec is available from:
Literature Department
C-Cube Microsystems, Inc.
399A West Trimble Road
San Jose, CA 95131
(408) 944-6300
A PostScript version of this document is available at ftp.uu.net, file
graphics/jpeg/jfif.ps.Z. It can also be obtained by e-mail from the C-
Cube mail server, netlib@c3.pla.ca.us. Send the message "send jfif_ps
from jpeg" to the server to obtain the JFIF document; send the message
"help" if you have trouble.
Page 6
