1 Introduction

1.1 License and Copyright

InsightCAE is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License1 as published by the Free Software Foundation. You accept the terms of this license by distributing or using this software.

This manual is Copyright (c) 2017-2021 silentdynamics GmbH.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ”GNU Free Documentation License”.

1.2 About InsightCAE

InsightCAE is a framework for building automated analysis and design workflows in Computer-Aided Engineering with a preference for open source tools.

Individual open source projects often meet only subtasks in an analysis process and have very different APIs. To conduct computational tasks, a combination of several software tools is often required. In order to use open source software productive and efficient for everyday tasks, the analysis automation framework InsightCAE was created.

InsightCAE serves as a framework for the implementation of analysis procedures. The objective is to provide adapters and interfaces to the tools and simulation programs that are needed for a specific computing task.

Some common use cases are:

1.3 Contributors

The following people have so far contributed to InsightCAE:

If you want to get involved in the development, please feel invited to do so! We greatly appreciate any contribution and we would very much like to add you to the above list.

If you made some modification or addition to the code, which you would like to be merged into the main development line, please consider to send us a pull request2 .

1.4 Features and Highlights

InsightCAE’s objective is to create automated analysis workflows. The high level API resides in the core ”toolkit” library. Automated workflows usually involve different external programs and utilities. For the realization of automated workflows, it is sometimes required, to create add-ons to these external programs. Thus InsightCAE is also a container for add-ons to other programs.

1.5 Reading this Manual

1.6 Recommendations for Working with Shell-based Tools in Linux

Sometimes it is necessary to execute tools in a bash shell, e.g. because no GUI for it is available. And often it is easier to keep an overview in graphical file manager. Having a console window open together with a file manager window at the same time is an obvious solution but to do so for many cases at a time may easily confuse the desktop.

Here are two useful hints to solve this issue:

  1. The KDE file manager dolphin offers the possibility to display a console in the lower half of the window (figure 1). The working directory is synchronized with the directory shown in the graphical window by injection of cd commands. Vice versa, when the working directory is changed in the shell, the graphical display is updated as well.

    Figure 1:Dolphin file manager with embedded terminal

  2. There is a Norton-Commander-like file manager named krusader (figure 2). It offers the same functionality regarding the embedded terminal but a more flexible way of displaying multiple folders. In addition to the two list view on the left and right, multiple tabs for folders can be added in each list view. And there is also a rich interface to define custom commands and file associations.

    Figure 2:Krusader file manager with embedded terminal

2 Resources

2.1 In the Web

2.2 Reporting Bugs and Feature Requests

Please use the issue tracker https://github.com/hkroeger/insightcae/issues to report any bugs.

We also monitor the web forum https://groups.google.com/forum/#!forum/insightcae for questions or feature requests.

2.3 Getting Professional Help and Support

Beyond the web resources above, silentdynamics GmbH offers commercial support3 for professional users of InsightCAE. Automated analyses according to customer needs and specifications are implemented by creating new specialized modules for Insight CAE. Typical support contracts include also user training and continuous customization and updating of InsightCAE and its add-ons.

3 Obtaining InsightCAE

3.1 Installation using Linux Package Manager

We provide binary installation packages for Ubuntu-based Linux distributions. We specifically support the latest Ubuntu LTS distibution.

The packages are held in our repository. To install them, first add the silentdynamics apt repository and the associated key by executing:

1$ sudo apt-key adv --fetch-keys http://downloads.silentdynamics.de/SD_REPOSITORIES_PUBLIC_KEY.gpg 
2$ sudo add-apt-repository http://downloads.silentdynamics.de/ubuntu 
3$ sudo apt-get update

Then, install the software by executing

1$ sudo apt-get install insightcae-ce

Continue with preparing the environment according to section 3.4

3.2 Installation on Windows

Currently, there is no native Windows version of InsightCAE available. However, it can be run in Windows 10 Enterprise (64 bit only) or Windows Server using the ”Linux Subsystem for Windows” (WSL). This should be preferred over virtualization solutions like VirtualBox, because it offers the best parallel performance. The processes share the memory with the Windows processes and the files are stored in the Windows file system. Various X servers are available for graphical output under Windows; Xming is used below.

To use this solution, the Linux subsystem must first be activated. Adminstration privileges are required. It is done by the following steps:

Start Windows PowerShell as an administrator (right-click on Start menu >”PowerShell (Admin)”) and execute:

1> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Restart the computer when prompted.

Download the Linux image:

1> Invoke-WebRequest -Uri https://aka.ms/wsl-ubuntu-1804 -OutFile ~/Ubuntu.zip -UseBasicParsing


1> Expand-Archive ~/Ubuntu.zip c:\Distros\Ubuntu

Configuring the Linux System: Switch to user ”root”:

1> c:\Distros\Ubuntu\ubuntu.exe config --default-user root

Set the password of the user ”user”:

1> c:\Distros\Ubuntu\ubuntu.exe 
2# passwd user

Install InsightCAE with OpenFOAM:

