Work Sheet File Format

Introduction

This documents the s-expression work sheet file format for all versions of KiCad from 6.0. Work sheet files are used to change the default border and title block for schematics and boards.

  • Work sheet files use the .kicad_wks extension.

Work Sheet Coordinates

  • The minimum internal unit for work sheet files is 1 micrometer so there is maximum resolution of three decimal places or 0.001 mm. Any precision beyond three places will be truncated.

Object Incrementing

All graphical objects can be drawn multiple times with a given repeat count and X and/or Y incremental distances. The direction of the increment is controlled by defining a start corner and/or end corner depending on the graphical object type. The table below defines the corner tokens and their meaning.

Token Description

ltcorner

Top left corner of the start or end point.

lbcorner

Bottom left corner of the start or end point.

rbcorner

Bottom right corner of the start or end point.

rtcorner

Top right corner of the start or end point.

Layout

A work sheet file includes the following sections:

Header Section

The kicad_wks token indicates that it is KiCad work sheet file. This section is required.

Third party scripts should not use pl_editor as the generator identifier. Please use some other identifier so that bugs introduced by third party generators are not confused with a work sheet file created by KiCad. 
(kicad_wks
  (version VERSION)                                             (1)
  (generator GENERATOR)                                         (2)

  ;; contents of the schematic file...                          (3)
)
1 The version token attribute defines the work sheet version using the YYYYMMDD date format.
2 The generator token attribute defines the program used to write the file.
3 The work sheet sections go here.

Set Up Section

The setup token defines the configuration information for the work sheet.

  (setup
    (textsize WIDTH HEIGHT)                                     (1)
    (linewidth WIDTH)                                           (2)
    (textlinewidth WIDTH)                                       (3)
    (left_margin DISTANCE)                                      (4)
    (right_margin DISTANCE)                                     (5)
    (top_margin DISTANCE)                                       (6)
    (bottom_margin DISTANCE)                                    (7)
  )
1 The textsize token attributes define the default WIDTH and HEIGHT of text.
2 The linewidth token attribute defines the default WIDTH of lines.
3 The textlinewidth token attribute define the default WIDTH of the lines used to draw text.
4 The left_margin token attributed defines the DISTANCE from the left edge of the page.
5 The right_margin token attributed defines the DISTANCE from the right edge of the page.
6 The top_margin token attributed defines the DISTANCE from the top edge of the page.
7 The bottom_margin token attributed defines the DISTANCE from the bottom edge of the page.

Drawing Object Section

The drawing object section can contain zero or more title block text, graphical line, graphical rectangle, graphical polygon, or image. The objects are ordered as they are added to the work sheet.

Title Block Text

The tbtext token attributes define text used in the title block of a work sheet.

  (tbtext
    "TEXT"                                                      (1)
    (name "NAME")                                               (2)
    (pos X Y [CORNER])                                          (3)
    (font [(size WIDTH HEIGHT)] [bold] [italic])                (4)
    [(repeat COUNT)]                                            (5)
    [(incrx DISTANCE)]                                          (6)
    [(incry DISTANCE)]                                          (7)
    [(comment "COMMENT")]                                       (8)
  )
1 The tbtext token attribute defines the TEXT string.
2 The name token attribute defines the NAME of the text object.
3 The pos token attributes define the X and Y coordinates the text. The optional CORNER attribute is used to define the initial corner for repeating incremental text.
4 The font token attributes define how the text is drawn. The optional size token attributes define the size of the font used to draw the text. If not defined, the default text size defined in the set up section is used. The optional bold token indicates the text be drawn with a bold font. The optional italic token indicates the text be drawn italicized.
5 The optional repeat token attribute defines the COUNT for repeated incremental text.
6 The optional incrx token attribute defines the repeat DISTANCE on the X axis.
7 The optional incry token attribute defines the repeat DISTANCE on the Y axis.
8 The optional comment token attribute is a comment for the text object.

Graphical Line

The line token attributes define how a line is drawn in the work sheet.

  (line
    (name "NAME")                                               (1)
    (start X Y [CORNER])                                        (2)
    (end X Y [CORNER])                                          (3)
    [(repeat COUNT)]                                            (4)
    [(incrx DISTANCE)]                                          (5)
    [(incry DISTANCE)]                                          (6)
    [(comment "COMMENT")]                                       (7)
  )
1 The name token attribute defines the NAME of the line object.
2 The start token attributes define the X and Y coordinates of the start point of the line. The optional CORNER attribute defines the initial corner for repeating incremental lines.
3 The end token attributes define the X and Y coordinates of the end point of the line. The optional CORNER attribute defines the end corner for repeating incremental lines.
4 The optional repeat token attribute defines the COUNT for repeated incremental lines.
5 The optional incrx token attribute defines the repeat DISTANCE on the X axis.
6 The optional incry token attribute defines the repeat DISTANCE on the Y axis.
7 The optional comment token attribute is a comment for the line object.

Graphical Rectangle

The rect token attributes define how a rectangle is drawn in the work sheet.

  (rect
    (name "NAME")                                               (1)
    (start X Y [CORNER])                                        (2)
    (end X Y [CORNER])                                          (3)
    [(repeat COUNT)]                                            (4)
    [(incrx DISTANCE)]                                          (5)
    [(incry DISTANCE)]                                          (6)
    [(comment "COMMENT")]                                       (7)
  )
1 The name token attribute defines the NAME of the rectangle object.
2 The start token attributes define the X and Y coordinates of the start point of the rectangle. The optional CORNER attribute defines the initial corner for repeating incremental rectangles.
3 The end token attributes define the X and Y coordinates of the end point of the rectangle. The optional CORNER attribute defines the end corner for repeating incremental rectangles.
4 The optional repeat token attribute defines the COUNT for repeated incremental rectangles.
5 The optional incrx token attribute defines the repeat DISTANCE on the X axis.
6 The optional incry token attribute defines the repeat DISTANCE on the Y axis.
7 The optional comment token attribute is a comment for the rectangle object.

Graphical Polygon

The polygon token defines a graphical polygon. This section will not exist if there are no polygons in the work sheet.

  (polygon
    (name "NAME")                                               (1)
    (pos X Y [CORNER])                                          (2)
    [(rotate ANGLE)]                                            (3)
    [(linewidth WIDTH)]                                         (4)
    COORDINATE_POINT_LIST                                       (5)
    [(repeat COUNT)]                                            (6)
    [(incrx DISTANCE)]                                          (7)
    [(incry DISTANCE)]                                          (8)
    [(comment "COMMENT")]                                       (9)
  )
1 The name token attribute defines the NAME of the polygon object.
2 The pos token attributes define the X and Y coordinates the text. The optional CORNER attribute is used to define the initial corner for repeating incremental polygons.
3 The optional rotate token attribute defines the rotation angle of the polygon object.
4 The optional linewidth token attribute defines the width of all of the polygons. If not defined, the default line width in the set up section is used.
5 The COORDINATE_POINT_LIST defines the list of X/Y coordinates of to draw line(s) between. A minimum of two points is required.
6 The optional repeat token attribute defines the COUNT for repeated incremental polygons.
7 The optional incrx token attribute defines the repeat DISTANCE on the X axis.
8 The optional incry token attribute defines the repeat DISTANCE on the Y axis.
9 The optional comment token attribute is a comment for the polygon object.

Image

The image token defines one or more embedded images. This section will not exist if no images are in the work sheet.

  (bitmap
    (name "NAME")                                               (1)
    (pos X Y )                                                  (2)
    (scale SCALAR)                                              (3)
    [(repeat COUNT)]                                            (4)
    [(incrx DISTANCE)]                                          (5)
    [(incry DISTANCE)]                                          (6)
    [(comment "COMMENT")]                                       (7)
    (pngdata IMAGE_DATA)                                        (8)
  )
1 The name toke attribute defines the NAME of the image.
2 The pos token attributes define the X and Y coordinates of the image. The optional CORNER attribute defines the start corner for repeating incremental images.
3 The scale token attribute defines the SCALE_FACTOR of the image.
4 The optional repeat token attribute defines the COUNT for repeated incremental image.
5 The optional incrx token attribute defines the repeat DISTANCE on the X axis.
6 The optional incry token attribute defines the repeat DISTANCE on the Y axis.
7 The optional comment token attribute is a comment for the image object.
8 The pngdata token attribute defines the IMAGE_DATA in the portable network graphics format (PNG).

Image Data

The data token defines the raw image data.

  (data XX1 ... XXN )                                           (1)
  ...
1 The data token attributes define the hexadecimal byte data separated by a space. A maximum of 32 bytes will be defined for each data token. The data tokens are defined until all of the image data is defined.