[Previous] [Up] [Next]
Go backward to The interface files between Ipe and Ipe user macros
Go up to Interfacing with Ipe
Go forward to Creating Ipe files from PLAGEO

The different entries in an Ipe format file

An entry describing an Ipe object consists of a type descriptor, and several keyword-parameter pairs. Usually, only a few keywords are obligatory, the others are optional. The different entry types are described in the following subsections. Objects can be grouped together by the construct

% Group
entry_1
entry_2
...
entry_n
% End
(This was the description of the Group object!) Note that the spaces between the percent sign and the keywords are necessary.

Polygonal Objects

Polylines, polygons, and rectangles are all polygonal objects. They are represented like this
% Line
% sk stroke_color
% fi fill_color
% # n
x_1 y_1
x_2 y_2
...
x_n y_n
% cl
% End
This describes a polygon. To describe a polygonal chain, omit the line
% cl
stroke_color and fill_color are real numbers between 0 (Black) and 1.0 (White). You can specify non-gray colors as well, using a line of the form
% skc red green blue
% fic red green blue
To get the color empty, simply omit the color specification. A non-solid line style can be given using
% ss linestyle linewidth
where line style is specified as an integer between 0 and 65535. Arrows can be specified using
% ar mode size
where mode is 1, 2, or 3 for <--, -->, and <--> arrows.

Spline Objects

Both splines and splinegons are spline objects. They are represented like polygonal objects.
% Spline
% sk stroke_color
% fi fill_color
% # n
x_1 y_1
x_2 y_2
...
x_n y_n
% cl
% End
Again, omit the cl keyword for splines instead of splinegons. The coordinate pairs describe the control points of the spline. To get control points with multiplicity, simply repeat the point. Line style and non-gray color can be specified as for polygonal objects. You can specify arrows as for poly-lines, but they will only be drawn on endpoints that are control points of multiplicity three.

Text Objects

A basic text object needs only a color, a position, and a string.
% Text
% sk color  
% s string
% xy x y
% End
The string will be set in 10 point Roman font. This can be changed by adding a line
% f font size
where font is 0, 1, 2, 3 for Roman, Italic, Bold, or "Math" font. As for lines, a non-gray color can be given using a skc keyword. Note that when Ipe writes an interface file for a Ium, it will actually add a field of the form
% tbb width height
which describes the bounding box for the text object (so that the Ium does not have to start up LaTeX to figure out such a bounding box). If a tbb field is present in an input file for Ipe, it will simply be ignored.

A minipage object contains the width of the bounding box like this.

% bb width
Note that for minipage objects the position specified with xy is the upper left corner of the bounding box.

To specify multi-line strings, just put additional s fields. Ipe concatenates them in the order in which they appear in the file. Note that no line feed is added after the last line. To specify that, you have to add an empty s field.

Circle Objects

Circles are specified as follows.
% Circle
% sk stroke_color
% fi fill_color
% xy center_x center_y
% r radius
% End
stroke_color and fill_color are as for (Poly)lines and can be omitted. Line style can be specified as for lines.

An ellipse can be specified by giving the 2x2 transformation matrix that transform the circle specified with xy and r into the desired ellipse.

% tfm a_1_1 a_1_2 a_2_1 a_2_2

Arc Objects

A circular arc is specified like a circle, plus the two angles bounding the arc. Note that smallangle can be larger than bigangle, if the arc spans 0 degrees.
% Arc
% sk stroke_color
% fi fill_color
% xy center_x center_y
% r radius
% ang smallangle bigangle
% End
Angles must be given in degrees. stroke_color and fill_color are as for (poly)lines and can be omitted. Line style and arrows can be specified as for lines.

Mark Objects

Marks are actually the simplest object. They only need a coordinate pair and a color.
% Mark
% xy x y
% sk color
% End
This puts a disc at position (x,y). The size is the current mark size in Ipe. A different type of marker can be specified by
% ty type
where type is 1,2,3,4,5 for circles, discs, boxes, squares, and crosses. A different size can be specified by
% sz size
Note that markers have only one color, even when they are filled.

Bitmap Objects

Bitmaps have a real size--in Postscript point coordinates--and a pixel size. There is not necessarily any relation between the two.
% Bitmap
% xy x y
% px pixel_width pixel_height
% bb real_width real_height
% bits number_of_words mode
data_string
% End
The bb field can be omitted. Then, real_width and real_height are set to pixel_width and pixel_height. The bitmap will fill the box with corners (x, y) and (x + real_width, y + real_height). Note that real_width and real_height can be negative.

The image itself is specified using a data_string as in Postscript. This string describes number_of_words pixels by giving their value in hexadecimal (digits '0' ... '9' and 'a' ... 'f'--no capitals!). Any characters not in this range are ignored while reading the string, so you can and should insert whitespace and line feeds to keep lines short. number_of_words must be equal to pixel_width * pixel_height.

The string should run in row-major order from the corner (x, y + real_height). Normally--that is if the real size is positive--this means that the string runs from top left to bottom right.

If mode is zero, the image is in gray levels and every pixel is specified by 8 bits (2 hexadecimal digits). If mode is one, the image is in color, and every pixel is specified by 24 bits (6 hexadecimal digits), 8 each for the red, green, and blue component.

Ipe can also read and write raw bitmaps. If the 0x08 bit of mode is set, then Ipe expects that after the % bits line the bitmap is written as raw data. If mode is 8, Ipe expects 8 bits per pixel, if mode is 9, Ipe will expect 32 bits per pixel (not 24 bits--this is the unsigned long word format used by the GL function lrectwrite).

Normally, when Ipe writes the interface file for a Ium, it will write raw bitmaps. This can be disabled using the Ium's flag. Ipe will not save bitmaps in raw format in any other circumstances.

Segments Objects

This object type is simply a compact representation of a collection of polygonal objects that all have the same color and line style. Ipe creates such objects internally as an alternative to a group of such polygonal objects (this means that you can compactify your Ipe files considerably if you group together large sets of similar polygonal objects--a typical situation for mechanically created drawings.) This object type is not written to Ium interface files, so there is no need for you to recognize it. However, you may want to produce this kind of object if you create Ipe drawings mechanically.
% Segments
% sk stroke_color
% fi fill_color
% # n
x_1 y_1 t_1
x_2 y_2 t_2
...
x_n y_n t_n
% End
Here, t_1, ..., t_n are one of the letters 'N', 'L', 'E', or 'C', and determine the connections between the specified vertices: 'N' starts a new polygonal chain, 'L' adds the vertex to the current chain, 'E' terminates an open chain, and 'C' adds the vertex and closes the chain.

Line style and non-gray color can be specified as for polygonal objects. You cannot specify arrows with this object type.


[Previous] [Up] [Next]