General Information

Lid is an image dithering program that is written in Python.


Lid was inpired by the solar powered version of [Lowtech Magazine]. I really loved their simple approach to images. They keep the filesize down using single color dithered images and then apply color filters to brighten up the page. That passes on the color work to the client rather than being a part of the web request (more data being sent).

Another inspiration was [Shizaru], a web server, by the founder of [Circumlunar Space], that places limits on the content that it will serve. The goal being to reduce web bloat and focus on content. One of those restrictions is on image size; 32k is the max! Lid was written to provide an easy way to get even large images down to a size that can be displayed by Shizaru.

Quick Start

Once Lid is installed on a system, run lid followed by a filepath and then the name you want to use for the output file.

There are a number of options/flags a user can set to get different output. The most common being -m which changes the dithering mode. The default dither produces an approximation of a four color pallet; this produces a very small file... but is not the best to look at. Using one of the other modes will produce a slightly larger file, but usually prettier output. Please read the [documentation] section to find out more.



Lid is run from the command line as follows: lid [flags]... [source path] [output name]. Flags are entirely optional and exist to fine tune the output.

By default lid can take in most image formats, but will output a png file. This is the recommended filetype for lid to output. It has the best balance of quality and filesize. However, lid does also support outputting jpg and gif as well.

At present lid offers six different dithering modes:

  1. t threshold dithering (aka average dithering)
  2. r radom dithering
  3. o4 ordered dithering w/ 4 levels (default)
  4. o9 ordered dithering w/ 9 levels
  5. e error diffusion dithering
  6. a all (converts input to every other mode offered)

The higher the number (above) the better the quality but the bigger the filesize. That said, when outputting to png all should be a good amount smaller than the source file. The exception to the higher number higher quality higher filesize statement is random dithering. Random dithering is an interesting effect, but its quality is not so photographic and it has nearly the same size as error diffusion, which is much more photographic.

The space savings of images produced via lid is usually less than half the size of the original, though that will vary from image to image. However, the idea behind lid is more about the aesthetics of an older way of doing things combined with reduced bloat. An image produced by lid is most definitely not going to equal to the picture quality of a full color digital photograph, that is not the intention. The hope is for people to see that you can do a lot of cool and creative stuff with small images, algorithms, and old-web charm.


Lid accepts a few flags allways given on the command line as the flag followed by a space followed by the value.

-- Flags --
Flag Values Notes
-f jpg, jpeg, gif, png (default) Changes the output format
-m o4 (default), o9, e, t, r, a Changes the dithering mode
-q Integer from 1 - 100 Set output quality (only for jpg output)
-t Integer from 0 - 255 Set the threshold (only for threshold mode, defaults to image average level)


lid -f jpg -m t -t 100 ~/Dekstop/myImage.png myDitheredImage

lid -m o9 ~/Desktop/myImage.png o9DitheredImage

In the above, the first line will create a jpg file named myDitheredImage.jpg. That image will be created using a threshold dither with the threshold set at 100.

The second example will use an o9 dither and export to the default file format (png) as o9DitheredImage.png.

Getting Lid

Lid is written in the programming language [Python]. Since Python is a scripting language it does not compile to binary files. As such, users will need to have Python running on their system. Lid requires a Python version >= 3.0. Many systems come with Python already installed, be sure to verify the version by running: 'python --version. Additionally, many systems have both Python 2.7 and Python 3+ installed. Sometimes Python 3 is aliased to 'python3'.

Lid requires the Python library Pillow (a Python imagine library fork). To acquire Pillow a user can try running: pip3 install Pillow (it is possible that your install may be aliased to just pip

That should take care of dependencies. You just need to make sure that lid, found in [this repo], is executable and on your path and you are good to go.

Image Examples

Below you will find images produced with lid, plus the original image, and then a version of the o9 image using css to achieve an example color effect. The color effect adds no size to the image and is done by the browser (assuming your browser supports css and images).

Ripley in her space suit, from the film Alien; threshold dither
t - threshold dithering - 15k

Ripley in her space suit, from the film Alien; 4 level ordered dither
o4 - ordered dithering w/ 4 levels - 20k

Ripley in her space suit, from the film Alien; 9 level ordered dither
o9 - ordered dithering w/ 9 levels - 42k

Ripley in her space suit, from the film Alien; random dither
r - random dithering - 64k

Ripley in her space suit, from the film Alien; error diffusion dither
e - error diffusion - 68k

Ripley in her space suit, from the film Alien; original full color, no dither
original image - 140k

CSS styled image using o9 dithering - still 42k