Skip to content

GIF: background handling & quantizer overflow fix - #3133

Merged
JimBobSquarePants merged 2 commits into
mainfrom
js/gif-background
May 26, 2026
Merged

GIF: background handling & quantizer overflow fix#3133
JimBobSquarePants merged 2 commits into
mainfrom
js/gif-background

Conversation

@JimBobSquarePants

Copy link
Copy Markdown
Member

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

See SixLabors/ImageSharp.Drawing#396

This pull request makes several significant improvements to GIF encoding and decoding, particularly around how background color is handled, quantization accuracy, and frame disposal behaviors. It also introduces a new regression test for a previously reported issue. The most important changes are grouped below:

GIF Background Color Handling:

  • The concept of background color in GifMetadata has been refactored: instead of storing a palette index (BackgroundColorIndex), the actual Color value is now stored and used throughout encoding and decoding. This change ensures more accurate and flexible background color management. [1] [2] [3] [4]
  • The encoder now determines the background color by first checking the encoder's setting, then falling back to the metadata's background color, and finally using transparent if neither is set. This color is then mapped to the palette for correct index assignment. [1] [2] [3]
  • The obsolete method for determining background index (GetBackgroundIndex) has been removed, simplifying the code and reducing potential for errors. [1] [2]

Quantization and Frame Encoding Enhancements:

  • The quantizer options are now adjusted for animated GIFs to reserve a color-table entry for transparency, improving color allocation for delta frames.
  • The quantization logic in the HexadecatreeQuantizer has been updated to use long instead of int for color channel sums and pixel counts, preventing overflow and improving accuracy for large images or many samples. [1] [2] [3]

Codebase and API Cleanups:

  • The now-unnecessary backgroundColor field in GifEncoderCore has been removed, and related constructor and method signatures have been updated for clarity and correctness. [1] [2] [3] [4]

Testing Improvements:

  • A new regression test (Issue_396) and supporting test images have been added to ensure correct handling of animated GIFs with frame disposal to background, verifying both encoding and decoding paths. [1] [2] [3] [4] [5]

