generativepy.nparray module


Martin McBride, 2020-11-25
Tags nparray numpy
Categories generativepy generative art

generativepy has moved to the pythoninformer.com website, and this page might not be up to date. Please visit the new location.

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

The module is similar to the bitmap module. However, in this module images are stored as NumPy arrays, rather than PIL images. Images are stored in the same format as that used for frames.

Images are stored as 1 byte per colour, in Grey, RGB or RGBA colour space. The data is stored as a 3 dimension NumPy array, with a dtype of np.uint8. The shape of the array is [height, width, channels] where width and height are the image dimensions in pixels, and channels is 1 (Grey), 3 (RGB), or 4 (RGBA). Note the swapping of width and height, because NumPy stores data by row then column. There is more detail in the section on frames.

NumPy doesn't offer the same image processing facilities as PIL, but is has advantages in some situations:

  • NumPy is very good for arithmetic operations on pixel data.
  • It is also a good choice if you want to perfrom multiple operations on individual pixels (as happens, for example, in certain fractal algorithms).
  • It interfaces more easily with certain libraries such as SciPy and opencv.

You can also store save and load NumPy arrays to file, in NumPy's own format. This just stores the data in a raw format, rather than a standard image format. This can be useful for storing imtermediate calculations.

make_nparray

Used to create a single PNG image.

generativepy.nparray.make_nparray(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 fro greyscale, 3 for RGB, 4 for RGBA

make_nparray creates a NumPy array object, then calls the user supplied paint function to fill the array.

The paint function must have the following signature:

paint(image, pixel_width, pixel_height, frame_no, frame_count)
Parameter Type Description
image array A NumPy array 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_nparray.
pixel_height int The height of the image in pixels. This is the same value as the height parameter in make_nparray.
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_nparray function only ever creates one image, so the frame_no will always be 0 and the frame_count will always be 1.

make_nparrays

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

generativepy.nparray.make_nparrays(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 fro greyscale, 3 for RGB, 4 for RGBA

make_nparray 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_nparray. 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_nparray_frame

Used to create a single PNG image.

generativepy.nparray.make_nparray_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 fro greyscale, 3 for RGB, 4 for RGBA

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

make_nparray_frames

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

generativepy.nparray.make_nparray_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 fro greyscale, 3 for RGB, 4 for RGBA

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

save_nparray

Save a NumPy array to file.

generativepy.nparray.save_nparray(outfile, array)
Parameter Type Description
outfile String The path and filename for the output file.
array NumPy array An array containing the data.

save_nparray stores a NumPy array object to file, using NumPy's own format. The file can be re-loaded using load_nparray.

array can be any type of NumPy array. It can be a frame (which is just a NumPy array in a particular format), but it can also be any other type of NumPy array.

load_nparray

Load a NumPy array from file.

generativepy.nparray.save_nparray(infile)
Parameter Type Description
infile String The path and filename for the input file.

save_nparray loads a NumPy array object from file, using NumPy's own format. It returns the NumPy array.

The file can contain any type of NumPy array. If the data is of the correct format for a frame, the data can be used with any functions that accept frame data (for example the save_frame function in the movies module). Howvever, this functions doesn't check compatibility, it will just load whatever type of data is in the file.

Scaler class

The Scaler class defined in the bitmap module can also be used with the nparray class.

Copyright (c) Axlesoft Ltd 2021