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.