Add chroma-key masks before dithering

[bablokb]

The background of dithered images often show artifacts. This is especially visible for white or black backgrounds. The idea is to add an (inverse) chroma mask for all the "native" colors of the display. So dithering would work as a multi-step process:

• create and join the masks using chroma-key extraction for every "native" color
• dither the image
• add the original image again with the inverted mask applied

In a first step, this could be limited to black and white.

For Spectra6/ACeP a theme with an extended palette would help: "native" colors plus a number of additional colors. So e.g. in a calendar multiple colors would be available, but only the additional colors will be dithered. The overall apperance should be much cleaner.

Not sure if PIL supports this.

[dmellok]

Sorry for the slow reply. This is built and on edge in v0.306.0.

The diagnosis matches the code. A pixel already sitting on a native colour
generates no error of its own, but it still receives its neighbours', so a
background beside saturated content gets pushed off its colour and quantises to
something else.

Rather than a separate chroma-key stage, it became a new source for a mask that
already existed: preserve_line_art and the per-cell dither overrides from #86
both resolve into one "force nearest here" buffer the .bin packers apply, and
"pixels already within a tolerance of a native colour" joins that union. Two
details worth naming. The mask is computed on the tone-mapped image rather than
the original, because exposure, the S-curve and the calibrated pre-pass all move
pixels and the calibrated path deliberately pulls white down to the panel's real
paper colour. And overwriting the output isn't enough on its own, so the
error-diffusion dithers also stop propagating through a protected region, which
otherwise collects error on one side and dumps it out the other. PIL was never a
constraint here: the .bin path runs its own numpy error diffusion.

It's a tolerance in sRGB distance in the palette profile's edge section, 0 is
off. Wired for the colour packers and for 1-bpp mono. Deliberately not for the
greyscale packers, where a 16-level ramp puts nearly every pixel close to some
level and the same guard would flatten photographs rather than clean
backgrounds.

Tolerance is the thing to tune. The bundled light themes paint warm paper rather
than pure white, so 16-24 is the range that catches them, not 1-4. If what
you're seeing sits on strict white or black and this doesn't move it, say so,
because then it isn't error landing on already-native pixels and I'd want to see
the frame.

The extended-palette theme is the better fix and I haven't started it: a
background painted exactly on the panel's own white needs no guard at all.

[dmellok]

How to actually turn it on, since the setting isn't where you'd guess.

Settings → Devices → your display → Calibration.

1. Apply a palette profile from the picker if the device doesn't have one.
   This step isn't optional: the guard is stored on the profile, so without
   one the control doesn't render at all. A bundled preset is fine, it forks
   into an editable copy the first time you change anything.
2. Open Tone & dither → Experimental: edge handling.
3. Set Protect the panel's own colours. 0 is off. 16 to 24 is the useful
   range; the bundled light themes paint warm paper rather than pure white,
   so smaller values won't catch a theme background.
4. Save and push a frame. It applies at pack time, so an already-cached
   render won't change until it's re-pushed.

Wired for the colour .bin packers and for 1-bpp mono. Not for the
greyscale packers: with a 16-level ramp nearly every pixel is close to some
level, so the same guard flattens photographs instead of cleaning
backgrounds.

Two coarser versions of the same idea already existed, if you want them
rather than the automatic per-pixel one. Whole frame: same Calibration tab,
under <renderer> — tone & dither, set Dither mode → None (snap to
palette). Per cell: the dashboard editor's Advanced → Override
dithering for this cell.

One thing to expect if you compare a Tesserae frame against a
convert -dither FloydSteinberg -remap frame from the same source. Two
inputs differ before the algorithm runs: ImageMagick's -colorspace RGB is
linear light, while Tesserae diffuses error in sRGB, and a palette profile
targets measured panel colours rather than nominal (255,0,0) primaries.
Same algorithm, different starting conditions, so the two won't match even
at identical settings.

[bablokb]

This sounds very promising. I will test this next week.

[bablokb]

Ok, tested with todays APOD using II7.3 with spectra_6. This is the diff (red, with the orignal in the background) I see when the protection-slider is at 24 (compare in1 in2 out from Image-Magick):

So it only seems to work on the right edge. Visually, there is no difference. But maybe the paperless black is not black enough for the image?! Should I try to redefine the palette colors and test again?

From the UI side, there is one minor and one larger problem. The minor problem is that two "fork&save" buttons show up (but I think both work):

The larger problem is that changes to the slider are ignored once they are forked&saved. I have to reset the palette to the default, and then I can edit again and choose a different value.

[dmellok]

Found it, and it wasn't your palette. The guard had never run on your frames.

Why

circuitpython_png and circuitpython_bmp share one pixel pipeline, and it
read exactly three things off the device: fit, pre-dither contrast, and dither
mode. Everything a palette profile carries was resolved by the server, handed
to the renderer, and dropped on the floor. So the whole Calibration tab was
inert for your display, not just the one slider.

The tab is gated on the panel's gamut rather than on whether the renderer
consumes profiles, which is how a Spectra 6 CircuitPython device ends up shown
the full editor with nothing behind it. Sorry, that one cost you an afternoon.

It also inverts your question about black. You weren't getting paperlesspaper's
#1F2226; this path quantises against the gamut's nominal palette, so panel
black is #000000. Redefining the palette colours would have changed nothing.

