Enable colorimetric normalization of JPEG image data during decode by JimBobSquarePants · Pull Request #2922 · SixLabors/ImageSharp

JimBobSquarePants · 2025-05-16T14:05:14Z

Prerequisites

I have written a descriptive pull-request title
I have verified that there are no overlapping pull-requests open
I have verified that I am following the existing coding patterns and practice as demonstrated in the repository. These follow strict Stylecop rules 👮.
I have provided test coverage for my change (where applicable)

Description

Fixes File conversion from jpg to webp changes colors of the image #2723
Fixes Color Changed When Resize #129 - opened 8 years, 2 months, and 7 days ago
Likely impacts Jpeg compressed tiff with photometric interpretation Separated is not supported #2454 (cc @brianpopow)

This PR adds support for normalizing color data in JPEG files (and TIFF files with JPEG compression) to sRGB during decoding.

A new DecoderOptions.ColorProfileHandling property controls this behavior with the following options:

Preserve - Leaves any embedded ICC color profiles intact. (default, preserves existing behavior)
Compact - Removes any embedded Standard sRGB ICC color profiles without transforming pixel data.
Convert - Transforms pixels based on embedded ICC profiles into the sRGB v4 color space, then removes the original profile.

Several internal helper methods have been introduced to allow decoders to determine and apply the correct behavior.

All shared JPEG color converters now use a common scalar interleaving path to manipulate planar data for ColorProfileConverter. There's likely room for SIMD-based performance improvements here (AVX-512?).

@waacton - might be of interest to you since it introduces questions around deriving RGB working spaces from ICC profiles which you are likely to better understand than I.
@saucecontrol - tagging you since your compact sRGB v4 profile implementation was invaluable (and shamelessly borrowed 😁).

Copilot

Pull Request Overview

Adds colorimetric normalization support for JPEG (and JPEG-compressed TIFF) data by embedding ICC-based conversions into the decoding pipeline.

Introduces DecoderOptions.ColorProfileHandling to specify Preserve, Compact, or Convert behavior.
Extends grayscale and CMYK JPEG converters with ConvertToRgbInPlaceWithIcc paths and integrates ICC removal in ImageDecoder.
Renames and updates YCbCr types to YCbCrTransform, and adjusts color-profile classes for the new workflows.

Reviewed Changes

Copilot reviewed 59 out of 59 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.GrayScaleVector512.cs	Add ICC-aware override and repeat grayscale channel in vectorized path
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.GrayScaleVector256.cs	Add ICC-aware override and repeat grayscale channel in vectorized path
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.GrayScaleVector128.cs	Add ICC-aware override and repeat grayscale channel in vectorized path
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.GrayScaleScalar.cs	Implement scalar ICC conversion with buffer packing/unpacking
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.CmykVector512.cs	Add ICC-aware override for CMYK vectorized converter
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.CmykVector256.cs	Add ICC-aware override for CMYK vectorized converter
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.CmykVector128.cs	Add ICC-aware override for CMYK vectorized converter
src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.CmykScalar.cs	Implement scalar ICC conversion for CMYK
src/ImageSharp/Formats/ImageDecoder.cs	Invoke `HandleIccProfile` after decode/identify to strip profiles
src/ImageSharp/Formats/DecoderOptions.cs	Expose `ColorProfileHandling` and add profile‐selection helpers
src/ImageSharp/Formats/ColorProfileHandling.cs	Define `Compact` and update docs for enum
src/ImageSharp/ColorProfiles/YccK.cs	Rename matrix references to `YCbCrTransform`
src/ImageSharp/ColorProfiles/YCbCrTransform.cs	Rename `YCbCrMatrix` to `YCbCrTransform` and update ctor/docs
src/ImageSharp/ColorProfiles/YCbCr.cs	Update property references to `YCbCrTransform`
src/ImageSharp/ColorProfiles/Y.cs	Update transform references for Y channel
src/ImageSharp/ColorProfiles/Rgb.cs	Replace `ToScaledVector3` calls with `AsVector3Unsafe`
src/ImageSharp/ColorProfiles/KnownYCbCrMatrices.cs	Rename constants to `YCbCrTransform`
src/ImageSharp/ColorProfiles/Icc/CompactSrgbV4Profile.cs	Rename class to `CompactSrgbV4Profile` and adjust namespace
src/ImageSharp/ColorProfiles/ColorConversionOptions.cs	Change `YCbCrMatrix` property to `YCbCrTransform`
src/ImageSharp/Advanced/AotCompilerTools.cs	Update AOT stubs to match new `GetPixelBuffer` signatures

Comments suppressed due to low confidence (5)

src/ImageSharp/ColorProfiles/ColorConversionOptions.cs:55

Update this XML summary to reflect the renamed property (YCbCrTransform) and its semantics (e.g., "Gets the YCbCr transform used to perform conversions...").

/// Gets the YCbCr matrix to used to perform conversions from/to RGB.

src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.GrayScaleVector512.cs:22

The Configuration type isn’t imported in this file, causing a compilation error; add using SixLabors.ImageSharp; at the top so that Configuration is recognized.

public override void ConvertToRgbInPlaceWithIcc(Configuration configuration, in ComponentValues values, IccProfile profile)

src/ImageSharp/Formats/ImageDecoder.cs:325

[nitpick] This logic is duplicated in two overloads; consider consolidating into a single generic or helper method to reduce code duplication.

private static void HandleIccProfile(DecoderOptions options, Image image)

