What is generativepy

generativepy is a free and open-source library for creating diagrams, images, and animations in Python.

It is mainly intended for geometric diagrams including generative art, mathematical illustrations, fractals, and similar. It can also be used for creating general diagrams and is particularly suited to automatically created data-dependent diagrams.

This software is used to create almost all of the images and videos on my GraphicMaths channel.

The library can also create animations, from simple GIFs to complex, multi-scene HD videos.

In addition to vector graphics, the library can also create and process bitmap images. Work is ongoing to add a 3D graphics capability.

Since the different image types are all converted to a common NumPy format, it is possible to automatically sequence and compose images of different types.

In this article, we will review the main features of the library.

Open source

generativepy is a free and open source, released under the MIT licence. The source is available on github at github.com/martinmcbride/generativepy.

You can use the library in any way you wish and can adapt it to your needs. However, if you add bug fixes, improvements, or new features please consider submitting a pull request so that your changes can potentially be added for other people to use.

Vector drawings

generativepy features a high-level vector drawing module based on the PyCairo library.

The library supports various primitive shapes as well as lines, polygons and bezier curves. It also supports compound shapes, for example, shapes containing holes. Text is supported, and text can be treated as a shape, allowing it to be used as part of a compound shape, or as a clip-path, etc. Shapes can be filled or outlined in solid colours or gradients, and the usual fill and stroke styles are available.

Drawing supports a user/device space model with the ability to transform and clip user space.

The color module supports RGB, HSL, greyscale, CSS named colours, and custom colour palettes. Transparency (alpha channel) is fully supported. Colours can be adjusted, for example, to create a lighter or greener version of an existing colour. Colour maps can be created for colorising fractals and other art.

All drawing features can be programmed in Python, making the library ideal for generative art and automated diagram creation. There are also several maths-specific features that will be discussed later.

Vector drawings are converted to an intermediate format of a NumPy array of RGB or RGBA pixels. This common format is also used by the bitmap and 3D graphics modes, allowing images from the different drawing modes to be combined or sequenced (for example, overlaying text and shapes on a photographic image).

Vector drawings can be saved as PNG images. They can also be saved in SVG format - this is a standard vector format allowing the vector images to be used in vector editing software such as Inkscape.

Animation

generativepy has extensive support for animation. An animation is created as a sequence of frames, typically with each frame slightly different to the previous frame.

The tweening system provides a simple way to control animation. A tween can be defined that controls how a variable changes over time. The variable can remain constant, step change, or smoothly change from one value to another. Multiple transitions can be chained together to build complex behaviour. Easing functions can be used to modify transitions, for example, to add bounce effects.

Any aspect of the image can be animated in any way. The position, size, shape, colour etc of any item can be animated.

Animations can be saved in GIF or MP4 format. It is also possible to save a numbered sequence of PNG images that can be used by a video editor if you want to post-process the movie.

The movie builder allows you to create one or more scenes (separate animation sequences) that can be automatically concatenated to form a single movie. Sound can be automatically added at this stage.

Bitmap images

generativepy can also create or process bitmap images. This can be used to create images using fractal techniques, and also to process existing images.

Images can be processed using NumPy. NumPy allows high-speed mathematical operations on pixels so it is useful for fractal generation, filtering, region detection and similar. It can also be used to process images with SciPy, OpenCV and other libraries.

Images can also be processed with Pillow. This is a more traditional image processing library with similar features to basic photo editing software.

These modules can be used to create images in NumPy format that are compatible with the vector images, so they can be composited and mixed in video output.

Maths features

generativepy has several specific features that help in creating mathematical diagrams.

It can be used to create 2D line graphs. It can plot y against x, x against y, polar plots, and parametric plots. Multiple plots can be placed on the same axes. The plot lines and the axes can be styled in a similar way to normal shapes.

Plots can be placed anywhere on an image. just like other items. An image can have multiple graphs, and they can be mixed with other items. It is also easy to draw points, shapes, text etc in the graph's coordinate system, so they exactly align with the graph's xy grid.

Graphs can be animated, for example, to zoom in on the axes, animate the curve being drawn, change the graph formula over time, and so on.

generativepy can render Latex formulas as high-quality images that can be placed on an image.

For trig diagrams, you can add angle markers, parallel line ticks, and length ticks to diagrams. Text position offsetting allows labels to be positioned easily, even if the shape is animated.

The Table class can be used to draw a table. The row and column sizes are individually adjusted, and it is possible to include any item in the table cells - text, formulas, shapes, plots etc.

The math module includes simple 2D vector and matrix implementations that are designed to work with the drawing classes.

There is also a simple turtle graphics implementation that can be used to draw shapes such as recursive line fractals.

Compositing

As mentioned earlier, all the drawing modes use a common NumPy format. This means that images from different modes (eg vector drawing and bitmap drawing) can be joined to form a single animation.

It is also possible to composite images, for example, to draw vector lines and text over a bitmap image. This can be done by combining the numpy arrays. This can be used to create images or animations.

Currently, generativepy doesn't have built-in compositing functionality, but it can be done with simple NumPy expressions.

3D geometry

3D geometry is still experimental and may change in the future.

The current implementation uses the moderngl library to render 2D graphics. This currently works at quite a low level and requires quite a lot of knowledge of OpenGL to create graphics.

Currently, I am experimenting with an alternative approach, using the Povray renderer, which has a Python interface via the vapory module.

Povray operates at a higher level than moderngl. It is possible to describe a scene in terms of 3D objects such as cubes, spheres, and cylinders. It also has many built-in textures such as glass, metal, and wood, that can be easily applied to objects.

Povray also supports constructive geometry. This means, for example, you can intersect a cone and a plane to show a conic function, without needing to calculate the intersection.

It might be that, moving forward, generativepy will support both, but with moderngl mainly aimed at people who already have OpenGL knowledge. Povray would be the default option for most users.

genpygoodies

genpygoodies is an extra library of more specialist or experimental features. It should be regarded as experimental in that anything in the library might change in the future. This might involve breaking changes to the code in some new version. Or it might be that some feature proves sufficiently useful and stable that it moves across to the main generativepy library.

Don't be put off using genpygoodies, just be aware that you might occasionally need to update your code a bit when moving to a new version.

Here are the main modules in the current library.

The diagrams module supports:

• Graphs - for drawing network diagrams. Supports vertices (nodes) and connections (edges). It also supports directed connections and weighted connections. Vertices and connections can be individually styled.
• Logic gates - symbols and connectors for all 1 and 2 input logic gates.

The formulas and tweens modules have a few utility functions creating common formula and tween setups.

See also

• Installing generativepy