Setting Up

ImageMagick is a command-line tool for image conversion and processing. The software feels a bit anachronistic because it has no GUI…but to its credit it does a fantastic job, is available for Windows, Mac and Linux, and is entirely free so everyone has a shot at using it.

Installing ImageMagic varies by platform and is beyond the scope of this guide, so head over to the ImageMagick download page for guidance on setting up the software.

Regardless of platform or installation procedure, in the end you will be working from the command line and typing things in…that’s just how it works. This means you’ll likely be using the Command Prompt in Windows, Terminal in macOS or Linux.

After ImageMagick is installed, download these PNG images to your computer and stash them away for safe keeping. You’ll need them later:

Working the Magic

Source images can be most any format. We’ll ask ImageMagic to output everything as .BMPs, because that’s what CircuitPython works with…it’s a relatively easy image format for microcontrollers to handle.

We’ll assume your source image(s) are already sized for the e-ink display (check the specific product page for your display’s dimensions, there’s a variety). ImageMagick does have scale and crop functions, but that’s a whole added layer of complexity…you’ll probably have an easier time using GUI tools, most operating systems have something basic included. But if you really need it, refer to the ImageMagic documentation for image resizing.

Put the image(s) you want to convert and the eink-*.png images in the same directory, then “cd” to that directory. (These could be in separate directories, but you’ll need to specify relative paths in that case…we’re keeping this example simple for command line novices.)

Supposing your source image is called “input.jpg,” and you want to create “output.bmp,” you’d type:

convert input.jpg -dither FloydSteinberg -define dither:diffusion-amount=85% -remap eink-3color.png BMP3:output.bmp

convert input.jpg -dither FloydSteinberg -define dither:diffusion-amount=85% -remap eink-3color.png BMP3:output.bmp

If using a monochrome (black & white) e-ink display, substitute eink-2color.png for the -remap argument.

For a 4-level grayscale e-ink display, use eink-4gray.png instead.

If your target application uses the Adafruit_ImageReader library for Arduino (which only handles 1- or 24-bit BMPs), you’ll need to insert “-type truecolor” just before the output filename, like so:

convert input.jpg -dither FloydSteinberg -define dither:diffusion-amount=85% -remap eink-3color.png -type truecolor BMP3:output.bmp

convert input.jpg -dither FloydSteinberg -define dither:diffusion-amount=85% -remap eink-3color.png -type truecolor BMP3:output.bmp

You do not need or want the truecolor option for CircuitPython. But…depending on the route you’re taking there…displayio.OnDiskBitmap vs. the adafruit_imageload library…the latter can handle run-length encoding compression, which saves a modest amount of disk space:

convert input.jpg -dither FloydSteinberg -define dither:diffusion-amount=85% -remap eink-3color.png -compress RLE BMP3:output.bmp

convert input.jpg -dither FloydSteinberg -define dither:diffusion-amount=85% -remap eink-3color.png -compress RLE BMP3:output.bmp

If you want something that works with either CircuitPython approach, skip the RLE compression. But I digress…let’s focus on the output…

Diffusion dithering used here gives us the most bang-for-buck in most cases.

Try different dither:diffusion-amount=X% settings until you find the right compromise between “too contrasty” (lower values) and “too snowy” (higher values). This is very subjective and the ideal setting will vary from image to image! Also, this setting is only available in recent releases of ImageMagick…older versions only work at 100%. If you have an old version 6 installation, this might be the time to upgrade.

Let’s see how different settings affect 2-color (left), 3-color (center) and 4-level gray (right) images:

Special Cases

A couple of alternate dither settings might be useful in certain situations…

Ordered dithering uses a structured pattern. It’s usually not the best for photos, as it tends to lose edge details, but may provide a “clean” look for flat artwork and diagrams:

convert input.jpg -ordered-dither o8x8 -remap eink-3color.png BMP3:output.bmp

convert input.jpg -ordered-dither o8x8 -remap eink-3color.png BMP3:output.bmp

In place of “o8x8”, you can try “o4x4” and “o2x2” for different (sometimes cleaner) results.

Remember to insert the “-type truecolor” or “-compress RLE” settings if (and only if) the situation demands it, as explained earlier.

You can also disable dithering altogether, which may be useful for text, high-contrast line art and 1980s Patrick Nagel prints:

convert input.jpg -dither None -remap eink-3color.png BMP3:output.bmp

convert input.jpg -dither None -remap eink-3color.png BMP3:output.bmp

While ImageMagick does have other dithering options, they tend to look best for ultra-high-DPI printed matter and are not well suited for these displays. We’ll not cover them here.

Rotated Images

Some displays operate natively in a “portrait” orientation (tall vs wide). If your source image is in the opposite orientation, you have two choices…

1. In your CircuitPython code, instruct the display to use a different rotation setting, e.g.:

display.rotation = 1

display.rotation = 1

(try 0, 1, 2 or 3)

2. Alternately, leave the code unchanged and rotate the image using ImageMagick, in which case you would insert the following before the output filename:

-rotate 90

-rotate 90

Use 90 to rotate the image clockwise, or -90 to rotate counterclockwise.