Engineering Sketch Pad (ESP) Version 1.02

Authors: John F. Dannenhoffer, III (Syracuse University) and Bob Haimes (MIT)

Date: May, 2013.

0.0 Table of Contents

1.0 Overview

2.0 Tutorial

3.0 Command Line

4.0 Interactive Options

5.0 Format of the .csm File

6.0 Example .csm File

7.0 Error Codes

8.0 Bug Reports and Other Feedback

9.0 Copyright

10.0 Glossary

1.0: Overview

The Engineering Sketch Pad (ESP) is a browser-based program for creating, editing, and generating constructive solid models for use in the multi-disciplinary analysis and optimization of engineered systems. ESP can use either the EGADS/OpenCASCADE or CAPRI geometric modeler.

In most cases, a user will start with a configuration that is described in a .csm file and then modify it and/or build it via OpenCSM's various commands.

Table of Contents

2.0: Tutorial

This Tutorial will help you understand the use of serveCSM and ESP for a variety of tasks. Details about the Command Line, cursor and keyboard options, and the .csm file are contained in sections that follow this Tutorial.

The Tutorial starts with a pre-made part that is defined by the file tutorial.csm. (See "Example .csm file" below for a listing of this file.)

To start ESP there are two steps: (1) start the "server" and (2) start the "browser". This can be done in a variety of ways, but the two most common follow.

Technique 1: issue the two commands:

        setenv WV_START "open -a /Applications/Firefox.app ../ESP/ESP.html"
        serveCSM ../data/tutorial
      
if using a c-shell; make appropriate changes for your shell and/or operating system.

The first of these tells serveCSM to open FireFox on the file ../ESP/ESP.html when serveCSM has generated a graphical representation of the configuration. The second of these actually starts the serveCSM server. As long as the browser stays connected to serveCSM, serveCSM will stay alive and handle requests sent to it from the browser. Once the last browser that is connected to serveCSM exits, serveCSM will shut down.

Technique 2: issue the command:

        serveCSM ../data/tutorial
      
Once the server starts, start a browser (for example, FireFox or GoogleChrome) and open the page ESP/ESP.html. As above, serveCSM will stay alive as long as there is a browser attached to it.

Note that the default "port" used by serveCSM is 7681. One can change the port in the call to serveCSM with a command such as:

        serveCSM ../data/tutorial -port 7788
      

Once the browser starts, you will be prompted for a "hostname:port" as in:

Most of the time, the "hostname" will be "Localhost" (meaning that serveCSM and the browser are on the same computer). It is possible to attach to serveCSM that is running on another computer by giving an appropriate "hostname".

As mentioned above, it is possible to change the "port" with a command line argument when starting serveCSM; if that is done, then the alternative "port" must be included in ESP's prompt.

Once all the setup is done, the browser then presents the following 3 windows:

The window on the top left is called the "Tree" window. It contains listings of the Parameters and Branches in the Model. It also contains the controls for the "Graphics" window.

The window on the top right is called the "Graphics" window. It contains a graphical representation of the current configuration.

The window on the bottom is called the "Messages" window. It contains the messages that ESP posts for the user.

The first thing to do is to play with the image in the "Graphics" window. This is done with the mouse in the following ways:

It is suggested that you use the left or middle mouse button for these operations, since in most browsers the right mouse button will post a popup menu.

At any time, a user might want to "save" a view. This is done by pressing the ">" key; the "saved" view can be retrieved by pressing the "<" key. If you want to retrieve a view more than once, simply press ">" after retrieving to re-"save" the view. If you press "<" twice, you will be returned to the original view.

The default (home) view can be obtained by pressing <Home>. (The home view is one in which the x-coordinate increases from left to right and the y-coordinate increases from bottom to top.) The view can be rotated 30 degrees left, right, up, or down, by pressing one of the arrow keys.

To re-center the image at a given point and simultaneously reset the point about which mouse rotations will occur, point to any location in the "Graphics" window and press "*"; the image will be recentered and a message will be posted in the "Messages" window.

When using the mouse, it is possible to enter "flying mode", in which the view continually changes until the mouse button is released. Flying mode is particularly useful when one needs to translate a long distance. Toggling flying mode is done with the "!" key.

To determine the identity of any object in the "Graphics" window, simply put your cursor on the object and press "^"; a summary of the identified object is shown in the "Messages" window.

To determine the approximate coordinates of any location in the "Graphics" window, simply put your cursor on the location and press "@"; the approximate coordinates of the location are shown in the "Messages" window.

Lastly, to get help on the commands that are available in the "Graphics" window, press "?" and a short listing will be given in the "Messages" window.

The results of several of these commands is shown in:

Now it is time to understand the "Tree" window. At the top of the "Tree" window is a series of buttons:

Below the buttons is a tree-like representation of the "Parameters" and "Branches" that describe the current "Model". In all cases, pressing the "+" at the beginning of any line expands (opens up) that particular entry in the tree; pressing the "-" at the beginning of any line collapses (closes) that particular entry.

Start off by pressing the "+" to the left of the word "Parameters". When this is done, all the Parameters in the current Model are displayed as shown in:

Notice that some of the Parameter names are shown in green type; this indicates that the Parameter can be "editted" by the user; those listed in black type are "read-only" Parameters that cannot be editted.

Press on the label "__Lbar" to edit the Parameter named "Lbar". (The leading underscores are there to adjust spacing in the listings and are NOT part of the actual Parameter name.) When this is done, the user is provided with a prompt that asks for the new value; the current value is pre-loaded in this prompt window, as in:

