1.1.0 • Public • Published

'npm version' 'downloads over month'


Convert a PNG image into an LCD/OLED compatible framebuffer


npm install png-to-lcd

What does it do?

png-to-lcd consumes a PNG image file, and returns the image data, formatted for OLED screens (an 8-bit/byte framebuffer). It's just monochrome support for now. It only supports SSD1306 OLED displays. You can buy these pretty cheaply on Adafruit (my favourite), Sparkfun, eBay, and sites like Banggood.

What doesn't it do?

Image prep - the image you pass in should be an RGBA PNG (both colour and greytone are acceptable), and sized to the exact dimensions of the screen you'd like to use. So if your screen is 128x64 pixels, size it so in your image editor of choice.

I suggest Pixelmator, Acorn, or GIMP if you're into desktop software. Alternatively, if you're into super awesome software made in the browser by a badass, try Jenn Schiffer's noice, which is really quite suitable for this kind of low res screen design.


png-to-lcd takes three arguments:

string filename - this is pretty obvious really.

bool dither - do you want to run a dithering algorithm on your image?

function callback - callback when image formatting complete


var pngtolcd = require('png-to-lcd');
pngtolcd('cat.png', true, function(err, buffer) {

What the heck is dithering?

Dithering is a method of diffusing pixels in order to avoid harsh edges or banding where the colours in an image contrast with each other. Fancy algorithms and stuff.

png-to-lcd uses the Floyd Steinberg algorithm specifically, as it produces the clearest images on a pixel screen in my experience.

When should I opt to use dithering?

If you're trying to convert a photo, or detailed image - use dithering! You'll retain more detail.

When should I not ask for dithering?

If you have crisp line detailing in your image, it's best not to dither as it makes a real mess of things. This includes things like text, and simple pixel art drawings. When you pass in false for the dither argument, png-to-lcd will just apply a simple threshold filter to produce your dark/light filters in the buffer.

Show me some output

Ok. You can make stuff like this.

Dithered 128 x 32 display example:
cat 128x32

Dithered 128 x 64 display example:
cat 128x32

Non dithered 128 x 32 display text example:

My images don't look perfect (╯°□°)╯︵ ┻━┻

That's understandable. A computer program will do its best to guess at the best optimizations, but it has little context for what the heck it's working on for you. You may find that some screen designs needs a little tweaking before it's perfect.

For non dithered pics - try nudging the pixels using just black and white only (no grey) in your image editor for best results before running it through this module.

Package Sidebar


npm i png-to-lcd

Weekly Downloads






Unpacked Size

39.3 kB

Total Files


Last publish


  • noopkat