Minimize imports

Libraries are necessary for almost all projects and will require some memory. As described in the previous section on optimizing file storage, be sure your library files are in .mpy format. That saves both file storage space and some RAM too. 

When importing libraries, only import the functions that you need. You can selectively import functions using from ... import as shown below.

from adafruit_display_text.bitmap_label import Label

This code imports the Label function from the adafruit_display_text.bitmap_label library. The code can now call this function by using the Label() command.

By selectively importing only the functions you need, you may be able to reduce your memory usage versus importing a whole library.  Each CircuitPython library is organized differently, so the impact of this technique will vary.  Measure the memory use of the import to see how much memory is saved by using selective imports. 

Biggest memory user #1: Bitmaps

Use OnDiskBitmap

If you are using Adafruit_Imageload for displaying bitmaps, that may be a large user of your precious RAM. Regarding bitmaps, one memory-saving alternative to Adafruit_Imageload is to display directly from the stored file using the OnDiskBitmap functions

Using OnDiskBitmap does not store the bitmap in RAM, it just draws it directly from the stored file location (could be the CIRCUITPY drive or an SD memory card). The downside is that the display will not update as fast when using OnDiskBitmap since it has to be loaded from the non-volatile memory which is often slower, and OnDiskBitmap does not take advantage of displayio’s “dirty rectangle” tracking that reduces redraw times.

Reduce color depth

If you need the fast display redrawing that you get with Adafruit_Imageload of bitmaps, you can consider simplifying the color depth of your bitmaps. The bitmaps that CircuitPython can use are so-called “indexed” bitmaps. They contain a palette of colors used in the bitmap, and then each pixel on the bitmap has an entry in the file that tells it which palette color should be used. If you can reduce the number of colors then it may reduce memory usage significantly. But keep in mind due to the binary nature of how bitmap colors are stored, there are breakpoints in the number of colors that will have an impact on memory usage. For example, if you have 32 colors, going to 31 colors won’t save anything, but reducing to 16 colors can reduce the amount of RAM that the bitmap uses. You need an external image editor to change the amount of colors, you can find software tools to do this. The main jumps occur between 2, 4, 8, 16, 32, 64, 128, and 256 (they’re binary factors of 2). Try reducing your color depth by a factor of two or four and evaluate whether that is a good solution for your project.

Use the vectorio module

If your bitmaps are relatively simple shapes and lines, replace them with the vectorio module functions. You can draw lines, circles and polygons and it doesn’t use much RAM at all. Learn more about vectorio in the docs.

Biggest memory user #2: Fonts and Text Labels

Fonts can also take up a lot of RAM since they are basically a collection of little bitmaps for each character glyph. If you need to display different font sizes, consider loading one smaller font file and then use the scale parameter in the label or bitmap_label from the display_text library.

If you’re going to use text labels with displayio, start with bitmap_label, it uses less RAM than label. (There are some counterintuitive situations where you may want to use label even though it uses more total RAM, we’ll discuss that situation later.)

Here’s a quick summary of these bitmap and font tips:

  • Load bitmaps directly from non-volatile memory using OnDiskBitmap
  • Reduce the color depth of bitmaps
  • use bitmap_label for creating text labels (from library adafruit_display_text)
  • Use vectorio for graphics whenever possible instead of bitmaps.
  • Load one small font and scale it as needed (see scale parameter for labels)

This guide was first published on Apr 17, 2021. It was last updated on Apr 17, 2021.

This page (Memory: Optimizing memory use) was last updated on Nov 27, 2021.

Text editor powered by tinymce.