# Preparing Graphics for E-Ink Displays

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/080/188/medium800/eink___epaper_mac-se.png?1567052694 Easter egg from Macintosh SE ROM — one of four development team photos)

_What’s old is new again._

Back in the early Macintosh computer days, when the Earth’s crust was still cooling, getting photos and artwork to look presentable on these computers’ 1-bit monochrome displays was something of an art form.

Much of that know-how has fallen by the wayside as screens improved…but with wafer-thin, ultra-low-power  **E-Ink displays**  appearing everywhere now, a refresher in those techniques is suddenly relevant again.

![](https://cdn-learn.adafruit.com/assets/assets/000/080/211/medium800/eink___epaper_e-ink-straight-view.jpg?1567140506)

A couple of software options are shown in this guide. _ **ImageMagick** _ (a free command-line tool) and _ **Photoshop** _ (not free, but many folks already have it).

![](https://cdn-learn.adafruit.com/assets/assets/000/080/314/medium800/eink___epaper_4.2_inch_e_ink_macro_04_ORIG_2019_08.jpg?1567388840)

The resulting BMP images can be used with **Arduino** or **CircuitPython** libraries for these displays.

For **Arduino** , that would be the [**Adafruit\_ImageReader** library](https://github.com/adafruit/Adafruit_ImageReader), which can be installed with the Arduino Library Manager (Sketch→Include Library→Manage Libraries…). The latest versions of the Arduino IDE will then take care of installing all the dependent libraries (Adafruit\_GFX and others). See the **EInk\*** examples included with the Adafruit\_ImageReader library for usage.

For **CircuitPython** , [here’s a whole guide to get you started](https://learn.adafruit.com/quickstart-using-adafruit-eink-epaper-displays-with-circuitpython/overview).

# Image Formats

The aforementioned libraries — both for Arduino and CircuitPython — read  **BMP**  image files. But even within BMP, there are a number of different _variations…_and these libraries, evolving independently, aren’t always in step. Knowing what each library can handle is important when converting images.

- **Adafruit\_ImageReader for Arduino:** reads 1-bit and 24-bit uncompressed BMPs _only._
- **CircuitPython displayio.OnDiskBitmap:** reads uncompressed BMPs of _any_ depth, 1- to 32-bit.
- **CircuitPython adafruit\_imageload:** 1-, 4- and 8-bit uncompressed _or_ RLE-compressed BMPs. 16-bit and higher depths are not supported.

Because E-ink displays typically offer just a few shades, 1- or 4-bit output would normally be ideal. But due to the library constraints above, sometimes it’s necessary to use 24-bit output regardless, which we’ll explain…

# Preparing Graphics for E-Ink Displays

## Convert With ImageMagick

# Setting Up
[_ **ImageMagick** _](https://imagemagick.org) 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](https://imagemagick.org/script/download.php)** 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:

![](https://cdn-learn.adafruit.com/assets/assets/000/079/735/medium800/eink___epaper_eink-2color.png?1566418640)

![](https://cdn-learn.adafruit.com/assets/assets/000/079/736/medium800/eink___epaper_eink-3color.png?1566418646)

![](https://cdn-learn.adafruit.com/assets/assets/000/096/557/medium800/eink___epaper_eink-4gray.png?1603900330)

# Working the Magic
Source images can be most any format. We’ll ask ImageMagic to output everything as **.BMP** s, 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](https://imagemagick.org/Usage/resize/) 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:

```python
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:

```none
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:

```none
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:

![](https://cdn-learn.adafruit.com/assets/assets/000/097/166/medium800/eink___epaper_output-060.png?1605842738 With diffusion-amount at 60%, light areas tend to “blow out.”)

![](https://cdn-learn.adafruit.com/assets/assets/000/097/167/medium800/eink___epaper_output-080.png?1605842790 80% seems a good diffusion amount for this image!)

![](https://cdn-learn.adafruit.com/assets/assets/000/097/168/medium800/eink___epaper_output-100.png?1605842816 100% has the smoothest transitions, but very “snowy” throughout.)

# 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:

```none
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._

![](https://cdn-learn.adafruit.com/assets/assets/000/097/169/medium800/eink___epaper_output-ordered.png?1605842871 Ordered dither is not great for photos, maybe good for artwork.)

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

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

![](https://cdn-learn.adafruit.com/assets/assets/000/097/170/medium800/eink___epaper_output-none.png?1605842913 BRB, getting my nails done.)

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
```

(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
```

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

# Preparing Graphics for E-Ink Displays

## Convert With Photoshop

Adobe Photoshop is not inexpensive. But if you’re fortunate enough to already have it, this does make conversion a bit simpler.

To begin, download and unzip these Photoshop color tables:

[eink-palettes.zip](https://cdn-learn.adafruit.com/assets/assets/000/096/558/original/eink-palettes.zip?1603900560)
Your source image should be in **RGB mode**  (Image→Mode→RGB) if it isn’t already. Use the **Image Size** and/or **crop** tools to **match the dimensions of your image(s) to your e-ink display**.

Then we’ll do the e-ink conversion using  **Image→Mode→Indexed Color…**

From the “ **Palette:** ” menu, select “ **Custom…** ” then click the “ **Load…** ” button to import one of the color tables from the ZIP you downloaded above. Use “eink-3color” to process images for 3-color displays, “eink-2color” for monochrome (black & white) displays, and “eink-4gray” for 4-level grayscale displays.

![](https://cdn-learn.adafruit.com/assets/assets/000/079/731/medium800/eink___epaper_ps-palette-load.png?1566418249)

Then experiment with settings in the **Options** pane to get the effect you desire (keep the “Preview” box checked to see the results interactively).

![](https://cdn-learn.adafruit.com/assets/assets/000/079/733/medium800/eink___epaper_ps-palette-apply.png?1566418339)

 **_Diffusion dithering_**  used here gives us the most bang-for-buck in most cases.

Try different “ **Amount** ” 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!**

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

![](https://cdn-learn.adafruit.com/assets/assets/000/097/171/medium800/eink___epaper_ps-dither-60.png?1605856014 Too-low diffusion amount makes lighter areas “blown out.” (60%))

![](https://cdn-learn.adafruit.com/assets/assets/000/097/172/medium800/eink___epaper_ps-dither-80.png?1605856032 80% seems a good diffusion amount for this image.)

![](https://cdn-learn.adafruit.com/assets/assets/000/097/173/medium800/eink___epaper_ps-dither-100.png?1605856052 100% has the smoothest transitions, but very “snowy” throughout.)

# Special Cases

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

**_Pattern_**  dithering uses a uniform dot arrangement. 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:

![](https://cdn-learn.adafruit.com/assets/assets/000/097/174/medium800/eink___epaper_ps-dither-pattern.png?1605856071 Pattern dither is not great for photos, maybe good for artwork.)

Unlike ImageMagick (explained on the prior page), Photoshop just has one pattern dither setting, there are no available tweaks.

The “ **None** ” dither setting may be useful for text, high-contrast line art and 1980s Patrick Nagel prints:

![](https://cdn-learn.adafruit.com/assets/assets/000/097/175/medium800/eink___epaper_ps-dither-none.png?1605856101 BRB, getting my nails done.)

Photoshop also has a “Noise” dither setting — it looks okay for ultra-high-DPI printed matter but is not well suited for these displays.

Once you have a satisfactory conversion, we’ll **export** in **BMP** format…it’s a relatively easy image format for microcontrollers to handle. As explained on the overview page, you have some options here depending on what code you’ll be using to display the image…

If your target system is **CircuitPython** , select **File→Save As…** then choose the “ **4 Bit** ” option here.

And if your CircuitPython code will be using the  **adafruit\_imageload** library (rather than **displayio.OnDiskBitmap** ), you can check the “**Compress (RLE)**” box to save a little bit of space. If you’re not sure, or might be using both libraries in different situations, leave this **unchecked**.

![eink___epaper_ps-bmp-4bit.png](https://cdn-learn.adafruit.com/assets/assets/000/097/191/medium640/eink___epaper_ps-bmp-4bit.png?1605894908)

And for **Arduino** with the **Adafruit\_ImageReader** library, first change the image’s color mode _back_ to RGB ( **Image→Mode→RGB Color** …_don’t _simply Undo, we need the _dithered_ version but in RGB mode, _not_ the original image), then select  **File→Save As…**

Choose the “ **24 Bit** ” option and save.

![eink___epaper_ps-bmp-24bit.png](https://cdn-learn.adafruit.com/assets/assets/000/097/192/medium640/eink___epaper_ps-bmp-24bit.png?1605895211)

# 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
```

(try 0, 1, 2 or 3)

2. Alternately, leave the code unchanged and _rotate the image using Photoshop:_

**Image→Image Rotation→90° Clockwise** or

**Image→Image Rotation→90° Counter Clockwise**

Then save as a BMP as described above.

# Preparing Graphics for E-Ink Displays

## Board Usage

Once you have an image which will work with the display you have in mind, you can use it.

The following guides demonstrate using e-ink displays:

### Bare E-Ink Displays Crash Course - Overview

[Bare E-Ink Displays Crash Course](https://learn.adafruit.com/bare-e-ink-displays-crash-course)
[Overview](https://learn.adafruit.com/bare-e-ink-displays-crash-course/overview)
### Quickstart using Adafruit eInk/ePaper displays with CircuitPython - Overview

[Quickstart using Adafruit eInk/ePaper displays with CircuitPython](https://learn.adafruit.com/quickstart-using-adafruit-eink-epaper-displays-with-circuitpython)
[Overview](https://learn.adafruit.com/quickstart-using-adafruit-eink-epaper-displays-with-circuitpython/overview)
Also look at the Adafruit Learning System guide for the specific display if bought on Adafruit.com for use. That information is typically near the bottom of the product page.


## Related Guides

- [MagTag 3D Printed Stand Case](https://learn.adafruit.com/magtag-3d-printed-stand-case.md)
- [MagTag Sports Schedule Viewer](https://learn.adafruit.com/magtag-sports-schedule-viewer.md)
- [Adafruit Circuit Playground Tri-Color E-Ink Gizmo](https://learn.adafruit.com/adafruit-circuit-playground-tri-color-e-ink-gizmo.md)
- [MagTag Cat Fed Clock](https://learn.adafruit.com/magtag-cat-feeder-clock.md)
- [MagTag AR Tarot Card Reading](https://learn.adafruit.com/magtag-tarot-cards.md)
- [Adafruit 2.13" Monochrome E-Ink Bonnet for Raspberry Pi](https://learn.adafruit.com/2-13-in-e-ink-bonnet.md)
- [MagTag Dishwasher Status](https://learn.adafruit.com/magtag-dishwasher-status.md)
- [MagTag Showerthoughts and Quotes](https://learn.adafruit.com/magtag-showerthoughts.md)
- [MagTag Twitter Display](https://learn.adafruit.com/magtag-twitter-display.md)
- [MagTag Lists From Google Spreadsheets](https://learn.adafruit.com/collaborative-spreadsheets-to-magtag.md)
- [eInk FeatherWing Display Stand](https://learn.adafruit.com/eink-featherwing-display-stand.md)
- [CircuitPython Animated Holiday Wreath Lights](https://learn.adafruit.com/circuitpython-animated-holiday-wreath-lights.md)
- [Adafruit 2.13" 250x122 Quad-Color eInk](https://learn.adafruit.com/adafruit-2-13-250x122-quad-color-eink.md)
- [MagTag Daily Weather Forecast Display](https://learn.adafruit.com/magtag-weather.md)
- [Wireless Image Transfer with Circuit Playground Bluefruit and E-Ink Gizmo](https://learn.adafruit.com/wireless-image-transfer-with-circuit-playground-bluetooth-and-eink-gizmo.md)