From 8456d2b98cf1dd4867abcad9088fabac549959ba Mon Sep 17 00:00:00 2001 From: DRC Date: Fri, 30 Aug 2024 10:50:13 -0400 Subject: [PATCH] Doc: "MCU block" = "iMCU" or "MCU" The JPEG-1 spec never uses the term "MCU block". That term is rarely used in other literature to describe the equivalent of an MCU in an interleaved JPEG image, but the libjpeg documentation uses "iMCU" to describe the same thing. "iMCU" is a better term, since the equivalent of an interleaved MCU can contain multiple DCT blocks (or samples in lossless mode) that are only grouped together if the image is interleaved. In the case of restart markers, "MCU block" was used in the libjpeg documentation instead of "MCU", but "MCU" is more accurate and less confusing. (The restart interval is literally in MCUs, where one MCU is one data unit in a non-interleaved JPEG image and multiple data units in a multi-component interleaved JPEG image.) In the case of 9b704f96b2dccc54363ad7a2fe8e378fc1a2893b, the issue was actually with progressive JPEG images exactly two DCT blocks wide, not two MCU blocks wide. This commit also defines "MCU" and "MCU row" in the description of the various restart marker options/parameters. Although an MCU row is technically always a row of samples in lossless mode, "sample row" was confusing, since it is used in other places to describe a row of samples for a single component (whereas an MCU row in a typical lossless JPEG image consists of a row of interleaved samples for all components.) --- ChangeLog.md | 8 +- cjpeg.1 | 16 ++- doc/html/group___turbo_j_p_e_g.html | 61 ++++----- doc/html/structtjregion.html | 4 +- java/TJBench.java | 9 +- java/TJExample.java | 6 +- java/doc/index-all.html | 13 +- java/doc/member-search-index.zip | Bin 1951 -> 1951 bytes java/doc/org/libjpegturbo/turbojpeg/TJ.html | 75 +++++++---- .../turbojpeg/TJDecompressor.html | 12 +- .../libjpegturbo/turbojpeg/TJTransform.html | 40 +++--- java/doc/package-search-index.zip | Bin 237 -> 237 bytes java/doc/type-search-index.zip | Bin 311 -> 311 bytes java/org/libjpegturbo/turbojpeg/TJ.java | 64 +++++++--- .../turbojpeg/TJDecompressor.java | 12 +- .../libjpegturbo/turbojpeg/TJTransform.java | 41 +++--- jpegtran.1 | 6 +- libjpeg.txt | 17 ++- tjbench.c | 9 +- tjexample.c | 4 +- turbojpeg.c | 2 +- turbojpeg.h | 120 +++++++++++------- usage.txt | 22 +++- 23 files changed, 323 insertions(+), 218 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 108f6ccb..e771e3ef 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -114,7 +114,7 @@ within the functions. 2. Fixed two minor issues in the interblock smoothing algorithm that caused mathematical (but not necessarily perceptible) edge block errors when -decompressing progressive JPEG images exactly two MCU blocks in width or that +decompressing progressive JPEG images exactly two DCT blocks in width or that use vertical chrominance subsampling. 3. Fixed a regression introduced by 3.0 beta2[6] that, in rare cases, caused @@ -471,9 +471,9 @@ prevented libjpeg-turbo from working properly with other linkers and also represented a potential security risk. 2. Fixed an issue whereby the `tjTransform()` function incorrectly computed the -MCU block size for 4:4:4 JPEG images with non-unary sampling factors and thus -unduly rejected some cropping regions, even though those regions aligned with -8x8 MCU block boundaries. +iMCU size for 4:4:4 JPEG images with non-unary sampling factors and thus unduly +rejected some cropping regions, even though those regions aligned with 8x8 iMCU +boundaries. 3. Fixed a regression introduced by 2.1 beta1[13] that caused the build system to enable the Arm Neon SIMD extensions when targetting Armv6 and other legacy diff --git a/cjpeg.1 b/cjpeg.1 index ca184571..28a633b3 100644 --- a/cjpeg.1 +++ b/cjpeg.1 @@ -1,4 +1,4 @@ -.TH CJPEG 1 "24 June 2024" +.TH CJPEG 1 "30 August 2024" .SH NAME cjpeg \- compress an image file to a JPEG file .SH SYNOPSIS @@ -270,8 +270,18 @@ machines. Embed ICC color management profile contained in the specified file. .TP .BI \-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. +Emit a JPEG restart marker every N MCU rows, or every N MCUs if "B" is attached +to the number. +.IP +In typical JPEG images, an MCU (Minimum Coded Unit) is the minimum set of +interleaved "data units" (8x8 DCT blocks if the image is lossy or samples if +the image is lossless) necessary to represent at least one data unit per +component. (For example, an MCU in an interleaved lossy JPEG image that uses +4:2:2 subsampling consists of two luminance blocks followed by one block for +each chrominance component.) In single-component or non-interleaved JPEG +images, an MCU is the same as a data unit. An MCU row is a row of MCUs +spanning the entire width of the image. +.IP .B \-restart 0 (the default) means no restart markers. .TP diff --git a/doc/html/group___turbo_j_p_e_g.html b/doc/html/group___turbo_j_p_e_g.html index 4deb7cba..b0eb355a 100644 --- a/doc/html/group___turbo_j_p_e_g.html +++ b/doc/html/group___turbo_j_p_e_g.html @@ -120,7 +120,7 @@ Macros  This option causes tj3Transform() to return an error if the transform is not perfect.
  #define TJXOPT_TRIM - Discard any partial MCU blocks that cannot be transformed.
