Adding Images

The poi can display BMP or GIF images. Images need to be 36 pixels tall (or however many LEDs your poi have).

The process for converting images is a little gritty right now, requiring a command-line tool written in Python. It also requires the Python Imaging Library (PIL).

Probably the least-bothersome way to do this right now is on a Raspberry Pi computer, where most of the tools are already built-in, though this requires some familiarity with the Linux operating system.

Phil says he'd like to make a more user-friendly tool for this in the future. But for the time being these steps remain a bit technical.

Installing and using Python varies from system to system. On the Raspberry Pi, Python is already installed by default, though PIL must be added manually:

Download: file
sudo apt-get install python-imaging

Things will be entirely different on Windows or Mac or even on other Linux distributions. Unfortunately setting up Python is way beyond the scope of this guide, so you might Google ’round for tutorials elsewhere. If this gets too dry and technical, don’t fret…I suspect that given time other users will post some good poi-ready images to the Adafruit Forums.  And the code as posted has a good number of images already installed.

Inside the “convert” folder included with the project is a file called “convert.py” — the Python script which readies images for the poi.

As written, this code is designed for the Genesis Poi project, which use fewer LEDs and a much smaller battery. For maximum eye-searing potential on our supernova poi, we need to make some small changes to the script. Open the file in a text editor and look for these three lines near the beginning:

Download: file
batterySize    = 150  # Battery capacity, in milliamp-hours (mAh)
runTime        = 1.1  # Est. max run time, in hours (longer = dimmer LEDs)
parallelStrips = 2    # Same data is issued to this many LED strips

Change these to:

Download: file
batterySize    = 2200 # Battery capacity, in milliamp-hours (mAh)
runTime        = 2.5  # Est. max run time, in hours (longer = dimmer LEDs)
parallelStrips = 2    # Same data is issued to this many LED strips

Save the changes to the file. But if you’ll ever be converting images for the Genesis Poi in the future, you’ll need to change those lines back.

Once everything is installed and your scripts are up to date, here's a video detailing how to add images to your poi.

So, let’s suppose we have this little flames image, which is 36 pixels tall (the same number as my LED count on each end):

The top of the image will correspond to the top of the poi, so if you're showing text or a directional image you may want to flip the image upside down so it looks upright at the top of the swing.  

To convert this using the Python script, you’d type:

Download: file
python convert.py images/flames.gif > graphics.h

Or you can convert a whole list of images:

Download: file
python convert.py images/*.gif > graphics.h

The “> graphics.h” redirects the output of the convert.py script to the plain-text file graphics.h, which can then be incorporated into an Arduino sketch.

Inside the file you’ll see one or more sections like this:

Download: file
// usa.gif -----------------------------------------------------------------

const uint8_t PROGMEM palette04[][3] = {
  {  56,  56,  56 },
  {  56,   0,   0 },
  {   0,   0,   0 },
  {   0,   3,  56 } };

const uint8_t PROGMEM pixels04[] = {
  0X22, 0X22, 0X22, 0X22, 0X22, 0X22, 0X22, 0X22,
  0X22, 0X22, 0X22, 0X22, 0X22, 0X22, 0X22, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X10, 0X10, 0X10, 0X10, 0X10, 0X10, 0X12, 0X22,
  0X33, 0X33, 0X33, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X30, 0X30, 0X30, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X33, 0X03, 0X03, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X30, 0X30, 0X30, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X33, 0X03, 0X03, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X30, 0X30, 0X30, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X33, 0X03, 0X03, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X30, 0X30, 0X30, 0X30, 0X10, 0X10, 0X12, 0X22,
  0X33, 0X33, 0X33, 0X30, 0X10, 0X10, 0X12, 0X22 };

Above is the data for an American flag…a four-entry color palette (white, red, black, blue) followed by the pixel data (packed two pixels per byte).

Then, near the bottom of the file, you’ll see a block like this:

Download: file
const image PROGMEM images[] = {
  { PALETTE1 ,  100, (const uint8_t *)palette00, pixels00 },
  { PALETTE4 ,   48, (const uint8_t *)palette01, pixels01 },
  { PALETTE4 ,   54, (const uint8_t *)palette02, pixels02 },
  { PALETTE4 ,    1, (const uint8_t *)palette03, pixels03 },
  { PALETTE4 ,   24, (const uint8_t *)palette04, pixels04 },
  { PALETTE4 ,    9, (const uint8_t *)palette05, pixels05 },
  { PALETTE4 ,   26, (const uint8_t *)palette06, pixels06 }
};

This table holds references to all of the images in the file, along with their widths in pixels (height is always 36) and format.

Paste this code into your arduino sketch (in the graphics.h tab) and upload it to your poi.  You're good to go!

This guide was first published on Feb 10, 2016. It was last updated on Feb 10, 2016. This page (Adding Images) was last updated on Oct 22, 2019.