1# echo deb http://downloads.silentdynamics.de/ubuntu bionic main > /etc/apt/sources.list.d/sd.list 
2# apt-key adv --fetch-keys http://downloads.silentdynamics.de/SD_REPOSITORIES_PUBLIC_KEY.gpg 
3# apt-get update 
4# apt-get install insightcae-base

Switch back to standard user (”user”):

1> c:\Distros\Ubuntu\ubuntu.exe config --default-user user

Add the file c:DistrosUbuntuubuntu.exe to the start bar

Then install the Xming server for graphical output:

Download Xming-Installer4 , then execute the installer:

Set the DISPLAY variable in the Bash environment

1$ sudo -i 
2# echo "export DISPLAY=:0" >> /etc/profile.d/xming.sh 
3# exit

Usage First start ”Xming” X-Server, then start Ubuntu Bash command line. Execute the application in the shell, e.g. the InsightCAE Workbench:

1$ workbench

3.3 Building from Sources

The source code of InsightCAE is hosted at Github. Cloning a working copy constitutes the best way to get updates and the latest bug fixes.

Alternatively, you can download snapshot archives from github, if you don’t want to bother with a git client. In this case, just replace the cloning step below with unpacking the archive.

First, get the the sources by cloning the git repository:

1$ git clone https://github.com/hkroeger/insightcae.git insight-src

CMake is utilized for managing the build. The preferred way is to build the software out of source in a separate build directory. Create a build directory, then configure the build using e.g. ccmake and finally build using make:

1$ mkdir insight && cd insight 
2$ ccmake ../insight-src

In the CMake GUI, you may need to change paths or adapt settings. Please refer to the CMake documentation5 on how to use CMake. The biggest difficulty will probably be, to provide all the software packages, on which InsightCAE depends.

The final step in CMake is, to generate the Makefiles. Once this is done without errors, start the compilation of the project by executing:

1$ make

To work with InsightCAE, some environment variables are needed to be set up. A script is provided therefore. It can be parsed e.g. in your ~/.bashrc script by adding to the end:

1source /path/to/insight/bin/insight_setenv.sh

3.4 Setting up the Snvironment

To set up the environment variables and search paths required by the InsightCAE components, a script needs to be parsed. This is conveniently added to the shell startup script file ~/.bashrc. Add the following line to the beginning of the ~/.bashrc file:

1source /opt/insightcae/bin/insight_setenv.sh

Note that the default contents of this file differs between linux distributions. Sometimes it contains statements which prematurely end its evaluation for non-interactive shells. This

4 Overview

4.1 Concept and Parts of the Project

The InsightCAE builds on top of available open-source engineering analysis tools (though closed-source tools could be used as well). The most used tool by far is the CFD software OpenFOAM.

For certain tasks, custom extensions to these tools are required. InsightCAE contains a selection of extensions, which are included in the distribution packages, when these are created.

The core of the project is the toolkit library. It contains the implementation of core classes in workflow management as the parameter set storage and tools and result set storage classes and handling tools. The toolkit library also maintains a list of available analysis modules, which is dynamically extensible by loadable add-ons.

Finally, on top of the toolkit library, custom analysis modules can be created. The InsightCAE base distribution contains a number of generic analysis modules as the ”Numerical Wind Tunnel” module and some generic test case analyses like flat plate, channel flow, pipe flow and so on. These might serve as examples for custom implementations.


Figure 3:Structure of the InsightCAE project

4.2 Terms and Defintions

Analysis InsightCAE bundles tools to create automated simulation procedures. These procedures can be written in Python or C++. The term analysis or workflow module is used for such a procedure.

Actually, an analysis is like a function in programming: it gets input parameters, executed some actions and returns a results data structure.

Parameter Set The analysis modules need input data, i.e. parameters. All parameters for a module are grouped together in a parameter set. Parameter sets are stored in XML files in human readable format (extension *.ist). They can also be edited in a GUI editor (application workbench).

Many analysis modules need external files (like CAD data in STL or any other format). These files can simply be referred in a parameter set by their relative path (relative to the *.ist-file containing the reference) or absolute path. It is also possible to embed the external files into the XML file in an base64-encoded form. This simplifies transfer of analysis setup from one computer to another, e.g. for remote execution.

Result Set The result of an analysis is returned in a result set. This is a hierarchical data structure which contains nodes like scalar values, charts, contour plots, images, tables or similar entities. It can be stored on disk in XML format. There is also a renderer which converts a result set into a PDF report.

Case Element The setup of CFD-runs is put together from a number of so-called case elements. Each case element represents some functional feature. It might be a boundary condition or a turbulence model or something similar. A case element is not necessarily associated with a certain configuration file but can modify multiple configuration files of a CFD case configuration.

There is also an editor for composing OpenFOAM cases from the available case elements: the OpenFOAM Case Builder.

5 Automation of Simulation Workflows

5.1 Building Bricks

5.1.1 Input: Parameter Sets

Parameter sets are a hierarchical collection of parameters. Parameters can be of different type, see table 1 for a list.

