Piglet FAQ

This section is designed to be read through sequentially as an overall tutorial to Piglet's operation. However, you can also use this index to jump to any section that you need a refresher on.

How do I...
  • Compile and install?
  • Get Started?
  • Set the Grid?
  • How do I UNDO a command?
  • Abbreviate command names?
  • Get a help reminder of command functions?
  • Edit a cell?
  • Set which layers are visible?
  • Add a rectangle to my drawing?
  • Input commands from a file?
  • Do command line editing?
  • Adjust the window view?
  • Zoom in and out of my drawing?
  • Add lines to my drawing?
  • Add a circle to my drawing?
  • Add a polygon to my drawing?
  • Add a note or text to my drawing?
  • Add a sub-cell or instance to my drawing?
  • wrap some cells into a sub-cell?
  • smash a sub-cell into it's components?
  • stretch a component after I've drawn it?
  • change things like line width, font size, etc.k?
  • Identify a component on the screen?
  • Find the location of a point on the screen?
  • Save my work?
  • Archive my work?
  • Delete old versions of my work?
  • Look at some demonstration drawings?
  • Get a screendump (GIF file) of my drawing?
  • Get a vector plot of my file?
  • Find the name of an instance on the screen?
  • Get the exact location of a point on the screen?
  • Find something useful to work on for Piglet?
  • Compiling and Installing

    Just type "make" and you should have a working piglet. You can play with it in the src directory until you decide you like it. Then you can run "make install" with sufficient priviledges to create and write in /usr/local/bin and /usr/local/man/man1.

    Getting Started

    Here are some things to try. Firstly, the drawings that you create will all be in the sub-directory ./cells. Later on, I plan to implement a search path for drawings.

    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:

    There are also UNIX style man pages in the ./web/man1p 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. All commands in piglet are terminated either with another command, or with a right mouse click, or with an ";" character. If you don't terminate a command with a ";" or right-button, you can usually keep using it over again to make multiple MOVes or COPys. Once you terminate a command, you have to type another command to start working again.

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

          |           |
          |  graphics |
          |           |---
          -------------   |
               | >text    |
    and set your mouse focus preference to "Focus follows mouse". That way you can use either typing or mouse clicking to enter coordinates.

    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".


    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>
    You can control visibility and modifiability with the following characters:
       + : make it visible
       - : turn it off
       # : visible and modifiable
    You control which kinds of components you are working with by the following component designators:
       E : everything
       A : arc
       C : circle
       I : instances
       L : lines
       N : notes
       O : oval
       P : polygons
       R : rectangles
       T : text
    The <layer> is either specific layer number, or if omitted, will control all layers. Some examples:
        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.

    Piglet allows zooming at all times with the mouse scroll button. It will zoom in/out of the current mouse location on the screen. If you scroll out from one location and then in from another, you can effectively pan the window from one location to another. This feature even works while in the middle of adding long and complicated components, such as a line.

    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

    You can wrap up any number of primitives by drawing a box around them with the WRAP command. These components are then "pushed" down one level of the drawing and named something like "NO_NAMExxx". This new block can be moved, copied, scaled, mirrored and rotated. You can also give the block a new name and save it as a cell. If you don't give the WRAPped block a new name it will be automatically dismember (SMAshed) when you finally exit the edi.

    Smashing Instances

    Any cell that you add to the drawing can be SMAshed. This will un-bundle all the components in the sub-cell and add them directly to the current drawing at the top level of hierarchy. Be careful with this command as it can easily create an unmanageably huge number of components.

    Stretching Instances

    An invaluable editing tool. You can click on any vertex of a component and pull it to a new position. You can also use the :R option to draw a box around any number of vertices and pull them all together to an new position. Lines and polygons will simply stretch to accomodate.

    Changing Instances

    If you click on any component using the CHA command, you may then enter any option such as :L<layer>, :F<fontsize>, :M<mirror_type>, :R<rotation> and the new option will be applied to the selected component. You can also click on text or notes and then enter a new string to replace the current value. Command line editing is in effect. If you have your .inputrc file set up for vi command editing, then you can type CHA, then click on a text or note, and use <esc>-k to pull up the old string definition. You can then edit the string using ksh-like commands. Use <enter> to replace the old text with the new string.

    Identify components

    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.

    Find the coordinates of a point

    The POInt command takes a series of xy points and simply prints their coordinates to the screen. No change is made to the database.

    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.

        "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.


    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.


    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.


    Make sure and read the man pages for each command to discover more options. Please write if you have any questions or suggestions.