Lua bindings for objects and attributes

The five Ipe objects are ipe::Group, ipe::Path, ipe::Text, ipe::Image, and ipe::Reference. They can be constructed from Lua as follows:

obj = ipe.Reference(attributes, name, pos)
obj = ipe.Text(attributes, text, pos)          -- Text of type label
obj = ipe.Text(attributes, text, pos, width)   -- Text of type minipage
obj = ipe.Path(attributes, shape, with_arrows)   
obj = ipe.Group(elements)       -- elements is a table of objects
obj = ipe.Image(rect, bitmap)   -- where bitmap is another Image object 

Here, attributes is a table defining the desired attributes, see below. shape is a table defining a shape, see below. To create path with arrows, you need to set with_arrows to true (it defaults to false). The arrow settings are then used from the attributes.

A bitmap can be created by reading from an image file:

bitmap, res = ipe.readImage(fname, format)

where format is one of "png" or "jpeg". If reading the bitmap fails, then bitmap is nil and res is an error message. Otherwise, bitmap is an Image object and res is the resolution in dots per inch. This will be (0,0) if the file does not contain that information.

Objects have the following methods:

obj:type()    -- return type as string: group, text, path, image, reference
obj:clone()   -- clone the object

obj:set(property, value)    -- see below
obj:get(property)           -- see below

obj:xml()                   -- return XML representation
obj:addToBBox(r, m)         -- including control points
obj:addToBBox(r, m, false)  -- without control points

obj:setCustom(s)            -- set string s as custom field
s = obj:getCustom()

-- text and reference objects only:
v = obj:position()
-- text objects only:
str = obj:text()
width, height, depth = obj:dimensions()
-- path objects only:
shape = obj:shape()                      
-- group objects only:
n = obj:count()                  
shape = obj:clip()           -- nil if no clipping
str = obj:text()             -- the link action (URL)
-- image objects only:
obj:info()                   -- returns table about bitmap
-- group objects only:
elements = obj:elements()    -- returns table with clones of elements 
element = obj:element(i)     -- returns clone of element #i
obj:elementType(i)           -- returns type of element #i


Attributes are represented in Lua as follows:

  • Symbolic names are strings
  • Absolute string values (e.g. dash style) are strings
  • Absolute numeric values are numbers
  • Absolute colors are tables with three entries with keys r, g, b
  • Boolean values (for minipage, farrow, rarrow) are booleans (but the strings "true" and "false" can be used to set them)
  • Transformations, Pinned, Linejoin, Linecap, Fillrule, Horizontal alignment, and Vertical alignment are represented by fixed strings, see table below.

The attributes argument to the object constructors is a table defining all desired attributes. Keys in the table are as follows. If a key is not present, the default value is used.

pathmode -- "stroked", "strokedfilled", "filled"
stroke   -- symbolic or color
fill     -- symbolic or color
dashstyle -- symbolic or absolute string
pen      -- symbolic or number
farrow   -- boolean
rarrow   -- boolean
farrowshape -- symbolic
rarrowshape -- symbolic
arrowsize  -- symbolic or number
symbolsize -- symbolic or number
symbolshape -- symbolic
textsize   -- symbolic or number
transformableText -- boolean
textstyle  -- symbolic
opacity    -- symbolic
tiling     -- symbolic
decoration -- symbolic ("normal" means no decoration)
minipage   -- boolean      
width      -- number
horizontalAlignment -- "left", "right", "hcenter"
verticalAlignment   -- "bottom", "baseline", "top", "vcenter"
linejoin            -- "normal", "miter", "round", "bevel"
linecap             -- "normal", "butt", "round", "square"
fillrule            -- "normal", "wind", "evenodd"
pinned              -- "none", "horizontal", "vertical", "fixed"
transformations     -- "translations", "rigid", "affine"


The set() and get() methods allow to access the attributes of objects. The property names are

    pen, symbolsize, 
    farrow, rarrow, farrowsize, rarrowsize, farrowshape, rarrowshape, 
    stroke, fill, markshape,
    pathmode, dashstyle, 
    textsize, textstyle, minipage, width, 
    opacity, tiling, gradient, 
    horizontalalignment, verticalalignment,
    linejoin, linecap, fillrule, 
    pinned, transformations,

It is okay to set a property on objects that do not support them (for instance, "textsize" on a path object). Reading such properties results in an "undefined" return value.


The geometry of a path object and the clipping path of a group object is an ipe::Shape. This is represented in Lua as a pure Lua object, namely an array with one entry per subpath.

Each subpath is again a table with a type field whose value must be one of "ellipse", "closedspline", or "curve".

For an ellipse, element 1 of the table is the matrix.

For a closed spline, the table contains the control points.

For a curve, the table has a second field closed, which is either true or false. The table also has an entry for each segment of the curve. Each segment is again a table with a type field, whose value is one of "arc", "segment", "spline", "oldspline", "cardinal", or "spiro". The segment table contains the control points of the segment. For arc segments, there is an additional arc field in the segment table that contains the arc as an ipe.Arc object. For cardinal spline segments, there is an additional tension field in the segment table.