A parameter set constitutes the full input data set for an analysis.

Beyond these primitive parameter types, there can be compounds, namely:

Type Description

double a scalar floating point value
int an integer value
bool a boolean value
vector a 3-tuple of doubles
string a simple text
selection a selection from a predefined set
path a file path, relative to the input file
matrix a matrix with arbitrary number of rows and cols
doublerangean array of double values

Table 1:Available primitive parameter types in a parameter set
5.1.2 Output: Results Sets

The output of an analysis is stored in a result set. It may contain elements like charts, images, tables, number etc. A result set can be saved to a XML file and/or rendered into a PDF report.

5.1.3 Analyses: the Simulation Procedure

The procedure of a simulation is contained in a so-called analyses or workflow module. You may think of it as an app for executing a certain type of simulation. It is essentially a program. Oftentimes, people create scripts or macros for speeding up their simulation workflows. The InsightCAE workflow modules serve a similar purpose, though the intention is to fully cover the whole simulation including all pre and post processing steps.

There is a GUI available which provides an editor for the input parameter set (see section 5.2.1). The GUI is also capable of displaying a 3D preview of the involved geometry and other elements, which are displayable. The analysis module is responsible of creating the 3D preview elements. Creation of the preview is optional and not every analysis module produces a preview.

The GUI also includes a viewer for the result set. From that viewer, the reports may be exported.

InsightCAE holds a runtime-extensible list of available analyses. This list can be extended at run time either by providing shared libraries containing more analysis modules or by python scripts.

The analyses can be programmed essentially in C++ or in Python. InsightCAE is essentially written in C++. Python wrappers for the relevant functions and objects are created using SWIG. So the API can also be accessed from Python.

If a new analysis shall be created, this parameter editing and result viewing infrastructure is easily reusable:

The analysis modules may group themselves into categories. This is used in the initial analysis creation dialog in the GUI.

Python Script A python based analysis comprises a single dedicated python script file. The InsightCAE functions are included by an initial statement like from Insight.toolkit import *.

This script needs to define three standalone functions:

  1. category()

    This functions returns a plain string with the category of the analysis. Multiple hierarchy levels are supported and have to be separated by slashes.

  2. defaultParameters()

    This function shall return an object of type ParameterSet, containing the default values of all the needed parameters. The user cannot add or delete parameters, just modify their values. So this defines the layout.

  3. executeAnalysis(parameters, workdir)

    This function finally runs the simulation. It gets an object of type ParameterSet, containing all the input parameters and the string workdir, which contains the execution directory.

Upon loading, the InsightCAE base library searches in

for files named *.py. Each of these files will be loaded and their defined analyses will become available in the GUI and all other InsightCAE tools.

C++ In C++, a new analysis is derived from the common base class Analysis. The necessary functions have to be overridden. The new analysis should be put into a dedicated shared library.

Upon loading, the InsightCAE base library searches in

for files named *.module. Each of these files has to contain a statement library <FILENAME>, where FILENAME is the name of the shared library file. These libraries will all be loaded and their defined analyses will become available in the GUI and all other InsightCAE tools.

5.2 User Front Ends

5.2.1 GUI: workbench

The GUI for editing analysis parameters, run analyses and monitor their progress and to review the result sets is called workbench.

It can be started from the command line by executing

1$ workbench

or from the global application menu.

The workbench can open and handle multiple analyses at a time. For each analysis, a sub window is opened (analysis form).

An analysis can either be created from scratch (see “Creating a New Analysis”) or by opening an existing analysis input file (select

SVG-Viewer needed.

SVG-Viewer needed.

in the menu).

The analysis form has three tabs. From left to right: the input parameter edit tab, the progress display tab and the result viewer tab.

Editing the Input Parameters The parameter input tab is shown in figure 5. On the left, there is a tree view showing all the available parameters of the analysis. The font display style of the parameter entry denotes the importance of the parameter:

The parameters can be selected my mouse click and edited (see “Modifying a Parameter”).

Some analyses (this is optional) support a 3D preview of the configured case. When an analysis is loaded, which supports 3D preview, a 3D view and a 3D element tree appears right of the parameter edit column. All views in the Input tab are shown in a horizontal splitter and their width can be adapted by dragging the splitter handle between them. It is also possible to hide the 3D preview widgets by collapsing their width to zero using the splitter handle (This might also occur accidentally). The collapsing can be undone by locating the splitter handle of the collapsed widget and dragging it back to some non-zero width. The layout of the splitter is saved on program exit and restored on the next start.

Saving Parameters Once all parameters are edited, the parameter set can be saved to a file. Very often, external files are referenced from a parameter set. Since it is also often necessary, to relocate parameter sets from one computer to another or between directories, InsightCAE parameter sets provide some special features which shall simplify relocation of parameter sets:

Running the Analysis With a properly edited parameter set, the analysis run can be started. This is achieved by clicking on the button ”Run” on the right side or by selecting

SVG-Viewer needed.

SVG-Viewer needed.

