ESP: The Engineering Sketch Pad Rev 1.09 -- August 2016 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, 6.9.1 and 7.0.0 have been released, but all of these have been found to be slightly less reliable than 6.8.0. 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 OSXnotes.txt - description of a major change in MAC builds (Rev 1.08) 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 externApps - the ESP connections to 3rd party Apps (outside of CAPS) include - location for all ESP header files lib - a directory that will contain libraries, shared objects and DLLs SlugsClinet - the browser code for Slugs src - source files (contains EGADS, CAPS, wvServer & OpenCSM) training15 - 2015 training slides and example code training16 - 2016 training slides wvClient - simple examples of Web viewing used by EGADS 1.2 Release Notes 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.08: CONPMTR to define a constant Parameter POINT for generating a Node (with its derivatives) GROUP for grouping Bodys for STORE, DUMP, and transformations; add associated @igroup at-Parameter IFTHEN, ELSEIF, ELSE, and ENDIF to conditionally control execution of Branches THROW, CATBEG, and CATEND to handle errors; also have statements throw errors that could be caught CSYSTEM and APPLYCSYS to generate and use coordinate systems Allow C1 or C0 continuity in BLEND command by duplicated sketeches; add oneFace=0 argument to BLEND Add ability to created rounded tips in BLEND command Add toler=0 and verify=0 arguments to ASSERT command Extend DUMP command to write .stl, .ugrid, .tess and .egg files Add toMark=0 argument to DUMP command Add useEdges=0 argument to PROJECT command Extend SELECT statement to allow a user to apply attributes to all Edges or Faces 1.2.2 Additional/modified OpenCSM user-defined primitives since v1.08: udfCreateBEM to create a BEM and associated file udfCreatePoly to write a .poly file udpPod to generate a pod (like in VSP) udpSample to act as a sample for new user-defined primitives Add sharpte argument to udpNaca Add sensitivities to udpParsec Add attributes to Faces in udpWaffle 1.2.3 Changes to ESP since v1.08: add --version command-line flag to return version add -verify and -addVerify command-line flags for verification execution and setup add -egg command-line flag to suppport external grid generator add -dict command-line flag to support dictionary of constant Parameters add -sensTess command-line flag to choose between configuration and tessellation sensitivities Configuration can be colored in Graphics Window if Face has "color" attribute Post messages in Message Window when ESP is started without a .csm file Add tooltips to ESP Clicking on Body name in Tree Window posts the Body's attributes Allow complete rebuild (without recycling) in ESP by pressing "Up to date" Add axis labels to axes in lower-left corner of Graphics Window Add (optional) light-grey axes centered at origin Allow user to expand/collapse Branch list in ESP Add "Show Attributes/Csystem" button in ESP Do not allow statements within a UDC to be edited in ESP Reorganize and update ESP-help Print mass properties (in serveCSM) for all Bodys on stack Quadrilaterals are generated (and visualized) if a Face has a _makeQuads attribute Add ocsmSetDtime, ocsmPrintEgo, ocsmGetNorm, ocsmRetCsys, ocsmGetCsys, and ocsmSetCsys functions to OpenCSM API Add support for an external grid generator (egg) to be used in place of the EGADS tessellator; add ocsmSetTess function to API Allow all lists to be input either as name of a multi-values Parameter or a semicolon-separated list of expressions Allow all command names to be specified either in lowercase or UPPERCASE Add global ID to all Edges and Faces Add Body, Face, Edge, and Node attribute printing in ocsmPrintBrep Update ocsmGetVel so that it returns vector sensitivities Add many new test cases, all with verification data Improve robustness of UNION when applied to SheetBodys Fix .ibody attribute for Edges associated with a Body that is restored more than once Fix .ibody attribute for Edges associated with FILLET, CHAMFER, HOLLOW, and CONNECT commands Fix .ibody attribute for Edges Fix ocsmGetUV and ocsmGetXYZ results when uv=NULL Fix several memory leaks Execute dimension checks at run-time (and not load-time) Fix bug that caused SELECT statements to be written incorrectly in ocsmSave Fix indentation for PATBREAK statement Fix bug associated with adding and editing a SELECT statement in ESP Fix bug associated with single digit attributes Fix sensitivity error for end-caps in EXTRUDEs, RULEs, and BLENDs Fix Face sensitivity info in udpBox Remove MACBEG, MACEND, and RECALL statements from ESP Mark Branch as dirty if an Attribute or Csystem changes Fix erroneous truncation of very long metadata in ESP 1.2.4 Changes to EGADS since v1.08: Support for C0 and C1 breaks in blend. Wingtip-like cap option for EG_blend. Addition of Coordinate Systems to the attribution of objects. Add the ability to create a TESSELLATION Object from external data. Support global indexing for TESSELLATION Objects. Copy Object now supports TESSELLATION Objects (optionally with displacements). 1.2.5 Known issues in v1.09: There is an error somewhere in OpenCASCADE's Solid Boolean Operators that causes "serveCSM tutorial1_new" to sometimes produce a segmentation fault (or other bizarre behavior) during rebuilds or sensitivity calculations. This behavior is OS/Compiler/OCC-revision dependent. 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. 1.3 For Release 1.10 The plan is to no longer support 32bit versions of ESP builds after this release. Please contact Bob Haimes is this will be a burden. 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 CAPS (Computational Aircraft Prototype Syntheses) Requirements 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, another procedure is used. If the package is loaded in the OS then nothing is done. If not loaded, then a static library is moved to the ESP lib directory. The use of a static library is to avoid having two differing versions of a shared object on the same system if installed later (which would only cause problems). 4.1 Python with CAPS (pyCAPS) Python may be used with CAPS to provide testing, general scripting and demonstration capabilities. The building of pyCAPS is turned on by 2 environment variables: PYTHONINC is the include path to find the Python includes for building PYTHONLIB is a description of the location of the Python libraries and the library to use For MACs and LINUX the configuration procedure inserts these environment variables with the locations it finds by executing the version of Python available in the shell performing the build. If makeEnv emits any errors related to Python, the resultant environment file(s) will need to be updated in order to use Python (the automatic procedure has failed). For Windows ESPenv.bat must be edited, the "rem" removed and the appropriate information set (if Python exists on the machine). Note that for Windows, the only Python version "certified" for use with CAPS is 2.7.5! Also note that the bit size (32 or 64) of Python that gets used on Windows must be consistent with the build of ESP. For Example on Windows (after downloading and installing Python on D:): set PYTHONINC=D:\Python27\include set PYTHONLIB=D:\Python27\Libs\python27.lib 4.2 3rd Party Environment Variables CAPS is driven by a plugin technology for the AIM (Analysis, Input and Meshing) modules. These AIMs allow direct coupling between CAPS and the external meshers and solvers. Many are built by default (where there are no licensing problems or other dependencies). The CAPS build subsystem will respond to the following (if these are not set, then the AIMs for these systems will not be built): AFLR (note please contact Bob Haimes if you have AFLR): AFLR is the path where the AFLR distribution has been deposited AFLR_ARCH is the architecture flag to use (MacOSX-x86-64, Linux-x86-64, WIN64) -- note that this is set by the config procedure AWAVE AWAVE is the location to find the FORTRAN source for AWAVE TETGEN TETGEN is the path where the TetGen distribution has been unpacked 4.3 The Cart3D Design Framework The application ESPxddm is the ESP connection to the Cart3D Design Framework. On LINUX this requires that the libxml2 development package be installed. If it is, then ESPxddm is built, otherwise it is not. 4.4 Building CAPS 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 for Windows: C:\> cd $DISROOT\src C:\> make CAPS 4.5 Documentation The CAPS documentation can be seen in PDF form from within the directory $DISROOT/doc/CAPSdoc. Or in html by $DISROOT/doc/CAPSdoc/html/index.html.