For now change the value to "9" and press "OK". Note that the Parameter name is now listed in red (to indicate that it has been changed) and that the button at the top of the "Tree" window has changed to a green button that says "Press to re-build". This tells the user that changes have been made, but that the configuration shown in the "Graphics" window has not been updated. (The reason this is done is that a user might want to make several changes to the "Model" before spending the CPU time necessary to re-build.)

Press the "Press to re-build" button and notice that it first turns yellow while the configuration is being rebuilt. Then (after a few seconds) the image in the "Graphics" window will be updated and the "Parameters" will no longer be red.

We will now change the value of "Lbar" back. But this time, instead of pressing on "__Lbar", we will use the context-sensitive menu. To do this, right-click on the "__Lbar" and the following menu will be displayed:

The first item in this menu, "Edit", is the default action that happens when you clicked on "__Lbar" (previously). Choose "Edit" and change the value back to "6". (Do not re-build yet.)

Collapse the Parameters by pressing the "-" to the left of the word "Parameters" and expand the Branches by pressing the "+" to the left of the word "Branches". This will result in a screen that looks like:

There is an "Undo" button near the top of the "Tree" window. This button un-does your last change; an example of using this is shown later in this tutorial.

We are going to want to add a "sphere" to this configuration. Do this by pressing "Branches", giving you the prompt:

We will choose a "sphere" and press "OK", giving us:

Now fill in the entries with "xcent" set to "1", "ycent" set to "0", "zcent" set to "0", and "radius" set to "2". Press "OK" and then "Press to -rebuild" and you should see:

Now let's look at the "Display" part of the "Tree" window. By default "Display" is expanded and you can see that you have two bodies named "Body 10" and "Body 9". Expand the listing for Body 9 by pressing the "+" to the left of "Body 9" and you will see entries for faces and edges. To the right of "____Faces" (below "__Body 9") you will see three items:

Try each of these and see what happens. (Notice that Body 9 is the original solid and Body 10 is the new sphere.)

Notice also that there is a "+" to the left of "____Faces", which indicates that you can interact with the object on a face-by-face basis. The basic rules here are:

Now let's "combine" the sphere and the original solid by adding a "union" Branch. (Press "Branches" and add a "union"). Re-build the configuration and you should get the solid shown in:

Note that we now only have one body.

After some thought you realize that you really didn't want the fusion of these two volumes, but instead you wanted the solid that is common to them. First, remove the "union"; this can easily be done by right-clicking on "Branches" and then choosing "Delete last Branch".

Now add the intersection by pressing "Branches" and then choosing "intersect". This operation wants to know what happens if more than one solid is produced by the operation. Specifically, the "$order" argument describes how the bodies that are produced should be ordered: for example in order of volume, surface area, ... The "index" argument tells which body in the list should be selected. Since we are only expecting one body to be produced, we can leave the defaults and then "Press to re-build", producing:

You notice that the "head" is too thin, and so you change the "radius" of the "sphere" to "2.3". (Press "__Brch_000011" and change the "radius".) While you are at it, change the Parameter "__Rbar" to "0.4" (you will need to expand the Parameters) and rebuild, producing:

Now we want to drill a hole through the center of the shaft; this is done by subtracting a cylinder from the solid; this is done with "Branches" and "cylinder". We want to the hole to go the entire length of the configuration (which is centered and whose length is 2*L), and so we enter "-1.2*L" for "xbeg" and "+1.2*L" for "xend"; the "1.2" simply ensures that the cylinder extends beyond the end of the configuration. Since it is on the centerline, set "ybeg", "zbeg", "ybeg", and "yend" all to "0", and finally the "radius" to "0.2".

Note that any argument can either be entered as a numeric constant or as an expression (using Matlab-like syntax), possibly using the name of a Parameter (such as "L").

To add the "subtract" Branch, we will right-click on "Branches" and choose "Add Branch at end" (which is the same as left-clicking on "Branches" since it is listed in the context-sensitive menu first). Choose "subtract", use the defaults and rebuild, producing:

Now we want to create a series (pattern) of small holes that are drilled across the shaft. Start by creating a new Parameter (by clicking on "Parameters") and name it "Rhole". The rules for names is that they must start with a letter and contain up to 32 letters, digits, and underscores. Since Parameters can have multiple values (think "array"), ESP asks for the number of rows and columns. Since we only have a single value, enter "1" for both of these and then the value "0.08".

