miniipe 0.4.0

An easy, no-dependencies package for writing IPE files from Python.

Mini-Ipe

This is a source-only, no-dependencies Python package to write Ipe files. The proper way to work with Ipe files from Python would probably be to use ipepython from ipe-tools, but this requires building a number of things from source, which may be difficult (or just time-consuming) depending on your computing environment. Mini-Ipe is a quick way to easily write Ipe files with minimum effort, from a plain Python environment.

Mini-Ipe is now on PyPI. Get it anywhere using (python3 -m) pip install miniipe.

What are Ipe files

Ipe is an "extensible drawing editor" that is excellent for making diagrams for scientific papers and presentations. This makes its file format ideal as output from computational experiments.

Important! An Ipe file needs a valid style file. See the remarks section below.

Getting started

First, get miniipe visible to your interpeter, for example using pip. (No need to clone the github repository.)

pip install miniipe

Then try the following small program and go from there.

from miniipe import Document, polygon

doc = Document()

ps = [(100,100), (200,200), (300,100)]
doc.path( polygon(ps) )

doc.write('simple.ipe')

Remarks

This is not a complete documentation, but looking at the examples will get you a long way. The best way to find out about all the methods and arguments is probably to import miniipe and use an IDE to look around (or skim the source source); here are some general remarks.

Points

Mini-Ipe accesses the X and Y coordinates 2D points you give it using index [0] and [1]. This means a 2-tuple of numbers is probably the easiest way to go in many cases (see the example above). We do not provide a class for working with 2D points/vectors: if you need to do nontrivial geometric computations, you probably already have some way to do that and we do not want to create additional API boundaries.

Note. We do provide a Matrix class for affine transformations, since this is an important concept in Ipe.

Document.path(...)

In Ipe, what is drawn is mostly orthogonal to how it it drawn. Polygons, circles, splines: almost everything is a path. Even filled shapes are paths with a fill property. This is reflected in the Mini-Ipe API: it is document.path( polygon(...), ...) rather than document.polygon( ..., ...).

• A path is described by a series of "path construction operators" (Ipe documentation). The Document.path method takes a string of such drawing instructions. You can write these on your own, but should probably use the convenience functions like rectangle, circle, polygon, and so forth. Under most circumstances, you can have multiple shapes be part of one "path" by concatenating these strings.

Layers

All objects (path, text, use) belong to a layer. As a consequence of the Ipe file format, if you don't specify the layer argument, the object goes in the same layer as the previous object.

Matrix

Matrices occur in multiple places in Ipe, most prominently as a property of objects: when drawing something that has a matrix property, Ipe transforms it using the given matrix. Use the Matrix class for this: it supports matrix multiplication using the @ operator, and helper functions for common transformations such as Translate, Scale and Rotate are provided. See the matrix fun example.

Note. Transformation by the matrix property is not done by miniipe: it merely writes the matrix property in the Ipe file. To actually transform a single point in a way that is consistent with Ipe, use the Matrix.transform(p) method. See the transform example to confirm that the results match.

Ellipse

The ellipse function takes a Matrix argument: it draws the ellipse resulting from transforming the unit circle by this matrix.

The 'parent' argument

The methods path, text and use take an optional argument called parent. If omitted, the object is added to the default page that a miniipe.Document starts with. If you make more pages, pass the page you want to add the object to instead. To put the object in a group (miniipe.Document.group(...)), pass the group instead.

Style files

It is not clear to me that I have the rights to distribute the standard Ipe style file, so you will have to provide your own. There are several ways to go about this.

1. Call import_stylefile() without arguments. This tries to import ~/.ipe/styles/basic.isy, which may or may not exist on your system. You get an error if this file does not exist.
2. Call import_stylefile(filename) with the filename of a valid style file. You can get one from Ipe as follows: make a new document, select Edit > Style sheets, select basic and click Save.
3. Do not import a style file when you make the document with miniipe and save it anyway. Ipe may complain when you open the file - colours, symbols et cetera will be missing. You can then add the basic style file after the fact. (See option 2 for how to get the basic style file.)

You can also make styles using Mini-Ipe. See the style example code.

Bitmap images

You can include bitmap images in Ipe files using add_bitmap and image. Mini-Ipe does not do any bitmap processing: the image payload is entirely your own responsibility. See the bitmap example.