gEDA/gaf File Format Document

by: Ales V. Hvezda, ahvezda@geda.seul.org

This document is released under GFDL

December 31st, 2003

Overview

This file is the official documentation for the file formats in gEDA/gaf (gschem And Friends). The primary file format used in gEDA/gaf is the schematic/symbol format. Files which end with .sch or .sym are schematics or symbol files. Until there is another file type in gEDA/gaf, then this document will only cover the symbol/schematic file format.
This file format document is current as of gEDA/gaf version 20040111. This document covers file format version 1 and 2.
Note, this file format and any other file formats associated with gEDA are placed under the General Public License (GPL) version 2.0. The gEDA/gaf symbol and schematic file format is Copyright (C) 1998-2004 Ales Hvezda.

Coordinate Space

All coordinates are in mils (1/1000 of an inch). This is an arbitrary decision. Remember in there is no concept of physical lengths/dimensions in schematics and symbols (for schematic capture only).

The following figure shows how the coordinate space is setup:

:geda:coordinatespace.jpg

X axis increases going to the right. Y axis increase going up. Coordinate system is landscape and corresponds to a sheet of paper turned on its side.

Filenames

Symbols end in .sym. The only symbol filename convention that is used in gEDA/gaf is that if there are multiple instances of a symbol with the same name (like a 7400), then a -1, -2, -3, … -N suffix is added to the end of the filename. Example: 7400-1.sym, 7400-2.sym, 7400-3.sym…
Schematics end in .sch. There used to be a schematic filename convention (adding a -1 .. -N to the end of the basename), but this convention is now obsolete. Schematic filenames can be anything that makes sense to the creator.

Object types

A schematic/symbol file for gEDA/gaf consists of:

The “object type” id is a single letter and this id must start in the first column. The object type id is case sensitive.
The schematic and symbol files share the same file layout. A symbol is nothing more than a collection of primitive objects (lines, boxes, circles, arcs, text, and pins). A schematic is a collection of symbols (components), nets, and buses.
The following sections describe the specifics of each recognized object type. Each section has the name of the object, which file type (sch/sym) the object can appear in, the format of the data, a description of each individual field, details and caveats of the fields, and finally an example with description.
For information on the color index (which is used in practically all objects), see the Color section.

version

Valid in: Schematic and Symbol files
type version fileformat_version

Pos.FieldType/unitDescription
# typecharv
1 versionintversion of gEDA/gaf that wrote this file
2 fileformat_versionintgEDA/gaf file format version number

Example:

v 20040111 1

line

Valid in: Schematic and Symbol files
type x1 y1 x2 y2 color width capstyle dashstyle dashlength dashspace

Pos.FieldType/unitDescription
# typecharL
1 x1int/milsFirst X coordinate
2 y1int/milsFirst Y coordinate
3 x2int/milsSecond X coordinate
4 y2int/milsSecond Y coordinate
5 colorintColor index
6 widthint/milsWidth of line
7 capstyleintLine cap style
8 dashstyleintType of dash style
9 dashlengthint/milsLength of dash
10 dashspaceint/milsSpace inbetween dashes

Example:

L 23000 69000 28000 69000 3 40 0 1 -1 75

A line segment from (23000, 69000) to (28000, 69000) with color index 3, 40 mils thick, no cap, dotted line style, and with a spacing of 75 mils in between each dot.

picture

Valid in: Schematic and Symbol files
type x1 y1 width height angle mirrored embedded
filename
[encoded picture data
encoded picture end]

Pos.FieldType/unitDescription
# typecharG
1 xint/milsLower left X coordinate
2 yint/milsLower left Y coordinate
3 widthint/milsWidth of the picture
4 heightint/milsHeight of the picture
5 angleint/degreesAngle of the picture
6 mirroredcharMirrored or normal picture
7 embeddedcharEmbedded or link to the picture file
8 filenamestringpath and filename of a not embedded picture
9 encoded picture datastringSerialized picture encoded using base64
10 encoded picture endstringA line containing only a dot character

Example 1:

G 16900 35800 1400 2175 0 0 0
../bitmaps/logo.jpg

A picture object with the lower left corner at (16900, 35800). The width of the image is 1400 mils, and its height is 2175 mils. The picture rotation is 0 degrees and the picture is not mirrored, neither embedded.
The picture path and filename is showed in the second line.

Example 2:

G 16900 35800 1400 2175 0 0 1
../bitmaps/logo.jpg
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
.

A picture object with the lower left corner at (16900, 35800). The width of the image is 1400 mils, and its height is 2175 mils.
The picture rotation is 0 degrees, it is not mirrored, and it is embedded.
The picture path and filename is showed in the second line. Since this is an embedded picture, the filename and path are not used.
The encoded picture data is only an example (it is not real data). The last line containing a single dot '.' character marks the end of the encoded picture data.

box

Valid in: Schematic and Symbol files
type x y width height color width capstyle dashstyle dashlength dashspace filltype fillwidth angle1 pitch1 angle2 pitch2

Pos.FieldType/unitDescription
# typecharB
1 xint/milsLower left hand X coordinate
2 yint/milsLower left hand Y coordinate
3 widthint/milsWidth of the box (x direction)
4 heightint/milsHeight of the box (y direction)
5 colorintColor index
6 widthint/milsWidth of lines
7 capstyleint/milsLine cap style
8 dashstyleintType of dash style
9 dashlengthint/milsLength of dash
10 dashspaceint/milsSpace inbetween dashes
11 filltypeintType of fill
12 fillwidthint/milsWidth of the fill lines
13 angle1int/degreesFirst angle of fill
14 pitch1int/milsFirst pitch/spacing of fill
15 angle2int/degreesSecond angle of fill
16 pitch2int/milsSecond pitch/spacing of fill

Example:

B 33000 67300 2000 2000 3 60 0 2 75 50 0 -1 -1 -1 -1 -1

A box with the lower left hand corner at (33000, 67300) and a width and height of (2000, 2000), color index 3, line width of 60 mils, no cap, dashed line type, dash length of 75 mils, dash spacing of 50 mils, no fill, rest parameters unset.

circle

Valid in: Schematic and Symbol files
type x y radius color width capstyle dashstyle dashlength dashspace filltype fillwidth angle1 pitch1 angle2 pitch2

Pos.FieldType/unitDescription
# typecharV
1 xint/milsCenter X coordinate
2 yint/milsCenter Y coordinate
3 radiusint/milsRadius of the circle
4 colorintColor index
5 widthint/milsWidth of circle line
6 capstyleint/mils0 unused
7 dashstyleintType of dash style
8 dashlengthint/milsLength of dash
9 dashspaceint/milsSpace inbetween dashes
10 filltypeintType of fill
11 fillwidthint/milsWidth of the fill lines
12 angle1int/degreesFirst angle of fill
13 pitch1int/milsFirst pitch/spacing of fill
14 angle2int/degreesSecond angle of fill
15 pitch2int/milsSecond pitch/spacing of fill

Example:

V 38000 67000 900 3 0 0 2 75 50 2 10 20 30 90 50

A circle with the center at (38000, 67000) and a radius of 900 mils, color index 3, line width of 0 mils (smallest size), no cap, dashed line type, dash length of 75 mils, dash spacing of 50 mils, mesh fill, 10 mils thick mesh lines, first mesh line: 20 degrees, with a spacing of 30 mils, second mesh line: 90 degrees, with a spacing of 50 mils.

arc

Valid in: Schematic and Symbol files
type x y radius startangle sweepangle color width capstyle dashstyle dashlength dashspace

Pos.FieldType/unitDescription
# typecharA
1 xint/milsCenter X coordinate
2 yint/milsCenter Y coordinate
3 radiusint/milsRadius of the arc
4 startangleint/degreesStarting angle of the arc
5 sweepangleint/degreesAmount the arc sweeps
6 colorintColor index
7 widthint/milsWidth of circle line
8 capstyleintCap style
9 dashstyleintType of dash style
10 dashlengthint/milsLength of dash
11 dashspaceint/milsSpace inbetween dashes

Example:

A 30600 75000 2000 0 45 3 0 0 3 75 50

An arc with the center at (30600, 75000) and a radius of 2000 mils, a starting angle of 0, sweeping 45 degrees, color index 3, line width of 0 mils (smallest size), no cap, center line type, dash length of 75 mils, dash spacing of 50 mils.

text and attributes

Depending on context, text objects can play different roles. Outside any environment, they represent informative lines of text. When enclosed by curly braces, they are interpreted as attributes. See the attributes section.

Valid in: Schematic and Symbol files
type x y color size visibility show_name_value angle alignment num_lines
string line 1
string line 2
string line 3

string line N

Pos.FieldType/unitDescription
# typecharT
1 xint/milsFirst X coordinate
2 yint/milsFirst Y coordinate
3 colorintColor index
4 sizeint/pointsSize of text
5 visibilityintVisibility of text
6 show_name_valueintAttribute visibility control
7 angleint/degreesAngle of the text
8 alignmentintAlignment/origin of the text
9 num_linesintNumber of lines of text (1 based)
10 string line 1 … NstringThe text strings, on a separate line

fileformat_textgraphic.jpg

Example 1:

T 16900 35800 3 10 1 0 0 0 1
Text string!

A text object with the origin at (16900, 35800), color index 3, 10 points in size, visible, attribute flags not valid (not an attribute), origin at lower left, not rotated, string: Text string!

Example 2:

T 16900 35800 3 10 1 0 0 0 5
Text string line 1
Text string line 2
Text string line 3
Text string line 4
Text string line 5

This is a similar text object as the above example, however here there are five lines of text.

Example 3:

T 10000 20000 3 10 1 1 8 90 1
pinlabel=R/\_W\_

A text object with the origin at (10000, 20000), color index 3, 10 points in size, visible, only the value of the attribute is visible, text origin at upper right, the text is rotated by 90 degree, the string: “R/W” has an overbar over the “W”.

net

Valid in: Schematic files ONLY
type x1 y1 x2 y2 color

Pos.FieldType/unitDescription
# typecharN
1 x1int/milsFirst X coordinate
2 y1int/milsFirst Y coordinate
3 x2int/milsSecond X coordinate
4 y2int/milsSecond Y coordinate
5 colorintColor index

Example:

N 12700 29400 32900 29400 4

A net segment from (12700, 29400) to (32900, 29400) with color index 4.

bus

Valid in: Schematic files ONLY
type x1 y1 x2 y2 color ripperdir

Pos.FieldType/unitDescription
# typecharU
1 x1int/milsFirst X coordinate
2 y1int/milsFirst Y coordinate
3 x2int/milsSecond X coordinate
4 y2int/milsSecond Y coordinate
5 colorintColor index
6 ripperdirintDirection of bus rippers

Example:

U 27300 37400 27300 35300 3 0

A bus segment from (27300, 37400) to (27300, 35300) with color index 3 and no nets have been connected to this bus segment.

pin

Valid in: Symbol files ONLY
type x1 y1 x2 y2 color pintype whichend

Pos.FieldType/unitDescription
# typecharP
1 x1int/milsFirst X coordinate
2 y1int/milsFirst Y coordinate
3 x2int/milsSecond X coordinate
4 y2int/milsSecond Y coordinate
5 colorintColor index
6 pintypeintType of pin
7 whichendintSpecifies the active end

Example:

P 0 200 200 200 1 0 0

A pin from (0, 200) to (200, 200) with color index 1, a regular pin, and the first point being the active connection end.

component

Valid in: Schematic files ONLY
type x y selectable angle mirror basename

Pos.FieldType/unitDescription
# typecharC
1 xint/milsOrigin X coordinate
2 yint/milsOrigin Y coordinate
3 selectableintSelectable flag
4 angleint/degreesAngle of the component
5 mirrorintMirror around Y axis
6 basenamestringThe filename of the component

Example:

C 18600 19900 1 0 0 7400-1.sym

A component who's origin is at (18600,19900), is selectable, not rotated, not mirrored, and the basename of the component is 7400-1.sym.

path

Valid in: Schematic and Symbol files
Valid since: Fileformat version 2 (release 1.5.1)
type color width capstyle dashstyle dashlength dashspace filltype fillwidth angle1 pitch1 angle2 pitch2 numlines
path data line 1
path data line 2
path data line 3

path data line N

Pos.FieldType/unitDescription
# typecharH
1 colorintColor index
2 widthint/milsWidth of line
3 capstyleintLine cap style
4 dashstyleintType of dash style
5 dashlengthint/milsLength of dash
6 dashspaceint/milsSpace inbetween dashes
7 filltypeintType of fill
8 fillwidthint/milsWidth of the fill lines
9 angle1int/degreesFirst angle of fill
10 pitch1int/milsFirst pitch/spacing of fill
11 angle2int/degreesSecond angle of fill
12 pitch2int/milsSecond pitch/spacing of fill
13 num_linesintNumber of lines of path data (1 based)
14 path data line 1 … Npath dataThe path data, on separate lines

Example:

H 3 10 0 0 -1 -1 0 -1 -1 -1 -1 -1 5
M 410,240
L 501,200
L 455,295
L 435,265
z

A path starting at (410,240) with lines drawn from there, and joining points (501,200), (455,295), (435,265), closing back to its origin. It has color index 3, is 10 mils thick, no cap, solid style. There are 5 lines of path data.

font

Valid in: Special font files ONLY
type character width flag

Pos.FieldType/unitDescription
# typecharF
1 charactercharThe character being defined
2 widthint/milsWidth of the character (mils)
3 flagintSpecial space flag

Example:

F 11 1

The above font definition is for the space character.

Colors

In the gEDA/gaf schematic and symbol file format colors are specified via an integer index. The relationship between integer and color is based on object type. Each object type typically has one or more colors. Here is a table of color index to object type:

IndexObject type
0BACKGROUND_COLOR
1PIN_COLOR
2NET_ENDPOINT_COLOR
3GRAPHIC_COLOR
4NET_COLOR
5ATTRIBUTE_COLOR
6LOGIC_BUBBLE_COLOR
7DOTS_GRID_COLOR
8DETACHED_ATTRIBUTE_COLOR
9TEXT_COLOR
10BUS_COLOR
11SELECT_COLOR
12BOUNDINGBOX_COLOR
13ZOOM_BOX_COLOR
14STROKE_COLOR
15LOCK_COLOR
16OUTPUT_BACKGROUND_COLOR
17FREESTYLE1_COLOR
18FREESTYLE2_COLOR
19FREESTYLE3_COLOR
20FREESTYLE4_COLOR
21JUNCTION_COLOR
22MESH_GRID_MAJOR_COLOR
23MESH_GRID_MINOR_COLOR

The actual color associated with the color index is defined on a per tool bases. Objects are typically assigned their corresponding color index, but it is permissible (sometimes) to assign other color index values to different object types.

Attributes

Attributes are enclosed in braces {} and can only be text. Attributes are text items which take on the form name=value. If it doesn't have name=value, it's not an attribute. Attributes are attached to the previous object. Here's an example:

P 988 500 1300 500 1
{
T 1000 570 5 8 1 1 0
pinseq=3
T 1000 550 5 8 1 1 0
pinnumber=3
}

The object is a pin which has an attribute pinnumber=3 and pinseq=3 (name=value). You can have multiple text objects (both the T … and text string are required) in between the braces {}. As of 20021103, you can only attached text items as attributes. Attaching other object types as attributes is unsupported.
You can also have “toplevel” attributes. These attributes are not attached to any object, but instead are just text objects that take on the form name=value.
These attributes are useful when you need to convey some info about a schematic page or symbol and need the netlister to have access to this info.

Embedded Components

Embedded components are components which have all of their definition stored within the schematic file. When a users place a component onto a schematic page, they have the option of making the component embedded. Other than storing all the symbol information inside of the schematic, an embedded component is just any other component. Embedded components are defined as:

C 18600 21500 1 0 0 EMBEDDED555-1.sym
[
...
... Embedded primitive objects
...
]

In the example above, 555-1.sym is the component. The EMBEDDED tag and the [ ] are the distinguishing characteristics of embedded components. componentname.sym must exist in one of the specified component-libraries if you want to unembed the component.

Path data

The gEDA/gaf path data format has been deliberately specified to match a subset of that in the W3C SVG standard..

CommandNameParametersDescription
M (absolute)moveto(x,y)+Start a new sub-path at the given (x,y) coordinate. M (uppercase) indicates that absolute coordinates will follow; m (lowercase) indicates that relative coordinates will follow. If a relative moveto (m) appears as the first element of the path, then it is treated as a pair of absolute coordinates. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands.
L (absolute)lineto(x,y)+Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. L (uppercase) indicates that absolute coordinates will follow; l (lowercase) indicates that relative coordinates will follow. A number of coordinates pairs may be specified to draw a polyline. At the end of the command, the new current point is set to the final set of coordinates provided.
C (absolute)curveto(x1,y1 x2,y2 x,y)+Draws a cubic Bézier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. C (uppercase) indicates that absolute coordinates will follow; c (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.
Z or zclosepath(none)Close the current subpath by drawing a straight line from the current point to current subpath's initial point.

As example, lets draw the outline of an AND gate. The path data is:

M 100,100 L 500,100 C 700,100 800,275 800,400
C 800,525 700,700 500,700 L 100,700 z

And a complete schematic:

v 20080706 1
H 3 0 0 0 -1 -1 0 2 20 100 -1 -1 6
M 100,100
L 500,100
C 700,100 800,275 800,400
C 800,525 700,700 500,700
L 100,700
z

The resulting path (with control points drawn on to illustrate their positions) is shown here:

Document Revision History

November 30th, 2002Created fleformats.tex from fleformats.html.
December 1st, 2002Continued work on this document.
October 4th, 2003Added new file format version flag info.
October 19th, 2003Added num lines text field.
November 2nd, 2008Added path object, bumping file format version to 2
May 26th, 2011Added a column for the position of parameters in the tables