ESP: The Engineering Sketch Pad Rev 1.06 February 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. Also 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. 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. Note that there are some problems with Intel Graphics and some WebGL Browsers under LINUX. Also, for LINUX "zlib" development is required. 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 bin - a directly that will contain executables config - files that allow for automatic configuration data - test and example scripts doc - documentation ESP - Web code for the Engineering Sketch Pad lib - a directly that will contain libraries, shared objects and DLLs src - source files (contains EGADS, wvServer & OpenCSM) wvClient - simple examples of Web viewing 1.2 Release Notes 1.2.1 Changes to EGADS API: The modifications to the function signatures since v1.03 are displayed in red and can be seen in the documentation ($DISROOT/doc/egads.pdf). These include: EG_chamferBody, EG_filletBody, EG_hollowBody and EG_sweep. 1.2.2 Changes to OpenCSM scripting language since v1.05: User-defined components (UDCs) have been implemented to execute consistently with user-defined primitives (UDPs). The main difference is that UDCs are defined in scripts (in a file named *.udc) whereas UDPs are defined in C-code that is pre-compiled. The first argument of the "udprim" statement selects a UDC if it starts with a "/" or a "$/"; otherwise it looks for a UDP. The "interface" statement has been added to be used within UDCs to define the UDC's interface, including the default values for its arguments. The "join" command was added to combine Bodys at common Faces. Using the "join" command is preferred over the "union" command when the user expects some of the Faces to match exactly. The "store" and "restore" commands were added to keep copies of Bodys in memory (rather than in an external files, as was done for "dump" and "import"). The advantage is that the build tree information is retained, allowing Bodys to sometimes be reused during the regeneration process. The "extract" command has been added to extract a lower-dimension object (for example, an Edge from a Body). The "combine" command has been added to create a higher-dimension object (for example, a Faces from a group of Edges). The "assert" command has been added to return an error if the assertion is not satisfied. The direction vectors in the "noselist" and "taillist" arguments to the "blend" command no longer need to be normalized. If the arguments to the "subtract" command are a SOLID Body and a SHEET Body, then the SOLID Body is scribed with Edges at the intersection of the SOLID and SHEET. An optional argument (wireonly) has been added to the "skend" command; if wireonly is set to 1, then a (possibly non-planar) WIRE Body is created instead of a SHEET Body. Array elements can be addressed with a single subscript, which are numbered across rows. Names are allowed to include colons ":", which is useful for hierarchically organizing names. The "ifnan", "sign", "ceil", and "floor" functions have been added to the expression evaluator. ".nrow", ".ncol", ".size", ".sum", ".min", and ".max" dot-suffixes can be appended to variables to return properties of the Design Parameter of Local Variable rather than its value. Global attributes are placed on all Bodys. 1.2.3 Additional OpenCSM user-defined primitives since v1.05: The "naca456" UDP was added to create NACA-4, -5, and -6 series airfoils. A FORTRAN compiler is required and if not found, this UDP will not be built. 1.2.4 Changes to ESP since v1.05: Keyboard shortcuts were added to the ESP viewer: home (same as ) zoom in (same as ) zoom out (same as ) front view (same as ) top view bottom view leftside view riteside view When a Branch is edited in ESP, the first field associated with the Branch in the Tree window is colored magenta, the Branch's parents are colored cyan, and the Branch's child is colored yellow. When a Design Parameter is editted in ESP, the first field associated with the Parameter in the Tree window is colored magenta. If one selects another Branch or Parameter in the Tree window while editting another Branch or Parameter, the current edit is cancelled and the new edit started. Axes are displayed in ESP. Branches are indented (with ">") in Tree Window in ESP. 1.2.5 Known issues in v1.06: 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. The (leftside view) keyboard shortcut does not work in Safari (since it appears that Safari intercepts the before it gets to ESP). Test cases with the "hollow" command do not work when using the pre-built 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. There are two different 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_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 and 2013 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 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 WV_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 WV_START "open -a /Applications/Firefox.app ../ESP/ESP.html" or % export WV_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 WV_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]