ESP: The Engineering Sketch Pad Rev 1.08 -- October 2015 1. Prerequisites The most significant prerequisite for this software is OpenCASCADE at release 6.5 or greater (which includes the OpenCASCADE Community Edition). This can be found at http://www.opencascade.org/getocc/download/loadocc or https://github.com/tpaviot/oce. Prebuilt versions are available at these sites for Windows using various versions of Visual Studio and for MAC OSX at 64-bits. Prebuilt releases can be found at: http://acdl.mit.edu/ESP. Any other configuration must be built from source (unless you are using a Debian variant of LINUX, such as Ubuntu, where there are available prebuilt packages as part of the LINUX distribution). Note that 6.8 is recommended (except for 64-bit OSX) and there are SBO robustness problems at 6.5.3-6.5.5, so ESP works best at 6.5.2 if you are going to use 6.5. OpenCASCADE 6.7.0 displays problems in mapping attributes after using SBOs, so it is not recommended. In 6.7.1 this has been corrected but the SBOs are not as robust as in 6.6.0 or 6.8.0. OCC 6.9.0 and 6.9.1 have been released, and 6.9.0 has been found to be slightly less reliable than 6.8.0. 6.9.1 is not recommended. Another prerequisite is a WebGL/Websocket capable Browser. In general these include Mozilla's FireFox and Google Chrome. Apple's Safari works at rev 6.0 or greater. Internet Explorer is NOT supported because of a problem in its Websockets implementation. Also, note that there are some problems with Intel Graphics and some WebGL Browsers. For LINUX, "zlib" development is required. CAPS is optionally built and has a dependency on UDUNITS2 (see Section 4). 1.1 Source Distribution Layout In the discussions that follow, $DISROOT will be used as the name of the directory that contains: README.txt - this file RELEASEnotes.txt - ESP bug fixes, list of enhancements and etc. bin - a directory that will contain executables config - files that allow for automatic configuration data - test and example scripts doc - documentation ESP - Web client code for the Engineering Sketch Pad lib - a directory that will contain libraries, shared objects and DLLs training - training slides and example code src - source files (contains EGADS, CAPS, wvServer & OpenCSM) SlugsClinet - the browser code for Slugs wvClient - simple examples of Web viewing used by EGADS 1.2 Release Notes serveCSM now returns 1 if running in batch and an error is encountered A warning is issued if a SolidBody has a non-positive volume A new ocsmDelPmtr function has been added to the OpenCSM API to delete a Design Parameter A new ocsmGetTessVel function has been added to the OpenCSM API to return the 3D sensitivities at all the tessellation points See the file "OSXnotes.txt" at the top level of the ESP distribution if you are an existing ESP user and run on MAC OSX. 1.2.1 Changes to OpenCSM scripting language since v1.07: An additional argument, relative=0, has been added to the skbeg statement. If set to 1, the coordinates specified by linseg, cirarc, arc, spline, and bezier statements are all relative to the coorindates in the skbeg statement The despmtr, lbound, and ubound statements have been extended to allow specification of a single value, a whole row, a whole column, or the whole matrix The smallang(ang) function has been added to convert angles into the range -180 < ang <= 180 The hypot3(x,y,z) function has been added for 3D vectors The mod(i,j) function has been added The x.norm dot suffix has been added to compute the norm of array x 1.2.2 Additional OpenCSM user-defined primitives since v1.07: A new biconvex UDP was written 1.2.3 Additional OpenCSM user-defined component since v1.07: none 1.2.4 Changes to ESP since v1.07: When an edit form is displayed, the first entry box now automatically gets focus on entry The TAB key now correctly moves between inputs in the edit forms in ESP Pressing the ENTER key in an edit form is now the same as pressing the OK button When a skbeg statement is added in ESP, a matching skend is automatically added and ESP then enters the sketcher If a skbeg Branch is deleted, the whole associated sketch is now deleted Once a udprim or udparg statement has been added, the number of name-value pairs cannot be changed. Add another udparg statement if more are needed. When a new Design Parameter is added, it defaults to be a scalar. New buttons have been added to "Add Row" or "Add Column" The Delete Parameter button has been added to the edit parameter form 5 levels of Undo are now kept in the sketcher Circle centers can now be constrained in the sketcher The X and Y constraints at the beginning of a relative sketch can no longer be deleted In the sketcher, the correct sign is suggested for W, D, R, and S constraints based pon what user draws Arrow keys and PgUp and PgDn can be used to transform the image in the sketcher Zero-length segments cannot be accidentally drawn via double clicks in the Sketcher. A new "z" command has been added to create zero-length segments. Pressing ESC in sketcher no longer exits the sketcher Pressing < to delete a constraint in the sketcher now gives the user the option to select the one constraint to delete if there are multiple constraints present The @ key in the sketcher reports coordinates in the Message window Descriptions of the supell and kulfan UDPs have been added to the help file 1.2.5 Changes to EGADS since v1.07: The signature to EG_matchBodyFaces has changed to add a tolerance to the matching algorithm. Also, the Face bounding-box is no longer used in the procedure. 1.2.6 Known issues in v1.08: When using 64-bit OSX 10.8 or higher, you should use OpenCASCADE 6.6.0 (as opposed to 6.8.0). There is an error somewhere that causes "serveCSM tutorial1_new" to sometimes produce a segmentation fault during rebuilds. Edges are not drawn in ESP when running a LINUX64 virtual machine under VMware with OSX 10.8 or higher as the host operating system. Some of the keyboard shortcuts are intercepted by some of the Browsers. Therefore a third line of buttons have been added to the left side of ESP; pressing the "L" button does the same thing as pressing . Test cases with the "hollow" command do not work when using the prebuilt versions of OpenCASCADE 6.6.0 or 6.8.0 for Windows. In OpenCASCADE 6.8.0, the tolerances associated with the "sew" operation cause cases with loose tolerances to no longer work. The "Edit" command in ESP can only be used to edit the .csm file; any .udc files that are opened cannot be edited. 2. Building the Software The config subdirectory contains scripts that need to be used to generate the environment both to build and run the software here. CAPS is not currently built by default, See section 4. There are two different build procedures based on the OS: If using Windows, skip to section 2.2. 2.1 Linux and Mac OSX The configuration is built using the path where the OpenCASCADE runtime distribution can be found. The pointer size (32 or 64bit) is determined from the shared objects/dynamic libraries found in the distribution. This path can be located in an OpenCASCADE distribution by looking for a subdirectory that includes an "inc" or "include" directory and either a "lib" or "$ARCH/lib" (where $ARCH is the name of your architecture) directory. For Debian prebuilt packaged installs this location is "/usr/include/opencascade". Once that is found, execute the commands: % cd $DISROOT/config % ./makeEnv **name_of_OpenCASCADE_directory_containing_inc_and_lib** An optional second argument to makeEnv is required if the distribution of OpenCASCADE has multiple architectures. In this case it is the subdirectory name that contains the libraries for the build of interest (CASARCH). This procedure produces 2 files at the top level: ESPenv.sh and ESPenv.csh. These are the environments for both sh (bash) and csh (tcsh) respectively. The appropriate file can be "source"d or included in the user's startup scripts. This must be done before either building and/or running the software. For example, if using the csh or tcsh: % cd $DISROOT % source ESPenv.csh or if using bash: $ cd $DISROOT $ source ESPenv.sh Skip to section 2.3. 2.2 Windows Configuration IMPORTANT: The ESP distribution MUST be unpackaged into a location ($DISROOT) that has NO spaces in the path! The configuration is built from the path where where the OpenCASCADE runtime distribution can be found. The pointer size (32 or 64bit) is determined from the MS Visual Studio environment in a command shell (the C/C++ compiler is run). Currently MS VS 2008, 2010, 2012, 2013 and 2015 are supported. The Windows environment is built simply by going to the config subdirectory and executing the script "winEnv" in a bash shell (run from the command window): C:\> cd $DISROOT\config C:\> bash winEnv D:\OpenCASCADE6.6.0\ros winEnv (like makeEnv) has an optional second argument that is only required if the distribution of OpenCASCADE has multiple architectures. In this case it is the subdirectory name that contains the libraries for the build of interest (CASARCH). This procedure produces a single file at the top level: ESPenv.bat. This file needs to be executed before either building and/or running the software. This is done with: C:\> cd $DISROOT C:\> ESPenv Check that the method that you used to unzip the distribution created directories named $DISTROOT\bin and $DISTROOT\lib. If it did not, create them using the commands: C:\> cd $DISTROOT C:\> mkdir bin C:\> mkdir lib 2.3 The Build For any of the operating systems, after properly setting the environment in the command window (or shell), follow this simple procedure: % cd $DISROOT/src % make or C:\> cd $DISROOT\src C:\> make You can use "make clean" which will clean up all object modules or "make cleanall" to remove all objects, executables, libraries, shared objects and dynamic libraries. Note that if a compiler option is not available for the version of the compiler that you are using (for example, gcc 4.0.1 does not support -Wno-unused-result), you can edit the file: $DISROOT/src/EGADS/include/$ESP_ARCH to remove the offending options. 3.0 Running For Windows OpenCASCADE distributions taken from the OpenCASCADE site, you may need to copy a file and put it in "$DISROOT\lib". This is required if you attempt to execute serveCSM and are told that "tbbmalloc.dll" cannot be found. If this is the case, go to the top level of the OpenCASCADE distribution and into the directory "3rdparty". There should be a subdirectory starting with "tbb", go into that directory. There are now different variants where you may need to select the architecture and then find a "bin" subdirectory with the possibility of additional levels based on the version of Visual C. Select the appropriate "tbbmalloc.dll" file (if there is a choice) and copy it into "$DISROOT\lib". 3.1 serveCSM and ESP 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. 3.1.1 Procedure 1: have ESP automatically started from serveCSM If it exists, the ESP_START environment variable contains the command that should be executed to start the browser once the server has created its scene graph. On a Mac, you can set this variable with commands such as % setenv ESP_START "open -a /Applications/Firefox.app ../ESP/ESP.html" or % export ESP_START="open -a /Applications/Firefox.app ../ESP/ESP.html" depending on the shell in use. The commands in other operating systems will differ slightly, depending on how the browser can be started from the command line. To run the program, use: % cd $DISROOT/bin % ./serveCSM ../data/tutorial1 3.1.2 Procedure 2: start the browser manually If the ESP_START environment variable does not exist, issuing the commands: % cd $DISROOT/bin % ./serveCSM ../data/tutorial1 will start the server. The last lines of output from serveCSM tells the user that the server is waiting for a browser to attach to it. This can be done by starting a browser (FireFox and GoogleChrome have been tested) and loading the file: $DISROOT/ESP/ESP.html Whether you used procedure 1 or 2, 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. 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: % cd $DISROOT/bin % ./serveCSM ../data/tutorial1 -port 7788 Once the browser starts, you will be prompted for a "hostname:port". Make the appropriate response depending on the network situation. Once the ESP GUI is functional, press the "help" button in the upper left if you want to execute the tutorial. 3.2 egads2cart This example takes an input geometry file and generates a Cart3D "tri" file. The acceptable input is STEP, EGADS or OpenCASCADE BRep files (which can all be generated from an OpenCSM "dump" command). % cd $DISROOT/bin % ./egads2cart geomFilePath [angle relSide relSag] 3.3 vTess and wvClient vTess allows for the examination of geometry through its discrete representation. Like egads2cart, the acceptable geometric input is STEP, EGADS or OpenCASCADE BRep files. vTess acts like serveCSM and wvClient should be used like ESP in the discussion in Section 3.1 above. % cd $DISROOT/bin % ./vTess geomFilePath [angle maxlen sag] 4.0 Building CAPS (Computational Aircraft Prototype Syntheses) CAPS requires the use of the Open Source Project UDUNITS2 for all unit conversions. Since there are no prebuilt package distributions for the Mac and Windows, the CAPS build procedure copies prebuilt DLL/DyLibs to the lib directory of ESP. Because most Linux distributions contain a UDUNITS2 package, this is not done under Linux and that package must be installed by the system procedure (based on the Linux flavor). This is done to avoid having two differing versions on the same system (which would only cause problems). For any of the operating systems, after properly setting the environment in the command window (or shell) and Building the core ESP, follow this simple procedure: % cd $DISROOT/src % make CAPS or C:\> cd $DISROOT\src C:\> make CAPS