ryan/mozjpeg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Various doc tweaks

Browse Source 
- "bits per component" = "bits per sample"

  Describing the data precision of a JPEG image using "bits per
  component" is technically correct, but "bits per sample" is the
  terminology that the JPEG-1 spec uses.  Also, "bits per component" is
  more commonly used to describe the precision of packed-pixel formats
  (as opposed to "bits per pixel") rather than planar formats, in which
  all components are grouped together.

- Unmention legacy display technologies.  Colormapped and monochrome
  displays aren't a thing anymore, and even when they were still a
  thing, it was possible to display full-color images to them.  In 1991,
  when JPEG decompression time was measured in minutes per megapixel, it
  made sense to keep a decompressed copy of JPEG images on disk, in a
  format that could be displayed without further color conversion (since
  color conversion was slow and memory-intensive.)  In 2024, JPEG
  decompression time is measured in milliseconds per megapixel, and
  color conversion is even faster.  Thus, JPEG images can be
  decompressed, displayed, and color-converted (if necessary) "on the
  fly" at speeds too fast for human vision to perceive.  (In fact, your
  TV performs much more complicated decompression algorithms at least 60
  times per second.)

- Document that color quantization (and associated features), GIF
  input/output, Targa input/output, and OS/2 BMP input/output are legacy
  features.  Legacy status doesn't necessarily mean that the features
  are deprecated.  Rather, it is meant to discourage users from using
  features that may be of little or no benefit on modern machines (such
  as low-quality modes that had significant performance advantages in
  the early 1990s but no longer do) and that are maintained on a
  break/fix basis only.

- General wordsmithing, grammar/punctuation policing, and formatting
  tweaks

- Clarify which data precisions each cjpeg input format and each djpeg
  output format supports.

- cjpeg.1: Remove unnecessary and impolitic statement about the -targa
  switch.

- Adjust or remove performance claims to reflect the fact that:
  * On modern machines, the djpeg "-fast" switch has a negligible effect
    on performance.
  * There is a measurable difference between the performance of Floyd-
    Steinberg dithering and no dithering, but it is not likely
    perceptible to most users.
  * There is a measurable difference between the performance of 1-pass
    and 2-pass color quantization, but it is not likely perceptible to
    most users.
  * There is a measurable difference between the performance of
    full-color and grayscale output when decompressing a full-color JPEG
    image, but it is not likely perceptible to most users.
  * IDCT scaling does not necessarily improve performance.  (It
    generally does if the scaling factor is <= 1/2 and generally doesn't
    if the scaling factor is > 1/2, at least on my machine.  The
    performance claim made in jpeg-6b was probably invalidated when we
    merged the additional scaling factors from jpeg-7.)

- Clarify which djpeg switches/output formats cannot be used when
  decompressing lossless JPEG images.

- Remove djpeg hints, since those involve quality vs. speed tradeoffs
  that are no longer relevant for modern machines.

- Remove documentation regarding using color quantization with 16-bit
  data precision.  (Color quantization requires lossy mode.)

- Java: Fix typos in TJDecompressor.decompress12() and
  TJDecompressor.decompress16() documentation.

- jpegtran.1: Fix truncated paragraph

  In a man page, a single quote at the start of a line is interpreted as
  a macro.

  Closes #775

- libjpeg.txt:
  * Mention J16SAMPLE data type (oversight.)
  * Remove statement about extending jdcolor.c.  (libjpeg-turbo is not
    quite as DIY as libjpeg once was.)
  * Remove paragraph about tweaking the various typedefs in jmorecfg.h.
    It is no longer relevant for modern machines.
  * Remove caveat regarding systems with ints less than 16 bits wide.
    (ANSI/ISO C requires an int to be at least 16 bits wide, and
    libjpeg-turbo has never supported non-ANSI compilers.)

- usage.txt:
  * Add copyright header.
  * Document cjpeg -icc, -memdst, -report, -strict, and -version
    switches.
  * Document djpeg -icc, -maxscans, -memsrc, -report, -skip, -crop,
    -strict, and -version switches.
  * Document jpegtran -icc, -maxscans, -report, -strict, and -version
    switches.
This commit is contained in:
DRC
2024-06-17 20:27:57 -04:00
parent 2c5312fd12
commit 94c64ead85
18 changed files with 383 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CMakeLists.txt
View File

@@ -309,12 +309,12 @@ endif()
# 1: + In-memory source/destination managers (libjpeg-turbo 1.3.x)
# 2: + Partial image decompression functions (libjpeg-turbo 1.5.x)
# 3: + ICC functions (libjpeg-turbo 2.0.x)
# 4: + 12-bit-per-component and lossless functions (libjpeg-turbo 2.2.x)
# 4: + 12-bit-per-sample and lossless functions (libjpeg-turbo 2.2.x)
#
# libjpeg v8 API/ABI emulation:
# 1: + Partial image decompression functions (libjpeg-turbo 1.5.x)
# 2: + ICC functions (libjpeg-turbo 2.0.x)
# 3: + 12-bit-per-component and lossless functions (libjpeg-turbo 2.2.x)
# 3: + 12-bit-per-sample and lossless functions (libjpeg-turbo 2.2.x)
set(SO_AGE 3)
if(NOT WITH_JPEG8)
set(SO_AGE 4)

4
ChangeLog.md
View File

@@ -13,8 +13,8 @@ type.
2. Hardened the default marker processor in the decompressor to guard against
an issue (exposed by 3.0 beta2[6]) whereby attempting to decompress a
specially-crafted malformed JPEG image (specifically an image with a complete
12-bit-per-component Start Of Frame segment followed by an incomplete
8-bit-per-component Start Of Frame segment) using buffered-image mode and input
12-bit-per-sample Start Of Frame segment followed by an incomplete
8-bit-per-sample Start Of Frame segment) using buffered-image mode and input
prefetching caused a segfault if the `fill_input_buffer()` method in the
calling application's custom source manager incorrectly returned `FALSE` in
response to a prematurely-terminated JPEG data stream.

6
README.ijg
View File

@@ -89,9 +89,9 @@ The library is intended to be reused in other applications.
In order to support file conversion and viewing software, we have included
considerable functionality beyond the bare JPEG coding/decoding capability;
for example, the color quantization modules are not strictly part of JPEG
decoding, but they are essential for output to colormapped file formats or
colormapped displays. These extra functions can be compiled out of the
library if not required for a particular application.
decoding, but they are essential for output to colormapped file formats. These
extra functions can be compiled out of the library if not required for a
particular application.
We have also included "jpegtran", a utility for lossless transcoding between
different JPEG processes, and "rdjpgcom" and "wrjpgcom", two simple

62
cjpeg.1
View File

