Add support for 4 color grayscale displays (#71)

[ThomasR]

resolves #71

Note

This is work in progress.

TODO

• Dither grayscale images before passing them to getBuffer_4Gray
• Update list_compatible_modules()
• Update documentation
• Adjust Layout where needed
• Add opt-out mechanism for partially-compatible displays (using epd2in7 driver for epd2in7b etc.)
• Fix unsupported epd4in2b_V2 (missing .so files from Waveshare) -> separate ticket?
• Test
• Update changelog

[txoof]

You work fast! Have you tested this out with paperpi, or just here in the library?

[ThomasR]

I am testing in with paperpi, but currently it has zero effect. I think this crucial step is missing

• Dither grayscale images before passing them to getBuffer_4Gray

The good news is: it doesn't crash 😉

[ThomasR]

Done that part. Now, this works on my display. However, looks like some adjustments are required in PaperPi too, see downstream ticket.

[ThomasR]

It would be nice if we could tests this with other hardware too.

[txoof]

Love what you're doing here. When you give me the go-ahead, I can merge this into a testing branch and bump the version number.

If you have any advice or best-practice next steps that you want to share, I'm totally open. I want to be cautious and make sure we don't leave PaperPi high-and-dry with a problematic push.

[ThomasR]

Ideally, you'd have access to various devices, or can ask some volunteers.

In any case, it's best to add an opt-out switch, which makes sense anyway because of this.

[ThomasR]

These require .so files from Waveshare, which don't come with the Python package.

[txoof]

@ThomasR Hey, can. you shoot me an email: [email protected]? This work is great, but I've got some stuff going on that's taking a lot of my attention right now. Maybe we can find a good way to move this forward.

[ThomasR]

Hey @txoof, I'm considering closing this PR and canceling my work on this issue.

Here's why:

Short version: this patch may increase text readability in certain cases, but is almost guaranteed to make image rendering worse than before.

---

Long version:

I ran extensive tests with lots of images, and here you can see one of the results:

(click for full size)

I generated this by emulating the ePaper's output on my PC.

Clearly, some color correction is needed, because the unaltered image (in column 3) just looks bad in most cases. So the natural thing to do is to pick a palette that corrects the error. However, there are 2 issues here:

1. Pillow's quantize does not offer any control over the dithering method, so the results with 4 colors are just meh. The output tends to be patchy, and no matter what I tried, I couldn't find a palette that works (even in the preview) for all photos. In the end, I settled on option 3 as a good compromise; it works well for my project (The palette is [0x00, 0x00, 0x00, 0x5d, 0x60, 0x58, 0x7b, 0x7e, 0x75, 0xff, 0xff, 0xff])
2. Much to my surprise, when I ran more tests on my device, I realized that the actual output differs from the emulated one, despite thorough calibration. How?
   Apparently the individual pixels may display different colors with the same input, depending on the pixel's neighbourhood. Here you can see that the gray pixels look rather dark at the top, but almost vanish when surrounded with white.
   (click for full size)
   I asked ChatGPT about this, and it called this effect optical crosstalk, but I'm not sure this is the correct technical term.
   It' common with ePaper displays, and is caused by hardware limitations, or poor voltage configuration in the driver.
   Whatever the reason, I'm pretty sure that this effect shows differently on different display models, which makes it almost impossible to find a one-size-fits-all solution.
   It doesn’t affect 1-bit mode - black pixels always appear black.

So in conclusion, the 4 gray mode works well if you carefully optimize your image for your display, but in general it is worse than 1bit-dithering. Text readability highly depends on the text color and background.

[txoof]

@ThomasR Wow!

Thanks for the incredibly thorough investigation. I'm inclined to think that the added complexity doesn't really add much value in terms of output. If you make any breakthroughs and want to move forward, I'm definitely open.

I've noticed some of the artifacts you've documented on 1bit screens in the past, especially the 2in7bc that I have, but never really understood what I was seeing. I always assumed it was due to bad wire connections or something. I also recall being underwhelmed by Pillows 4-color dithering, but never bothered to document it. Your sample images really show its limitations clearly!

I've been through several different screens and eventually landed on the larger HD screens because they're much more readable from a distance, allow for practical font anti-aliasing and do reasonable grayscale output.