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

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