@@ -1,4 +1,4 @@
.TH CJPEG 1 "14 Dec 2023"
.TH CJPEG 1 "21 June 2024"
.SH NAME
cjpeg \- compress an image file to a JPEG file
.SH SYNOPSIS
@@ -16,7 +16,8 @@ cjpeg \- compress an image file to a JPEG file
compresses the named image file, or the standard input if no file is
named, and produces a JPEG/JFIF file on the standard output.
The currently supported input file formats are: PPM (PBMPLUS color
format), PGM (PBMPLUS grayscale format), BMP, GIF, and Targa.
format), PGM (PBMPLUS grayscale format), BMP, GIF [legacy feature], and Targa
[legacy feature].
.SH OPTIONS
All switch names may be abbreviated; for example,
.B \-grayscale
@@ -29,7 +30,7 @@ Upper and lower case are equivalent (thus
.B \-BMP
is the same as
.BR \-bmp ).
British spellings are also accepted (e.g.,
British spellings are also accepted (e.g.
.BR \-greyscale ),
though for brevity these are not mentioned below.
.PP
@@ -40,13 +41,12 @@ Scale quantization tables to adjust image quality. Quality is 0 (worst) to
100 (best); default is 75. (See below for more info.)
.TP
.B \-grayscale
Create monochrome JPEG file from color input. By saying
Create monochrome JPEG file from color input. By specifying
.BR \-grayscale,
you'll get a smaller JPEG file that takes less time to process.
.TP
.B \-rgb
Create RGB JPEG file.
Using this switch suppresses the conversion from RGB
Create RGB JPEG file. Using this switch suppresses the conversion from RGB
colorspace input to the default YCbCr JPEG colorspace.
.TP
.B \-optimize
@@ -63,15 +63,15 @@ decompression are unaffected by
Create progressive JPEG file (see below).
.TP
.B \-targa
Input file is Targa format. Targa files that contain an "identification"
field will not be automatically recognized by
.BR cjpeg ;
for such files you must specify
Input file is Targa format [legacy feature]. Targa files that contain an
"identification" field will not be automatically recognized by
.BR cjpeg .
For such files, you must specify
.B \-targa
to make
.B cjpeg
treat the input as Targa format.
For most Targa files, you won't need this switch.
treat the input as Targa format. For most Targa files, you won't need this
switch.
.PP
The
.B \-quality
@@ -153,10 +153,15 @@ Switches for advanced users:
Create JPEG file with N-bit data precision. N is 8, 12, or 16; default is 8.
If N is 16, then
.B -lossless
must also be specified.
must also be specified. Note that only the PBMPLUS input file format supports
data precisions other than 8. (For historical reasons,
.B cjpeg
allows GIF input files to be converted into 12-bit-per-sample JPEG files, but
this is not a useful conversion.)
.B Caution:
12-bit and 16-bit JPEG is not yet widely implemented, so many decoders will be
unable to view a 12-bit or 16-bit JPEG file at all.
12-bit and 16-bit data precision is not yet widely implemented, so many
decoders will be unable to handle a 12-bit-per-sample or 16-bit-per-sample JPEG
file at all.
.TP
.BI \-lossless " psv[,Pt]"
Create a lossless JPEG file using the specified predictor selection value
@@ -174,11 +179,11 @@ non-zero point transform value right-shifts the input samples by the specified
number of bits, which is effectively a form of lossy color quantization.)
.B Caution:
lossless JPEG is not yet widely implemented, so many decoders will be unable to
view a lossless JPEG file at all. In most cases, compressing and decompressing
a lossless JPEG file is considerably slower than compressing and decompressing
a lossy JPEG file, and lossless JPEG files are much larger than lossy JPEG
files. Also note that the following features will be unavailable when
compressing or decompressing a lossless JPEG file:
handle a lossless JPEG file at all. In most cases, compressing and
decompressing a lossless JPEG file is considerably slower than compressing and
decompressing a lossy JPEG file, and lossless JPEG files are much larger than
lossy JPEG files. Also note that the following features will be unavailable
when compressing or decompressing a lossless JPEG file:
.IP
- Quality/quantization table selection
.IP
@@ -205,8 +210,8 @@ Any switches used to enable or configure those features will be ignored.
.B \-arithmetic
Use arithmetic coding.
.B Caution:
arithmetic coded JPEG is not yet widely implemented, so many decoders will be
unable to view an arithmetic coded JPEG file at all.
arithmetic-coded JPEG is not yet widely implemented, so many decoders will be
unable to handle an arithmetic-coded JPEG file at all.
.TP
.B \-dct int
Use accurate integer DCT method (default).
@@ -349,10 +354,10 @@ This example compresses the PPM file foo.ppm with a quality factor of
.I foo.jpg
.SH HINTS
Color GIF files are not the ideal input for JPEG; JPEG is really intended for
compressing full-color (24-bit) images. In particular, don't try to convert
cartoons, line drawings, and other images that have only a few distinct
colors. GIF works great on these, JPEG does not. If you want to convert a
GIF to JPEG, you should experiment with
compressing full-color (24-bit through 48-bit) images. In particular, don't
try to convert cartoons, line drawings, and other images that have only a few
distinct colors. GIF works great on these; JPEG does not. If you want to
convert a GIF to JPEG, you should experiment with
.BR cjpeg 's
.B \-quality
and
@@ -407,8 +412,3 @@ relevant to libjpeg-turbo, to wordsmith certain sections, and to describe
features not present in libjpeg.
.SH ISSUES
Not all variants of BMP and Targa file formats are supported.
.PP
The
.B \-targa
switch is not a bug, it's a feature. (It would be a bug if the Targa format
designers had not been clueless.)

129
djpeg.1
View File

