python-halftone

A Python 3 module that uses Pillow to give images a halftone effect (see below for examples).

It is adapted from this StackOverflow answer (which includes example images) by fraxel.

Running it over large images, or with settings that create large images, can take some time.

Also see Clay Flannigan's halftone in case that suits your needs better.

NOTE: Colors in the output files are darker in JPEG files compared to PNGs. This is something to do with color profiles and RGB/CMYK conversion that I don't understand. Suggestions welcome on this Issue.

Basic usage

import halftone

h = halftone.Halftone("/path/to/myimage.jpg")
h.make()

Will create a new image at /path/to/myimage_halftoned.jpg, using the default settings.

Options

There are a number of options that can be added to the make() call, e.g.:

h.make(filename_addition="_new", scale=2)

The full list of options:

angles

A list of angles, in degrees, that each channel should be rotated by. If style="color" then 4 angles, one per channel (CMYK, in that order) are required. If style="grayscale" only 1 angle is required; any extra are ignored. Experimenting with different angles can increase or reduce moiré patterns. More on screen angles.

Default: [0, 15, 30, 45]

antialias

A boolean value, indicating whether the circles drawn should be antialiased. Because Pillow doesn't draw antialias shapes, this is done by drawing the image at 4x the size and then reducing it to the desired size, antialiasing as part of the process.

Default: False

filename_addition

When saving the new image, this string will be added to the original filename. e.g. if the original filename is "puppy.jpg" and filename_addition="_new", the saved file will be "puppy_new.jpg".

Default: "_halftoned"

output_format

Either "default", "jpeg", or "png". What format should the halftone file be saved as? If "default" then it's the same as the original input image's format.

Default: "default"

output_quality

When saving any JPEG images, what quality to use. From 0 to 100. Pillow says to avoid anything over 95. Has no effect on non-JPEG images.

Default: 75

percentage

How much of the gray component to remove from the CMY channels and put in the K channel.

Default: 0

sample

When creating each circle in the new image, what area of pixels should that circle represent?

Default: 10

save_channels

Whether to save the four CMYK channels as separate images, in addition to the combined halftoned image. Boolean. The files will have the color letter appended to the filename, like puppy_halftoned_c.jpg for the cyan channel. Only functions if the overall style argument is "color".

Default: False

save_channels_format

Either "default", "jpeg", or "png". If save_channels is True then what format should the four separate images be saved as? If "default" then it's the same as the original input image's format.

Default: "default"

save_channels_style

Either "color" or "grayscale". If save_channels is True then whether the four separate images should be saved in color or grayscale. If the overall style argument is "grayscale" then the four CMYK channels will always be "grayscale", no matter what this setting.

Default: "color"

scale

Scale of the output image. The maximum output dot diameter is sample * scale (which is also the number of possible dot sizes).

Default 1

style

Either "color" or "grayscale". For color, four screens are output, one each for cyan, magenta, yellow and black. For grayscale, only black dots are generated, only the first number in the angles list is used, and the percentage value is ignored.

Default: "color"

Examples

An example of make() using all options:

h.make(
    angles=[15, 75, 0, 45],
    antialias=True,
    filename_addition="_new",
    output_format="jpeg",
    output_quality=95,
    percentage=50,
    sample=5,
    save_channels=True,
    save_channels_format="jpeg",
    save_channels_style="grayscale",
    scale=2,
    style="color"
)

See the examples/ directory for the example images below.

Original image

Other than the filename_addition option, the images below have been created using the options specified.

Default settings

h.make()

Custom screen angles

Using different screen angles to reduce moiré (but resulting in a different pattern).

h.make(angles=[15, 45, 0, 75])

Smaller sample

Reducing the sample size and increasing the scale (to increase output detail).

h.make(sample=5, scale=2)

Antialias

With antialiased circles.

h.make(antialias=True)

Grayscale

Black and white, setting the angle to 45 (the default angle would be 0, resulting in circles being in rows and columns).

h.make(style="grayscale", angles=[45])