Fix #22: Add documentation for converting RGB values to color palette indices

[Ununp3ntium115]

Fixes issue #22: How to translate Max For Live colors to Palette Color Index?

Adds a new section explaining how to convert arbitrary RGB color values to
the closest Push 2 color palette index.

Changes:

• Added section "Converting RGB Values to Color Palette Indices"
• Step-by-step algorithm with distance calculation methods
• Includes Euclidean and LAB color space methods

Files Changed:

• doc/AbletonPush2MIDIDisplayInterface.asc

Ready for squash-and-merge.

[Copilot]

Pull request overview

This pull request adds documentation to address issue #22, which asks how to translate Max For Live colors to Push 2 color palette indices. The addition provides clear guidance on converting arbitrary RGB values to the closest available palette index, including algorithm steps and alternative approaches.

Changes:

• Added a new documentation section "Converting RGB Values to Color Palette Indices"
• Explains the constraint that Push 2 LEDs require palette indices (0-127) rather than direct RGB values
• Provides step-by-step algorithm with distance calculation methods (Euclidean and LAB color space)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rsu-ableton]

The text is good.

Two things should be mentioned, though:

1. If the palette is modified, this changes the respective colors for all Apps running in parallel (e.g. when using Max For Live); also, Live might reinstall it's palette when reconnecting to Push (this is also the reason why the default palette is not documented,it's usually overwritten)

2. There is sysex command 0x3b to assign an arbitrary RGB color to any LED, independently from the palette; strange enough we have no documented it, although there are people out there using it ...

Here is the documentation

Arbitrary RGB LED Color

In addition to the index color palette with 128 entries,
it is possible to set individual LEDs to arbitrary RGB color.
The color will be in effect until either a different color is
sent or the color is set to a palette entry using the respective
control change (CC) or note-on message. The specified RGB color
(3x8 bit) is subject to the same processing as the RGB values from
the palette, i.e. white balancing, color spaces, brightness and
animation. The function is not needed for white leds as for these
the existing palette essentially covers the possible range of values.

Command 0x3b: Set Arbitrary RGB LED Color

  Set the RGB value for the LED given by CC/note number, with
  the respective channel to chose the animation. The CC/note number
  and channel are the same as in the note/CC message sent to chose
  a color from the palette. The change is immediately applied.

  tc     - type and channel:
           000cccc for note-on
           001cccc for CC
  n      - note/CC number (0..127)
  r(LSB) - lower 7 bits of red color
  r(MSB) - higher 1 bit of red color
  g(LSB) - same for green color
  g(MSB)
  b(LSB) - same for blue color
  b(MSB)

[rsu-ableton]

I'm through with the PRs now. Big thanks for the work on this documentation.
I might add the 0x3b sysex command description myself later, if you don't have the time.

[brunchboy]

How interesting about the 0x3b sysex, I’d probably have used that in Afterglow if I knew about it rather than constantly messing with the palette. Maybe I should do some benchmarking to see if it’s worth changing approach.