in the menu. This analysis form switches automatically to the ”Run” tab (see figure 6). In the lower half, the log message are displayed. Sometimes, errors in an external program occur and are not correctly reported. It is therefore a good practice to watch the log messages for errors or warnings.

When the simulation solver runs, InsightCAE shows progress variables graphically. The plots are shown above the log widget. The number and meaning of the progress variables depend on the analysis conducted.

Especially for OpenFOAM-bases analyses, a number of quantities are extracted from solver output and forwarded to the GUI as progress variables:

Cancel a Simulation To cancel a simulation run, click on the button ”Kill” on the right side or by select

SVG-Viewer needed.

SVG-Viewer needed.

in the menu.

Viewing the Results Once the simulation run is finished (that means that the solver has finished and that all post processing steps are done), a result set is created and loaded into the workbench. It is displayed in the ”output” tab (see figure 7). The result set can be rendered into a report (see “Rendering Results into a Report”).

Rendering Results into a Report

Modifying a Parameter

Creating a New Analysis A new analysis is created by selecting in the menu

SVG-Viewer needed.

SVG-Viewer needed.

. Then a new dialog appears, in which the list of available analyses is displayed (figure 4). The required analysis should be selected and confirmed by clicking ”Ok”.


Figure 4:Dialog for selection of the type of a new analysis


Figure 5:Parameter editing tab of the workbench


Figure 6:Solution progress tab of the workbench


Figure 7:Result explorer tab of the workbench

5.2.2 Console on Headless Computers: analyze

5.3 Available Simulation Workflows

5.3.1 Numerical Wind Tunnel

5.3.2 Internal Pressure Loss

6 Supporting Simulations with OpenFOAM

6.1 Case Setup GUI: isofCaseBuilder

6.2 Execution Monitor GUI: isofExecutionManager

6.3 Tabular Output Data Plot: isofPlotTabular

7 Extensions to Back-End-Tools

7.1 OpenFOAM

8 InsightCAD

8.1 Introduction

InsightCAD is a script-based tool for creating three-dimensional geometry models. All geometric operations are based on the OpenCASCADE geometry kernel. It uses the boundary representation approach (BREP) for treating the geometry. Thus it is possible to import and export the common exchange formats IGES and STEP.

Although the primary intention of InsightCAD is creation of fully parameterized CAD models for systematic numerical simulations, it can also be used for mechanical design purposes. It therefore provides the possibility to export projections and sections of the created models in DXF format for use in drawings. Additionally, there is support for a library of parametric standard parts.

8.2 Basic Concept

The basic entity in InsightCAD is a ”model”. A model is described by a script and stored in an ASCII script file (extension ”.iscad”). Inside a model script, symbols are defined, which can represent the following data types:

There is no explicit type declaration: the data type of each symbol is deduced from the defining expression.

Beyond their geometry representation, geometry feature objects are containers for scalar, vector, datum and feature objects. These symbols can be accessed in the model script but are read-only.

In a model script, after the definition of the aforementioned symbols, an optional section with postprocessing actions can follow. These can be e.g. file export, drawing export or others.

General CAD Model Script Syntax The general model script layout begins with a mandatory symbol defining section, followed by an optional postprocessing section, started by ”@post”:

1<identifier> [ = | ?= | : ] <expression>; 
6<postprocessing action>; 

Comments are lines starting with ”#” or text regions enclosed by ”/*” and ”*/” (C-style).

8.3 Submodels and Subassemblies

It is possible to load another model into the current one by the ”loadmodel” command (see section ”Features”). In this case, the loaded model represents a subassembly, i.e. a compound of features. Since not all defined geometry objects in the submodel may represent assembly components, marking of components is supported by the feature definition syntax and needs to be utilized properly in the definition script of the submodel. Also, when loading models (subassemblies), parameters can be passed to the submodel. These can be scalars, vectors, datums or features.

8.4 Symbol Definition

8.4.1 Scalars


1D ?= 123.5; 
2L = 2.*D;

The ”?=” operator assigns a default value. This needs to be used for symbols which are intended to be used as parameters in the ”loadmodel” feature command. Symbols defined by the equal sign operator (”=”) cannot be overridden during the loadmodel command.

Supported operations are listed in table 2.

InsightCAD script Description

+ - * / basic algebra
mag(⟨ vector⟩ ) magnitude of vector
sqrt(⟨ scalar⟩ ) square root
sin(⟨ scalar⟩ ) sin(x)
cos(⟨ scalar⟩ ) cos(x)
tan(⟨ scalar⟩ ) tan(x)
asin(⟨ scalar⟩ ) arcsin(x)
acos(⟨ scalar⟩ ) arccos(x)
ceil(⟨ scalar⟩ ) smallest following integer
floor(⟨ scalar⟩ ) largest previous integer
round(⟨ scalar⟩ ) round to next integer
pow(⟨ scalar:a⟩ , ⟨ scalar:n⟩ ) aˆn
atan2(⟨ scalar:y⟩ , ⟨ scalar:x⟩ )arctan(y/x)
atan(⟨ scalar⟩ ) arctan(x)
volume(⟨ feature⟩ ) volume of feature
cumedgelen(⟨ feature⟩ ) sum of all edges lengths
⟨ vector⟩ .x x component of vector
⟨ vector⟩ .y y component of vector
⟨ vector⟩ .z z component of vector
⟨ feature⟩ $ ⟨ identifier⟩ scalar property of feature
⟨ vector⟩ & ⟨ vector⟩ Scalar product

