ESP: The Engineering Sketch Pad Rev 1.11 -- 13 June 2017 1. Prerequisites The most significant prerequisite for this software is OpenCASCADE at release 6.6 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 -- use 6.6) and there are SBO robustness problems. 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, 7.0.0 and 7.1.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 SLUGS - the browser code for Slugs (web Slugs client) src - source files (contains EGADS, CAPS, wvServer & OpenCSM) training - training slides and examples udc - a collection of User Defined Components 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 (upgrading from Rev 1.08) and run on MAC OSX. 1.2.1 Known issues in v1.11: 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. 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 the OpenCASCADE runtime distribution can be found. MS Visual Studio is required and a command shell where the C/C++ compiler should be opened and the following executed in that window (note that MS VS 2008, 2010, 2012, 2013, 2015 and 2017 are all 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. If you are using MSVS 2010 with SDK 7.1 and get the message: C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\INCLUDE\intrin.h(26): fatal error C1083: Cannot open include file: 'ammintrin.h': No such file or directory This is a Microsoft bug and can be worked-around by placing an empty file 'ammintrin.h' in $DISROOT\src\EGADS\src 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_ROOT/ESP/ESP.html" or % export ESP_START="open -a /Applications/Firefox.app $ESP_ROOT/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, for example for Windows it may be: % set ESP_START=""C:\Program Files (x86)\Mozilla Firefox\firefox.exe" %ESP_ROOT%\ESP\ESP.html" 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 Python development package is required under Linux. 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 The execution of pyCAPS requires a single environment variable: PYTHONPATH is a Python environment variable that needs to have the path $DISROOT/lib included. 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). Also note that the bit size (32 or 64) of Python that gets used on Windows must be consistent with the build of ESP, now only 64bit. 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.