https://github.com/thorfdbg/libjpeg/blob/master/README

This project implements a complete(!) JPEG (Rec. ITU-T T.81 | ISO/IEC

10918-1) codec, plus a library that can be used to encode and decode

JPEG streams. It also implements ISO/IEC 18477 aka JPEG XT which is

an extension towards intermediate, high-dynamic-range lossy and

lossless coding of JPEG. In specific, it supports ISO/IEC

18477-3/-6/-7/-8/-9 encoding.

--------------------------------------------------------------------------

Unlike many other implementations, libjpeg also implements:

- 12 bpp image coding for the lossy DCT process,

- the predictive lossless mode of Rec. ITU-T T.81 | ISO/IEC 10918-1,

- the hierarchical process of Rec. ITU-T T.81 | ISO/IEC 10918-1,

- the arithmetic coding option of Rec. ITU-T T.81 | ISO/IEC 10918-1,

- coding of up to 256 component images

- upsampling of images for all factors from 1x1 to 4x4

Standard features are of course also supported, such as

sequential and progressive mode in 8bpp.

--------------------------------------------------------------------------

In addition, this codec provides methods to encode images

- with a bit depth between 8 and 16 bits per sample, fully backwards

compatible to Rec. ITU-T T.81 | ISO/IEC 10918 baseline coding.

- consisting of floating point samples, specifically images with

high dynamic range.

- to encode images without loss, regardless of their bit-depth and their

sample data type.

--------------------------------------------------------------------------

Example usage:

Standard JPEG compression, with 444 (aka "no") subsampling:

$ jpeg -q <quality> infile.ppm outfile.jpg

Standard JPEG compression, with 422 subsampling:

$ jpeg -q <quality> -s 1x1,2x2,2x2 infile.ppm outfile.jpg

Intermediate dynamic range compression, i.e. compression of images

of a bit-depth between 8 and 16 bits:

$ jpeg -r -q <base-quality> -Q <extension-quality> -h -r12 infile.ppm outfile.jpg

This type of encoding uses a technology known as "residual scans" which

increase the bit-depths in the spatial domain which is enabled by the -r

command line switch. The -Q parameter sets the quality of the residual image.

To improve the precision in the frequency domain, "refinement scans" can be used.

The following encodes a 12-bit image with four additional refinement scans,

enabled by the "-R 4" parameter.

$ jpeg -q <quality> -R 4 -h infile.ppm outfile.jpg

Both technologies can be combined, and the precision of the residual scan

can also be enlarged by using residual refinement scans with the -rR option.

The following command line with use a 12-bit residual scan with four refinement

scans:

$ jpeg -r -q <base-quality> -Q <extension-quality> -h -rR 4 infile.ppm outfile.jpg

High-dynamic range compression allows three different profiles of varying

complexity and performance. The profiles are denoted by "-profile <X>" where

<X> is a,b or c. The following encodes an HDR image in profile C:

$ jpeg -r -q <base-quality> -Q <extension-quality> -h -profile c -rR 4 infile.pfm outfile.jpg

HDR images here have to be fed into the command line in "pfm" format.

exr or hdr is not supported as input format and requires conversion to

pfm first. pfm is the floating-point equivalent of ppm and encodes each

pixel by three 32-bit floating point numbers.

Encoding in profiles a and b works likewise, though it is generally advisable to

use "open loop" rather than "closed loop" coding for these two profiles by

additionally providing the "-ol" parameter. This also works for profile C:

$ jpeg -ol -r -profile a -q <base-quality> -Q <extension-quality> -h infile.pfm out.jpg

similar for profile B.

What is common to profiles A and C is that you may optionally also specify

the LDR image, i.e. the image that a legacy JPEG decoder will show. By default,

a simple tone mapping algorithm ("global Reinhard") will be used to derive a

suitable LDR image from the input image:

$ jpeg -ldr infile.ppm -q <base-quality> -Q <extension-quality> -h -rR 4 infile.pfm out.jpg

The profile is by default profile c, but it also works for profile a:

$ jpeg -ol profile a -ldr infile.ppm -q <base-quality> -Q <extension-quality> infile.pfm out.jpg

It is in general advisable for profile c encoding to enable residual refinement scans,

profiles a or b do not require them.

The following options exist for lossless coding integer:

predictive Rec. ITU-T T.81 | ISO/IEC 10918-1 coding. Note, however,

that not many implementations are capable of decoding such stream,

thus this is probably not a good option for all-day purposes.

$ jpeg -p -c infile.ppm out.jpg

While the result is a valid Rec. ITU-T T.81 | ISO/IEC 10918-1 stream,

most other implementations will hick up and break, thus it is not

advisable to use it.

A second option for lossless coding is residual coding within profile c:

$ jpeg -q <quality> -Q 100 -h -r infile.ppm out.jpg

This also works for floating point coding. Note that lossless coding is enabled

by setting the extension quality to 100.

$ jpeg -q <quality> -Q 100 -h -r infile.pfm out.jpg