@@ -1,4 +1,4 @@
.TH DJPEG 1 "4 November 2020"
.TH DJPEG 1 "17 June 2024"
.SH NAME
djpeg \- decompress a JPEG file to an image file
.SH SYNOPSIS
@@ -28,47 +28,46 @@ Upper and lower case are equivalent (thus
.B \-BMP
is the same as
.BR \-bmp ).
British spellings are also accepted (e.g.,
British spellings are also accepted (e.g.
.BR \-greyscale ),
though for brevity these are not mentioned below.
.PP
The basic switches are:
.TP
.BI \-colors " N"
Reduce image to at most N colors. This reduces the number of colors used in
the output image, so that it can be displayed on a colormapped display or
stored in a colormapped file format. For example, if you have an 8-bit
display, you'd need to reduce to 256 or fewer colors.
Reduce image to at most N colors [legacy feature]. This reduces the number of
colors used in the output image so that it can be stored in a colormapped file
format. This feature cannot be used when decompressing lossless JPEG images.
.TP
.BI \-quantize " N"
Same as
.BR \-colors .
.B \-colors
is the recommended name,
is the recommended name.
.B \-quantize
is provided only for backwards compatibility.
is provided only for backward compatibility.
.TP
.B \-fast
Select recommended processing options for fast, low quality output. (The
default options are chosen for highest quality output.) Currently, this is
equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR.
Select recommended processing options for low-quality output [legacy feature].
(The default options are chosen for highest-quality output.) Currently, this
is equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR. On
modern CPUs, these settings have little or no performance benefit and are
retained solely for backward compatibility.
.TP
.B \-grayscale
Force grayscale output even if JPEG file is color. Useful for viewing on
monochrome displays; also,
.B djpeg
runs noticeably faster in this mode.
Force grayscale output even if JPEG file is full-color. This feature cannot be
used when decompressing full-color lossless JPEG images.
.TP
.B \-rgb
Force RGB output even if JPEG file is grayscale.
Force RGB output even if JPEG file is grayscale. This feature cannot be used
when decompressing grayscale lossless JPEG images.
.TP
.BI \-scale " M/N"
Scale the output image by a factor M/N. Currently the scale factor must be
M/8, where M is an integer between 1 and 16 inclusive, or any reduced fraction
thereof (such as 1/2, 3/4, etc.) Scaling is handy if the image is larger than
your screen; also,
.B djpeg
runs much faster when scaling down the output.
your screen. This feature cannot be used when decompressing lossless JPEG
images.
.TP
.B \-bmp
Select BMP output format (Windows flavor). 8-bit colormapped format is
@@ -77,32 +76,36 @@ emitted if
or
.B \-grayscale
is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color
format is emitted.
format is emitted. This format can only be used when decompressing
8-bit-per-sample JPEG images.
.TP
.B \-gif
Select GIF output format (LZW-compressed). Since GIF does not support more
than 256 colors,
Select GIF output format (LZW-compressed) [legacy feature]. Since GIF does not
support more than 256 colors,
.B \-colors 256
is assumed (unless you specify a smaller number of colors). If you specify
.BR \-fast,
the default number of colors is 216.
the default number of colors is 216. This format can only be used when
decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images.
.TP
.B \-gif0
Select GIF output format (uncompressed). Since GIF does not support more than
256 colors,
Select GIF output format (uncompressed) [legacy feature]. Since GIF does not
support more than 256 colors,
.B \-colors 256
is assumed (unless you specify a smaller number of colors). If you specify
.BR \-fast,
the default number of colors is 216.
the default number of colors is 216. This format can only be used when
decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images.
.TP
.B \-os2
Select BMP output format (OS/2 1.x flavor). 8-bit colormapped format is
emitted if
Select BMP output format (OS/2 1.x flavor) [legacy feature]. 8-bit colormapped
format is emitted if
.B \-colors
or
.B \-grayscale
is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color
format is emitted.
format is emitted. This format can only be used when decompressing
8-bit-per-sample JPEG images.
.TP
.B \-pnm
Select PBMPLUS (PPM/PGM) output format (this is the default format).
@@ -111,12 +114,13 @@ PGM is emitted if the JPEG file is grayscale or if
is specified; otherwise PPM is emitted.
.TP
.B \-targa
Select Targa output format. Grayscale format is emitted if the JPEG file is
grayscale or if
Select Targa output format [legacy feature]. Grayscale format is emitted if
the JPEG file is grayscale or if
.B \-grayscale
is specified; otherwise, colormapped format is emitted if
.B \-colors
is specified; otherwise, 24-bit full-color format is emitted.
is specified; otherwise, 24-bit full-color format is emitted. This format can
only be used when decompressing 8-bit-per-sample JPEG images.
.PP
Switches for advanced users:
.TP
@@ -157,18 +161,18 @@ behavior, whereas the integer methods should give the same results on all
machines.
.TP
.B \-dither fs
Use Floyd-Steinberg dithering in color quantization.
Use Floyd-Steinberg dithering when quantizing colors [legacy feature].
.TP
.B \-dither ordered
Use ordered dithering in color quantization.
Use ordered dithering when quantizing colors [legacy feature].
.TP
.B \-dither none
Do not use dithering in color quantization.
By default, Floyd-Steinberg dithering is applied when quantizing colors; this
is slow but usually produces the best results. Ordered dither is a compromise
between speed and quality; no dithering is fast but usually looks awful. Note
that these switches have no effect unless color quantization is being done.
Ordered dither is only available in
Do not use dithering when quantizing colors [legacy feature]. By default,
Floyd-Steinberg dithering is applied when quantizing colors. This is slower
but usually produces the best results. Ordered dithering is a compromise
between speed and quality. No dithering is faster but usually looks awful.
Note that these switches have no effect unless color quantization is being
done. Ordered dithering is only available in
.B \-onepass
mode.
.TP
@@ -176,9 +180,9 @@ mode.
Extract ICC color management profile to the specified file.
.TP
.BI \-map " file"
Quantize to the colors used in the specified image file. This is useful for
producing multiple files with identical color maps, or for forcing a
predefined set of colors to be used. The
Quantize to the colors used in the specified image file [legacy feature]. This
is useful for producing multiple files with identical color maps, or for
forcing a predefined set of colors to be used. The
.I file
must be a GIF or PPM file. This option overrides
.B \-colors
@@ -189,14 +193,14 @@ and
Use a faster, lower-quality upsampling routine.
.TP
.B \-onepass
Use one-pass instead of two-pass color quantization. The one-pass method is
faster and needs less memory, but it produces a lower-quality image.
Use one-pass instead of two-pass color quantization [legacy feature]. The
one-pass method needs less memory, but it produces a lower-quality image.
.B \-onepass
is ignored unless you also say
is ignored unless you also specify
.B \-colors
.IR N .
Also, the one-pass method is always used for grayscale output (the two-pass
method is no improvement then).
Also, the one-pass method is always used for grayscale output. (The two-pass
method has no improvement in that case.)
.TP
.BI \-maxmemory " N"
Set limit for amount of memory to use in processing large images. Value is
@@ -260,36 +264,13 @@ Same as
Print version information and exit.
.SH EXAMPLES
.LP
This example decompresses the JPEG file foo.jpg, quantizes it to
256 colors, and saves the output in 8-bit BMP format in foo.bmp:
This example decompresses the JPEG file foo.jpg and saves the output in 8-bit
BMP format in foo.bmp:
.IP
.B djpeg \-colors 256 \-bmp
.B djpeg \-bmp
.I foo.jpg
.B >
.I foo.bmp
.SH HINTS
To get a quick preview of an image, use the
.B \-grayscale
and/or
.B \-scale
switches.
.B \-grayscale \-scale 1/8
is the fastest case.
.PP
Several options are available that trade off image quality to gain speed.
.B \-fast
turns on the recommended settings.
.PP
.B \-dct fast
and/or
.B \-nosmooth
gain speed at a small sacrifice in quality.
When producing a color-quantized image,
.B \-onepass \-dither ordered
is fast but much lower quality than the default behavior.
.B \-dither none
may give acceptable results in two-pass mode, but is seldom tolerable in
one-pass mode.
.SH ENVIRONMENT
.TP
.B JPEGMEM

26
djpeg.c
View File

@@ -107,8 +107,8 @@ usage(void)
#endif
fprintf(stderr, "Switches (names may be abbreviated):\n");
fprintf(stderr, " -colors N Reduce image to no more than N colors\n");
fprintf(stderr, " -fast Fast, low-quality processing\n");
fprintf(stderr, " -colors N Reduce image to no more than N colors [legacy feature]\n");
fprintf(stderr, " -fast Low-quality processing [legacy feature]\n");
fprintf(stderr, " -grayscale Force grayscale output\n");
fprintf(stderr, " -rgb Force RGB output\n");
fprintf(stderr, " -rgb565 Force RGB565 output\n");
@@ -120,13 +120,13 @@ usage(void)
(DEFAULT_FMT == FMT_BMP ? " (default)" : ""));
#endif
#ifdef GIF_SUPPORTED
fprintf(stderr, " -gif Select GIF output format (LZW-compressed)%s\n",
fprintf(stderr, " -gif Select GIF output format (LZW-compressed)%s [legacy feature]\n",
(DEFAULT_FMT == FMT_GIF ? " (default)" : ""));
fprintf(stderr, " -gif0 Select GIF output format (uncompressed)%s\n",
fprintf(stderr, " -gif0 Select GIF output format (uncompressed)%s [legacy feature]\n",
(DEFAULT_FMT == FMT_GIF0 ? " (default)" : ""));
#endif
#ifdef BMP_SUPPORTED
fprintf(stderr, " -os2 Select BMP output format (OS/2 style)%s\n",
fprintf(stderr, " -os2 Select BMP output format (OS/2 style)%s [legacy feature]\n",
(DEFAULT_FMT == FMT_OS2 ? " (default)" : ""));
#endif
#ifdef PPM_SUPPORTED
@@ -134,7 +134,7 @@ usage(void)
(DEFAULT_FMT == FMT_PPM ? " (default)" : ""));
#endif
#ifdef TARGA_SUPPORTED
fprintf(stderr, " -targa Select Targa output format%s\n",
fprintf(stderr, " -targa Select Targa output format%s [legacy feature]\n",
(DEFAULT_FMT == FMT_TARGA ? " (default)" : ""));
#endif
fprintf(stderr, "Switches for advanced users:\n");
@@ -150,16 +150,18 @@ usage(void)
fprintf(stderr, " -dct float Use floating-point DCT method [legacy feature]%s\n",
(JDCT_DEFAULT == JDCT_FLOAT ? " (default)" : ""));
#endif
fprintf(stderr, " -dither fs Use F-S dithering (default)\n");
fprintf(stderr, " -dither none Don't use dithering in quantization\n");
fprintf(stderr, " -dither ordered Use ordered dither (medium speed, quality)\n");
fprintf(stderr, " -dither fs Use Floyd-Steinberg dithering when quantizing colors (default)\n");
fprintf(stderr, " [legacy feature]\n");
fprintf(stderr, " -dither none Don't use dithering when quantizing colors [legacy feature]\n");
fprintf(stderr, " -dither ordered Use ordered dithering when quantizing colors\n");
fprintf(stderr, " [legacy feature]\n");
fprintf(stderr, " -icc FILE Extract ICC profile to FILE\n");
#ifdef QUANT_2PASS_SUPPORTED
fprintf(stderr, " -map FILE Map to colors used in named image file\n");
fprintf(stderr, " -map FILE Quantize to colors used in named image file [legacy feature]\n");
#endif
fprintf(stderr, " -nosmooth Don't use high-quality upsampling\n");
fprintf(stderr, " -nosmooth Use faster, lower-quality upsampling\n");
#ifdef QUANT_1PASS_SUPPORTED
fprintf(stderr, " -onepass Use 1-pass quantization (fast, low quality)\n");
fprintf(stderr, " -onepass Use 1-pass color quantization (low quality) [legacy feature]\n");
#endif
fprintf(stderr, " -maxmemory N Maximum memory to use (in kbytes)\n");
fprintf(stderr, " -maxscans N Maximum number of scans to allow in input file\n");

2
java/doc/index-all.html
View File

@@ -968,7 +968,7 @@ $('.navPadding').css('padding-top', $('.fixedNav').css("height"));
</dd>
<dt><span class="memberNameLink"><a href="org/libjpegturbo/turbojpeg/TJCompressor.html#setSourceImage(java.awt.image.BufferedImage,int,int,int,int)">setSourceImage(BufferedImage, int, int, int, int)</a></span> - Method in class org.libjpegturbo.turbojpeg.<a href="org/libjpegturbo/turbojpeg/TJCompressor.html" title="class in org.libjpegturbo.turbojpeg">TJCompressor</a></dt>
<dd>
<div class="block">Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
<div class="block">Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
with this compressor instance.</div>
</dd>
<dt><span class="memberNameLink"><a href="org/libjpegturbo/turbojpeg/TJCompressor.html#setSourceImage(org.libjpegturbo.turbojpeg.YUVImage)">setSourceImage(YUVImage)</a></span> - Method in class org.libjpegturbo.turbojpeg.<a href="org/libjpegturbo/turbojpeg/TJCompressor.html" title="class in org.libjpegturbo.turbojpeg">TJCompressor</a></dt>

BIN
java/doc/member-search-index.zip
View File

Binary file not shown.

4
java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html
View File

@@ -369,7 +369,7 @@ implements java.io.Closeable</pre>
int&nbsp;width,
int&nbsp;height)</code></th>
<td class="colLast">
<div class="block">Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
<div class="block">Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
with this compressor instance.</div>
</td>
</tr>
@@ -677,7 +677,7 @@ implements java.io.Closeable</pre>
int&nbsp;width,
int&nbsp;height)
throws <a href="TJException.html" title="class in org.libjpegturbo.turbojpeg">TJException</a></pre>
<div class="block">Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
<div class="block">Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
with this compressor instance.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>

4
java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
View File

@@ -1184,7 +1184,7 @@ public&nbsp;byte[]&nbsp;decompress&#8203;(int&nbsp;desiredWidth,
<dd><code>pixelFormat</code> - pixel format of the decompressed image (one of
<a href="TJ.html#PF_RGB"><code>TJ.PF_*</code></a>)</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a buffer containing an 8-bit-per-sample packed-pixel decompressed
<dd>a buffer containing a 12-bit-per-sample packed-pixel decompressed
image.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="TJException.html" title="class in org.libjpegturbo.turbojpeg">TJException</a></code></dd>
@@ -1258,7 +1258,7 @@ public&nbsp;byte[]&nbsp;decompress&#8203;(int&nbsp;desiredWidth,
<dd><code>pixelFormat</code> - pixel format of the decompressed image (one of
<a href="TJ.html#PF_RGB"><code>TJ.PF_*</code></a>)</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a buffer containing an 8-bit-per-sample packed-pixel decompressed
<dd>a buffer containing a 16-bit-per-sample packed-pixel decompressed
image.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="TJException.html" title="class in org.libjpegturbo.turbojpeg">TJException</a></code></dd>

BIN
java/doc/package-search-index.zip
View File

Binary file not shown.

BIN
java/doc/type-search-index.zip
View File

Binary file not shown.

2
java/org/libjpegturbo/turbojpeg/TJCompressor.java
View File

@@ -263,7 +263,7 @@ public class TJCompressor implements Closeable {
}
/**
* Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
* Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
* with this compressor instance.
*
* @param srcImage a <code>BufferedImage</code> instance containing a

4
java/org/libjpegturbo/turbojpeg/TJDecompressor.java
View File

@@ -582,7 +582,7 @@ public class TJDecompressor implements Closeable {
* @param pixelFormat pixel format of the decompressed image (one of
* {@link TJ#PF_RGB TJ.PF_*})
*
* @return a buffer containing an 8-bit-per-sample packed-pixel decompressed
* @return a buffer containing a 12-bit-per-sample packed-pixel decompressed
* image.
*/
public short[] decompress12(int pitch, int pixelFormat) throws TJException {
@@ -655,7 +655,7 @@ public class TJDecompressor implements Closeable {
* @param pixelFormat pixel format of the decompressed image (one of
* {@link TJ#PF_RGB TJ.PF_*})
*
* @return a buffer containing an 8-bit-per-sample packed-pixel decompressed
* @return a buffer containing a 16-bit-per-sample packed-pixel decompressed
* image.
*/
public short[] decompress16(int pitch, int pixelFormat) throws TJException {

9
jpeglib.h
View File

@@ -585,11 +585,10 @@ struct jpeg_decompress_struct {
*/
int actual_number_of_colors; /* number of entries in use */
JSAMPARRAY colormap; /* The color map as a 2-D pixel array
If data_precision is 12 or 16, then this is
actually a J12SAMPARRAY or a J16SAMPARRAY,
so callers must type-cast it in order to
read/write 12-bit or 16-bit samples from/to
the array. */
If data_precision is 12, then this is
actually a J12SAMPARRAY, so callers must
type-cast it in order to read/write 12-bit
samples from/to the array. */
/* State variables: these variables indicate the progress of decompression.
* The application may examine these but must not modify them.

14
jpegtran.1
View File

@@ -1,4 +1,4 @@
.TH JPEGTRAN 1 "13 July 2021"
.TH JPEGTRAN 1 "17 June 2024"
.SH NAME
jpegtran \- lossless transformation of JPEG files
.SH SYNOPSIS
@@ -13,7 +13,7 @@ jpegtran \- lossless transformation of JPEG files
.SH DESCRIPTION
.LP
.B jpegtran
performs various useful transformations of JPEG files.
performs various useful transformations of lossy (DCT-based) JPEG files.
It can translate the coded representation from one variant of JPEG to another,
for example from baseline JPEG to progressive JPEG or vice versa. It can also
perform some rearrangements of the image data, for example turning an image
@@ -64,13 +64,13 @@ Perform optimization of entropy encoding parameters.
.B \-progressive
Create progressive JPEG file.
.TP
.B \-arithmetic
Use arithmetic coding.
.TP
.BI \-restart " N"
Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is
attached to the number.
.TP
.B \-arithmetic
Use arithmetic coding.
.TP
.BI \-scans " file"
Use the scan script given in the specified text file.
.PP
@@ -166,8 +166,8 @@ the current JPEG format; the upper left corner of the selected region must fall
on an iMCU boundary. If it doesn't, then it is silently moved up and/or left
to the nearest iMCU boundary (the lower right corner is unchanged.) Thus, the
output image covers at least the requested region, but it may cover more. The
adjustment of the region dimensions may be optionally disabled by attaching an
'f' character ("force") to the width or height number.
adjustment of the region dimensions may be optionally disabled by attaching
an 'f' character ("force") to the width or height number.
The image can be losslessly cropped by giving the switch:
.TP

126
libjpeg.txt
View File

@@ -5,7 +5,7 @@ Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding.
Lossless JPEG Modifications:
Copyright (C) 1999, Ken Murchison.
libjpeg-turbo Modifications:
Copyright (C) 2010, 2014-2018, 2020, 2022-2023, D. R. Commander.
Copyright (C) 2010, 2014-2018, 2020, 2022-2024, D. R. Commander.
Copyright (C) 2015, Google, Inc.
For conditions of distribution and use, see the accompanying README.ijg file.
@@ -114,22 +114,24 @@ used by the free LIBTIFF library to support JPEG compression in TIFF.)
12-bit and 16-bit Data Precision
--------------------------------
The JPEG standard provides for baseline 8-bit and 12-bit DCT processes as well
as 8-bit, 12-bit, and 16-bit lossless (predictive) processes. This code
supports 12-bit-per-component lossy or lossless JPEG if you set
cinfo->data_precision to 12 and 16-bit-per-component lossless JPEG if you set
cinfo->data_precision to 16. Note that this causes the sample size to be
larger than a char, so it affects the surrounding application's image data.
The sample applications cjpeg and djpeg can support 12-bit mode only for PPM,
PGM, and GIF file formats and 16-bit mode only for PPM and PGM file formats.
The JPEG standard provides for baseline (8-bit-per-sample) and
12-bit-per-sample DCT processes as well as 8-bit-per-sample, 12-bit-per-sample,
and 16-bit-per-sample lossless (predictive) processes. This code supports
12-bit-per-sample lossy or lossless JPEG if you set cinfo->data_precision to 12
and 16-bit-per-sample lossless JPEG if you set cinfo->data_precision to 16.
Note that this causes the sample size to be larger than a char, so it affects
the surrounding application's image data. The sample applications cjpeg and
djpeg can support 12-bit data precision only for PPM, PGM, and GIF file formats
and 16-bit data precision only for PPM and PGM file formats.
Note that, when 12-bit data precision is enabled, the library always compresses
in Huffman optimization mode, in order to generate valid Huffman tables. This
is necessary because our default Huffman tables only cover 8-bit data. If you
need to output 12-bit files in one pass, you'll have to supply suitable default
Huffman tables. You may also want to supply your own DCT quantization tables;
the existing quality-scaling code has been developed for 8-bit use, and
probably doesn't generate especially good tables for 12-bit.
Note that, when 12-bit data precision is enabled in lossy mode, the library
compresses in Huffman optimization mode by default, in order to generate valid
Huffman tables. This is necessary because our default Huffman tables only
cover 8-bit data. If you need to output 12-bit-per-sample JPEG files in one
pass, you'll have to supply suitable default Huffman tables. You may also want
to supply your own DCT quantization tables; the existing quality-scaling code
has been developed for 8-bit data precision and probably doesn't generate
especially good tables for 12-bit data precision.
Functions that are specific to 12-bit data precision have a prefix of "jpeg12_"
instead of "jpeg_" and use the following data types and macros:
@@ -160,7 +162,8 @@ Refer to the descriptions of the data_precision compression and decompression
parameters below for further information.
This documentation uses "J*SAMPLE", "J*SAMPROW", "J*SAMPARRAY", and
"J*SAMPIMAGE" to generically refer to the 8-bit, 12-bit, or 16-bit data types.
"J*SAMPIMAGE" to generically refer to the 8-bit-per-sample, 12-bit-per-sample,
or 16-bit-per-sample data types.
Outline of typical usage
@@ -267,10 +270,9 @@ and the other references mentioned in the README.ijg file.
Pixels are stored by scanlines, with each scanline running from left to
right. The component values for each pixel are adjacent in the row; for
example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an
array of data type JSAMPLE or J12SAMPLE --- which is typically "unsigned char"
or "short" (respectively), unless you've changed jmorecfg.h. (You can also
change the RGB pixel layout, say to B,G,R order, by modifying jmorecfg.h. But
see the restrictions listed in that file before doing so.)
array of data type JSAMPLE, J12SAMPLE, or J16SAMPLE --- which is typically
"unsigned char", "short", or "unsigned short" (respectively) unless you've
changed jmorecfg.h.
A 2-D array of pixels is formed by making a list of pointers to the starts of
scanlines; so the scanlines need not be physically adjacent in memory. Even
@@ -285,10 +287,11 @@ have it all in memory, but usually it's simplest to process one scanline at
a time.
For best results, source data values should have the precision specified by
cinfo->data_precision (normally 8 bits). For instance, if you choose to
compress data that's only 6 bits/channel, you should left-justify each value in
a byte before passing it to the compressor. If you need to compress data
that has more than 8 bits/channel, set cinfo->data_precision = 12 or 16.
cinfo->data_precision (normally 8 bits per sample). For instance, if you
choose to compress data that's only 6 bits/channel, you should left-justify
each value in a byte before passing it to the compressor. If you need to
compress data that has more than 8 bits/channel, set cinfo->data_precision = 12
or 16.
The data format returned by the decompressor is the same in all details,
@@ -301,8 +304,8 @@ a 2-D J*SAMPARRAY in which each row holds the values of one color component,
that is, colormap[i][j] is the value of the i'th color component for pixel
value (map index) j. Note that since the colormap indexes are stored in
J*SAMPLEs, the maximum number of colors is limited by the size of J*SAMPLE
(ie, at most 256 colors for 8-bit data precision, 4096 colors for 12-bit data
precision, and 65536 colors for 16-bit data precision).
(ie, at most 256 colors for 8-bit data precision and 4096 colors for 12-bit
data precision).
Compression details
@@ -972,7 +975,7 @@ jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline)
entries are constrained to the range 1..255 for full JPEG baseline
compatibility. In the current implementation, this only makes a
difference for quality settings below 25, and it effectively prevents
very small/low quality files from being generated. The IJG decoder
very small/low-quality files from being generated. The IJG decoder
is capable of reading the non-baseline files generated at low quality
settings when force_baseline is FALSE, but other decoders may not be.
@@ -1079,12 +1082,12 @@ boolean arith_code
If FALSE, use Huffman coding.
int data_precision
To create a 12-bit-per-component JPEG file, set data_precision to 12
prior to calling jpeg_start_compress() or using the memory manager,
then use jpeg12_write_scanlines() or jpeg12_write_raw_data() instead of
jpeg_write_scanlines() or jpeg_write_raw_data(). To create a
16-bit-per-component lossless JPEG file, set data_precision to 16 prior
To create a 12-bit-per-sample JPEG file, set data_precision to 12 prior
to calling jpeg_start_compress() or using the memory manager, then use
jpeg12_write_scanlines() or jpeg12_write_raw_data() instead of
jpeg_write_scanlines() or jpeg_write_raw_data(). To create a
16-bit-per-sample lossless JPEG file, set data_precision to 16 prior to
calling jpeg_start_compress() or using the memory manager, then use
jpeg16_write_scanlines() instead of jpeg_write_scanlines(). Note that
16-bit data precision requires lossless mode. (See
jpeg_enable_lossless().)
@@ -1138,7 +1141,10 @@ boolean optimize_coding
Huffman tables. In most cases optimal tables save only a few percent
of file size compared to the default tables. Note that when this is
TRUE, you need not supply Huffman tables at all, and any you do
supply will be overwritten.
supply will be overwritten. This parameter has no effect in
progressive mode or lossless mode, in which optimal Huffman tables are
always computed, and it defaults to TRUE for 12-bit data precision
unless Huffman tables have been supplied.
unsigned int restart_interval
int restart_in_rows
@@ -1303,13 +1309,13 @@ recorded in the source file and need not be supplied by the application.
the postprocessing done on the image to deliver it in a format suitable
for the application's use. Many of the parameters control speed/quality
tradeoffs, in which faster decompression may be obtained at the price of
a poorer-quality image. The defaults select the highest quality (slowest)
a poorer-quality image. The defaults select the highest-quality (slowest)
processing.
The following fields in the JPEG object are set by jpeg_read_header() and
may be useful to the application in choosing decompression parameters:
int data_precision Data precision (bits per component)
int data_precision Data precision (bits per sample)
If data_precision is 12, then use jpeg12_read_scanlines(),
jpeg12_skip_scanlines(), jpeg12_crop_scanline(), and/or
jpeg12_read_raw_data() instead of jpeg_read_scanlines(),
@@ -1344,11 +1350,8 @@ J_COLOR_SPACE out_color_space
based on jpeg_color_space; typically it will be RGB or grayscale.
The application can change this field to request output in a different
colorspace. For example, set it to JCS_GRAYSCALE to get grayscale
output from a color file. (This is useful for previewing: grayscale
output is faster than full color since the color components need not
be processed.) Note that not all possible color space transforms are
currently implemented; you may need to extend jdcolor.c if you want an
unusual conversion.
output from a color file. Note that not all possible color space
transforms are currently implemented.
unsigned int scale_num, scale_denom
Scale the image by the fraction scale_num/scale_denom. Default is
@@ -1356,31 +1359,33 @@ unsigned int scale_num, scale_denom
are M/8 with all M from 1 to 16, or any reduced fraction thereof (such
as 1/2, 3/4, etc.) (The library design allows for arbitrary
scaling ratios but this is not likely to be implemented any time soon.)
Smaller scaling ratios permit significantly faster decoding since
fewer pixels need be processed and a simpler IDCT method can be used.
boolean quantize_colors
[legacy feature]
If set TRUE, colormapped output will be delivered. Default is FALSE,
meaning that full-color output will be delivered.
The next three parameters are relevant only if quantize_colors is TRUE.
int desired_number_of_colors
[legacy feature]
Maximum number of colors to use in generating a library-supplied color
map (the actual number of colors is returned in a different field).
Default 256. Ignored when the application supplies its own color map.
boolean two_pass_quantize
[legacy feature]
If TRUE, an extra pass over the image is made to select a custom color
map for the image. This usually looks a lot better than the one-size-
fits-all colormap that is used otherwise. Default is TRUE. Ignored
when the application supplies its own color map.
J_DITHER_MODE dither_mode
[legacy feature]
Selects color dithering method. Supported values are:
JDITHER_NONE no dithering: fast, very low quality
JDITHER_NONE no dithering: faster, very low quality
JDITHER_ORDERED ordered dither: moderate speed and quality
JDITHER_FS Floyd-Steinberg dither: slow, high quality
JDITHER_FS Floyd-Steinberg dither: slower, high quality
Default is JDITHER_FS. (At present, ordered dither is implemented
only in the single-pass, standard-colormap case. If you ask for
ordered dither when two_pass_quantize is TRUE or when you supply
@@ -1395,16 +1400,18 @@ selects a suitable color map and sets these two fields itself.
only accepted for 3-component output color spaces.]
JSAMPARRAY colormap
[legacy feature]
The color map, represented as a 2-D pixel array of out_color_components
rows and actual_number_of_colors columns. Ignored if not quantizing.
CAUTION: if the JPEG library creates its own colormap, the storage
pointed to by this field is released by jpeg_finish_decompress().
Copy the colormap somewhere else first, if you want to save it.
CAUTION: if data_precision is 12 or 16, then this is actually a
J12SAMPARRAY or a J16SAMPARRAY, so it must be type-cast in order to
read/write 12-bit or 16-bit samples from/to the array.
CAUTION: if data_precision is 12, then this is actually a J12SAMPARRAY,
so it must be type-cast in order to read/write 12-bit samples from/to
the array.
int actual_number_of_colors
[legacy feature]
The number of colors in the color map.
Additional decompression parameters that the application may set include:
@@ -1461,6 +1468,7 @@ boolean do_block_smoothing
boolean enable_1pass_quant
boolean enable_external_quant
boolean enable_2pass_quant
[legacy feature]
These are significant only in buffered-image mode, which is
described in its own section below.
@@ -2330,7 +2338,7 @@ limited changes of parameters. ONLY THE FOLLOWING parameter changes are
allowed after jpeg_start_decompress() is called:
* dct_method can be changed before each call to jpeg_start_output().
For example, one could use a fast DCT method for early scans, changing
to a higher quality method for the final scan.
to a higher-quality method for the final scan.
* dither_mode can be changed before each call to jpeg_start_output();
of course this has no impact if not using color quantization. Typically
one would use ordered dither for initial passes, then switch to
@@ -3182,10 +3190,10 @@ This does not count any memory allocated by the application, such as a
buffer to hold the final output image.
The above figures are valid for 8-bit JPEG data precision and a machine with
32-bit ints. For 12-bit and 16-bit JPEG data, double the size of the strip
buffers and quantization pixel buffer. The "fixed-size" data will be somewhat
smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual
color spaces will require different amounts of space.
32-bit ints. For 12-bit-per-sample and 16-bit-per-sample JPEG data, double the
size of the strip buffers and quantization pixel buffer. The "fixed-size" data
will be somewhat smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK
or other unusual color spaces will require different amounts of space.
The full-image coefficient and pixel buffers, if needed at all, do not
have to be fully RAM resident; you can have the library use temporary
@@ -3211,14 +3219,6 @@ The maximum number of components (color channels) in the image is determined
by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we
expect that few applications will need more than four or so.
On machines with unusual data type sizes, you may be able to improve
performance or reduce memory space by tweaking the various typedefs in
jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s
is quite slow; consider trading memory for speed by making JCOEF, INT16, and
UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int.
You probably don't want to make J*SAMPLE be int unless you have lots of memory
to burn.
You can reduce the size of the library by compiling out various optional
functions. To do this, undefine xxx_SUPPORTED symbols as necessary.
@@ -3257,9 +3257,7 @@ than 8 bits or short is much bigger than 16 bits. The code should work
equally well with 16- or 32-bit ints.
In a system where these assumptions are not met, you may be able to make the
code work by modifying the typedefs in jmorecfg.h. However, you will probably
have difficulty if int is less than 16 bits wide, since references to plain
int abound in the code.
code work by modifying the typedefs in jmorecfg.h.
char can be either signed or unsigned, although the code runs faster if an
unsigned char type is available. If char is wider than 8 bits, you will need

308
usage.txt
View File

@@ -1,5 +1,8 @@
NOTE: This file was modified by The libjpeg-turbo Project to include only
information relevant to libjpeg-turbo and to wordsmith certain sections.
This file was part of the Independent JPEG Group's software:
Copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
libjpeg-turbo Modifications:
Copyright (C) 2010, 2012, 2014-2017, 2020-2024, D. R. Commander.
For conditions of distribution and use, see the accompanying README.ijg file.
USAGE instructions for the Independent JPEG Group's JPEG software
=================================================================
@@ -50,9 +53,10 @@ or
This syntax works on all systems, so it is useful for scripts.
The currently supported image file formats are: PPM (PBMPLUS color format),
PGM (PBMPLUS grayscale format), BMP, GIF, and Targa. cjpeg recognizes the
input image format automatically, with the exception of some Targa files. You
have to tell djpeg which format to generate.
PGM (PBMPLUS grayscale format), BMP, GIF [legacy feature], and Targa [legacy
feature]. cjpeg recognizes the input image format automatically, with the
exception of some Targa files. You have to tell djpeg which format to
generate.
JPEG files are in the defacto standard JFIF file format. There are other,
less widely used JPEG-based file formats, but we don't support them.
@@ -73,12 +77,12 @@ The basic command line switches for cjpeg are:
(See below for more info.)
-grayscale Create monochrome JPEG file from color input. By
saying -grayscale, you'll get a smaller JPEG file that
takes less time to process.
specifying -grayscale, you'll get a smaller JPEG file
that takes less time to process.
-rgb Create RGB JPEG file.
Using this switch suppresses the conversion from RGB
colorspace input to the default YCbCr JPEG colorspace.
-rgb Create RGB JPEG file. Using this switch suppresses the
conversion from RGB colorspace input to the default
YCbCr JPEG colorspace.
-optimize Perform optimization of entropy encoding parameters.
Without this, default encoding parameters are used.
@@ -89,11 +93,12 @@ The basic command line switches for cjpeg are:
-progressive Create progressive JPEG file (see below).
-targa Input file is Targa format. Targa files that contain
an "identification" field will not be automatically
recognized by cjpeg; for such files you must specify
-targa to make cjpeg treat the input as Targa format.
For most Targa files, you won't need this switch.
-targa Input file is Targa format [legacy feature]. Targa
files that contain an "identification" field will not
be automatically recognized by cjpeg. For such files,
you must specify -targa to make cjpeg treat the input
as Targa format. For most Targa files, you won't need
this switch.
The -quality switch lets you trade off compressed file size against quality of
the reconstructed image: the higher the quality setting, the larger the JPEG
@@ -162,10 +167,14 @@ Switches for advanced users:
-precision N Create JPEG file with N-bit data precision.
N is 8, 12, or 16; default is 8. If N is 16, then
-lossless must also be specified. CAUTION: 12-bit and
16-bit JPEG is not yet widely implemented, so many
decoders will be unable to view a 12-bit or 16-bit JPEG
file at all.
-lossless must also be specified. Note that only the
PBMPLUS input file format supports data precisions other
than 8. (For historical reasons, cjpeg allows GIF input
files to be converted into 12-bit-per-sample JPEG files,
but this is not a useful conversion.) CAUTION: 12-bit
and 16-bit data precision is not yet widely implemented,
so many decoders will be unable to handle a
12-bit-per-sample or 16-bit-per-sample JPEG file at all.
-lossless psv[,Pt] Create a lossless JPEG file using the specified
predictor selection value (1 - 7) and optional point
@@ -177,7 +186,7 @@ Switches for advanced users:
number of bits, which is effectively a form of lossy
color quantization.) CAUTION: lossless JPEG is not yet
widely implemented, so many decoders will be unable to
view a lossless JPEG file at all. In most cases,
handle a lossless JPEG file at all. In most cases,
compressing and decompressing a lossless JPEG file is
considerably slower than compressing and decompressing
a lossy JPEG file, and lossless JPEG files are much
@@ -197,9 +206,9 @@ Switches for advanced users:
Any switches used to enable or configure those features
will be ignored.
-arithmetic Use arithmetic coding. CAUTION: arithmetic coded JPEG
-arithmetic Use arithmetic coding. CAUTION: arithmetic-coded JPEG
is not yet widely implemented, so many decoders will
be unable to view an arithmetic coded JPEG file at
be unable to handle an arithmetic-coded JPEG file at
all.
-dct int Use accurate integer DCT method (default).
@@ -240,6 +249,9 @@ Switches for advanced users:
behavior, whereas the integer methods should give the
same results on all machines.
-icc FILE Embed ICC color management profile contained in the
specified file.
-restart N Emit a JPEG restart marker every N MCU rows, or every
N MCU blocks (samples in lossless mode) if "B" is
attached to the number. -restart 0 (the default) means
@@ -255,9 +267,23 @@ Switches for advanced users:
For example, -max 4m selects 4000000 bytes. If more
space is needed, an error will occur.
-verbose Enable debug printout. More -v's give more printout.
-memdst Compress to memory instead of a file. This feature was
implemented mainly as a way of testing the in-memory
destination manager (jpeg_mem_dest()), but it is also
useful for benchmarking, since it reduces the I/O
overhead.
-report Report compression progress.
-strict Treat all warnings as fatal. Enabling this option will
cause the compressor to abort if an LZW-compressed GIF
input image contains incomplete or corrupt image data.
-verbose Enable debug printout. More -v's give more output.
or -debug Also, version information is printed at startup.
-version Print version information and exit.
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
@@ -300,64 +326,78 @@ DJPEG DETAILS
The basic command line switches for djpeg are:
-colors N Reduce image to at most N colors. This reduces the
or -quantize N number of colors used in the output image, so that it
can be displayed on a colormapped display or stored in
a colormapped file format. For example, if you have
an 8-bit display, you'd need to reduce to 256 or fewer
colors. (-colors is the recommended name, -quantize
is provided only for backwards compatibility.)
-colors N Reduce image to at most N colors [legacy feature].
or -quantize N This reduces the number of colors used in the output
image so that it can be stored in a colormapped file
format. This feature cannot be used when decompressing
lossless JPEG images. (-colors is the recommended
name. -quantize is provided only for backward
compatibility.)
-fast Select recommended processing options for fast, low
quality output. (The default options are chosen for
highest quality output.) Currently, this is equivalent
to "-dct fast -nosmooth -onepass -dither ordered".
-fast Select recommended processing options for low-quality
output [legacy feature]. (The default options are
chosen for highest-quality output.) Currently, this is
equivalent to "-dct fast -nosmooth -onepass -dither
ordered". On modern CPUs, these settings have little
or no performance benefit and are retained solely for
backward compatibility.
-grayscale Force grayscale output even if JPEG file is color.
Useful for viewing on monochrome displays; also,
djpeg runs noticeably faster in this mode.
-grayscale Force grayscale output even if JPEG file is full-color.
This feature cannot be used when decompressing
full-color lossless JPEG images.
-rgb Force RGB output even if JPEG file is grayscale.
-rgb Force RGB output even if JPEG file is grayscale. This
feature cannot be used when decompressing grayscale
lossless JPEG images.
-scale M/N Scale the output image by a factor M/N. Currently
the scale factor must be M/8, where M is an integer
between 1 and 16 inclusive, or any reduced fraction
thereof (such as 1/2, 3/4, etc. Scaling is handy if
the image is larger than your screen; also, djpeg runs
much faster when scaling down the output.
-scale M/N Scale the output image by a factor M/N. Currently the
scale factor must be M/8, where M is an integer between
1 and 16 inclusive, or any reduced fraction thereof
(such as 1/2, 3/4, etc.) Scaling is handy if the image
is larger than your screen. This feature cannot be
used when decompressing lossless JPEG images.
-bmp Select BMP output format (Windows flavor). 8-bit
colormapped format is emitted if -colors or -grayscale
is specified, or if the JPEG file is grayscale;
otherwise, 24-bit full-color format is emitted.
otherwise, 24-bit full-color format is emitted. This
format can only be used when decompressing
8-bit-per-sample JPEG images.
-gif Select GIF output format (LZW-compressed). Since GIF
does not support more than 256 colors, -colors 256 is
assumed (unless you specify a smaller number of
colors). If you specify -fast, the default number of
colors is 216.
-gif Select GIF output format (LZW-compressed) [legacy
feature]. Since GIF does not support more than 256
colors, -colors 256 is assumed (unless you specify a
smaller number of colors). If you specify -fast, the
default number of colors is 216. This format can only
be used when decompressing 8-bit-per-sample or
12-bit-per-sample lossy JPEG images.
-gif0 Select GIF output format (uncompressed). Since GIF
does not support more than 256 colors, -colors 256 is
assumed (unless you specify a smaller number of
colors). If you specify -fast, the default number of
colors is 216.
-gif0 Select GIF output format (uncompressed) [legacy
feature]. Since GIF does not support more than 256
colors, -colors 256 is assumed (unless you specify a
smaller number of colors). If you specify -fast, the
default number of colors is 216. This format can only
be used when decompressing 8-bit-per-sample or
12-bit-per-sample lossy JPEG images.
-os2 Select BMP output format (OS/2 1.x flavor). 8-bit
colormapped format is emitted if -colors or -grayscale
is specified, or if the JPEG file is grayscale;
otherwise, 24-bit full-color format is emitted.
-os2 Select BMP output format (OS/2 1.x flavor) [legacy
feature]. 8-bit colormapped format is emitted if
-colors or -grayscale is specified, or if the JPEG file
is grayscale; otherwise, 24-bit full-color format is
emitted. This format can only be used when
decompressing 8-bit-per-sample JPEG images.
-pnm Select PBMPLUS (PPM/PGM) output format (this is the
default format). PGM is emitted if the JPEG file is
grayscale or if -grayscale is specified; otherwise
PPM is emitted.
grayscale or if -grayscale is specified; otherwise PPM
is emitted.
-targa Select Targa output format. Grayscale format is
emitted if the JPEG file is grayscale or if
-targa Select Targa output format [legacy feature]. Grayscale
format is emitted if the JPEG file is grayscale or if
-grayscale is specified; otherwise, colormapped format
is emitted if -colors is specified; otherwise, 24-bit
full-color format is emitted.
full-color format is emitted. This format can only be
used when decompressing 8-bit-per-sample JPEG images.
Switches for advanced users:
@@ -401,32 +441,39 @@ Switches for advanced users:
behavior, whereas the integer methods should give the
same results on all machines.
-dither fs Use Floyd-Steinberg dithering in color quantization.
-dither ordered Use ordered dithering in color quantization.
-dither none Do not use dithering in color quantization.
By default, Floyd-Steinberg dithering is applied when
quantizing colors; this is slow but usually produces
the best results. Ordered dither is a compromise
between speed and quality; no dithering is fast but
usually looks awful. Note that these switches have
no effect unless color quantization is being done.
Ordered dither is only available in -onepass mode.
-dither fs Use Floyd-Steinberg dithering when quantizing colors
[legacy feature].
-dither ordered Use ordered dithering when quantizing colors [legacy
feature].
-dither none Do not use dithering when quantizing colors [legacy
feature]. By default, Floyd-Steinberg dithering is
applied when quantizing colors. This is slower but
usually produces the best results. Ordered dithering
is a compromise between speed and quality. No
dithering is faster but usually looks awful. Note that
these switches have no effect unless color quantization
is being done. Ordered dithering is only available in
-onepass mode.
-map FILE Quantize to the colors used in the specified image
file. This is useful for producing multiple files
with identical color maps, or for forcing a predefined
set of colors to be used. The FILE must be a GIF
or PPM file. This option overrides -colors and
-onepass.
-icc FILE Extract ICC color management profile to the specified
file.
-map FILE Quantize to the colors used in the specified image file
[legacy feature]. This is useful for producing
multiple files with identical color maps, or for
forcing a predefined set of colors to be used. The
FILE must be a GIF or PPM file. This option overrides
-colors and -onepass.
-nosmooth Use a faster, lower-quality upsampling routine.
-onepass Use one-pass instead of two-pass color quantization.
The one-pass method is faster and needs less memory,
but it produces a lower-quality image. -onepass is
ignored unless you also say -colors N. Also,
the one-pass method is always used for grayscale
output (the two-pass method is no improvement then).
-onepass Use one-pass instead of two-pass color quantization
[legacy feature]. The one-pass method needs less
memory, but it produces a lower-quality image.
-onepass is ignored unless you also specify -colors N.
Also, the one-pass method is always used for grayscale
output. (The two-pass method has no improvement in
that case.)
-maxmemory N Set limit for amount of memory to use in processing
large images. Value is in thousands of bytes, or
@@ -434,18 +481,62 @@ Switches for advanced users:
For example, -max 4m selects 4000000 bytes. If more
space is needed, an error will occur.
-verbose Enable debug printout. More -v's give more printout.
-maxscans N Abort if the JPEG image contains more than N scans.
This feature demonstrates a method by which
applications can guard against denial-of-service
attacks instigated by specially-crafted malformed JPEG
images containing numerous scans with missing image
data or image data consisting only of "EOB runs" (a
feature of progressive JPEG images that allows
potentially hundreds of thousands of adjoining
zero-value pixels to be represented using only a few
bytes.) Attempting to decompress such malformed JPEG
images can cause excessive CPU activity, since the
decompressor must fully process each scan (even if the
scan is corrupt) before it can proceed to the next
scan.
-memsrc Load input file into memory before decompressing. This
feature was implemented mainly as a way of testing the
in-memory source manager (jpeg_mem_src().)
-report Report decompression progress.
-skip Y0,Y1 Decompress all rows of the JPEG image except those
between Y0 and Y1 (inclusive.) Note that if
decompression scaling is being used, then Y0 and Y1 are
relative to the scaled image dimensions.
-crop WxH+X+Y Decompress only a rectangular subregion of the image,
starting at point X,Y with width W and height H. If
necessary, X will be shifted left to the nearest iMCU
boundary, and the width will be increased accordingly.
Note that if decompression scaling is being used, then
X, Y, W, and H are relative to the scaled image
dimensions. Currently this option only works with the
PBMPLUS (PPM/PGM), GIF, and Targa output formats.
-strict Treat all warnings as fatal. This feature also
demonstrates a method by which applications can guard
against attacks instigated by specially-crafted
malformed JPEG images. Enabling this option will cause
the decompressor to abort if the JPEG image contains
incomplete or corrupt image data.
-verbose Enable debug printout. More -v's give more output.
or -debug Also, version information is printed at startup.
-version Print version information and exit.
HINTS FOR CJPEG
Color GIF files are not the ideal input for JPEG; JPEG is really intended for
compressing full-color (24-bit) images. In particular, don't try to convert
cartoons, line drawings, and other images that have only a few distinct
colors. GIF works great on these, JPEG does not. If you want to convert a
GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options
to get a satisfactory conversion. -smooth 10 or so is often helpful.
compressing full-color (24-bit through 48-bit) images. In particular, don't
try to convert cartoons, line drawings, and other images that have only a few
distinct colors. GIF works great on these; JPEG does not. If you want to
convert a GIF to JPEG, you should experiment with cjpeg's -quality and -smooth
options to get a satisfactory conversion. -smooth 10 or so is often helpful.
Avoid running an image through a series of JPEG compression/decompression
cycles. Image quality loss will accumulate; after ten or so cycles the image
@@ -460,20 +551,6 @@ is often a lot more than it is on larger files. (At present, -optimize
mode is always selected when generating progressive JPEG files.)
HINTS FOR DJPEG
To get a quick preview of an image, use the -grayscale and/or -scale switches.
"-grayscale -scale 1/8" is the fastest case.
Several options are available that trade off image quality to gain speed.
"-fast" turns on the recommended settings.
"-dct fast" and/or "-nosmooth" gain speed at a small sacrifice in quality.
When producing a color-quantized image, "-onepass -dither ordered" is fast but
much lower quality than the default behavior. "-dither none" may give
acceptable results in two-pass mode, but is seldom tolerable in one-pass mode.
HINTS FOR BOTH PROGRAMS
If the memory needed by cjpeg or djpeg exceeds the limit specified by
@@ -489,12 +566,12 @@ explicit -maxmemory switch.
JPEGTRAN
jpegtran performs various useful transformations of JPEG files.
It can translate the coded representation from one variant of JPEG to another,
for example from baseline JPEG to progressive JPEG or vice versa. It can also
perform some rearrangements of the image data, for example turning an image
from landscape to portrait format by rotation. For EXIF files and JPEG files
containing Exif data, you may prefer to use exiftran instead.
jpegtran performs various useful transformations of lossy (DCT-based) JPEG
files. It can translate the coded representation from one variant of JPEG to
another, for example from baseline JPEG to progressive JPEG or vice versa. It
can also perform some rearrangements of the image data, for example turning an
image from landscape to portrait format by rotation. For EXIF files and JPEG
files containing Exif data, you may prefer to use exiftran instead.
jpegtran works by rearranging the compressed data (DCT coefficients), without
ever fully decoding the image. Therefore, its transformations are lossless:
@@ -650,10 +727,15 @@ The default behavior is -copy comments. (Note: in IJG releases v6 and v6a,
jpegtran always did the equivalent of -copy none.)
Additional switches recognized by jpegtran are:
-outfile filename
-icc FILE
-maxmemory N
-maxscans N
-outfile filename
-report
-strict
-verbose
-debug
-version
These work the same as in cjpeg or djpeg.