Review: PR #454 adds Floyd-Steinberg dithering to imgconvert.py

[Copilot]

Context

This is a review of PR #454 by @DavyLandman which addresses poor grayscale quality on ED047C1 displays where only ~8 levels are perceptually visible instead of 16.

Changes in PR #454

Core algorithm change:

• Replaces bit truncation (l >> 4) with PIL's quantize + Floyd-Steinberg dithering
• Creates proper palette mapping to display's 16 gray levels
• Packs palette indices (0-15) instead of truncated grayscale values

New parameters:

• -l LEVELS: Configure gray levels (1-16, default: 16)
• -nd: Disable dithering

Image handling improvements:

• Handles I;16 PNG conversion edge case
• Properly drops alpha from RGBA images
• Uses RGB mode for quantization (better algorithm performance)

Visual Impact

Before (bit truncation):

0x00, 0x00, 0x00, 0x11, 0x11, 0x11, 0x22, 0x22...  # harsh banding

After (dithering):

0x00, 0x00, 0x01, 0x11, 0x11, 0x12, 0x21, 0x22...  # smooth transitions

Review Status

✅ Recommend approval

• All functional tests pass (16-level, 8-level, RGBA, I;16, odd widths)
• Backward compatible (default args unchanged)
• No security issues
• Documentation updated

Optional enhancements:

• Add help text to -nd and -l parameters
• Validate levels >= 1

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Is my ED047C1 just low contrast or are the gray levels not uniform?</issue_title>
<issue_description>Someone gifted met an "old" lilygo T5 4.7 (the one with an old esp32 on there). It has a 16 levels of gray ED047C1 but it if run the grayscale_test program I only see about 8 levels very clearly and after that is so light that I can barely see the difference.

Which if I compare to for example: https://css-tools.com/gradient-generator--black-to-white the gradient should have a lot more darker colors?

I'm guessing my question are:

• is there a place where the expected output of the grayscale test is stored?
• am I initialzing the display correctly?
• is my display maybe broken in some way?
• what is the color space I should be doing the color math in? for example scripts/imgconver.py just divides by 16 it seems?

Also, thanks for this great library, what a work 👍🏼

this is the setup of the library:

    epd_init(&epd_board_lilygo_t5_47, &ED047TC1, EPD_LUT_64K);

and I changed the temperature to 20C instead of 25.</issue_description>

<agent_instructions>Please check and review @DavyLandman pull request for dithering in this issue</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@martinberlin Hello Davi.

• is there a place where the expected output of the grayscale test is stored?
  Not really, don't understand what you mean by that, can you explain? Stored where?

• am I initialzing the display correctly?
  Yes

• is my display maybe broken in some way?
  No it is simply that is hard to get the grays correctly and not straight forward.

Temperature update won't do really anything if in the waveform file there are not ranges defined.
The waveform format in this component is tricky. There are some issues already about it and you can also read the WiKi.
Long story short: Is very hard to get perfect 16 grays with an open source controller. Even if you could parse perfectly the original waveform you do not have the same update speed of a professional controller, so it won't also come out the same.
Other components like FastEPD that I think does not support that model do have a friendlier way to edit the waveform, that is not really any waveform at all, is simply instructions on how the +15 and -15 pushes should go, in order to go from gray A to gray B.</comment_new>

• Fixes Is my ED047C1 just low contrast or are the gray levels not uniform? #453

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.