Table 2:Algebraic operations in ISCAD scripts

There are scalars predefined in each model. They are included in table 5.

8.4.2 Vectors


1v ?= 5*EX + 3*EY + [0,0,1]; 
2ev = v/mag(v);

The ”?=” operator assigns a default value. This needs to be used for symbols which are intended to be used as parameters in the ”loadmodel” feature command. Symbols defined by the equal sign operator (”=”) cannot be overridden during the loadmodel command.

Supported operations are listed in table 3.

InsightCAD script Description

+ - basic algebra
[⟨ x⟩ , ⟨ y⟩ , ⟨ z⟩ ] vector from components
⟨ feature⟩ @⟨ vector⟩ vector property of feature
⟨ scalar⟩ *⟨ vector⟩ scaled vector
⟨ vector⟩ /⟨ scalar⟩ scaled vector
⟨ vector:a⟩ ˆ⟨ vector:b⟩ Cross product ⃗a× ⃗b
bbmin(⟨ feature⟩ ) minimum corner of feature bounding box
bbmax(⟨ feature⟩ ) maximum corner of feature bounding box
cog(⟨ feature⟩ ) center of gravity coordinates of feature
refpt(⟨ datum⟩ ) reference point of datum (base point of axis or plane)
refdir(⟨ datum⟩ ) reference direction of datum (direction of axis or normal of plane)

Table 3:Vector operations and functions in ISCAD scripts

There are vectors predefined in each model. They are included in table 5.

8.4.3 Datums

Some simple examples are given below.

1myaxis ?= RefAxis(O, EX+EY); # diagonal axis 
2myplane = Plane(5*EX, EY); # offset plane 
3myplane2 = XZ << 5*EX; # same offset plane 
4axis2 = xsec_plpl(XY, myplane); # axis at intersection of XY-Plane and offset plane

The ”?=” operator assigns a default value. This needs to be used for symbols which are intended to be used as parameters in the ”loadmodel” feature command. Symbols defined by the equal sign operator (”=”) cannot be overridden during the loadmodel command.

Supported operations are listed in table 4.

InsightCAD script Description

⟨ feature⟩ %⟨ identifier⟩ Access datum inside another feature.
⟨ datum⟩ << ⟨ vector:⃗Δ  ⟩ Copy of datum, translated by Δ⃗
Plane(⟨ vector:p0⟩ , ⟨ vector:n⟩ )
Datum plane with origin p0 and normal n.
SPlane(⟨ vector:p0⟩ , ⟨ vector:n⟩ , ⟨ vector:e_up⟩ )
Additionally, the y-direction of the plane CS is aligned with ⃗eup  .
RefAxis(⟨ vector:p0⟩ , ⟨ vector:e_x⟩ )
Axis with origin p0 and direction ⃗ex  .
xsec_axpl(⟨ datum:ax⟩ , ⟨ datum:pl⟩ )
Datum point at intersection between axis ax and plane pl
xsec_plpl(⟨ datum:pl1⟩ , ⟨ datum:pl2⟩ )
Datum axis at intersection between plane pl1 and pl2
xsec_ppp(⟨ datum:pl1⟩ , ⟨ datum:pl2⟩ , ⟨ datum:pl3⟩ )
Datum point at intersection between three planes

Table 4:Vector operations and functions in ISCAD scripts

There are datums predefined in each model. They are listed in table 5.

InsightCAD scriptDescription

M_PI π
deg Conversion factor from degrees to radians (180∕π  )
EX Unit vector in X direction             T
⃗ex = (1 0 0)
EY Unit vector in Y direction ⃗e = (0 1 0)T
EZ Unit vector in Z direction ⃗e  = (0  0 1)T
O Origin ⃗O = (0 0 0)T
XY X-Y-Plane
XZ X-Z-Plane
YZ Y-Z-Plane

Table 5:Predefined symbols (scalars, vectors and datums) in ISCAD scripts
8.4.4 Features

A very simple example is given below. It consists of two primitive features (cylinder) and a boolean operation (subtraction).

1tool = Cylinder(-10*EY, 10*EY, 2); 
4Cylinder(O, 20*EX, 10, centered) 

Geometry symbols can be defined by a ”=” or a ”:” operator. The difference comes from a possible use of the model as a subassembly later on. Since usually not all defined features in a model are assembly components but some are only intermediate modeling steps, there are these two syntaxes for defining a feature with a subtle difference: ”⟨ identifier⟩ = ⟨ expression⟩ ;” defines an intermediate feature while ”⟨ identifier⟩ : ⟨ expression⟩ ;” does the same geometry operation but marks the result as being an assembly component. In the above example, only the feature ”pierced_cylinder” is marked as a component. Thus if the above example would be loaded as a subassembly, only the ”pierced_cylinder” will be shown and included in e.g. mass calculations.

