Feature proposal: Dithering by Lehonti · Pull Request #457 · PintaProject/Pinta

Lehonti · 2023-08-23T14:57:17Z

Explanation: Sometimes we want to render an image using a different (usually more limited) palette, but also have the result look decent. Some of the most common algorithms for this 'diffuse the error' to neighboring pixels. In other words, instead of, say, simply applying a threshold to each pixel, they rely on neighboring pixels to help approximate the overall original look of the area.

This is the output in my development setup after dithering the image that is used to test the effects, with the default settings of this proposed effect, which consist of a fixed 16-color palette and the Floyd-Steinberg diffusion matrix:

The output looks sane, but we still need to verify that it is actually correct.

I will freely admit the code that I'm proposing needs to be improved. I wrote it quickly in order to have something working. Opening a pull request opens the door for discussion, though.

The implementation was inspired by this article:

https://tannerhelland.com/2012/12/28/dithering-eleven-algorithms-source-code.html

cameronwhite · 2023-08-24T03:25:45Z

Very cool, thanks for working on this! I'll need to take a closer look through the code later once it's ready for review

A couple initial thoughts:

I think this is also similar to the Quantize effect in Paint.NET, although I'm not on a windows machine to test right now. From the documentation I think it's just using more automated methods of choosing a palette with some number of colours, but I'm not sure what it does for error diffusion
For the EffectData, you'll want this just consist of simple data members that can be used by the standard effect dialog to configure the effect, and then those can be translated into more complex structures internally

cameronwhite

Added a few comments from reading through the first bit of code

cameronwhite · 2023-08-24T03:28:04Z

+		int deltaB = color1.B - color2.B;
+
+		// Euclidean distance
+		return Math.Sqrt (deltaR * deltaR + deltaG * deltaG + deltaB * deltaB);


I think working in terms of squared distance would be fine here and let you avoid the square root and keep things in integers?

cameronwhite · 2023-08-24T03:29:39Z

+		byte newR = Utility.ClampToByte (color.R + (int) (factor * errorRed));
+		byte newG = Utility.ClampToByte (color.G + (int) (factor * errorGreen));
+		byte newB = Utility.ClampToByte (color.B + (int) (factor * errorBlue));
+		return ColorBgra.FromBgra (newB, newG, newR, 255);


Should this preserve the original alpha?

cameronwhite · 2023-08-24T03:33:49Z

