Introduction to generativepy
Categories: generativepy
This is the user guide for generativepy, currently at version 2024.11.
What is generativepy
generativepy is a Python library for creating images, diagrams, animations, and videos. It is general purpose but includes features that make it particularly suitable for creating mathematical and technical diagrams and videos.
generativepy is a library. It has no user interface. To create a diagram or video you need to write some Python code that calls the library. This guide gives lots of examples, and the code to create a simple diagram isn't complicated. Of course, if you want to create a very complex diagram the code can get as sophisticated as you like.
Uses
generativepy can be used to create images and animations (movies and GIFs), It is particularly suitable for geometry diagrams, graphs, and other mathematical illustrations, but it can be used for any type of diagram that can be constructed from drawing primitives.
Since diagrams are created programmatically, it is very useful if you need to create diagrams that are frequently updated with new data, as the changes can be made automatically without manual effort each time.
Installing
generativepy is a pure Python library. It can be installed using pip, or it can just be downloaded from github (https://github.com/martinmcbride/generativepy) and placed in a suitable location.
It has the following Python library requirements:
- numpy 1.26.4
- pycairo 1.27.0
- pillow 10.4.0
- vapory 0.1.2
- moderngl 5.12.0
- imageio 2.33.1
- moviepy 2.0.0
It also requires the following command line utilities to be installed:
- latex TexLive 2023
- dvipng 1.15
- gifsicle 1.94
- ffmpeg 6.1.1
History
generativepy started out as a wrapper for the Pycairo graphics library. At the time I was interested in experimenting with generative art. However, I was also building up the GraphicMaths website, and I quickly realised that the library could also be useful in creating mathematical diagrams for the site. Over the past few years (6 years at the time of writing) I have been developing the library while also using it to create images and videos.
So far I have created diagrams for a couple of hundred online maths articles and several maths books. I have also created about 100 YouTube videos, using the video capabilities of the library.
While I developed the library primarily for my own use, it has always been available as an open-source library, and I have done my best to make it useful for others. I have reorganised the code a few times to ensure the interfaces remained consistent, but at this stage, the library is quite mature and stable, and most docstrings are up to date.
Together with this guide, anyone who is a reasonably able Python coder should be able to use generativepy.
Features
generativepy has the following features:
- Vector drawing - generativepy uses the Pycairo library, which is a very capable, high-quality, vector graphics library supporting geometric shapes, text, different fill and stroke styles, coordinate transformations, transparency, and clipping. It has most of the features of a vector graphics program such as Inkscape, but is controlled by Python code. Images can be saved as PNG or SVG files.
- Bitmap drawing - bitmap images can be created or manipulated using the Pillow library, a well-known Python imaging library. Images can also converted to NumPy arrays, and manipulated using NumPy and related libraries (for example SciPy). Bitmap images can be saved as PNG files.
- Color - generativepy supports grayscale and RGB colour, with optional transparency. The colour library allows colours to be created from RGB values, HSL values, or CSS colour names, and for new colours to be created by manipulating existing colours in various ways.
- Compositing - all images are accessible as frames. A frame is a NumPy array. This allows two images to be combined in any way you want, before being saved as an image or animation frame (see next).
- Animation - generativepy can be used to create a sequence of frames for animation. These can be stored as animated GIFs, mp4 files, or as a sequence of PNG images to be processed by an external video editor. Individual frames are stored in the standard frame format (NumPy arrays) so frames can be processed/combined while the video is being created (eg for text overlay, picture-in-picture, or other effects). There is a simple tweening system for animation. Audio can be added as the video is created.
- Maths features - generativepy supports various features for geometric diagrams, including angle markers, tick marks etc. It can plot graphs, add annotations, and also create tables. These can all be mixed with other drawings on the same image. Formulas in LaTeX format can be rendered and placed on the same image. All maths features can be animated, just like any other drawing features.
- 3D drawing - this feature is still quite primitive, but generativepy supports 3D rendering using either Povray or moderngl. Povray support includes basic 3D plots.
genpygoodies
genpygoodies is an additional library that can be used alongside generativepy. It adds extra functionality that is either more specialised or less well-defined. It is a place where I add things that may or may not be useful, so they haven't quite earned their place in the main library.
This library might be slightly less stable than the main library, as some features might evolve over time.
See also
Join the GraphicMaths Newletter
Sign up using this form to receive an email when new content is added:
Popular tags
adder adjacency matrix alu and gate angle answers area argand diagram binary maths cartesian equation chain rule chord circle cofactor combinations complex modulus complex polygon complex power complex root cosh cosine cosine rule cpu cube decagon demorgans law derivative determinant diagonal directrix dodecagon eigenvalue eigenvector ellipse equilateral triangle euler eulers formula exercises exponent exponential exterior angle first principles flip-flop focus gabriels horn gradient graph hendecagon heptagon hexagon horizontal hyperbola hyperbolic function hyperbolic functions infinity integration by parts integration by substitution interior angle inverse hyperbolic function inverse matrix irrational irregular polygon isosceles trapezium isosceles triangle kite koch curve l system line integral locus maclaurin series major axis matrix matrix algebra mean minor axis nand gate newton raphson method nonagon nor gate normal normal distribution not gate octagon or gate parabola parallelogram parametric equation pentagon perimeter permutations polar coordinates polynomial power probability probability distribution product rule proof pythagoras proof quadrilateral questions radians radius rectangle regular polygon rhombus root sech segment set set-reset flip-flop sine sine rule sinh sloping lines solving equations solving triangles square standard curves standard deviation star polygon statistics straight line graphs surface of revolution symmetry tangent tanh transformation transformations trapezium triangle turtle graphics variance vertical volume volume of revolution xnor gate xor gate