InsightCAD script Description

⟨ feature:a⟩ - ⟨ feature:b⟩ Boolean subtract of feature b from feature a
⟨ feature:a⟩ | ⟨ feature:b⟩ Boolean unite of feature a and feature b
⟨ feature:a⟩ & ⟨ feature:b⟩ Boolean intersection of feature a and feature b
⟨ feature⟩ << ⟨ vector:delta⟩ Copy of feature, translated by vector delta
⟨ feature⟩ * ⟨ scalar:s⟩ Copy of feature, scaled by s (relative to global origin O)
⟨ feature⟩ .⟨ identifier:subfeatname⟩ Access of subfeature
Table 6:Vector operations and functions in ISCAD scripts

8.5 Feature Commands

In this section, an incomplete subset of the avilable feature commands is described in detail. For a complete list, please refer to the online documentation in the iscad editor (press Ctrl+F).

8.5.1 Transformation

Transform(⟨ feature:f⟩ , ⟨ vector:delta⟩ , ⟨ vector:phi⟩ )

Transformation of feature f. Translation by vector delta and rotation around axis vector phi (magnitude of phi gives rotation angle).

Place(⟨ feature:f⟩ , ⟨ vector:p_0⟩ , ⟨ vector:e_x⟩ , ⟨ vector:e_z⟩ )

Places the feature f in a new coordinate system. The new origin is at point ⃗p0  , the new x-axis along vector ⃗ex  and the new z-direction is ⃗ez  .

8.5.2 Import

import(⟨ path⟩ )

Imports solid geometry from a file. The format is recognized from the filename extension. Supported formats are IGS, STP, BREP.

Sketch(⟨ datum:pl⟩ , ⟨ path:file⟩ , ⟨ string:name⟩ [, ⟨ identifier⟩ =⟨ scalar⟩ , ... ])

Reads a sketch (i.e. a singly closed contour) from a file. The geometry in the sketch is expected to be drawn in the X-Y-Plane. It is placed on the given plane pl. Sketch file format is recognized from the file name extension. Supported are ”.dxf” and ”.fcstd” (FreeCAD). The name is interpreted as layer name in DXF and sketch name in FreeCAD files.

For FreeCAD sketches, a list of parameter values can optionally be supplied. Upon loading, the sketch will be regenerated through FreeCAD with these values.

loadmodel( ⟨ identifier:modelname⟩ [, ⟨ identifier⟩ = ⟨ feature⟩ | ⟨ datum⟩ | ⟨ vector⟩ | ⟨ scalar⟩ , ... ] )

Parses another InsightCAD model (submodel) and inserts a compound of all features into the current model, which were marked as components in the submodel (i.e. which were defined with the colon ”:” operator instead of the equal sign ”=” in the submodel).

The model filename has to be ”⟨ modelname⟩ .iscad”. It is searched for in the following directories:

  1. the directories listed in the environment variable ”ISCAD_MODEL_PATH” (separated by ”:”)
  2. the subdirectory ”iscad-library” in InsightCAEs shared file directory
  3. in the current directory

Optionally, a list of symbols is inserted into the namespace of the submodel (additional optional parameters).

8.5.3 Geometry Construction

Primitives There are commands for creation of several different geometrical primitives, e.g.

Extrusion(⟨ feature:f⟩ , ⟨ vector:L⟩ [, centered ] )

Extrude the feature f with direction and length vector L. When the keyword ”centered” is given, the extrusion is centered around f.

Revolution( ⟨ feature:f⟩ , ⟨ vector:p_0⟩ , ⟨ vector:axis⟩ , ⟨ scalar:phi⟩ [, centered] )

Creates a revolution of the planar feature f. The rotation axis is specified by origin point ⃗p0  and the direction vector axis. Revolution angle is specified by phi. By giving the keyword ”centered”, the revolution is created symmetrically around the base feature.

Other Feature Commands There are more features available. A comprehensive list is obtained by pressing Ctrl+F in the iscad editor.

8.6 Lower Dimensional Shape Selection

ISCAD supports rule based selection of lower dimensional features (i.e. edges or faces of a solid). The selection is generated by a selection command: a question mark, followed by the type of shape to query. The result is a selection object:

1<feature expression|feature selection>?(vertices|edges|faces|solids);(<commandstring> [, parameter 0 [, ..., parameter n] ] )

It is possible to supply additional arguments to the selection expression, like scalars, vectors or features.

An example: the following expression selects the circumferential face of the cylinder c (all faces, which are not plane) and stores the selection in ”shell_faces”:

1c = Cylinder(O, 5*EZ); 
2shell_face = c ? faces(!isPlane); 
3min_end_face = c ? faces(isPlane&&minimal(CoG.z));

The selection command string contains rules for the selection. Finally, the command string is evaluated as a boolean expression comprising comparison operators, boolean operators and query functions. Within these boolean expressions, quantity functions can be used. The available set of query functions and quantity functions depends on the type of shape which shall be queried.