However, this is only lossless for 16 bit input samples, i.e. there is a precision

loss due to down-converting the 32-bit input to 16 bit. If samples are out of the

601 gamut, the problem also exists that clamping will happen. To avoid that,

encode in the XYZ color space (profile C only, currently):

$ jpeg -xyz -q <quality> -Q 100 -h -r infile.pfm out.jpg

A second option for lossless integer coding is to use a lossless 1-1 DCT

process. This is enabled with the -l command line option:

$ jpeg -l -q 100 -c infile.ppm out.jpg

Refinement scans can be used to increase the sample precision to up to 12

bits. The "-c" command line option disables the lossy color transformation.

Additionally, this implementation also supports JPEG LS, which is

outside of Rec. ITU-T T.81 | ISO/IEC 10918-1 and ISO/IEC 18477. For

that, use the command line option -ls:

$ jpeg -ls -c infile.ppm out.jpg

The "-c" command line switch is necessary to disable the color transformation

as JPEG LS typically encodes in RGB and not YCbCr space.

Optionally, you may specify the JPEG LS "near" parameter (maximum error) with

the -m command line switch:

$ jpeg -ls -m 2 -c infile.ppm out.jpg

JPEG LS also specifies a lossless color transformation that is enabled with

-cls:

$ jpeg -ls -cls infile.ppm out.jpg

To encode images with an alpha channel, specify the source image that

contains the alpha channel with -al. The alpha channel is a one-component

grey-scale image, either integer or floating point. The quality of the

alpha channel is specified with -aq, that of the regular image with -q:

$ jpeg -al alpha.pgm -aq 80 -q 85 input.ppm output.jpg

Alpha channels can be larger than 8bpp or can be floating point. In both

cases, residual coding is required. To enable residual coding in the alpha

channel, use the -ar command line option. Similar to the regular image,

where residual coding requires two parameters, -q for the base quality and

-Q for the extension quality, an alpha channel that uses residual coding

also requires a base and extension quality, the former is given by -aq,

the latter with -aQ:

$ jpeg -ar -al alphahigh.pgm -q 85 -Q 90 -aq 80 -aQ 90 input.ppm out.jpg

The alpha channel can be encoded without loss if desired. For that, enable

residual coding with -ar and specify an extension quality of 100:

$ jpeg -ar -al alphahigh.pgm -q 85 -Q 90 -aq 80 -aQ 100 input.ppm out.jpg

The alpha channel can use the same technology extensions as the image,

namely refinement scans in the base or extension image, or 12-bit residual

images. The number of refinement scans is selected with -aR and -arR for

the base and residual image, a 12-bit residual image is selected with -ar12.

--------------------------------------------------------------------------

Decoding is much simpler:

$ jpeg infile.jpg out.ppm

or, for floating point images:

$ jpeg infile.jpg out.pfm

If you want to decode a JPEG LS image, then you may want to tell the

decoder explicitly to disable the color transformation even though the

corresponding marker signalling coding in RGB space is typically missing

for JPEG LS:

$ jpeg -c infile.jpg out.ppm

If an alpha channel is included in the image, the decoder does not

reconstruct this automatically, nor does it attempt to merge the alpha

image into the file. Instead, it may optionally be instructed to write the

alpha channel into a separate 1-component (grey-scale) file:

$ jpeg -al alpha.pgm infile.jpg outfile.ppm

The -al option for the decoder provides the target file for the alpha

channel.

--------------------------------------------------------------------------

Starting with release 1.30, libjpeg will include a couple of optimization

parameters to improve the performance of JPEG and JPEG XT. In this

release, the following additional command line switches are available:

-qt <n> : Selects a different quantization table. The default table,

also enabled by -qt 0, is the one in the legacy JPEG standard

(Rec. ITU-T T.81 | ISO/IEC 10918-1). -qt 1 is the "flat" table for

PSNR-optimal performance. It is not recommended for real-life usage as

its visual performance is non-ideal, it just generates "nice

numbers". -qt 2 is MS-SSIM ideal, but similarly, not necessarily a

good recommendation for all-day use. -qt 3 is a good compromize and

usually works better than -qt 0.

-dz : This option enables a deadzone quantizer that shifts the buckets

by 1/8th of their size to the outside. This is (almost) the ideal choice

for Laplacian sources which would require a shift of 1/12th. Nevertheless,

this option improves the rate-distortion performance by about 0.3dB on

average and works pretty consistent over many images.

Additional options are planned for future releases.

-------------------------------------------------------------------------------------

Release 1.40:

In this release, we included additional support for "full profile" encoding, i.e.

encoding parameters that do not fit any of the four profiles specified in 18477-7.

Using such encoding parameters will generate a warning on the command line, but

encoding will proceed anyhow, generating a bitstream that conforms to 18477-7, but

not to any of the profiles in this standard.

With "-profile a -g 0" or "-profile b -g 0" the encoder will generate a file that

uses an inverse TMO lookup similar to profile C with other encoding parameters

identical to those defined by profiles A and B.

The command line option "-lr" will use a logarithmic encoding instead of the gamma

