How to show an image on Inky Impression?

[callumlocke]

The example image is a .jfif file. I want to render a regular format like a PNG to the Inky Imression if possible. My use case is I want to download and display an image every hour from a remote URL. I have tried to piece it together from the examples here and snippets found online but I can't get much working.

Are there any special rules for exporting or generating 7-colour images for display on the Inky Impression? I can't find any documentation about this.

A step-by-step guide to rendering a custom image to the Inky Impression would be really helpful.

[callumlocke]

Aside: I was trying to figure things out from the source code, came across something strange here in inky_uc8159.py: the names SATURATED_PALETTE and DESATURATED_PALETTE seem to be backwards. Does this represent a bug?

For example the 'red' in the SATURATED_PALETTE is 156, 72, 75 and in DESATURATED_PALETTE it's 255, 0, 0.

Edited to show swatches in IDE:

I don't really understand why there's 'saturated' and 'desaturated' sets, with 14 colours between them. Can the display actually show 14 colours? I would really appreciate some input from Pimoroni to help me understand and get off the ground.

[callumlocke]

I managed to render a PNG (exported from Photoshop as a 24-bit RGB PNG, with the image only containing pixels in the exact 7 colours that the Inky Impression supports), but the colours are all randomly mixed up on the display. I also tried exporting as an 8-bit indexed PNG from Photoshop, but couldn't get this working at all.

Just to clarify what I'm asking, here's a PNG I made in Photoshop:

It is the right size (600x448), and it contains only 7 colours (indexed), the exact ones the Inky Impression supports.

How can I display an image like this on the Inky Impression, with the colours in the right order?

[jerbzz]

The order of channels is critical. I used The GIMP to get it to work properly. It has a pretty decent custom palette feature.

On Fri, 9 Jul 2021 at 09:12, Callum Locke ***@***.***> wrote: I managed to render a PNG (exported from Photoshop as a 24-bit RGB PNG, with the image only containing pixels in the exact 7 colours that the Inky Impression supports), but the colours are all randomly mixed up on the display. I also tried exporting as an 8-bit indexed PNG from Photoshop, but couldn't get this working at all. Just to clarify what I'm asking, here's a PNG I made in Photoshop: [image: test-image] <https://user-images.githubusercontent.com/250617/125045924-6b4eb000-e095-11eb-89be-eb28b9e0623e.png> It is the right size (600x448), and it contains only 7 colours, the exact ones the Inky Impression supports. How can I display an image like this on the Inky Impression, with the colours in the right order? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#115 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGZ77JFGJMOZ7GGWSWMUJADTW2VN5ANCNFSM47VD74HQ> .

--

[Gadgetoid]

I don't really understand why there's 'saturated' and 'desaturated' sets, with 14 colours between them. Can the display actually show 14 colours? I would really appreciate some input from Pimoroni to help me understand and get off the ground.

These colours represent the values Inky will quantize toward when converting and dithering a full colour image for display on the 7-colour board.

The SATURATED palette includes de-saturated colours which - when used as the target for quantization - produce a saturated output image on the display.

The DESATURATED palette is the inverse of this. By pretending the display's colours are super saturated the resulting image usually appears less saturated.

What actually happens internally is that we take these two palettes and mix them together to provide a target with a customizable amount of saturation.

Our final palette - the mix of saturated/desaturated colours - is the target toward which all pixels in the image you're displaying will be clamped. When you use a desaturated target (that's much less vibrant than the actual display colours) then desaturated colours in the source image are more likely to be snapped toward a more vibrant display colour (or dithered mix of colours, as it were) than they otherwise would. And the reverse is also true.

So TLDR- these variables are named for the result they produce, and not for the colours they contain. The colours were obtained by photographing the display - for the saturated palette - and using the full-saturation colours - for the desaturated palette.

Inky will have a good go at displaying basically any image you throw at it, using these colours as a target for quantization/dithering.

For example here's a particularly challenging source image:

Fully saturated:

Fully desaturated:

While the desaturated image is quantized toward how the colours actually look on Inky Impression the result is pretty underwhelming because the bright colours don't match up well with what's actually possible on the display.

The desaturated image actually has truer-to-the-original brightness and dynamic range, so there are very clearly some tradeoffs.

Here's the same image with a saturation of 0.7 which is bringing back some of the dynamic range at the expense of losing the popping colours/vibrancy:

This is all only applicable to automatically dithering photographs for display on Inky- if you're creating your own art targeting the colours it supports and outputting a palette-based image then - as @jerbzz suggests - it's only the colour order that matters and not the actual colours since the raw image data is just copied verbatim into Inky's display buffer.

[KodeMunkie]

I've written an improved general use algorithm (non PIL based) for dithering, based on testing with various dithers and colour distance algorithms used in existing work in some of my other older projects.
The results seem to be better for the poor sky-blue output on these devices, and also avoids over saturation of yellow found in the advanced dithers included in the project.
Unfortunately there doesn't seem to be a method to bypass the "blend" saturation function and dump the image directly onto the display.

Is there a way /can you provide a way to do this cleanly please?

I attach a screenshot of the above image run through my algorithm choices as a preview. Nb. this does not use the exact sat or desat palettes given in the source but an adapted palette, taken from a real sample done by another user of the generic waveshare 7 color variant, that produces a more pleasing result actually on the device (e.g. blues are not greens, off white contains white+slight blue tints, not white+yellow etc.).

.

[Gadgetoid]

If you supply a "P" type PIL image - which should be the output from your dither operation - then no conversion will take place the data is copied verbatim to the display.

Conversion only happens if the image is not already a palette type image:

inky/library/inky/inky_uc8159.py

Lines 385 to 395 in 45024c0

	if not image.mode == "P":
	if Image is None:
	raise RuntimeError("PIL is required for converting images: sudo apt install python-pil python3-pil")
	palette = self._palette_blend(saturation)
	# Image size doesn't matter since it's just the palette we're using
	palette_image = Image.new("P", (1, 1))
	# Set our 7 colour palette (+ clear) and zero out the other 247 colours
	palette_image.putpalette(palette + [0, 0, 0] * 248)
	# Force source image data to be loaded for `.im` to work
	image.load()
	image = image.im.convert("P", True, palette_image.im)

[KodeMunkie]

Thanks for pointing out the above.

Currently I provide a 24 bit image that has been quantized already to 7 "idealistic" colours. The colours need a simple 1:1 mapping to the official physical hardware palette for the device. I am uncertain as to which constants, sat or desat I need to use (I think it's the sat, but would like confirmation).

This operation should be as simple as a simple 1:1 palette mapping by index, but try as I might I can't find the convert function at line 395 documented or precisely what it does.
I am also unable to use the PIL documentation image.convert() (which has different args) as it requires an optional matrix, which given lack of adequate documentation I can only assume is a dither matrix. This confuses me as the only dither option I would use is "None" so I don't trust it to not try and do some sort of redundant processing or further dither.

I realise this isn't the PIL project but was wondering if you had some pointers as to how best to map the 7 colour RGB palette to a 7 colour P image without the convert function, or at least point me to the line 395 convert function documentation/source you used?

Should you be interested the python source for the diffuse image conversion is a relatively small 100 line file here: https://github.com/KodeMunkie/inky-impression-slideshow/blob/main/image_processor.py

[kyleratti]

@KodeMunkie were you ever able to solve the problem of mapping the calculated color palette to one of the 7 display colors? I am in the process of writing a .NET driver for the Inky Impression 5.7" board and I am arriving at the same difficulty. I have my dithered image, but I need to be able to map that to the appropriate display color.

I believe I also went down the path of mapping it by index of the calculated color palette index -> display color index, but the colors are not accurate this way.

[turian]

I would be interested to learn more about this too, @KodeMunkie

[KodeMunkie]

@kyleratti @turian Probably not what you're looking for but the algorithm I wrote is in a (greatly modified by me) fork of another project: https://github.com/KodeMunkie/inky-impression-slideshow