Now we are going to add a pattern of holes. Do this by adding a new "patbeg" Branch; the "$pmtrName" will be "i" and the "ncopy" will be 7 (since we want 7 holes). (The "$" at the beginning of "$pmtrName" says that this is the name of the Parameter that will be created rather than the value of the Parameter "i". Also add a "cylinder" with "xbeg" and "xend" set to "i/3", "ybeg" and "yend" set to "0", "zbeg" set to "-1", "zend" set to "+1", and "radius" set to "Rhole". Press "OK".

We would now like to name this Branch. To do this, edit the Branch (by pressing "__Brch_000017") and change its "Name" to "small_holes". (Notice that we could not name it when we created it since the names are originally auto-created to ensure that we do not get an illegal name.)

Next add another "subtract" Branch and finally a "patend" Branch and then re-build (which will take several seconds), giving:

Now we want to change the hole in the center of the shaft into a hole that starts at "xbeg" equal to "0". Make the change to "__Brch_000014" and re-build. To see if you were successful, change the visibility of the faces and ensure that you have the correct hole, as in:

Now change the cylindrical hole into a conical hole. To do this, we must delete the cylinder hole (which is Brch_000014). Right-click on "__Brch_000014" and choose "Delete this Branch". Notice that doing this tells you that you have an error. To fix the error, add a conical hole after "__Brch_000013" by right-clicking "__Brch_000013" and choosing "Add Branch after", as in:

Re-build and notice that the vertex of the cone is near the head; we had meant to do it the other way, so change "xvrtx" to "0" and "xbase" to "1.2*L" and re-build, producing (after manipulating the display):

Now let's rotate the small holes, so after the "__small_holes" Branch, add a "rotatex" with arguments "-15*(i-1)", "0", and "0", and rebuild, producing:

Now we will experiment with the "activity" of the Branches. A Branch that is "suppressed" is skipped during the re-build process. So press on "__small_holes" and set the activity to "Suppressed". Note that a few other Branches become "inactive" (since they cannot be executed). Re-build, producing:

Now suppress "__Brch_000021" and activate "__small_holes" and re-build. Note that the hole re-appeared but that the rotatex is not executed. Finally, re-activate all Branches and re-build.

Another feature is ESP allows a user to only build part of the configuration. This is done by right-clicking on a Branch (for example, "__Brch_000010") and choosing "Build to this Branch", giving:

To rebuild the whole configuration, re-build to the last Branch.

The last part of the ESP tutorial involves attributes. Each Branch can have zero or more attributes associated with it that are carried throughout the build process. By pressing the "+" to the left of "__Brch_000009", its attribute ("____clipper") can be seen to have the value "1". Change the attribute to "10" by pressing "____clipper" and entering "10" at the prompt.

We can add an attribute to "__Brch_000009" by right-clicking and choosing "Add Attribute"; use the name "test" and the value "ESP". Press the "+" to the left of "__Brch_000009" and you will see that the Branch now has 2 attributes. After some thought, you realize that "ESP" is not defined, so you can "undo" this change by pressing the "Undo" button at the top of the "Tree" window. Re-build.

Now point to the face that represents the corner of the head (as shown with its grid here) and press the "^" key, producing:

(Depending on the version of OpenCASCADE that you are using, the face number that is returned may be different.)

Note that the "Messages" window contains a description of the face including the attribute that we editted ("clipper" is "10") as well as a "body" and "brch" attribute. The latter tells which Branch ("__Brch_000009") was responsible for generating that face.

Lastly, save your work by pressing the "Save" button and choosing "tutorial_new.csm" as the name of the new file. Exit the browser and you should see that serveCSM also shuts down.

If we now rename the file journal file with:

        mv port7681.jrnl tutorial.jrnl
      
we can replay our session by the command:
        serveCSM ../data/tutorial -jrnl tutorial.jrnl
      

Alternatively, we can start with the new tutorial_new.csm file with the command:

        serveCSM tutorial_new
      

This tutorial covered most of ESP's user interface. Further details are contained in the sections that follow.

Table of Contents

3.0: Command Line

To start serveCSM, one uses the command:

        serveCSM filename [-port portnum] [-outLevel n] [-jrnl jrnlname]
      

The -port option tells serveCSM with which port to connect.

The -outLevel option sets the level of output (0 to 3) that the server should produce during its execution. Higher numbers are useful for debugging and should seldom be used by most users.

The -jrnl option is useful for replaying a previous session. This journal file is an ASCII file that can be created with any text-editor. But more typically, user modifies the file portX.jrnl that is automatically produced every time serveCSM is started. (Note: be sure to copy and/or rename this file before using it as an input to serveCSM since the next serveCSM will overwrite this file.)

Table of Contents

4.0: Interactive Options

The Tutorial (above) gives an overview of nearly all the interactive commands that are available in ESP. Future versions of this document will add more details here.

Table of Contents

5.0: Format of the .csm File

The .csm file contains a series of statements.

If a line contains a hash (#), all characters starting at the hash are ignored.

If a line contains a backslash, all characters starting at the backslash are ignored and the next line is appended; spaces at the beginning of the next line are treated normally.

All statements begin with a keyword (described below) and must contain at least the indicated number of arguments.

Extra arguments in a statement are discarded and can thus be used as a comment.

The last statement must be "end". (Everything else is ignored.)

All arguments must not contain any spaces or must be enclosed in a pair of double quotes (for example, "a + b").

Parameters are evaluated in the order that they appear in the file, using MATLAB-like syntax (see "Expression rules" below).

During the build process, OpenCSM maintains a LIFO "Stack" that can contain Bodies and Sketches.

The csm statements are executed in a stack-like way, taking their inputs from the Stack and depositing their results onto the Stack.

The default name for each Branch is "Brch_xxxxxx", where xxxxxx is a unique sequence number.

5.1: Special characters

#          introduces comment
"          ignore spaces until following "
\          ignore this and following characters and concatenate next line
    separates arguments in .csm file

0-9        digits used in numbers and in names
A-Z a-z _  letters used in names
.          decimal separator (used in numbers)
,          separates function arguments and row/column in subscripts
;          multi-value item separator
( )        groups expressions and function arguments
[ ]        specifies subscripts in form [row,column]
+ - * / ^  arithmetic operators
!          as first character, forces argument to be evaluated
$          as first character, forces argument not to be evaluated (used internally)
@          as first character, introduces @-parameters (see below)

~          not used
%          not used
&          not used
=          not used
{ }        not used
'          not used
:          not used
< >        not used
?          not used
      

5.2: Valid CSM statements

The following is taken from the OpenCSM.h file:

dimension pmtrName nrow ncol despmtr=0
          use:    set up a multi-value Parameter
          pops:   -
          pushes: -
          notes:  sketcher may not be open
                  solver   may not be open
                  nrow >= 1
                  ncol >= 1
                  pmtrName must not start with '@'
                  if despmtr=0, then marked as INTERNAL
                  if despmtr=1, then marked as EXTERNAL
                  does not create a Branch

despmtr   pmtrName values
          use:    define a (constant) driving design Parameter
          pops:   -
          pushes: -
          notes:  sketcher may not be open
                  solver   may not be open
                  pmtrName can be in form "name" or "name[irow,icol]"
                  pmtrName must not start with '@'
                  name must not refer to an INTERNAL Parameter
                  name will be marked as EXTERNAL
                  name is used directly (without evaluation)
                  irow and icol cannot contain a comma or open bracket
                  values cannot refer to any other Parameter
                  if values has multiple values (separated by ;), then
                     any subscripts in pmtrName are ignored
                  values are defined across rows
                  if values is longer than Parameter size, extra values are lost
                  if values is shorter than Parameter size, last value is repeated
                  does not create a Branch

set       pmtrName exprs
          use:    define a (redefinable) driven Parameter
          pops:   -
          pushes: -
          notes:  solver   may not be open
                  pmtrName can be in form "name" or "name[irow,icol]"
                  pmtrName must not start with '@'
                  name must not refer to an EXTERNAL Parameter
                  name will be marked as INTERNAL
                  name is used directly (without evaluation)
                  irow and icol cannot contain a comma or open bracket
                  if exprs has multiple values (separated by ;), then
                     any subscripts in pmtrName are ignored
                  exprs are defined across rows
                  if exprs is longer than Parameter size, extra exprs are lost
                  if exprs is shorter than Parameter size, last expr is repeated

box       xbase ybase zbase dx dy dz
          use:    create a box Body
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  face order is: xmin, xmax, ymin, ymax, zmin, zmax

sphere    xcent ycent zcent radius
          use:    create a sphere Body
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  face order is: ymin, ymax

cone      xvrtx yvrtx zvrtx xbase ybase zbase radius
          use:    create a cone Body
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  face order is: (empty), base, umin, umax

cylinder  xbeg ybeg zbeg xend yend zend radius
          use:    create a cylinder Body
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  face order is: beg, end, umin, umax

torus     xcent ycent zcent dxaxis dyaxis dzaxis majorRad minorRad
          use:    create a torus Body
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  face order is: xmin/ymin, xmin/ymax, xmax/ymax, xmax,ymax

import    filename bodynumber=1
          use:    import from filename
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  filename is used directly (without evaluation)

udprim    primtype argName1 argValue1 argName2 argValue2 argName3 argValue3 argName4 argValue4
          use:    create a Body by executing a user-defined primitive
          pops:   -
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  primtype  determines the type of primitive and the number of argName/argValue pairs
                  primtype  is used directly (without evaluation)
                  argName#  is used directly (without evaluation)
                  argValue# is evaluated if it starts with "!", otherwise it is used directly
                  if argValue# is <<, use data to matching >> as inline file
                  see udp documentation for full information

extrude   dx dy dz
          use:    create a Body by extruding a Sketch
          pops:   Sketch
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  if Sketch is a SHEET Body, then a SOLID Body is created
                  if Sketch is a WIRE  Body, then a SHEET Body is created
                  face order is: base, end, feat1, ...

loft      smooth
          use:    create a Body by lofting through Sketches since mark
          pops:   Sketch1 ...
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  all Sketches must have the same number of Segments
                  if Sketch is a SHEET Body, then a SOLID Body is created
                  if Sketch is a WIRE  Body, then a SHEET Body is created
                  face order is: base, end, feat1, ...
                  if NINT(smooth)==1, then sections are smoothed
                  the first and/or last Sketch can be a point

revolve   xorig yorig zorig dxaxis dyaxis dzaxis angDeg
          use:    create a Body by revolving a Sketch around an axis
          pops:   Sketch
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  if Sketch is a SHEET Body, then a SOLID Body is created
                  if Sketch is a WIRE  Body, then a SHEET Body is created
                  face order is: (base), (end), feat1, ...

fillet    radius edgeList=0
          use:    apply a fillet to a Body
          pops:   Body
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  if previous operation is boolean, apply to all new Edges
                  edgeList=0 is the same as edgeList=[0;0]
                  edgeList is a [n*2] multi-valued Parameter
                  rows of edgeList are processed in order
                  rows of edgeList are interpreted as follows:
                    col1  col2   meaning
                     =0    =0    add all Edges
                     >0    >0    add    Edges between iford=+icol1 and iford=+icol2
                     <0    <0    remove Edges between iford=-icol1 and iford=-icol2
                     >0    =0    add    Edges adjacent to iford=+icol1
                     <0    =0    remove Edges adjacent to iford=-icol1

chamfer   radius edgeList=0
          use:    apply a chamfer to a Body
          pops:   Body
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  if previous operation is boolean, apply to all new Edges
                  edgeList=0 is the same as edgeList=[0;0]
                  edgeList is a [n*2] multi-valued Parameter
                  rows of edgeList are processed in order
                  rows of edgeList are interpreted as follows:
                    col1  col2   meaning
                     =0    =0    add all Edges
                     >0    >0    add    Edges between iford=+icol1 and iford=+icol2
                     <0    <0    remove Edges between iford=-icol1 and iford=-icol2
                     >0    =0    add    Edges adjacent to iford=+icol1
                     <0    =0    remove Edges adjacent to iford=-icol1

hollow    thick   iface1=0  iface2=0  iface3=0  iface4=0  iface5=0  iface6=0
          use:    hollow out a solid Body
          pops:   Body
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  if iface*=0, then Face not added to list
                  if all iface*=0 then create an offset body instead

intersect order=none index=1
          use:    perform Boolean intersection (Body2 & Body1)
          pops:   Body1 Body2
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  Body1 and Body2 must be SOLID Bodys
                  if intersection does not produce at least index Bodies, an error is returned
                  order may be one of:
                      none    same order as returned from geometry engine
                      xmin    minimum xmin   is first
                      xmax    maximum xmax   is first
                      ymin    minimum ymin   is first
                      ymax    maximum ymax   is first
                      zmin    minimum zmin   is first
                      zmax    maximum zmax   is first
                      amin    minimum area   is first
                      amax    maximum area   is first
                      vmin    minimum volume is first
                      vmax    maximum volume is first
                  order is used directly (without evaluation)

subtract  order=none index=1
          use:    perform Boolean subtraction (Body2 - Body1)
          pops:   Body1 Body2
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  Body1 and Body2 must be SOLID Bodys
                  if subtraction does not produce at least index Bodies, an error is returned
                  order may be one of:
                      none    same order as returned from geometry engine
                      xmin    minimum xmin   is first
                      xmax    maximum xmax   is first
                      ymin    minimum ymin   is first
                      ymax    maximum ymax   is first
                      zmin    minimum zmin   is first
                      zmax    maximum zmax   is first
                      amin    minimum area   is first
                      amax    maximum area   is first
                      vmin    minimum volume is first
                      vmax    maximum volume is first
                  order is used directly (without evaluation)

union
          use:    perform Boolean union (Body2 | Body1)
          pops:   Body1 Body2
          pushes: Body
          notes:  sketcher may not be open
                  solver   may not be open
                  Body1 and Body2 must be SOLID Bodys

translate dx dy dz
          use:    translates the entry on top of Stack
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  solver   may not be open

rotatex   angDeg yaxis zaxis
          use:    rotates entry on top of Stack around x-like axis
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  solver   may not be open

rotatey   angDeg zaxis xaxis
          use:    rotates entry on top of Stack around y-like axis
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  solver   may not be open

rotatez   angDeg xaxis yaxis
          use:    rotates entry on top of Stack around z-like axis
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  solver   may not be open

scale     fact
          use:    scales entry on top of Stack
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  solver   may not be open

skbeg     x y z
          use:    start a new sketch with the given point
          pops:   -
          pushes: -
          notes:  opens sketcher
                  solver   may not be open

linseg    x y z
          use:    create a new line segment, connecting the previous
                     and specified points
          pops:   -
          pushes: -
          notes:  sketcher must be open
                  solver   may not be open

cirarc    xon yon zon xend yend zend
          use:    create a new circular arc, using t he previous point
                     as well as the two points specified
          pops:   -
          pushes: -
          notes:  sketcher must be open
                  solver   may not be open

spline    x y z
          use:    add a point to a spline
          pops:   -
          pushes: -
          notes:  sketcher must be open
                  solver   may not be open

skend
          use:    completes a Sketch
          pops:   -
          pushes: Sketch
          notes:  sketcher must be open
                  solver   may not be open
                  all linsegs and cirarcs must be x-, y-, or z-co-planar
                  if sketch is     closed, then a SHEET Body is created
                  if sketch is not closed, then a WIRE  Body is created
                  if skend immediately follows skbeg, then a Point
                     is created (which can be used at either end of a loft)
                  closes sketcher

solbeg    varlist
          use:    starts a solver block
          pops:   -
          pushes: -
          notes:  solver must not be open
                  opens the solver
                  varlist is a list of semi-colon-separated INTERNAL parameters
                  varlist must end with a semi-colon

solcon    expr
          use:    constraint used to set solver variables
          pops:   -
          pushes: -
          notes:  sketcher must not be open
                  solver must be open
                  solend will drive expr to zero

solend
          use:    close a solver block
          pops:   -
          pushes: -
          notes:  sketcher must not be open
                  solver must be open
                  adjust variables to drive constrains to zero
                  closes the solver

select    type arg1 ...
          use:    selects entity for which @-parameters are evaluated
          pops:   -
          pushes: -
          notes:  if arguments are: body
                     @-parameters apply to last Body on Stack
                  if arguments are: face iface
                     @-parameters apply to Face iface in the last Body on Stack
                  if arguments are: face ibody1 iford1 iseq=1
                     @-parameters apply to the Face in the last Body on Stack
                        that matches ibody1/iford1
                  if arguments are: edge iedge
                     @-parameters apply to Edge iedge in the last Body on Stack
                  if arguments are: edge ibody1 iford1 ibody2 iford2 iseq=1
                     @-parameters apply to the Edge in the last Body on Stack
                        that adjoins Faces ibody1/iford1 and ibody2/iford2
                  if arguments are: node inode
                     @-parameters apply to Node inode in the last Body on Stack
                  if arguments are: node ibody1 iford1 ibody2 iford2 ibody3 iford3 iseq=1
                     @-paramaters apply to the Node in the last Body on Stack
                        that adjoins Faces ibody1/iford1, ibody2/iford2,
                        and ibody3/iford3
                  Face specifications are stored in faceID attribute
                  Edge specifications are stored in edgeID attribute
                  Node specifications are stored in nodeID attribute
                  iseq selects from amongst multiple Faces/Edges/Nodes that
                     match the ibody/iford specifications

macbeg    imacro
          use:    marks the start of a macro
          pops:   -
          pushes: -
          notes:  sketcher may not be open
                  solver   may not be open
                  imacro must be between 1 and 100
                  cannot overwrite a previous macro

macend
          use:    ends a macro
          pops:   -
          pushes: -
          notes:

recall    imacro
          use:    recalls copy of macro from a storage location imacro
          pops:   -
          pushes: any
          notes:  sketcher may not be open
                  solver   may not be open
                  storage location imacro must have been previously filled by a macro command

patbeg    pmtrName ncopy
          use:    execute the pattern multiple times
          pops:   -
          pushes: -
          notes:  solver   may not be open
                  pattern contains all statement up to the matching patend
                  pmtrName must not start with '@'
                  pmtrName takes values from 1 to ncopy (see below)
                  pmtrName is used directly (without evaluation)

patend
          use:    mark the end of a pattern
          pops:   -
          pushes: -
          notes:  solver   may not be open
                  there must be a matching patbeg for each patend

mark
          use:    used to identify groups such as in loft
          pops:   -
          pushes: -
          notes:  sketcher may not be open
                  solver   may not be open

dump      filename remove=0
          pops:   -
          pushes: -
          notes:  solver   may not be open
                  if file exists, it is overwritten
                  filename is used directly (without evaluation)
                  if remove == 1, then Body is removed after dumping

name      branchName
          use:    names the entry on top of Stack
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  does not create a Branch

attribute attrName attrValue
          use:    sets an attribute for the entry on top of Stack
          pops:   any
          pushes: any
          notes:  sketcher may not be open
                  attrValue is treated as a string
                  if first char of attrValue is !, then evaluate
                  does not create a Branch
                  if before first Branch, then defines a global Attribute

end
          pops:   -
          pushes: -
          notes:  sketcher may not be open
                  solver   may not be open
                  Bodys on Stack are returned in LIFO
       

5.3: Expression rules

The following is taken from the OpenCSM.h file:

Valid names:
    start with a letter
    contain letters, digits, and underscores
    contain fewer than 32 characters

Array names:
    basic format is: name[irow,icol]
    name must follow rules above
    irow and icol must be valid expressions

Valid operators (in order of precedence):
    ( )            parentheses, inner-most evaluated first
    func(a,b)      function arguments, then function itself
    ^              exponentiation      (evaluated left to right)
    * /            multiply and divide (evaluated left to right)
    + -            add and subtract    (evaluated left to right)

Valid function calls:
    pi(x)                        3.14159...*x
    min(x,y)                     minimum of x and y
    max(x,y)                     maximum of x and y
    sqrt(x)                      square root of x
    abs(x)                       absolute value of x
    int(x)                       integer part of x  (3.5 -> 3, -3.5 -> -3)
    nint(x)                      nearest integer to x
    exp(x)                       exponential of x
    log(x)                       natural logarithm of x
    log10(x)                     common logarithm of x
    sin(x)                       sine of x          (in radians)
    sind(x)                      sine of x          (in degrees)
    asin(x)                      arc-sine of x      (in radians)
    asind(x)                     arc-sine of x      (in degrees)
    cos(x)                       cosine of x        (in radians)
    cosd(x)                      cosine of x        (in dagrees)
    acos(x)                      arc-cosine of x    (in radians)
    acosd(x)                     arc-cosine of x    (in degrees)
    tan(x)                       tangent of x       (in radians)
    tand(x)                      tangent of x       (in degrees)
    atan(x)                      arc-tangent of x   (in radians)
    atand(x)                     arc-tangent of x   (in degrees)
    atan2(y,x)                   arc-tangent of y/x (in radians)
    atan2d(y,x)                  arc-tangent of y/x (in degrees)
    hypot(x,y)                   hypoteneuse: sqrt(x^2+y^2)
    Xcent(xa,ya,Cab,xb,yb)       X-center of circular arc
    Ycent(xa,ya,Cab,xb,yb)       Y-center of circular arc
    Xmidl(xa,ya,Cab,xb,yb)       X-point at midpoint of circular arc
    Ymidl(xa,ya,Cab,xb,yb)       Y-point at midpoint of circular arc
    turnang(xa,ya,Cab,xb,yb)     turning angle of circular arc (in degrees)
    tangent(xa,ya,Cab,xb,yb,...
                     Cbc,xc,yc)  tangent angle at b (in degrees)
    ifzero(test,ifTrue,ifFalse)  if test=0, return ifTrue, else ifFalse
    ifpos(test,ifTrue,ifFalse)   if test>0, return ifTrue, else ifFalse
    ifneg(test,ifTrue,ifFalse)   if test<0, return ifTrue, else ifFalse

@-parameters depend on the last "select" statement.  Each time
    a new Body is added to the Stack, "select body" is implicity called

             body face edge node
    @nbody   x    x    x    x   current body (also number of bodies)
    @nface   x    x    x    x   number of faces in current body
    @nedge   x    x    x    x   number of edges in current body
    @nnode   x    x    x    x   number of nodes in current body

    @ibody1       x    x        first  element of "Body" attribute
    @ibody2       x    x        second element of "Body" attribute

    @iface        x             current face
    @iedge             x        current edge
    @inode                  x   current node

    @xmin    x    x    *    x   x-min of bounding box or x at beg of edge
    @ymin    x    x    *    x   y-min of bounding box or y at beg of edge
    @zmin    x    x    *    x   z-min of bounding box or z at beg of edge
    @xmax    x    x    *    x   x-max of bounding box or x at end of edge
    @ymax    x    x    *    x   y-max of bounding box or y at end of edge
    @zmax    x    x    *    x   z-max of bounding box or z at end of edge

    @length            x        length of edge
    @area    x    x             area of face or surface area of body
    @volume  x                  volume of body (if a solid)

    @xcg     x    x    x    x   location of center of gravity
    @ycg     x    x    x    x
    @zcg     x    x    x    x

    @Ixx     x    x    x        centroidal moment of inertia
    @Ixy     x    x    x
    @Ixz     x    x    x
    @Iyx     x    x    x
    @Iyy     x    x    x
    @Iyz     x    x    x
    @Izx     x    x    x
    @Izy     x    x    x
    @Izz     x    x    x
       

Table of Contents

6.0: Example .csm file

The following is a copy of tutorial.csm

# tutorial
# written by John Dannenhoffer

# default design parameters
despmtr   Lbar      6.00      length of bar
despmtr   Rbar      0.15      radius of bar
despmtr   T         0.50      thickness of weights
despmtr   D         2.00      diameter  of weights
despmtr   Rout      1.20      outer radius (for intersection)
despmtr   Rfil      0.10      fillet radius at end of bar

set       L         Lbar/2

# shaft
cylinder  -L        0.0       0.0       +L        0.0       0.0       Rbar
name      shaft
attribute shaft     1

# left weight
box       -L-T/2    -D/2      -D/2      T         D         D
name      left_weight
attribute weight    1
union
fillet    Rfil

# rite weight
box       +L-T/2    -D/2      -D/2      T         D         D
name      rite_weight
attribute weight    2
union
fillet    Rfil

# clip weights with outer cylinder
cylinder  -L-T      0.00      0.00      +L+T      0.00      0.00      Rout
intersect
attribute clipper   1

end
      

Table of Contents

7.0: Error Codes

7.1: OpenCSM error codes

OpenCSM performs extensive error checking that can issue the following error codes:

OCSM_FILE_NOT_FOUND                  -201
OCSM_ILLEGAL_STATEMENT               -202
OCSM_NOT_ENOUGH_ARGS                 -203
OCSM_NAME_ALREADY_DEFINED            -204
OCSM_PATTERNS_NESTED_TOO_DEEPLY      -205
OCSM_PATBEG_WITHOUT_PATEND           -206
OCSM_PATEND_WITHOUT_PATBEG           -207
OCSM_NOTHING_TO_DELETE               -208
OCSM_NOT_MODL_STRUCTURE              -209

OCSM_DID_NOT_CREATE_BODY             -211
OCSM_CREATED_TOO_MANY_BODYS          -212
OCSM_EXPECTING_ONE_BODY              -213
OCSM_EXPECTING_TWO_BODYS             -214
OCSM_EXPECTING_ONE_SKETCH            -215
OCSM_EXPECTING_NLOFT_SKETCHES        -216
OCSM_LOFT_WITHOUT_MARK               -217
OCSM_TOO_MANY_SKETCHES_IN_LOFT       -218
OCSM_MODL_NOT_CHECKED                -219

OCSM_FILLET_AFTER_WRONG_TYPE         -221
OCSM_CHAMFER_AFTER_WRONG_TYPE        -222
OCSM_NO_BODYS_PRODUCED               -223
OCSM_NOT_ENOUGH_BODYS_PRODUCED       -224
OCSM_TOO_MANY_BODYS_ON_STACK         -225
OCSM_FACE_NOT_FOUND                  -226
OCSM_EDGE_NOT_FOUND                  -227
OCSM_NODE_NOT_FOUND                  -228

OCSM_SKETCHER_IS_OPEN                -231
OCSM_SKETCHER_IS_NOT_OPEN            -232
OCSM_COLINEAR_SKETCH_POINTS          -233
OCSM_NON_COPLANAR_SKETCH_POINTS      -234
OCSM_TOO_MANY_SKETCH_POINTS          -235
OCSM_TOO_FEW_SPLINE_POINTS           -236
OCSM_SKETCH_DOES_NOT_CLOSE           -237

OCSM_ILLEGAL_CHAR_IN_EXPR            -241
OCSM_CLOSE_BEFORE_OPEN               -242
OCSM_MISSING_CLOSE                   -243
OCSM_ILLEGAL_TOKEN_SEQUENCE          -244
OCSM_ILLEGAL_NUMBER                  -245
OCSM_ILLEGAL_PMTR_NAME               -246
OCSM_ILLEGAL_FUNC_NAME               -247
OCSM_ILLEGAL_TYPE                    -248
OCSM_ILLEGAL_NARG                    -249

OCSM_NAME_NOT_FOUND                  -251
OCSM_NAME_NOT_UNIQUE                 -252
OCSM_PMTR_IS_EXTERNAL                -253
OCSM_PMTR_IS_INTERNAL                -254
OCSM_FUNC_ARG_OUT_OF_BOUNDS          -255
OCSM_VAL_STACK_UNDERFLOW             -256  /* probably not enough args to func */
OCSM_VAL_STACK_OVERFLOW              -257  /* probably too many   args to func */

OCSM_ILLEGAL_BRCH_INDEX              -261  /* should be from 1 to nbrch */
OCSM_ILLEGAL_PMTR_INDEX              -262  /* should be from 1 to npmtr */
OCSM_ILLEGAL_BODY_INDEX              -263  /* should be from 1 to nbody */
OCSM_ILLEGAL_ARG_INDEX               -264  /* should be from 1 to narg  */
OCSM_ILLEGAL_ACTIVITY                -265  /* should OCSM_ACTIVE or OCSM_SUPPRESSED */
OCSM_ILLEGAL_MACRO_INDEX             -266  /* should be between 1 and 100 */
OCSM_ILLEGAL_ARGUMENT                -267
OCSM_CANNOT_BE_SUPPRESSED            -268
OCSM_STORAGE_ALREADY_USED            -269
OCSM_NOTHING_PREVIOUSLY_STORED       -270

OCSM_SOLVER_IS_OPEN                  -271
OCSM_SOLVER_IS_NOT_OPEN              -272
OCSM_TOO_MANY_SOLVER_VARS            -273
OCSM_UNDERCONSTRAINED                -274
OCSM_OVERCONSTRAINED                 -275
OCSM_SINGULAR_MATRIX                 -276
OCSM_NOT_CONVERGED                   -277

OCSM_UDP_ERROR1                      -281
OCSM_UDP_ERROR2                      -282
OCSM_UDP_ERROR3                      -283
OCSM_UDP_ERROR4                      -284
OCSM_UDP_ERROR5                      -285
OCSM_UDP_ERROR6                      -286
OCSM_UDP_ERROR7                      -287
OCSM_UDP_ERROR8                      -288
OCSM_UDP_ERROR9                      -289

OCSM_OP_STACK_UNDERFLOW              -291
OCSM_OP_STACK_OVERFLOW               -292
OCSM_RPN_STACK_UNDERFLOW             -293
OCSM_RPN_STACK_OVERFLOW              -294
OCSM_TOKEN_STACK_UNDERFLOW           -295
OCSM_TOKEN_STACK_OVERFLOW            -296
OCSM_UNSUPPORTED                     -298
OCSM_INTERNAL_ERROR                  -299
      

7.2: EGADS error codes

In addition, sometimes EGADS or CAPRI will issue an error code. The EGADS error codes that may be seen from time to time include:

EGADS_NOTFOUND                         -1
EGADS_NULLOBJ                          -2
EGADS_NOTOBJ                           -3
EGADS_MALLOC                           -4
EGADS_INDEXERR                         -5
EGADS_NONAME                           -6
EGADS_NODATA                           -7
EGADS_MIXCNTX                          -8
EGADS_NOTCNTX                          -9
EGADS_NOTXFORM                        -10
EGADS_REFERCE                         -11
EGADS_NOTTOPO                         -12
EGADS_EMPTY                           -13
EGADS_NOTTESS                         -14
EGADS_NOTGEOM                         -15
EGADS_RANGERR                         -16
EGADS_NOLOAD                          -17
EGADS_NOTMODEL                        -18
EGADS_WRITERR                         -19
EGADS_NOTBODY                         -20
EGADS_GEOMERR                         -21
EGADS_TOPOERR                         -22
EGADS_CONSTERR                        -23
EGADS_DEGEN                           -24
EGADS_NOTORTHO                        -25
EGADS_BADSCALE                        -26
EGADS_OCSEGFLT                        -27
      

Table of Contents

8.0: Bugs Reports and Other Feedback

All reports of possible "bugs" and any other feedback should be e-mailed to "jfdannen@syr.edu". If a bug report, please include the version number you are running (listed in the title bar at the top of the program), what you were doing at the time of the bug, and what happened that you didn't expect. The more information that you include, the better the chances that the bug can be reproduced and hence fixed.

Table of Contents

9.0: Copyright

Copyright (C) 2010/2013 John F. Dannenhoffer, III (Syracuse University)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Table of Contents

10.0: Glossary

activity An attribute of a Branch which tells if the Branch should be executed the next time the Model is re-built. ESP supports "active" and "suppressed" activities.

Branch An entity in the Model's feature tree that corresponds to either a primitive solid, transformation, boolean operator, sketch entity, or other item used in the construction of a Model.

browser A computer program with which a user interacts with ESP. ESP currently runs in FireFox, GoogleChrome, SeaMonkey, and Safari.

collapse The process of "closing up" a node in a tree so that its children are not displayed. This is accomplished by pressing the - to the left of an (expanded) tree node.

drag An operation in which a user presses a mouse button and holds it down while moving it to another location on the screen.

ESP The Engineering Sketch Pad is a browser-based software system that allows users create, modify, (re-)build, and save constructive solid models built via OpenCSM.

expand The process of "opening up" a node in a tree to see its children nodes. This is accomplished by pressing the + to the left of a (collapsed) tree node.

flying mode A way of panning, zooming, and rotating a display in which the motion of the image in the Graphics Window changes as long as the user holds the mouse button. Use the ! key in the Graphics Window to toggle flying mode on and off.

Graphics window The window on the top-right of the ESP screen that contains a graphical representation of the current configuration.

hostname The name of the computer that is running the server (typically serveCSM). If using a single computer for both the browser and server, use "Localhost" as the hostname.

journal A file that is written (on the server) that keeps track of the commands that user executed while running ESP. A user (who has access to the server) can copy the journal file to another name and use it to automatically replay the session that was journalled during a future invocation of serveCSM.

Messages window The window on the bottom of the ESP screen that contains status information and other messages to the user.

Model A container that contains the Parameters and (feature-tree) Branches.

Parameter A two-dimensional array of floating-point numbers that is used during the build process to generate a specific instance of a Model.

port The port number on which the server (typically serveCSM) is listening for requests by the browser. serveCSM uses 7681 as its default port.

server A computer program in which OpenCSM runs and which "serves" Models and Boundary Representations to ESP. The program "serveCSM" is the initial server for ESP.

Tree window The window on the top-left of the ESP screen that contains command buttons, a tree-like view of the current Parameters, a tree-like view of the current Branches (of the feature tree), and a tree-like view of the display settings.

Table of Contents