Fixed in v0.312.0 on edge

The profile's edge knobs now apply on both CircuitPython renderers, using the
same helpers and the same meaning as the .bin packers: smoothing before the
dither, then line-art preservation and the native-colour guard as a
nearest-colour overlay on top of it. All three are no-ops at their defaults, so
nobody's existing frames move until they touch that block.

Use a much higher tolerance than I told you. Measured on this path, an
800x480 near-black star field with a bright core:

tolerance	indices that change
8	0.03%
16	0.39%
24	2.99%
32	9.30%
48	12.76%

That 13% at 48 is almost exactly the red / blue / green speckle: on the
baseline frame, 85% of the sky lands on black and about 14% lands on a
saturated entry, which is diffused error rather than content. The guard is what
takes it back.

The reason it needs 32-48 here and single digits on a calibrated .bin panel
is the palette. Against nominal black at #000000, a sky sitting at 0-25 is up
to ~43 away. On the calibrated path the pre-pass parks those same pixels right
on top of the measured black, so a small tolerance catches them. Same control,
different distances. My earlier "16 to 24" was measured on theme backgrounds
and was wrong for both photographs and for your renderer; start at 40 and work
down.

What is still not wired

The calibrated palette itself, and the tone / dither knobs. The nominal palette
per gamut is a contract with the client and switching it would repaint every
existing CircuitPython panel on upgrade, so I want that opt-in per display
rather than shipped as a surprise. Say if you want it and I'll build it that
way; you'd be the first person through it.

The two UI bugs you reported, also fixed

The slider ignored after a fork. The tone editor forks a bundled preset on
the first tweak and edits the fork in place after that. The fork path saved the
edge settings you submitted; the edit-in-place path saved the base profile's
instead. So every edge control took whatever value it was forked with and
silently discarded later changes, exactly the reset-and-start-again dance you
found. "Preserve line-art edges" and "Smoothing radius" had it too. Tone and
dither always saved, which is why the editor looked healthy, and it means the
24 you were testing with may never have been the stored value.

The duplicate button. The inline Save and the sticky save bar are meant to
be alternatives, but the bar is sticky rather than fixed, so its natural
position is a few pixels under the inline button and both were on screen as
soon as a slider moved. The inline one now stands down while the bar is up.

One thing that still doesn't add up: a sliver down the right edge. That
pipeline is deterministic, so two renders of the same composition are
byte-identical, and with the guard inert both of your frames should have been
too. If it shows up again on v0.312.0 I'd like to see the pair.

[bablokb]

One thing that still doesn't add up: a sliver down the right edge. That
pipeline is deterministic, so two renders of the same composition are
byte-identical, and with the guard inert both of your frames should have been
too

What is different on the right side is the time in the status bar. Maybe this propagates down.

I will test the new version this afternoon.

[bablokb]

UI fixed. The new algorithm also works. If it improves the overall image quality depends probably on the image and your preferences. I will do some more tests tomorrow with the weather widgets and the calendar widgets. For the APOD image, it is hard to tell which version is "better".

I put together a comparison of the various algorithms (you have to look at them at the original size):

• first row is Tesserae with normal dither and with slider at 40
• second row is ImageMagick with pure colors and with paperless colors
• third row is the undithered original

The paperless palette produces almost no artifacts, but the cost is detail. I assume this will be different for other images. The input image has a reduced color set after all.

The type of artifacts is also interesting: I have seen this with other images as well. Tesserae (like Pimoroni original drivers) produce "stringy" artifacts, while IM produces specles/dots.

[dmellok]

You solved the right edge: it's the clock digit. Floyd-Steinberg carries error
right and down, so one changed character smears a wedge below it. Nothing to fix.

Agreed there's no winner on the APOD frame. The guard targets flat backgrounds
next to saturated content, so on a photo it trades speckle for detail and which
you prefer is a real preference. Your grid answered two other things though,
below. Weather and calendar should show the guard at its clearest, since that's
the case it was built for.

The stringy artifacts do have a cause. Your renderer quantises through Pillow,
so it only offers two dither modes, Floyd-Steinberg and none. The .bin
renderers use Tesserae's own dither and offer eight. Two of the missing ones
target exactly what you're seeing:

• Serpentine scanning. Pillow always scans left to right, and that is what
  correlates the error into chains. Alternating direction each row is the
  standard fix.
• Atkinson. Discards a quarter of the error instead of propagating it, so it
  reads as dots rather than strings.

That's my guess at the difference from ImageMagick, though I haven't checked
their scan order.

Your paperless-palette read is right, and it comes down to range. Calibrated
black to white is #1F2226 to #B9C7C9, not #000000 to #FFFFFF, and the
source gets compressed into that band. Less room for error means fewer artifacts
and less detail together.

Both of those need the CircuitPython path to run Tesserae's dither instead of
Pillow's. Bigger change than the edge work, and it would move existing frames,
so I'd make it opt-in per display. Say if you want it.

[bablokb]

I don't use my CP client in a production setting yet, so you are free to do incompatible changes. And I don't think anybody else is using it either yet. I am almost finished with initial documentation and once that is out, I will try to give Tesserae some more visibility by a short Adafruit-Playground post.

In the end it is more about priorities: which open ends are more important for the user base as a whole?