generativepy.bitmap module


Martin McBride, 2020-09-06
Tags bitmap
Categories generativepy generative art

The bitmap module provides the ability to paint bitmap images and save them as either PNG images or frames.

The module is based on the popular PIL Python imaging library. This provides many functions for manipulating bitmap images, such as colour manipulation, filters, enhancement, morphing, colour channel operations, and pixel access. It also provides drawing operations (rectangles, ellipses, text etc), but these are not as powerful as the vector methods available via Pycairo in the generativepy.drawing module.

generativepy actually uses the Pillow library, which is a fork of PIL. That is because Pillow is actively maintained whereas PIL is not. The Pillow library is compatible, and is still imported using the name PIL. We will refer to is as PIL in the documentation.

make_bitmap

Used to create a single PNG image.

generativepy.bitmap.make_bitmap(outfile, paint, pixel_width, pixel_height, channels=3)
Parameter Type Description
outfile String The path and filename for the output PNG file. It should end in '.png'.
paint Function A drawing function object, see below.
pixel_width int The width of the image that will be created, in pixels.
pixel_height int The height of the image that will be created, in pixels.
channels int The number of colour channels. 1 for greyscale, 3 for RGB, 4 for RGBA

make_bitmap creates a PIL Image object, then calls the user supplied paint function to fill the image.

The paint function must have the following signature:

paint(image, pixel_width, pixel_height, frame_no, frame_count)
Parameter Type Description
image Image A PIL Image object that the paint function should work on.
pixel_width int The width of the image in pixels. This is the same value as the width parameter in make_bitmap.
pixel_height int The height of the image in pixels. This is the same value as the height parameter in make_bitmap.
frame_no int The number of the current frame.
frame_count int The total number of frames.

frame_no and frame_count only apply to functions that create a sequence of images. The make_bitmap function only ever creates one image, so the frame_no will always be 0 and the frame_count will always be 1.

make_bitmaps

Used to create a sequence of PNG images. These can be combined into an animated GIF or video.

generativepy.bitmap.make_bitmaps(outfile, paint, pixel_width, pixel_height, count, channels=3)
Parameter Type Description
outfile String The path and filename for the output PNG file. It should end in '.png'.
paint Function A drawing function object, see below.
pixel_width int The width of the image that will be created, in pixels.
pixel_height int The height of the image that will be created, in pixels.
count int The total number of images that will be created.
channels int The number of colour channels. 1 for greyscale, 3 for RGB, 4 for RGBA

make_bitmap creates a PIL Image object, then calls the user supplied paint function to fill the image.

The outfile parameter should be a base filepath. For example:

C:/temp/image

In this case the files will be created in the folder C:/temp, and their names will be based on the base name "image":

image00000000.png
image00000001.png
image00000002.png
etc

Once the images have been created, you can use an external program to convert them into an animated GIF or movie.

The paint function has the same signature as for make_bitmap. In this case though, it will be called count times. The frame_count will always be set to count, and the frame_no will increment each time draw is called. You can use the frame_no value to draw a different image each time, to create animation.

make_bitmap_frame

Used to create a single PNG image.

generativepy.bitmap.make_bitmap_frame(paint, pixel_width, pixel_height, channels=3)
Parameter Type Description
paint Function A drawing function object, see below.
pixel_width int The width of the image that will be created, in pixels.
pixel_height int The height of the image that will be created, in pixels.
channels int The number of colour channels. 1 for greyscale, 3 for RGB, 4 for RGBA

This works in a simlar way to make_bitmap, but instead of saving the image to a file, it returns a frame.

make_bitmap_frames

Used to create a sequence of PNG images. These can be combined into an animated GIF or video.

generativepy.bitmap.make_bitmap_frames(paint, pixel_width, pixel_height, count, channels=3)
Parameter Type Description
paint Function A drawing function object, see below.
pixel_width int The width of the image that will be created, in pixels.
pixel_height int The height of the image that will be created, in pixels.
count int The total number of images that will be created.
channels int The number of colour channels. 1 for greyscale, 3 for RGB, 4 for RGBA

This works in a similar way to make_bitmaps, but instead of saving the images to a set of files, it returns a lazy sequence of frames.

get_mode

Convert the number of channels into a PIL mode string.

generativepy.bitmap.get_mode(channels)
Parameter Type Description
channels int The number of colour channels. 1 for greyscale, 3 for RGB, 4 for RGBA

Returns a string:

  • 'L' if channels is 1.
  • 'RGBA' if channels is 4.
  • 'RGB' in all other cases.

Scaler class

A PIL Image object always works in pixels. Unlike a Pycairo context used by make_image and similar functions, Image has no concept of a user space.

However, it is sometimes useful to be able to calculate values in a user space and convert them to image pixels (device space), or vice versa.

The Scaler class provides this functionality. You can create a scaler object with the dimensions of the image and the required user space. The scaler object can then be used to convert coordinates from one space to another. See the user space tutorial for more details.

Scaler constructor

Creates an Scaler object.

Scaler(self, pixel_width, pixel_height, width=None, height=None, startx=0, starty=0)
Parameter Type Description
pixel_width int The width of the image in pixels. Use the value passed into paint.
pixel_height int The height of the image in pixels. Use the value passed into painty.
width float The required image width in user coordinates.
height float The required image height in user coordinates.
startx float The user space x coordinate of the device space origin.
starty float The user space y coordinate of the device space origin.

device_to_user

Converts a device coordinate to user space.

device_to_user(self, device_x, device_y)
Parameter Type Description
device_x int The x coordinate in device space.
device_y int The y coordinate in device space.

Returns float (x, y), a tuple of the equivalent coordinates in user space.

user_to_device

Converts a user coordinate to device space.

user_to_device(self, user_x, user_y)
Parameter Type Description
user_x float The x coordinate in user space.
user_y float The y coordinate in user space.

Returns int (x, y), a tuple of the equivalent coordinates in device space.

For an example, see the user space tutorial.

If you found this article useful, you might be interested in the book Computer Graphics in Python or other books by the same author.

Prev
Next

Popular tags

2d arrays abstract data type alignment and angle animation arc array arrays bar chart bar style behavioural pattern bezier curve built-in function callable object chain circle classes clipping close closure cmyk colour combinations comparison operator comprehension context context manager conversion count creational pattern data science data types decorator design pattern device space dictionary drawing duck typing efficiency ellipse else encryption enumerate fill filter font font style for loop function function composition function plot functools game development generativepy tutorial generator geometry gif global variable gradient greyscale higher order function hsl html image image processing imagesurface immutable object in operator index inner function input installing iter iterable iterator itertools join l system lambda function len lerp line line plot line style linear gradient linspace list list comprehension logical operator lru_cache magic method mandelbrot mandelbrot set map marker style matplotlib monad mutability named parameter numeric python numpy object open operator optimisation optional parameter or pandas partial application path pattern permutations pie chart polygon positional parameter print pure function python standard library radial gradient range recipes rectangle recursion reduce regular polygon repeat rgb rotation roundrect scaling scatter plot scipy sector segment sequence setup shape singleton slice slicing sound spirograph sprite square str stream string stroke structural pattern subpath symmetric encryption template text text metrics tinkerbell fractal transform translation transparency triangle truthy value tuple turtle unpacking user space vectorisation webserver website while loop zip