Boolean expressions available for all kinds of lower dimensional shapes are listed in table 7.

Quantity functions available for all kinds of lower dimensional shapes are listed in table 8.

Command Description

==, <, >, >=, <= value comparison
! not
&& and
|| or
⟨ value 1⟩ ˜ ⟨ value 2⟩ {⟨ tolerance⟩ }approximate equality
in(⟨ selection set⟩ ) true if shape is in other selection
maximal(⟨ quantity⟩ ) true for the shape with maximum quantity
minimal(⟨ quantity⟩ ) true for the shape with minimum quantity

Table 7:General boolean functions and operators available for all kinds of lower dimensional shape

Command Description

angleMag(⟨ vec 1⟩ , ⟨ vec 2⟩ )angle between vec 1 and vec 2
angle(⟨ vec 1⟩ , ⟨ vec 2⟩ ) angle between vec 1 and vec 2
%d⟨ index⟩ parameter ⟨ index⟩ as scalar
%m⟨ index⟩ parameter ⟨ index⟩ as vector
%⟨ index⟩ parameter ⟨ index⟩ as selection set

Table 8:General quantity functions available for all kinds of lower dimensional shape
8.6.1 Vertices

There are no special boolean functions or operators for vertices.

The available quantity functions for vertices are listed in table 9.


loc location of the vertex

Table 9:Quantity functions available for vertex selections
8.6.2 Edges

Boolean functions for edges are listed in table 10.

The available quantity functions for edges are listed in table 11.

Command Description

isLine true, if edge is straight
isCircle true, if edge is circular
isEllipse true, if edge is elliptical
isHyperbola true, if edge is on a hyperbola
isParabola true, if edge is on a parabola
isBezierCurve true, if edge is a bezier curve
isBSplineCurve true, if edge is a BSpline curve
isOtherCurve true, if edge is none of the above
isFaceBoundary true, if edge is boundary of some face
boundaryOfFace(⟨ set⟩ )true, if edge is boundary of one of the faces in set
isPartOfSolid(⟨ set⟩ ) true, if edge is part of one of the solids in set
isCoincident(⟨ set⟩ ) true, if edge is coincident with one of the edges in set
isIdentical(⟨ set⟩ ) true, if edge is identical with one of the edges in set
projectionIsCoincident(⟨ set⟩ , ⟨ vec:p0⟩ , ⟨ vec:n⟩ , ⟨ vec:up⟩ , ⟨ scalar:tol⟩ )
true, if projection of edge is coincident with some edge in set

Table 10:Boolean functions available for edge selections


len length of edge
radialLen(⟨ vec:ax⟩ , ⟨ vec:p0⟩ )
radial distance between ends with respect to axis (p0,ax)
CoG center of gravity of edge
start start point coordinates
end end point coordinates

Table 11:Quantity functions available for edge selections
8.6.3 Faces

Boolean functions for faces are listed in table 12.

The available quantity functions for faces are listed in table 13.

Command Description

isPlane true, if is a plane
isCylinder true, if is a cylindrical surface
isCone true, if is a conical surface
isSphere true, if is a spherical surface
isTorus true, if is a toroidal surface
isBezierSurface true, if is a bezier surface
isBSplineSurface true, if is a BSpline surface
isSurfaceOfRevolution true, if is a surface of revolution
isSurfaceOfExtrusion true, if is a surface of extrusion
isOffsetSurface true, if is a offset surface
isOtherSurface true, if is some other kind of surface
isPartOfSolid(⟨ set⟩ )
isCoincident(⟨ set⟩ )
isIdentical(⟨ set⟩ )
adjacentToEdges(⟨ set⟩ )
adjacentToFaces(⟨ set⟩ )

Table 12:General boolean functions available for face selections


area area of the face
CoG center of gravity of the face
cylRadius radius of a cylindrical face
cylAxis axis direction of a cylindrical face

Table 13:Quantity functions available for face selections
8.6.4 Solids

There are no special boolean functions or operators for solids.

The available quantity functions for solids are listed in table 14.


CoG center of gravity
volume volume of the solid

Table 14:Quantity functions available for solid selections

8.7 Postprocessing Actions

8.7.1 Drawing Export

DXF(⟨ path:outputfile⟩ ) << ⟨ feature:f⟩ ⟨ view_definition⟩ [, ⟨ view_definition⟩ , ... ]

The DXF postprocessing action creates a DXF file for further use in drawings. Several views are derived from the feature f. A ⟨ view_definition⟩ takes the following form:

1<identifier:viewname> ( 
2<vector:p_0>, <vector:n>, up <vector:e_up> 
3 [, section] 
4 [, poly] 
5 [, skiphl] 
6 [, add [l] [r] [t] [b] [k] ] 
7 )

It defines a view on the point vector ⃗p0  with normal direction vector ⃗n  of the view plane. The upward direction (Y-direction) is aligned with vector ⃗eup  .