+	public override void Render (ImageSurface src, ImageSurface dest, ReadOnlySpan<RectangleI> rois)
+	{
+		var src_data = src.GetReadOnlyPixelData ();
+		var src_copy = new ColorBgra[src_data.Length];


The article you linked to mentioned that you only need a couple rows to store the errors accumulated for the current + next row (varies based the matrix of course), so that could be a future optimization.

Or, at least avoid the extra copy by copying into the destination image and then working in-place there

cameronwhite · 2023-08-24T03:35:15Z

+		var src_copy = new ColorBgra[src_data.Length];
+		src_data.CopyTo (src_copy);
+		var dst_data = dest.GetPixelData ();
+		foreach (var rect in rois) {


Because this algorithm is sequential, we definitely need to do some testing of rendering it live in Pint with the live preview dialog. I think it will try to run the effect separately on many small tiles which won't behave correctly?

cameronwhite · 2023-08-24T03:39:32Z

+		var dst_data = dest.GetPixelData ();
+		foreach (var rect in rois) {
+			for (int y = 0; y < rect.Height - Data.DiffusionMatrix.RowsBelow; y++) {
+				for (int x = Data.DiffusionMatrix.ColumnsToLeft; x < rect.Width - Data.DiffusionMatrix.ColumnsToRight; x++) {


I'm not really sure about the indexing here, this seems to ignore the left and top coordinates of the rectangle?
Also I think the dithering should likely still be applied to the first pixel(s) of the row?

Lehonti · 2023-08-24T08:59:10Z

Thank you for the feedback.

I took a look at the 'Quantize' effect in Paint.NET. It's kinda sorta similar but it has a few key differences. Among those that I could notice:

There is a choice between the "Octree" and "Median Cut" algorithms. I am not sure about the details of each, but I think "Octree" achieves a nicer result for photos, and "Median Cut" looks slightly more Andy Warhol-esque.
The user can choose the number of colors in the palette, but the colors itself can't be chosen. Instead, a color palette optimized for the image in question is created dynamically. I'm not saying this is a bad feature to have...I would also like Pinta to be able to create an optimized palette, but I would also like to be able to use my own palette.
It indeed does error diffusion. There's a setting for the "Dithering level". By the visual output, it seems that if the setting is higher, the error is spread over a larger area. This would also be nice to have in Pinta, too, although I need to do more research and see how it can be achieved.
It deals with transparency. Yeah, I should modify my feature so that it does the same.
Paint.NET allows for a transparency threshold (how translucent must a color be for it to be considered transparent?). Of course this would also be nice to have in Pinta

…hould be implemented

…at the standard effect dialog can be used

Lehonti · 2023-08-24T15:24:01Z

Also, points taken. I will address the issues you've raised, little by little, when I have the time.

The first thing I've done is changing the EffectData so that its fields are enum-valued, at least for now. This will allow to choose among pre-defined settings. Ideally, in the future, the standard effect dialog can be extended so that it can edit palettes, and such.

cameronwhite · 2023-08-25T01:18:02Z

Sounds good! Yeah I agree that being able to use a specific palette seems like a useful option to still have

… from even being changed. Now I must figure out why the effect doesn't work as intended...

cameronwhite · 2023-08-26T03:26:21Z

Just to let you know, I'll be on vacation the next couple weeks so I won't be responsive on here for a bit :)

…nation data itself, So that effect doesn't 'spill over' to pixels outside ROIs

…e color is being quantized but the dithering is not being done. I wonder why

Lehonti · 2023-08-27T14:36:00Z

I finally made the dithering work in the application itself instead of the fake Pinta setup I used at the beginning. Also, no pixels are being ignored (addressing one of the points you made)

One thing I'm noticing is that the ROIs are being passed one by one, by which I mean the Render() method is being called as many times as the image has rows, and the array with ROIs has only one item at a time, instead of passing the ROIs all at once. I wonder why that is. I think it would be better to just pass all of them at once. It would make it possible for the effect not to 'spill over' pixels that are not part of any ROI, as we would be able to keep track of all pixels in all ROIs at the beginning, and limit the effect to those pixels.

cameronwhite · 2023-09-13T22:54:58Z

Yeah, this is happening because the live preview manager controls the multithreading, so it decides on the tiles to render and then calls Render() many times in parallel with the different rectangles. (And, if the effect is slow to render it will update the canvas to show partial progress)
The problem as you've noted is that this assumes the effect can be computed independently per region, whereas your effect needs to run serially

Lehonti · 2024-01-13T15:11:06Z

Thank you, you are right about the clamping, and I just added checks so that the application of the matrix stays within the rectangle.

I updated the images being used for testing, too, and they are indeed different after making this change.

…ring

Lehonti · 2024-01-13T23:13:39Z

I added a few new palettes. Not necessarily the most important ones, but rather a selection of those that are easy to create programmatically (usually those that can be represented exactly in the color space that most modern computers use).

`RgbColorCube` instead of `ColorCube`, as there may be an `RgbaColorCube`

…ring

cameronwhite · 2024-01-14T03:20:18Z

+
+		static Predefined ()
+		{
+			BlackWhite = ImmutableArray.CreateRange (new[] { ColorBgra.FromBgr (0, 0, 0), ColorBgra.FromBgr (255, 255, 255) });


ColorBgra.White and Black can be used here

cameronwhite · 2024-01-14T03:27:28Z

+
+	public sealed class DitheringData : EffectData
+	{
+		[Caption ("Diffusion Matrix")]


Diffusion Matrix might not be the most helpful for non-technical users. Maybe just something like Dithering Method or Diffusion Method?

Sure. I changed it to "Error Diffusion Method"

cameronwhite · 2024-01-14T03:33:18Z

+
+public enum PredefinedDiffusionMatrices
+{
+	Sierra,


These should probably get Caption attributes added, e.g. Floyd-Steinberg should have a hyphen in it from what I see online, along with explanations for translators

It would also be good to see if there are any more descriptive names for users, e.g. "Fake" Floyd-Steinberg might not help a user understand what it does

Sure. I added a CaptionAttribute to those values that have hyphens or spaces; and I labeled the matrix you mentioned as "Floyd-Steinberg Lite"

Thanks - since these captions will also show up as translatable strings, also adding some Translators: ... comments would be good to explain to translators that these are algorithms named after people

Sure. I just added comments for translators making it clear that the matrices were named after people

cameronwhite · 2024-01-14T03:34:23Z

+	FakeFloydSteinberg,
+}
+
+internal sealed class ErrorDiffusionMatrix


Please also add some doc comments for this class

I just added a doc comment with basic explanation

cameronwhite · 2024-01-14T03:37:23Z

+						if (thisItem.Y < roi.Top || thisItem.Y >= roi.Bottom)
+							continue;
+
+						if (thisItem.X < 0 || thisItem.X >= settings.sourceWidth)


This second set of checks should be unnecessary since the rectangle should be inside the image bounds

At first I added it because I wasn't sure if the ROIs were guaranteed to be inside the image bounds, but in the light of this I removed it.

…ring

Lehonti Ramos added 8 commits August 23, 2023 16:54

Feature proposal: Dithering

bf62d01

Fixed spelling mistakes to make the spell checker happy

68b14c3

Fixed more spelling mistakes to make the spell checker happy

39d1a29

changed name to variable and used clamping functions in Utility

00bfc1d

Put new effect in Pinta.Effects namespace

c66b6c9

Removed unnecessary comment

9a181d7

Added a new default palette

499a054

Corrected overflow that happened when creating web-safe color cube

e35ceea

cameronwhite reviewed Aug 24, 2023

View reviewed changes

Lehonti Ramos added 2 commits August 24, 2023 13:54

Overridden LaunchConfiguration, as a reminder in the code that it s…

186b28c

…hould be implemented

ForwardErrorDiffusionDitheringData now has enum-typed fields, so th…

33474f6

…at the standard effect dialog can be used

Added old ms paint palette

39a3c1c

Lehonti Ramos and others added 4 commits August 25, 2023 09:15

Launches simple effect dialog

6dcb04b

Debugged in Ubuntu and fixed indexing issues that prevented any pixel…

7739ae2

… from even being changed. Now I must figure out why the effect doesn't work as intended...

Fixed formatting

cc78400

Removed unnecessary class qualification

39c44dd

John Doe and others added 7 commits August 27, 2023 15:32

Started re-writing the algorithm

01b27a7

Fixed formatting

8636a6d

Another attempt, separating it into a 'working surface' and the desti…

c2b5899

…nation data itself, So that effect doesn't 'spill over' to pixels outside ROIs

Fixed formatting

400d18c

I finally understood how the ROIs are being passed as an argument. Th…

e351f9e

…e color is being quantized but the dithering is not being done. I wonder why

Finally dithering works

d4a8f50

Fixed formatting

19db393

Lehonti added 8 commits January 13, 2024 16:29

Changed test files

b2fa05f

Merge branch 'PintaProject:master' into feature/error_diffusion_dithe…

5a73b5b

…ring

Expanded selection of color palettes

7f88f7c

Sorted lines in PaletteHelper

9819be8

Expanded palette selection further

3a3cfb2

Added another palette

6a725f9

Added another palette

6468687

Local refactoring

4606508

Lehonti added 8 commits January 14, 2024 00:24

Removed WebSafe, as it was repeated

adfd3e1

Created ColorCube method to bring many of those palettes together

2dc1247

Formatting

f66b20d

Made name more specific

a6d126e

`RgbColorCube` instead of `ColorCube`, as there may be an `RgbaColorCube`

Added Rgb12Bit palette

7875e19

"Compressed" the logic even further

37d6749

Made code even more compact

d618420

Merge branch 'PintaProject:master' into feature/error_diffusion_dithe…

5858023

…ring

cameronwhite reviewed Jan 14, 2024

View reviewed changes

Lehonti added 5 commits January 14, 2024 04:50

Implemented suggested changes

86a6123

Changed label

b15875a

Merge branch 'PintaProject:master' into feature/error_diffusion_dithe…

733be7c

…ring

Merge branch 'PintaProject:master' into feature/error_diffusion_dithe…

1f80229

…ring

Added comments for translators

1372f7b

Lehonti mentioned this pull request Jan 14, 2024

Voronoi diagrams #692

Merged

cameronwhite merged commit c544cfb into PintaProject:master Jan 14, 2024

Lehonti deleted the feature/error_diffusion_dithering branch January 14, 2024 16:39

Lehonti mentioned this pull request May 10, 2025

Being able to add or remove colors from palette graphically #1436

Open

Lehonti mentioned this pull request May 24, 2025

Fixed a mistake in Atkinson dithering method #1489

Merged

cameronwhite mentioned this pull request Nov 18, 2025

Add Color Quantization effect #1815

Open

Uh oh!

Conversation

Lehonti commented Aug 23, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cameronwhite commented Aug 24, 2023

Uh oh!

cameronwhite left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lehonti commented Aug 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lehonti commented Aug 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cameronwhite commented Aug 25, 2023

Uh oh!

cameronwhite commented Aug 26, 2023

Uh oh!

Lehonti commented Aug 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cameronwhite commented Sep 13, 2023

Uh oh!

Lehonti commented Jan 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lehonti commented Jan 13, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Lehonti commented Aug 23, 2023 •

edited

Loading

Lehonti commented Aug 24, 2023 •

edited

Loading

Lehonti commented Aug 24, 2023 •

edited

Loading

Lehonti commented Aug 27, 2023 •

edited

Loading

Lehonti commented Jan 13, 2024 •

edited

Loading