From 22b215c3b031535ab1864ba2945c71bb357c4ab4 Mon Sep 17 00:00:00 2001 From: "Ben Scholzen (DASPRiD)" Date: Sun, 5 Apr 2026 21:38:52 +0200 Subject: [PATCH] docs: document ImageMagick path fill rendering bug ImageMagick's GetFillAlpha function (MagickCore/draw.c) has two interacting bugs that can produce single white pixel artifacts in filled regions: 1. The winding number calculation uses `x <= bounds.x1` instead of `x < bounds.x1`, causing pixels at an edge's leftmost x to be incorrectly classified as outside the polygon. 2. DestroyEdge does not decrement the loop counter after removing an edge, causing the next edge in the array to be skipped in the distance phase. Neither canvas padding nor post-processing can reliably fix this. Users should use SvgImageBackEnd or GDLibRenderer instead. Closes #195 Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 8291c26..37d4336 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,26 @@ $writer = new Writer($renderer); $writer->writeFile('Hello World!', 'qrcode.png'); ``` +## Known issues + +### ImagickImageBackEnd: white pixel artifacts + +When using `ImagickImageBackEnd`, single white pixels may appear inside filled regions. This is +most visible with margin 0 (where artifacts appear at the image edge), but can in theory occur at +any position. The cause is a bug in ImageMagick's path fill rasterizer (`GetFillAlpha` in +`MagickCore/draw.c`): an off-by-one error in the winding number calculation combined with an edge +skipping bug in the scanline processing can incorrectly classify pixels as outside the polygon. + +The bug cannot be reliably worked around in this library: + +- **Canvas padding** (rendering on a larger canvas and cropping) does not work because the required + padding depends on the scale factor, path complexity, and ImageMagick's internal edge processing + state. No fixed padding value is safe for all inputs. +- **Post-processing** (scanning for and fixing isolated white pixels) risks corrupting legitimate + rendering features such as curved module edges. + +For artifact-free output, use `SvgImageBackEnd` or `GDLibRenderer` instead. + ## Development To run unit tests, you need to have [Node.js](https://nodejs.org/en) and the pixelmatch library installed. Running