encoding for profile B. Again, this will leave the profile, but will be within the

bounds of 18477-7.

Other than that, a couple of bug fixes have been made. Profile A and B setup could

not reset the toe value for the inverse gamma map, due to a typo of one of the

parameters. Profile B accepted a different gamma value than the default, but never

communicated it to the core code, i.e. it was simply ignored. Profile B setup ignored

the epsilon values for numerator and denomiator, and they were communicated wrongly

into the core code. This was corrected, and epsilons can now be specified on the

command line.

--------------------------------------------------------------------------

Release 1.50:

This release fixes encoding of ISO/IEC 18477-8 if the IDCT was selected as

transformation in the extension layer and refinement scans were added, i.e.

the command line options -rl -rR 4 created invalid codestreams. Previous

releases used the wrong type of refinement scan (dct bypass refinement instead

of regular refinement) and hence broke reconstruction. Furthermore, previous

releases no longer allowed near lossless coding with DCT bypass. Instead, regular

DCT coding conforming to ISO/IEC 18477-7 was used. To enable the near-lossless

DCT bypass mode, use the new option "-ro" now.

Profile B encoding could potentially create codestreams that run into

clipping of the extension channel; this always happens if the denominator is

larger than 1, and has to happen according to Annex C of ISO/IEC 18477-3.

This release avoids this issue by adjusting the exposure value such that

the denominator always remains smaller than 1.

--------------------------------------------------------------------------

Release 1.51:

If the JPEG-XT markers were delayed to the frame-header intead the global

header, the previous code did not built up the necessary infrastructure

to compute the checksum and hence could not verify the checksum in such

a condition. The 1.51 release fixes this problem.

--------------------------------------------------------------------------

Release 1.52:

This file is an updated/enhanced version of the 1.51 release of

the JPEG XT demo software found on https://github.com/thorfdbg/. It

includes additional features presented in the paper

"JPEG on Steroids : Common Optimization Techniques for JPEG Image Compression"

by the same author.

In specific, the following command line flags are *NEW* to this version and

are available only as a contribution to ICIP 2016:

-oz: This enables the dynamic programming algorithm to enhance

the rate-distortion performance by soft-threshold quantization. It has been

used for the tests in section 3.3 of the paper.

-dr: This enables the smart de-ringing algorithm that has been used

in section 3.6.

Additionally, the following switches have been used for other subsections

of the paper; they are not new to this distribution but available as

part of the regular libjpeg distribution at github or www.jpeg.org:

-s 1x1,2x2,2x2: Enable 420 subsampling (444 is default)

-s 1x1,2x1,2x1: Enable 422 subsampling (444 is default)

-qt n (n=0..8) Use quantization matrix n.

In the paper, n=1 (flat) was used for PSNR-optimized

coding, unless otherwise noted.

-dz The deadzone quantizer in section 3.3

(simpler than -oz)

-v Enable coding in processive mode (section 3.5)

-v -qv Optimized progressive mode (section 3.5)

-h Optimized Huffman coding (always used, unless noted

otherwise, see section 3.4)

--------------------------------------------------------------------------

Release 1.53:

This release includes additional functionality to inject markers, or

retrieve markers from a codestream while reading. For that, set

the JPGTAG_ENCODER_STOP tag of the JPEG::Write() call to a bitmask

where the encoder should interrupt writing data (this flag already

existed before) then write custom data with JPEG::WriteMarker(), then

continue with JPEG::Write(). On decoding, set JPGTAG_DECODER_STOP to

a bitmask where to stop for markers, then identify markers with

JPEG::PeekMarker(), and retrieve them with JPEG::ReadMarker(). Details

can be found in cmd/encodec.cpp for encoding, and cmd/reconstruct.cpp.

Otherwise, no functional changes.

--------------------------------------------------------------------------

Release 1.54:

In this release, upsampling has been made conforming to the latest

corrigendum of 18477-1 and 18477-8. In particular, upsampling is now

by design always centered and never co-sited. The co-sited upsampling

procedure is still included in the source code, but never executed.

--------------------------------------------------------------------------

Release 1.55:

This release only addresses some minor formulation issues of the

command line such that references are formatted properly to make this

software package acceptable as a JPEG reference software.

No functional changes.

--------------------------------------------------------------------------

Release 1.56:

Encoding and reconstruction of 2-component images was actually never

supported, as it was considered a rather exotic use-case. Now that a

request was made, support for 2-components was added and should

hopefully work ok.

--------------------------------------------------------------------------

Release 1.57:

Newer g++ compiler versions warned about implicit fall-throughs in switch/

case constructs that are actually harmless. This release adds an autoconf

detection of such compiler versions, adds consistent comments throughout

the code.

--------------------------------------------------------------------------

For license conditions, please check the file "LICENSE" in this

directory.

Finally, I want to thank Accusoft and the Computing Center of the University of

Stuttgart and Fraunhofer IIS for sponsoring this project.

Thomas Richter, April 2020

-------------------------------------------------------------------------------------