Module `generativepy.drawing`

The drawing module provides the ability to draw vector images and save them as either PNG images, SVG images, or frames.

The module is based on the Pycairo library. This provides many vector drawing methods.

However, it is often more convenient to use the geometry module of generativepy, which provides higher level versions of most of the primitive drawing functions.

Functions

def example_pycairo_draw_function(ctx, pixel_width, pixel_height, frame_no, frame_count)

This is an example draw function for use with make_image() and similar functions. It is a dummy function used to document the required parameters.

Args

ctx: PyCairo context object - The context object that the image will be drawn on.
pixel_width: int - The width of the image in pixels.
pixel_height: int - The height of the image in pixels.
frame_no: int - the number of the current frame. For single images this will always be 0. For animations this paint function will be called frame_count times (once for each frame) with frame_no incrementing by 1 each time (ie it counts from 0 to frame_count - 1.
frame_count: int - The total number of frames being created.For single images this will always be 0. For animations this will be set to the total number of frames in the animation.

def make_image(outfile, draw, width, height, channels=3)

Creates a Pycairo drawing context object, then calls the user supplied draw function to draw on the context. It then stores the image as a PNG file.

The draw function must have the signature described for example_draw_function.

Args

outfile: str - The path and filename for the output PNG file. The '.png' extension is optional, it will be added if it isn't present.
draw: 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.

def make_image_frame(draw, width, height, channels=3)

Used to create a single image as a frame. A frame is a NumPy array with shape (pixel_height, pixel_width, channels).

make_image_frame() creates a Pycairo drawing context object, then calls the user supplied draw function to draw on the context. The image is returned as a NumPy frame.

The draw function must have the signature described for example_draw_function.

Args

draw: 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.

Yields

A frame.

def make_image_frames(draw, width, height, count, channels=3)

Used to create a single image as a frame. A frame is a NumPy array with shape (pixel_height, pixel_width, channels).

make_image_frames() creates a Pycairo drawing context object, then calls the user supplied draw function to draw on the context. It repeats this process count times to create a sequence of image frames.

The function returns a lazy iterator. When this iterator is evaluated, the image frames are created on demand.

The draw function must have the signature described for example_draw_function. Each time the paint function is called, fn will contain the frame number - 0, 1 etc

Args

draw: 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.

Yields

A frame.

def make_images(outfile, draw, width, height, count, channels=3)

Used to create a sequence of PNG images. These can be combined into an animated GIF or video. This is similar to make_image() except it creates count files instead of just one.

Creates a Pycairo drawing context object, then calls the user supplied draw function to draw on the context. It repeats this process count times to create a sequence of image files.

The image files are stored in numbered files. For example if outfile is "myfolder/myname.png" the files will be saved as "myfolder/myname00000000.png", "myfolder/myname00000001.png" and so on.

The paint function must have the signature described for example_draw_function. Each time the draw function is called, fn will contain the frame number - 0, 1 etc

Args

outfile: str - The path and filename template for the output PNG file. The '.png' extension is optional, it will be added if it isn't present.
draw: 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 number of images to create
channels: int - The number of colour channels. 1 for greyscale, 3 for RGB, 4 for RGBA.

def make_svg(outfile, draw, width, height)

Used to create a single SVG image. This function is similar to make_image() except that it returns an SVG (vector image) instead of a PNG (bitmap image).

make_svg() creates a Pycairo drawing context object, then calls the user supplied draw function to draw on the context. It then stores the image as a PNG file.

The draw function must have the signature described for example_draw_function.

Args

outfile: str - The path and filename for the output SVG file. The '.svg' extension is optional, it will be added if it isn't present.
draw: 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.

def setup(ctx, pixel_width, pixel_height, width=None, height=None, startx=0, starty=0, background=None, flip=False)

This function performs a scaling to set the drawing coordinates. This is optional, but in generative art you will often be using functions that work at a particular scale. It is very useful to be able to set your drawing coordinates to maths this, so you don't need to worry about scaling values when you draw.

As a convenience it can also set the page background colour.

Args

ctx: Pycairo context - The drawing context.
pixel_width: int - Pycairo context. Use the value passed into the draw function.
pixel_height: int - The device space height. Use the value passed into the draw function.
width: number - The user space width.
height: number - The user space height.
startx: number - The x offset of the top left corner from the origin.
starty: number - The y offset of the top left corner from the origin.
background: Color - Color of the background.
flip: bool - If true, flips the page in the y direction, so the origin is at the bottom left, useful for mathematical drawing.