+ Discard any partial iMCUs that cannot be transformed.
  #define TJXOPT_CROP  Enable lossless cropping.
@@ -386,10 +386,10 @@ Functions

Variables

static const int tjMCUWidth [TJ_NUMSAMP] - MCU block width (in pixels) for a given level of chrominance subsampling.
+ iMCU width (in pixels) for a given level of chrominance subsampling
  static const int tjMCUHeight [TJ_NUMSAMP] - MCU block height (in pixels) for a given level of chrominance subsampling.
+ iMCU height (in pixels) for a given level of chrominance subsampling
  static const int tjRedOffset [TJ_NUMPF]  Red offset (in samples) for a given pixel format.
@@ -664,7 +664,7 @@ scalingFactor).

This option causes tj3Transform() to return an error if the transform is not perfect.

-

Lossless transforms operate on MCU blocks, the size of which depends on the level of chrominance subsampling used (see tjMCUWidth and tjMCUHeight.) If the image's width or height is not evenly divisible by the MCU block size, then there will be partial MCU blocks on the right and/or bottom edges. It is not possible to move these partial MCU blocks to the top or left of the image, so any transform that would require that is "imperfect." If this option is not specified, then any partial MCU blocks that cannot be transformed will be left in place, which will create odd-looking strips on the right or bottom edge of the image.

+

Lossless transforms operate on iMCUs, the size of which depends on the level of chrominance subsampling used (see tjMCUWidth and tjMCUHeight.) If the image's width or height is not evenly divisible by the iMCU size, then there will be partial iMCUs on the right and/or bottom edges. It is not possible to move these partial iMCUs to the top or left of the image, so any transform that would require that is "imperfect." If this option is not specified, then any partial iMCUs that cannot be transformed will be left in place, which will create odd-looking strips on the right or bottom edge of the image.

@@ -697,7 +697,7 @@ scalingFactor).

-

Discard any partial MCU blocks that cannot be transformed.

+

Discard any partial iMCUs that cannot be transformed.

@@ -900,7 +900,7 @@ scalingFactor).

Huffman table optimization improves compression slightly (generally 5% or less), but it reduces compression performance considerably.

TJPARAM_PROGRESSIVE 

Progressive JPEG.

-

In a progressive JPEG image, the DCT coefficients are split across multiple "scans" of increasing quality. Thus, a low-quality scan containing the lowest-frequency DCT coefficients can be transmitted first and refined with subsequent higher-quality scans containing higher-frequency DCT coefficients. When using Huffman entropy coding, the progressive JPEG format also provides an "end-of-bands (EOB) run" feature that allows large groups of zeroes, potentially spanning multiple MCU blocks, to be represented using only a few bytes.

+

In a progressive JPEG image, the DCT coefficients are split across multiple "scans" of increasing quality. Thus, a low-quality scan containing the lowest-frequency DCT coefficients can be transmitted first and refined with subsequent higher-quality scans containing higher-frequency DCT coefficients. When using Huffman entropy coding, the progressive JPEG format also provides an "end-of-bands (EOB) run" feature that allows large groups of zeroes, potentially spanning multiple MCUs, to be represented using only a few bytes.

Value