The keyword ”section” toggles whether only the outline is projected or if the view plane creates a section through the geometry.

If keyword ”poly” is given, the DXF geometry will be discretized. This is more robust but creates much larger DXF files.

Keyword ”skiphl” toggles whether hidden lines are output.

The keyword ”add” followed by the key letters l, r, t, b and/or k enables creation of additional projections from the left, right, top, bottom and/or back, respectively.

An example is given below:

1c: Cylinder(O, 100*EX, 20); 
5DXF("c.dxf") << c 
6   top ( O, EX, up EY ) 
7   front ( O, EZ, up EY ) 

8.7.2 Mesh Creation

gmsh(⟨ path:outputfile⟩ ) << ⟨ feature:f⟩ as ⟨ identifier:l⟩ ⟨ mesh_parameters⟩

Generates a (triangular or tetrahedral) mesh for an FEA analysis of the feature f. Gmsh is used as a meshing backend. The mesh format is determined by the outputfile extension (.med = MED format). The label of the mesh is set to l.

The syntax of the ⟨ mesh_parameters⟩ are as follows:

1L = ( <scalar:Lmax> <scalar:Lmin> ) 
3vertexGroups( [ <identifier:group name> = <vertex set> [ @ <scalar:size> ], ... ] ) 
4edgeGroups( [ <identifier:group name> = <edge set> [ @ <scalar:size> ], ... ] ) 
5faceGroups( [ <identifier:group name> = <face set> [ @ <scalar:size> ], ... ] ) 
6[ vertices ( [ <identifier:vertex name> = <vector:location> ], ... ) ]

The general mesh size is set by Lmax and Lmin. The optional keyword ”linear” switch from quadratic to linear elements. Named groups of vertices, edges and faces can be created using the keywords ”vertexGroups”, ”edgeGroups” and ”faceGroups” repectively. Each group definition takes the form ”groupname” = ”selection set” (see section ”Lower dimensional shape selection” for definition of selection sets). Optionally, a mesh size can be assigned to each defined group by appending an @ sign followed by a scalar value.

An example is given below:

2Cylinder(O, 100*EX, 20) 
4Cylinder(100*EX, ax 100*EX, 50) 
9gmsh("c.med") << c as cyl 
10   L = (10 0.1) 
11   linear 
12   vertexGroups() 
13   edgeGroups() 
14   faceGroups( 
15    lo_f = c?faces(isPlane&&minimal(CoG.x)) 
16    up_f = c?faces(isPlane&&maximal(CoG.x)) 
17   ) 

Result: ISCAD model (left) and resulting mesh (right):

pict pict

8.8 Graphical Editor ISCAD

ISCAD is a graphical editor for InsightCAD scripts. It consists of a text editor for editing the script contents and a 3D view and some other elements for inspecting the resulting model. A screenshot is shown in the figure below.

The model script is entered into the text editor widget right of the 3D display. Once a script shall be evaluated, it can be parsed by clicking in the button ”Rebuild” or pressing Ctrl+Return.

After parsing the model, the following results are displayed:


8.8.1 3D Graphics Display

View Manipulation

Model Navigation When hoovering the mouse pointer over a displayed feature in the 3D geometry window, it is highlighted. The highlighted feature is the one, which would be selected during subsequent mouse clicks.

When the left mouse button is pressed, the highlighted feature is selected and all its contained reference points are displayed.

When the right mouse button is pressed, a context menu for the selected feature is displayed.


The context menu provides these functions:

8.8.2 Text Editor

When script code is entered into the text editor window, it is parsed in the background. Once this has been done successfully, some extensions of the context menu is available:

9 Developer Documentation

InsightCAE is a toolbox for the creation of custom workflows. It is therefore very natural to use its API in own extensions.

There are different developer perspectives:

  1. Creating extensions (own workflow modules).

    To write own workflow modules, just a plain binary installation of InsightCAE is required. It brings header files for its libraries and a CMake configuration which enables the developer to build his own extensions. It is recommended to create a custom library containing the additions (plug-in). See section 9.1 for a guide.

  2. Modifying and extending the InsightCAE base project itself.

    Since InsightCAE is free and open software, it is perfectly possible to take it and apply extensions or corrections or any other modification or improvement. Please note that silentdynamics GmbH develops InsightCAE primarily with its own applications in mind so there are almost certainly features missing in the API which third party users might need. If you implement something which might be of public interest, please think about sharing it with us and the rest of the community. We are very open to integrate foreign contributions into the project.

    Now, modifying the InsightCAE project requires to build the project from its sources. Please see section 9.2 for a guide to set up a self-built working copy of the sources.

9.1 Plug-In Development

9.2 InsightCAE Development

9.2.1 Dependencies

The InsightCAE toolkit requires a number of dependencies. Not all versions have been tested, of course. The following list contains the major dependencies along with the versions, which are currently utilized in binary packages:

9.2.2 OpenFOAM Analysis


Figure 8:Inheritance of OpenFOAMAnalysis class

SVG-Viewer needed.

10 Getting Started, Tutorials