src/ImageSharp/Formats/Jpeg/Components/ColorConverters/JpegColorConverter.GrayScaleScalar.cs:54

Allocating a new buffer for every decode may impact performance; consider reusing pooled buffers or using stackalloc for small images to reduce allocation overhead.

using IMemoryOwner<float> memoryOwner = configuration.MemoryAllocator.Allocate<float>(values.Component0.Length * 3);

src/ImageSharp/Formats/DecoderOptions.cs:72

The out parameter value is overly generic and nullable despite the NotNullWhen(true) annotation; rename it to a descriptive name (e.g. out IccProfile profileToConvert) and consider making it non-nullable when returned true.

internal bool TryGetIccProfileForColorConversion(IccProfile? profile, [NotNullWhen(true)] out IccProfile? value)

waacton · 2025-05-18T08:32:10Z

(Sorry, misclicking!) Happy to take a look but will be in a couple of weeks after my break

waacton · 2025-06-02T09:34:52Z

 {
+    private static readonly Vector3 TruncatedD50 = new(0.9642029F, 1F, 0.8249054F);
+
+    // sRGB v4 Preference


waacton · 2025-06-02T11:21:51Z

+        }
+
+        // Fallback: best-guess heuristic
+        return


This reminded me that profiles with absolute intent aren't currently handled correctly, but doesn't look like they throw exceptions either yet? (Not that I can find such a profile.)

Could be worth including intent in this check?

I think, in this case, it's not wise to introduce a none sRGB relevant check here. If we attempt to convert an example in the wild someone can raise an issue and we can complete the converter.

waacton · 2025-06-02T11:28:56Z


    internal void SetConfiguration(Configuration configuration) => this.configuration = configuration;
+
+    internal bool TryGetIccProfileForColorConversion(IccProfile? profile, [NotNullWhen(true)] out IccProfile? value)


This return bool isn't currently used, easier to return the IccProfile? itself?

Not at the moment but I think it will be used in other formats.

waacton · 2025-06-02T11:32:49Z

I've scanned over the ICC profile stuff, and if the goal is to detect an sRGB profile and bypass using it since sRGB calculations are already implemented programmatically as the default behaviour, then it makes sense to me.

I've also double-checked the sRGB profile IDs just to be sure 👍

JimBobSquarePants · 2025-06-04T04:40:02Z

Thanks @waacton very much appreciated!

JimBobSquarePants · 2025-06-04T06:26:29Z

Let's merge this!

JimBobSquarePants added 4 commits May 14, 2025 22:12

Rename type

ea56484

Use ICC profile when available for JPEG decoding color transforms.

74d475d

Update Rgb.cs

a744f93

Merge branch 'main' into js/jpeg-icc-normalize

0e31840

JimBobSquarePants added this to the v4.0.0 milestone May 16, 2025

JimBobSquarePants requested review from antonfirsov, brianpopow, Copilot, dlemstra, tocsoft and waacton May 16, 2025 14:05

JimBobSquarePants added formats:jpeg metadata:icc labels May 16, 2025

Copilot AI reviewed May 16, 2025

View reviewed changes

JimBobSquarePants added 3 commits May 17, 2025 00:49

Tweak grayscale converter code

e2cde19

Put that thing back where it came from or so help me!

b10d88a

Add YCCK test

b860f55

waacton closed this May 18, 2025

waacton reopened this May 18, 2025

waacton reviewed Jun 2, 2025

View reviewed changes

JimBobSquarePants added 2 commits June 4, 2025 14:37

Merge branch 'main' into js/jpeg-icc-normalize

818412b

Update IccProfileHeader.cs

04053c5

Update comments

65bb20b

JimBobSquarePants merged commit c19a82e into main Jun 4, 2025
8 checks passed

JimBobSquarePants deleted the js/jpeg-icc-normalize branch June 4, 2025 06:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Enable colorimetric normalization of JPEG image data during decode#2922

Enable colorimetric normalization of JPEG image data during decode#2922
JimBobSquarePants merged 10 commits into
mainfrom
js/jpeg-icc-normalize

JimBobSquarePants commented May 16, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

waacton commented May 18, 2025

Uh oh!

waacton Jun 2, 2025

Uh oh!

waacton Jun 2, 2025

Uh oh!

JimBobSquarePants Jun 4, 2025

Uh oh!

waacton Jun 2, 2025

Uh oh!

JimBobSquarePants Jun 4, 2025

Uh oh!

waacton commented Jun 2, 2025

Uh oh!

JimBobSquarePants commented Jun 4, 2025

Uh oh!

JimBobSquarePants commented Jun 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		internal void SetConfiguration(Configuration configuration) => this.configuration = configuration;

		internal bool TryGetIccProfileForColorConversion(IccProfile? profile, [NotNullWhen(true)] out IccProfile? value)

Uh oh!

Conversation

JimBobSquarePants commented May 16, 2025

Prerequisites

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

waacton commented May 18, 2025

Uh oh!

waacton Jun 2, 2025

Choose a reason for hiding this comment

Uh oh!

waacton Jun 2, 2025

Choose a reason for hiding this comment

Uh oh!

JimBobSquarePants Jun 4, 2025

Choose a reason for hiding this comment

Uh oh!

waacton Jun 2, 2025

Choose a reason for hiding this comment

Uh oh!

JimBobSquarePants Jun 4, 2025

Choose a reason for hiding this comment

Uh oh!

waacton commented Jun 2, 2025

Uh oh!

JimBobSquarePants commented Jun 4, 2025

Uh oh!

JimBobSquarePants commented Jun 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants