Compiling and Installing

Getting Started

Notice that piglet creates a graphic window. The editor is scanning both the graphic window and the original shell window that you used to start piglet. You can either type coordinates, or click them with the mouse. The shell window should have a prompt:

    MAIN>

If you are using KDE under linux, then it works best to set the text window just under the graphics window:

      -------------
      |           |
      |  graphics |
      |           |---
      -------------   |
           | >text    |
           ------------

The latest version of piglet adds shell command capability. When you type a command at the text prompt, piglet searches for an internal command of that name. If it doesn't find one to execute, then it looks through the $PATH variable to see if there is a UNIX command that can be executed. If so, it spawns a subshell and runs the UNIX command sending stdout to the terminal. This is a handy facility for running the ls command.

A few commands terminate the current action with a double click on the same coordinate. An example of this is the "ADD L<layer>" add line command. A double-click terminates the current line, but leaves you in the add line command to continue adding lines until you finally are ready to do something different.

Anything that you can type, you can also enter by clicking on the menu. Piglet's graphical language is identical to it's command line language, so you can either type "ADD R6 x1,y1 x2,y2;" or you can click the mouse on "ADD" "R" "6" and then mouse the two coordinates.

Usually, it is only necessary to type on the keyboard for entering the names of cells, and for entering TEXT and NOTE strings.

Setting the GRID

Try playing with the grid. If you type "gri 20 2;", you'll get a 20x20 grid tick with a skip of two. You'll see what I mean if you try it. You can move your mouse in the graphic area and see the xy coordinates of the mouse displaying in the upper left corner.

You can also offset the grid. Try "gri 20 2 5 5;" and notice that the origin is now at 5,5 instead of 0,0.

Finally, you can make a non-isotropic grid with something like "gri 10 20 2 4 7 7"; This form of the command sets:

   gri xspacing yspacing xskip yskip xorig yorig

When entering points with the mouse, the clicks ALWAYS snap to the grid, giving a powerful way to enter precise coordinates.

The grid also allows an option ":C{0-7}" which will set the color of the grid to any of the 8 system colors. For example: "grid :c2 10 2" creates a red grid. The colors are "white, red, green, blue, cyan, magenta, yellow".

You can also turn the grid on with "GRI ON" or off with "GRI OFF". Typing "GRI;" with no arguments toggles the grid state.

Undoing/Redoing Commands

All commands that change the drawing can be undone with the UNDO command. Any command that is UNDone can be reapplied with the REDO command. The depth of the UNDO command is limited only by the available memory. This makes it safe to explore piglet's commands. If you make a mistake, just UNDO it!

Abbreviating Commands

All the piglet built-in commands can be abbreviated to just three letters with one exception. DISPLAY must be entered as "DISP" or "disp" to distinguish it from "DIStance".

Online Help

You can get a list of all commands by typing "?" or "HELP". You can get a summary on just one command by typing "HELP {command}".

There are also UNIX style man pages in the ./man directory. If you did a "make install", these should be in your /usr/local/man/man1 directory. If this is in your MANPATH environment variable, you can type "man piglet" and get an overview of the editor. There will be a list of commands at the end of the page that can also be viewed. Each command has a separate man page so you can look at "man add_rect", "man move", "man copy", and so on.

EDIT command

Once you are happy with the grid spacing and color, try adding some primitives to the drawing. First give your drawing a name with "edi mycell".

SHOW

OVERVIEW: Before you can add anything to your drawing you need to make some of the layers modifiable. They default to "visible and locked" by default. Type "SHO #E;" and you are set to go. You'll need to do this everytime you edit a new cell.

Now the details: The show command controls what layers are visible and modifiable in the drawing. The default when starting to edit a new file is ALL layers visible and ALL layers non-modifiable. This feature makes it much safer to browse critical files with Piglet. You can't change anything unless you unlock the layers with the SHOW command. For a beginner, you can just remember to set all layers visible and modifiable with the command: "SHO #E;". The SHOW command syntax is:

SHOW {+|-|#}[EACILN0PRT]<layer>

   + : make it visible
   - : turn it off
   # : visible and modifiable

   E : everything
   A : arc
   C : circle
   I : instances
   L : lines
   N : notes
   O : oval
   P : polygons
   R : rectangles
   T : text

    SHO #E;       /* ALL layers visible and modifiable */
    SHO #E -C7;   /* ALL layers vis. and mod. except layer 7 circles */
    SHO -E #R3;   /* Nothing editable except layer 3 Rectangles */
    SHO #E7 +E5;  /* display layers 7 and 5, only 7 is modifiable */

Adding Rectangles

NOTE: Remember that you can't add anything until you type "SHO #E;" to unlock "Everything" and make the layers editable!

Now try adding a rectangle on layer 7 by typing "ADD R7" then clicking the two corners of your rectangle with your left mouse button. You can add as many rectangles as you want by continuing to click pairs. The command can be terminated with a right-click or by typing either a ";" or another command name at the keyboard. You can get different colors by adding R. The layers cycle mod(8) through the color table and then cycle through line types. For example, "ADD R15" is the same color as "ADD R7", but uses a dot-dash line type. Later on, the plan is to implement the PROCESS command which will allows you to to bind layer numbers to specific outline colors, fill patterns, fill colors and so on.

As always with piglet, you can either use the mouse to enter coordinates or the keyboard. For example, you can type:

	"ADD R22 0,0 100,121;"

to explicitly add precise coordinates without using the mouse. This is very handy when you are entering precise coordinates from a table or from calculations.

Inputting commands from a file

If you don't want to do all your typing at the prompt, you can use a program to create lines like the above, print them into a file named "./cells/foo", and then read them into your current cell using the input command: "INP foo".

Command Line Editing

Anything typed at the command line goes into a readline buffer. I have mine set up with a vi command history binding. You can change the binding by editing ~/.inputrc. My file looks like:

------------ cut here for gnu readline ~/.inputrc file ----------
set editing-mode vi
set keymap vi
------------ cut here for gnu readline ~/.inputrc file ----------

If you don't set anything, I think you get either an emacs or up-arrow, down-arrow editing mechanism.

When you use the CHAnge command on text or notes, the string of the note is put in the command buffer. You can move up with command line editing and easily modify the string.

Zooming around in the window

You can fit the window to the bounding box of the drawing by typing "WIN :F;". You can center the drawing on a particular point by typing "WIN" and then double clicking on any given point. Clicking two different points will window in on a region. You can get a zoom in or zoom out by using "WIN :X{factor}".

If you have a very complex drawing with lots of hierarchy, you can simplify things by using the ":N{nest_level}" of the WIN command. "WIN :N0" will show all sub-cells as bounding boxes. "WIN :N1" will show all sub-cells of sub-cells as bounding boxes, and so on.

Adding lines to the drawing

You can add lines with "ADD L{layer_number}". Keep clicking your coordinates with your left-mouse button. Double-clicking on the same point will terminate the line and still let you create new lines. Right-clicking or typing ";" will terminate both the line and the command. If it is a long line and you need to place the coordinates accurately, you can zoom around in the middle of the command using the mouse scroll button.

Lines can have width. Typing "ADD L7 :W20" will let you enter a line with a width of 20. The default is a width of zero.

Adding circles to the drawing

Circles are added with "ADD C{layer} :R{degrees} XY1 XY2". The ":R" option gives the resolution in degrees. This is handy for making regular polygons. For instance "ADD C7 :R72" will create a perfect pentagon. The pentagon rotates during rubberband drawing such that the second point, XY2, is always on one of the vertices. "ADD C7 :R90" is a way to add a rotated square. "ADD C7 :R120" adds an equilateral triangle. You can add ovals by using the :Y{xyratio} option to "ADD C". Try "ADD C7 :Y.3" to add an oval with a major/minor axis ratio of 0.3.

Adding polygons to the drawing

Similiar to lines. The polygons are always closed for you while you are drawing. Double clicking terminates but keeps the command active.

Adding notes and text to the drawing

You can add notes (drawn with zero width strokes) with

    ADD N{layer} :F{fontsize} "text to be displayed";

Text is drawn with polygons and can be entered with

    ADD T{layer} :F{fontsize} "text to be displayed";

The fontsize is the vertical spacing of the characters that will produce single-spaced lines of text. So, a fontsize of :F20 will produce a capital letter with a height of 15 units.

Other options are

    ":M{x|y|xy}"     mirror the text around x,y, or both xy axes
    ":R{angle}"      rotate text by {angle} in degrees
    ":Y{yxratio}"    set y to x ratio to make skinny or fat letters
    ":Z{slant}"      create italics by slanting the text by {slant} degrees

These fonts are defined in NOTEDATA.F and TEXTDATA.F and are easily changed. I have quite a few fonts that are derived from the Hershey font database. The format is pretty simple and is documented in readfont.c.

Adding Instances (subcells)

You can save your drawing with the "SAVE;" command. You can then "EXIT;" and you are ready to "EDI" a new drawing. This is the fun part of piglet. Try doing "EDI newdrawing" and adding a copy of our previous drawing as a sub-cell. Doing "ADD mycell" lets you click to add copies of your previous drawing "mycell" to "newdrawing". You can use options to add copies with scaling, rotation, etc:

    ":M{x|y|xy}"     mirror the text around x,y, or both xy axes
    ":R{angle}"      rotate text by {angle} in degrees
    ":X{factor}"     scale instance by {factor}
    ":Y{yxratio}"    set y to x ratio to make skinny or fat letters
    ":Z{slant}"      create italics by slanting the text by {slant} degrees

This nesting can be arbitrarily deep. You can "SAVE newdrawing" and then "EDI biggerdrawing" and add copies of both "newdrawing" and "mydrawing" into "biggerdrawing".

Also, the subcells are live. This means that if you finish with a drawing using sub-drawings of slotted screws, you can change them all to philips-style screws by simply editing the original definition. It will change in all the drawings that have called the cell, no matter how complex the nesting or the transformations applied.

Wrapping Instances

Smashing Instances

Stretching Instances

Changing Instances

Identify components

Find the coordinates of a point

Saving your work

When you "SAV" a cell it creates a text file in ./cells/CELLNAME.d The file is human readable and is a nicely formatted transcript of the exact commands that you typed and moused to create the cell in the first place. You can edit this file (carefully) and the textual changes will take effect next time you start a new piglet and read in the definition. The "CELLNAME.d" file only contains the definition of the cell CELLNAME. If CELLNAME includes other cells, they will only be called by name and not defined. In other words, if you mail a friend a ".d" file, they will be unable to reconstruct your cell if it has any hierarchy. If you want a full definition of your work, then you should use the "ARCHIVE" command.

Archive your work

When you "ARC" a cell it creates a text file in ./cells/CELLNAME_I which contains a full hierarchical description of CELLNAME including all sub-cells. The "_I" archive file is constructed to have no forward references and includes PURGE commands to delete any previously defined cells before redefining them.

Purging old versions of your work

If you want to use textual processing to change a cell that's already been read into memory, you can "PURGE cellname", and then re-edit it. The second edit will re-read the disk definition including any changes that have been added. If you type PURGE interactively, rather than input it from a file, you will be asked permission to delete the memory copy, and then any disk copies of the cell.

Demo files

There are several big drawings in the cells directory. You can take a look at these to see how piglet handles thousands of polygons.

Try: 

    "EDI CDRCFR"   a hybrid substrate for a 2.488 GHz phase locked loop
    "EDI tone"     a schematic for a PBX dial tone generator
    "EDI fontest"  an example of all the characters in note and text fonts
    "EDI H20919M1" a 24x36 inch 6-layer Printed Circuit Board design
    "EDI testpen"  a sample of all the line types
    "EDI PLAN2"    the floor plans of the two houses on my lot 
    "EDI slic"     a telephone subscriber line interface circui
    "EDI pict3"    a 3-D drawing of a high-speed test fixture
    "EDI RTILE"    a GAAS delay line integrated circuit layout 
    "EDI RINGOSC"  the layout for the first 3/5 ring oscillator

You can look at the CELL.d files to see the top level definitions or you can look at the CELL_I file to see the full hierarchical archive which includes all the sub-cell definitions. The archive file is fully self-contained and is suitable for e-mailing a complete design to another person.

Graphical Screen Dump

The DUMP command creates a Portable Pix Map copy of the current graphic window in the file "./device_name.ppm". You can view/print/convert this with xv(1), or convert it to gif format with ppmtogif(1) from the pbmtools package.

Vector Plot

The PLOT command creates a postscript dump of the current device in the file "./device_name.ps. The file is suitable for printing on letter sized paper, and will automatically fit the drawing to either landscape or portrait depending on the shape of the drawing.

Identify command

The IDEntify command takes a series of xy points and for each point highlights the nearest primitive and prints some information about it to the screen.

Point command

The POInt command takes a series of xy points and simply prints their coordinates to the screen. No change is made to the database. You might also notice that Piglet constantly updates a textual version of your current mouse coordinates in the upper left hand corner of the graphical window.

TODO list

There are data structures and stubs for OVALS and ARCS. These and others should be an easy project. I would like to make an option for lines to do parametric spline curves.

Support for isometric grids would be nice.

MACROS

The original piglet had macros and command line math evaluation so you could define more complex functions and type things like:

    ADD R7 0,0 (35/2),(100+5*sqrt(2));

for computing precise coordinates on the fly. The implementation is simple. The parser looks for parenthetic expressions and passes them to an evaluation engine. The result is put back on the token stack as a simple numeric value.

REVISION CONTROL

It would be easy to have every SAVE do a "ci -l" on the cell, thereby keeping revision control on every cell.

I'm thinking of allowing the user to create variables that are stored with the cell. They could look like:

$$F: "some text keyed to F" $$
$$H: "some text keyed to H" $$

The user could then add text to the drawing referencing these variables with something like:

	ADD T7 :F20 $F;

If one of the variables has the $Id keyword in it, then RCS will substitute that keyword dynamically with the version number at each checkin. This makes it trivial to put a text block in the lower left corner of your drawing that is always lists the latest rev number for the drawing. You could also define variables that would make the cell automatically upgrade to the latest available version, or insist that the version be frozen at particular rev number.

LEARN MORE