@JimBobSquarePants JimBobSquarePants added bug formats:gif breaking Signifies a binary breaking change. labels May 26, 2026
@JimBobSquarePants
JimBobSquarePants merged commit 8f2716b into main May 26, 2026
12 checks passed
@JimBobSquarePants
JimBobSquarePants deleted the js/gif-background branch May 26, 2026 04:01
This was referenced Aug 12, 2026
IhateTrains added a commit to ParadoxGameConverters/ImperatorToCK3 that referenced this pull request Aug 23, 2026
Updated [SixLabors.ImageSharp](https://github.com/SixLabors/ImageSharp)
from 3.1.12 to 4.1.1.

<details>
<summary>Release notes</summary>

_Sourced from [SixLabors.ImageSharp's
releases](https://github.com/SixLabors/ImageSharp/releases)._

## 4.1.1

## What's Changed
* Fix CCITT decompressor bounds checks and error handling by
@​JimBobSquarePants in SixLabors/ImageSharp#3176


**Full Changelog**:
SixLabors/ImageSharp@v4.1.0...v4.1.1

## 4.1.0

## What's Changed
* GIF: background handling & quantizer overflow fix by
@​JimBobSquarePants in SixLabors/ImageSharp#3133
* Validate PBM max pixel value by @​JimBobSquarePants in
SixLabors/ImageSharp#3134
* Add support for Apple CgBI PNG images by @​Erik-White in
SixLabors/ImageSharp#3136
* Fix GIF transparency handling and dither by @​JimBobSquarePants in
SixLabors/ImageSharp#3143
* Bump codecov/codecov-action from 6 to 7 by @​dependabot[bot] in
SixLabors/ImageSharp#3141
* Add BlendWithCoverage overloads. Optimize Rgba32 compatible shuffling.
by @​JimBobSquarePants in
SixLabors/ImageSharp#3150
* Bump actions/checkout from 6 to 7 by @​dependabot[bot] in
SixLabors/ImageSharp#3146
* Bump actions/cache from 5 to 6 by @​dependabot[bot] in
SixLabors/ImageSharp#3149
* Fix convolution sampling for bounds smaller than the kernel radius by
@​JimBobSquarePants in SixLabors/ImageSharp#3152
* Enhance pixel formats and associated-alpha operations with
optimizations by @​JimBobSquarePants in
SixLabors/ImageSharp#3154
* Bump actions/setup-dotnet from 5 to 6 by @​dependabot[bot] in
SixLabors/ImageSharp#3155
* Fix degeneracy check for resize transforms by @​JimBobSquarePants in
SixLabors/ImageSharp#3157
* Improvements to Apple CgBI PNG handling by @​Erik-White in
SixLabors/ImageSharp#3137
* Clone TIFF profiles into image metadata by @​JimBobSquarePants in
SixLabors/ImageSharp#3159
* Add AOT compiler seeds for pixel formats and ICO, CUR, QOI codecs by
@​JimBobSquarePants in SixLabors/ImageSharp#3160
* Normalize SIMD pipelines using TensorPrimitives_ by
@​JimBobSquarePants in SixLabors/ImageSharp#3161
* Add ANI decoder support by @​Poker-sang in
SixLabors/ImageSharp#2899
* Remove AntialiasThreshold from GraphicsOptions by @​JimBobSquarePants
in SixLabors/ImageSharp#3162
* Add plus and extended pixel blend modes by @​JimBobSquarePants in
SixLabors/ImageSharp#3163
* Fix 16-bit binary PBM sample byte order by @​JimBobSquarePants in
SixLabors/ImageSharp#3164
* Make MemoryAllocator limits configurable and extensible by
@​JimBobSquarePants in SixLabors/ImageSharp#3165

## New Contributors
* @​Erik-White made their first contribution in
SixLabors/ImageSharp#3136

**Full Changelog**:
SixLabors/ImageSharp@v4.0.0...v4.1.0

## 4.0.0

## What's Changed
* Update to net8 by @​stefannikolei in
SixLabors/ImageSharp#2583
* Handle dedup of local palette of 256 length - Main by
@​JimBobSquarePants in SixLabors/ImageSharp#2607
* Replace custom Crc32 by @​JimBobSquarePants in
SixLabors/ImageSharp#2611
* Sync 3.1 DrawImage fixes by @​tocsoft in
SixLabors/ImageSharp#2612
* Fix handling gif encoding for global palettes - Main by
@​JimBobSquarePants in SixLabors/ImageSharp#2615
* Bump actions/setup-dotnet from 3 to 4 by @​dependabot[bot] in
SixLabors/ImageSharp#2613
* Adjusted the casing of the Webp format name by @​jscarle in
SixLabors/ImageSharp#2623
* Fix Paeth Filter decode on platforms that do not support Ssse3 - Main
by @​JimBobSquarePants in
SixLabors/ImageSharp#2620
* Fix WebP animation speed bug by @​marklagendijk in
SixLabors/ImageSharp#2624
* Promote PixelTypeInfo to Pixel by @​stefannikolei in
SixLabors/ImageSharp#2601
* TGA: Treat 32 bit True Color images always as transparent by
@​brianpopow in SixLabors/ImageSharp#2643
* Modernize and optimize pixel format operations across platforms. by
@​JimBobSquarePants in SixLabors/ImageSharp#2645
* Cleanup SimdUtils by @​JimBobSquarePants in
SixLabors/ImageSharp#2654
* Bump actions/cache from 3 to 4 by @​dependabot[bot] in
SixLabors/ImageSharp#2648
* Bump codecov/codecov-action from 3 to 4 by @​dependabot[bot] in
SixLabors/ImageSharp#2657
* Bump NuGet/setup-nuget from 1 to 2 by @​dependabot[bot] in
SixLabors/ImageSharp#2658
* Add v3.1.x fixes #​2673 and #​2674 into main. by @​JimBobSquarePants
in SixLabors/ImageSharp#2675
* Add fixes 2668, 2676, and 2677 to main by @​JimBobSquarePants in
SixLabors/ImageSharp#2678
* Merge 2681 to v4 Main by @​JimBobSquarePants in
SixLabors/ImageSharp#2690
* Add JPEG COM marker support by @​RobertMut in
SixLabors/ImageSharp#2641
* Bump actions/upload-artifact from 3 to 4 by @​dependabot[bot] in
SixLabors/ImageSharp#2625
* Only exit JPEG scan decoding after multiple EOF hits by
@​JimBobSquarePants in SixLabors/ImageSharp#2701
* V4 Ensure VP8X alpha flag is updated correctly. by @​JimBobSquarePants
in SixLabors/ImageSharp#2703
* Fix animated png handling (issue #​2708) by @​SpaceCheetah in
SixLabors/ImageSharp#2710
* Merge latest release from v3 by @​JimBobSquarePants in
SixLabors/ImageSharp#2720
* Fix MacOS jobs by @​antonfirsov in
SixLabors/ImageSharp#2728
* Fix async-over-sync issue in Image.DecodeAsync() by @​kroymann in
SixLabors/ImageSharp#2725
* Fix overflow in MemoryAllocator.Create(options) by @​antonfirsov in
SixLabors/ImageSharp#2730
* GifDecoder: Limit lzw bits to a maximum of 12 bits by @​brianpopow in
SixLabors/ImageSharp#2744
* GifDecoder : Allow skipping bad metadata using identify by
@​JimBobSquarePants in SixLabors/ImageSharp#2749
* Add ICO and CUR file decoder. by @​frg2089 in
SixLabors/ImageSharp#2579
* v4 - Fix off-by-one error when centering a transform. by
@​JimBobSquarePants in SixLabors/ImageSharp#2761
* v4 Fix 2758 by @​JimBobSquarePants in
SixLabors/ImageSharp#2764
* Simplify Color Space Conversion APIs by @​JimBobSquarePants in
SixLabors/ImageSharp#2739
* Webp: Fix Issue 2763 by @​brianpopow in
SixLabors/ImageSharp#2767
* V4 Correctly break during Png decoding by @​JimBobSquarePants in
SixLabors/ImageSharp#2773
* V4 : Fix filtering on PNG encode. by @​JimBobSquarePants in
SixLabors/ImageSharp#2778
* Fix #​2779 buffer overrun by @​KirillAldashkin in
SixLabors/ImageSharp#2780
* Fix ImageMetadata docs typo by @​lofcz in
SixLabors/ImageSharp#2781
* Add API for metadata conversion between formats. by
@​JimBobSquarePants in SixLabors/ImageSharp#2751
* Tiff decoder: Fix issue 2679 by @​brianpopow in
SixLabors/ImageSharp#2789
* Replace PngCrcChunkHandling by @​JimBobSquarePants in
SixLabors/ImageSharp#2786
* Add tagname to debugger visualization for Exif- and Iptc-values, to
facilitate easier debugging and discovery by @​lassevk in
SixLabors/ImageSharp#2787
* V4 - Correctly handle transform spaces when building transform
matrices. by @​JimBobSquarePants in
SixLabors/ImageSharp#2795
* Allow decoding Tiff of different frame size. by @​JimBobSquarePants in
SixLabors/ImageSharp#2788
* Add progressive JPEG encoder by @​ardabada in
SixLabors/ImageSharp#2740
* Fix using dither in BmpEncoder when bit per pixel is <= 4 by @​mistoll
in SixLabors/ImageSharp#2819
* Add QuadDistortion to ProjectiveTransformBuilder by @​Socolin in
SixLabors/ImageSharp#2748
* WEBP : Use Correct Width With AlphaDecoder by @​JimBobSquarePants in
SixLabors/ImageSharp#2823
 ... (truncated)

Commits viewable in [compare
view](SixLabors/ImageSharp@v3.1.12...v4.1.1).
</details>

[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=SixLabors.ImageSharp&package-manager=nuget&previous-version=3.1.12&new-version=4.1.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: iht <IhateTrains@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking Signifies a binary breaking change. bug formats:gif

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant