Tutorials/Version1.2/Unstructured Grids for OpenFOAM With Blender and enGrid
From enGrid Wiki
NOTE: This page has moved to the new wiki location: Unstructured Grids for OpenFOAM With Blender and enGrid 1.2
The content below is kept here only for historic reasons.
This article is an adapted transcript of this document: 
Original Authors: Paul Bomke & Albert Baars
Author Contact: paul.bomke [at] hs-bremen.de
- Faculty 5: Nature and engineering - Biomimetics
- University of Applied Sciences Bremen
- Neustadtswall 30
- 28199 Bremen
- July 2010
This guide gives an introduction to a new open-source grid generation toolchain for unstructured grids used with the open-source CFD toolbox OpenFOAM®. The heart of this toolchain, the newly developed software enGrid by Oliver Gloth features a surface mesher, prism layer extrusion of individual surfaces, boundary and solver setup and export of ready-to-run case directories for OpenFOAM®. A complete walk-through from creating a geometry to exporting the grid and solver parameters is presented in the following sections. Please note that, although version 1.2.0 is a stable release, enGrid is still under development. If you encounter any problems or think you have found a bug, feel free to visit the enGrid user forum found on the enGits website. For reporting bugs, you can go directly to enGrid's Bug Tracker.
- enGrid, OpenFOAM®, Blender, unstructured grid generation, prismatic boundary layer, computational fluid dynamics.
Unstructured Meshing with Blender and enGrid
For the generation of unstructered meshes two open source software tools are suggested. The first of these two, Blender, is actually a tool for movie animation but contains a powerful mesh manipulation engine. We use it for modelling the geometry of our mesh. The version used for this tutorial is 2.49b, also known as 249.2.
The model is then imported into enGrid which is used for refining the surface mesh of the model, extruding a prism layer around it to ensure an adequate resolution and minimum skew of the boundary layer cells and for volume meshing with tetrahedral cells. Blender can be obtained in the following ways:
- In Ubuntu/Debian can be installed with the following terminal command:
paul@bionik:~$ sudo apt-get install blender
and can be started by typing:
- In Windows, can be downloaded from here: Browse Blender 2.49b release folder.
- Download either the file blender-2.49b-windows.zip or the file blender-2.49b-win64-python26.zip, depending on your Windows architecture.
- Unpack the zip file somewhere where you won't forget about it.
- Then run blender.exe.
In Linux, enGrid has to be compiled from source to make sure the release 1.2.0 is used. Fortunately an install script is provided by enGits. Follow the instructions on the website and make sure you have all the dependencies relevant for your distribution installed. Edit the configuration file
engrid_installer_updater.cfg according to your needs:
- It is important to download the source code via the git repository to obtain the newest version. Ensure that line 25 and 38 are set accordingly.
- Set the number of processors you want to use for compiling in line 89.
- Set your desired install location (default:
After installation enGrid can be started by:
paul@bionik:~$ . /opt/engits/bin/start_engrid
In Windows, installers have been prepared and can be downloaded from here: enGrid 1.2 folder at sourceforge.net
To establish an interface between Blender and enGrid an export script is provided by enGits. In Linux, copy it into your
~/.blender/scripts directory. In Windows, the tilde ~ is interpreted to be Blender's folder.
Getting into Blender
Lets start with running blender. The GUI is overwhelming at first glimpse and learning this software intuitively seems impossible. Therefore a brief introduction to the program’s main elements is given in the following paragraphs. Note that only the aspects relevant for modelling and exporting to enGrid are covered here. For further information please consult the tutorial web page Blender Noob to Pro or the excellent Blender precision modelling guide. If you already are adept at using Blender you might as well skip the following and proceed with the section Modelling with Blender.
Keyboard and Mouse
The keyboard is Blender’s main input device, although it is possible to perform every action via the menus as well. For every step within this script the keyboard short cuts are given. The left mouse button is abbreviated by LMB and middle and right mouse buttons by MMB and RMB respectively. Keyboard maps are given in Appendix A. Note that keyboard short cuts take effect only in the window that the mouse is placed in. In fact, different types of windows (e.g. 3D view and Outliner, we’ll learn about this later) may have different short cuts.
Window SetupThe GUI consists of a number of embedded windows. Right after the start three windows appear on the screen:
- On top the User preferences window is placed. It resembles what in other software would be called menu bar.
- In the middle a big window with a 3D View of our model is placed.
- At the bottom we have a Buttons Window with menu panels that will be used later for mesh manipulation.
- Each of those windows has a Header which is located either at the top or the bottom and consists of a menu-like structure offering commands and options regarding the contents of the window.
- The contents of each window are to be adjusted via the first button from the left on each Header. LMB results in a pull down menu which enables to choose between different window contents.
- Panels can be adjusted by placing the mouse over the border between two of them. Clicking and holding LMB enables moving the panel boarder and thus resizing the adjacent panels.
- Click RMB on the border between panels and a menu pops up offering to Split or Join panels. LMB on Split produces a thin line that can be placed at the position where the split is needed.
The first thing we need to do is to split the 3D panel vertically. The new panel will show the same 3D view. We want an Outliner window instead which can be changed via the Header. The outliner presents a hierarchical structure of our model and will be needed later on. The correct window setup can be seen in Figure 2.
Toggling the 3D View
The 3D view can be adjusted via the mouse or the numeric pad of your keyboard. For the latter please refer to the keyboard maps presented in Appendix A. For mouse control a few shortcuts shall be given here:
|Shift + MMB||Pan|
|Ctrl + MMB||Zoom continuously|
|Shift + MMB (scroll)||Pan vertically|
|Ctrl + MMB (scroll)||Pan horizontally|
After playing around with these commands for a while we notice that our center of rotation has moved, especially due to extensive panning. This would be annoying if we wanted to zoom in on a non centered object. Thankfully the center of rotation can be actively set back to where ever we want it to be in Blender. This is done using the Cursor which is represented by a white and red dashed circle:
- The view is centered to the cursor by striking C.
- The cursor itself can be positioned by clicking LMB anywhere in the 3D view.
- If we want to center the view onto an object, lets say the lovely little cube that comes up with every new blender file, we have to select the cube by clicking it with RMB. Then we press Shift + S and select Cursor → Selection.
In terms of rendering two modes exist: Solid and Wireframe. They can be toggled by pressing Z.
Two Ways of Manipulating Models
Now we get to the main concern of this script: creating and modifying objects in order to generate a model of our fluid domain.
First, it is important to know that two modes for changing geometries exist. There is Object mode which is mostly used to create objects and define their position and orientation in space. This mode is represented by pink outlines in the 3D view.
Then there is Edit mode which allows to change the topology of single objects by altering their mesh and is represented by yellow outlines in 3D view. This is a very powerful mode that provides vertex, edge and face manipulation procedures. Pressing Tab switches between both modes.
At this point it has to be mentioned that the export script only accepts changes done in Edit mode. Just to make this absolutely clear: please do refrain from scaling, translating, rotating or changing objects in any way imaginable if in Object mode.
Generally everything in the 3D view can be selected by RMB. Further selection tools are given below:
- Multiple selections are performed by RMB while holding Shift.
- A bounding box selection is available by pressing B, the selection is carried out with LMB in this case.
- A selection brush can be obtained by pressing B twice. This is available in Edit mode only.
- If the Solid view mode is activated, the Occlude background geometry button can be activated to prevent hidden surfaces from being selected (see Figure 3).
- A toggles the selection, i.e. selects nothing or everything.
Length values are given in Blender units. Fortunately, in our case one Blender unit equals one meter.
Modelling with Blender
After the basics have been clarified we proceed with creating a first model. Let’s make a cube-like fluid domain that contains a solid sphere. Luckily we already have got a cube object in our new model.
We also have got a spot light object and a camera object, as it can be seen in the Outliner window. We don’t need the light and the cam so we delete them by simply clicking RMB onto them in the Outliner and selecting Delete.
Next, we are going to change the size of our fluid domain cube. We select it by clicking RMB onto it. Then we press Tab to change into Edit mode.
Edit mode offers three ways to modify meshes: Vertex, edge and face based. To change between those modes the short cut Ctrl + Tab is predefined.
We want to enlarge our cube, so we have to translate each face outwards. Let’s select a face by clicking onto the dot on its center with RMB after switching to face selection mode. Pressing N will produce a dialog called Transform properties which shows the median coordinates of the current selection (see Figure 3). First make sure that the small Global button is activated. Then the coordinates can be changed by clicking onto them with LMB. Now we repeat these steps for each face until we end up with a cube like fluid domain of the desired size.
The next step is to create a neat sphere object inside of our fluid domain. Therefore we change back to Object mode and press Shift + A. In the pop up menu we select Add → Mesh → Icosphere and set Subdivisions to 4 while leaving the radius at 1 BE (see Figure 4). The geometry is finished now and ready to be saved as a
To ensure interoperability with enGrid our geometry has to meet certain requirements:
- All normal vectors have to point away from the fluid. While in Edit mode select Draw Normals in the Mesh tools more panel of the Buttons window. The NSize text field above defines the length of the normals. If normals point inwards the corresponding faces have to be selected and can then be flipped by striking W → Flip normals.
Alternative shortcuts: Shift + Ctrl + N and Ctrl + N.
- The model has to be watertight. While in Edit mode, ensure that nothing is selected and that either vertice or edge selection is activated. Shift + Ctrl + Alt + M will now select any vertice or line adjacent to a leak in the geometry. If this problem occurs at this point, please refer to the section Advanced editing and repairing geometries.
- The model must exclusively consist of triangle elements. To convert quads to triangles simply select the corresponding faces in Edit mode and press Ctrl + T.
- There should be no duplicate vertices. Select everything in Edit mode (press A) and hit W → Remove doubles.
Assigning Boundary Patches
Before exporting the geometry to enGrid boundary patches can be assigned by turning individual groups of the cube’s faces into distinct Objects. In Edit mode we select the faces of our desired inlet patch. To separate them from the cube press P → Selected and they immediately appear as a distinct Object in the Outliner. The new inlet object should now be renamed by clicking Ctrl + LMB onto it in the Outliner and typing a new name.
The remaining patches are separated from the cube following the same procedure. Obviously the last remaining boundary patch doesn’t have to be separated since the cube object itself simply can be renamed. In this tutorial the patch names inlet, outlet, top, bottom, front and back are used.
Note that enGrid's surface mesher will smoothen sharp edges of the model if the adjacent faces belong to the same boundary patch. This means that even if neighbouring faces (e.g. the four faces of our cube that are neither inlet nor outlet) will later on share the same physical boundary conditions they have to be separated into different patches (e.g. wall1, wall2, etc). Concerning our sphere: there is no need to divide it into distinct patches since it does not have sharp edges that have to be protected. It’s time to save again now, but without overwriting the existing file.
Exporting the Model
The model is now ready to be exported:
- Make sure you are in Edit mode.
- Select all of the geometries with Shift + LMB.
- Finally export by clicking Export → Engrid (*.bgec) in the File menu.
Advanced Editing and Repairing Geometries
Skip this paragraph if you passed all the mesh checks and just want to go ahead with our simple geometry.
It may however happen that a geometry does not meet the requirements stated in section Checking geometries. If the geometry is not watertight, the easiest way to get rid of this problem is to select all points adjacent to the leak and fill in a polygonal by pressing F or one or more triangular faces using Shift + F. This technique also provides a handy tool to remesh geometries that have been imported from *.stl format. In this case the Alt + F short cut might also prove itself useful which beautifies the mesh, probably using Delaunay sweeps. Some more general short cuts for mesh modification are listed below
|W||Special mesh modification menu|
Note that the normal of your screen represents the axis for rotation an scaling. Using the numerical block of your keyboard may be helpful for adjusting the view. While extruding, scaling or rotating the individual input parameters appear at the bottom of the 3D view. Simply type the values you need and use Tab to switch between different parameters if more than one is needed.
Meshing with enGrid
In comparison to Blender, enGrid offers a far more simple GUI and is fairly easy to handle. The main window consists of a tool bar at the top which contains all the input buttons, an output terminal at the left where information about the current operation is displayed, and some display options on the right (see Figure 7).
Toggling the 3D View
Navigating the 3D view is a bit different from Blender but similar to Paraview because VTK is used. The commands are:
Individual boundary patches can be displayed or hidden in order to look inside of the fluid domain by striking V and selecting the ones desired for display from the View menu.
Setting Up the Program
The Configure enGrid entry in the Tools menu results in a dialog which allows to set up the basic configuration. The only thing to change for now is the Maximal number of iterations in the Surface meshing tab which should be set to 1. This increases the traceability of the surface meshing process.
After the geometry has been exported from Blender it can be opened in enGrid by clicking Import → Blender in the menu bar. This will bring up our fluid domain cube on the screen. To take a look inside we hide the boundary patches inlet, top and front. It is apparent that every boundary is coloured different from in and outside which represents the orientation of the corresponding normal vectors which point outwards of the green side. Therefore, if we carefully checked our model’s face normal orientation in Blender we should see green faces from the outside of the fluid domain and yellow faces from within. If all faces show the wrong orientation the normals can be flipped by clicking Change surface orientation in the menu bar. Individual flipped faces can be repaired by clicking Correct surface orientation. However, for elegance’s sake surface orientation should be checked from the very start in Blender.
Setting Up the Boundary Conditions
Before we jump into serious meshing we have to assign some physical boundary conditions to our patches by pressing E. The appearing window asks for the required input information for setting up a whole case (see Figure 8). The Boundary conditions tab presents an overview of all boundary patches, their names and their physical boundary conditions called Boundary types.
Before anything different from patch becomes selectable, the physical properties of our desired boundary conditions have to be defined in the Boundary types tab (see Figure 9). Here, we simply type in a name, let’s say ourInlet, select one of the predefined physical conditions (e.g. inlet) from the drop down menu on the right and click Add. If we now select the new entry ourInlet from the list below, its parameters can be edited at the bottom of the window. Back in the first tab we are now allowed to replace the boundary type patch of our inlet boundary patch with the newly created ourInlet. We repeat those steps for all boundary patches, selecting Inviscid wall for our top, bottom, front and back patches, Viscid wall for the sphere patch, and Outlet for the outlet patch. This procedure seems a little redundant at first but has its advantages in cases where, for example, multiple inlets have to be set up with different values.
Next, a Volume, i.e. a name for our fluid domain, has to be set up in the Boundary conditions tab. We type the favoured name into the text field below the boundary table and click Add. A new column will appear in the boundary table. Double-clicking on each cell will result in a pull down menu which offers two colours: green and yellow. Here we have to select the outside colour of the fluid which is green in our case. Having finished the boundary conditions we move on the next step.
Before starting the meshing process a few attributes have to be set up in the menu that can be found by clicking the Edit surface parameters button in the tool bar. In the dialog that comes up we select the first tab Boundary codes and pick the boundary patches that we want to remesh from the list on the left (see Figure 11). Let’s mesh our sphere first.
The desired edge length (aka. characteristic length) can be set using two methods:
- At the bottom of the window we adjust the Maximal edge length, i.e. the desired characteristic length of the cell edges in general. This affects all the edges between the individual boundary patches.
A second attribute, the Cell growth factor predicts the cell expansion rate from the edges of a boundary patch towards the center of that patch.
- Clicking Add set produces a new set in the table above. For each edge the adjacent patches have to be specified in a set and the Edge length has to be specified. This is of interest if some edges have a different characteristic length than others.
At the moment both methods have to be used, i.e. each edge has to be specified via the sets and general edge length has to be set as well. This may change in future releases of enGrid.
We start with meshing the sphere only. With a diameter of 1 and Edge length of 0.05 should be sufficient. The Cell growth factor should remain at 1.5. We add a set and select the sphere only (it does not contain any edges but the set is needed nevertheless).
Let’s close the dialog box and start meshing by clicking the Create / improve surface mesh menu button. The first surface mesh iteration is initiated and we can see the output in the terminal on the left. A useful estimate of the surface mesh generation’s progress is the ratio between Inserted and Deleted nodes. If this ratio is equal or close to 1 the mesh has not yet reached its desired cell edge length and we have to click Create / improve surface mesh again. If the number of inserted nodes approaches several ten thousands we might have to think about reducing the cell edge length in order to generate a mesh with a bearable number of cells (at least if you don’t have a super-duper computer at hand). This is the reason why Maximal number of iterations is set to one in the Configure enGrid menu: it gives us more control and reduces the risk of blocking the program if to many cells are inserted. If after several iterations the ratio between Inserted and Deleted nodes approaches 1, the surface mesh is finished.
The sphere should show an evenly distributed mesh now and we shall proceed with the outer boundaries of our fluid domain: the cube. The necessary adjustements in the Edit surface parameters menu are shown in Figure 12.
Extruding a Prism Layer
To ensure a decent mesh quality near all physical surfaces a layer of prismatic elements can be extruded from the surface mesh of individual patches. Therefore, we simply click on the Create / improve prismatic boundary layer button in the menu bar. In the menu that pops up we select the boundary patches we want to extrude. Of course it only makes sense to select boundary patches that resemble a physical (viscid) wall, i.e. patches where a boundary layer will be present. Hence, in our case we select the sphere only (see Figure 13). The corresponding volume has to be marked in the list on the right as well. The thickness of the prism layer can be controlled via the values of Relative and Absolute height of layer. The relative value specifies the height of the prism layer as multiples of the cell edge length of the corresponding surface mesh. The absolute value takes the height in meters. Blending between both values is possible via the Blending value at the bottom.
The Remove points option has to be marked if the prism layer that we want to create would intersect a second boundary patch. In this case the program is allowed to remove points from this patch. Imagine a symmetry plane going through the middle of our sphere. The prism layer extruded from the sphere would conflict with the points of the symmetry plane. In this case points are removed from the symmetry plane. We don’t have a symmetry plane so we need to unmark this option (marking it would result in an error message).
After everything is set up properly we finally click OK and watch the output screen while enjoying a cup of tea. The prism layer is created and the rest of the volume is filled with tetrahedrons directly afterwards. To see the result of this operation we have to mark the Enable volume elements checkbox in the Display options menu on the right. Also Clipping should be activated with the center and normal of the clipping plane adjusted to cut through our sphere (default values are fine). If for some reason we do not like the prism layer we can try to improve it by clicking the Divide / improve prismatic boundary layer again and marking the Improve existing layer checkbox before clicking OK.
Dividing the Prism Layer
The new prism layer should now be divided into several layers to resolve the velocity gradient of the boundary layer around our sphere properly. Simply click the Divide prismatic boundary layer button in the menu bar. Values for the Initial layer thickness and the Increase factor can be specified here, along with the desired Number of layers (see Figure 14). We want 10 evenly distributed layers so we choose an Initial layer thickness of 0.1 with the Relative spacing option marked. This means that all values are normalized using the prism layer thickness. We also choose an Increase factor of 1 and a Number of layers of 10. Afterwards we simply click OK and the prismatic layer should be devided after no time.
Improving the Volume Mesh
If the tetrahedron mesh looks to coarse we can refine it by clicking the Refine volume mesh button in the menu bar.
Exporting to OpenFOAM®
The mesh is now finished and is ready for a final export to OpenFOAM® . From the menu bar we select Export → OpenFOAM® → OpenFOAM® (Grid only). We thereby create a case directory with the
constant/polymesh folder, sadly marking the end of the main part of this tutorial.
enGrid also offers the export of complete case directories including solver settings. These have to be set up in the Solver tab of the Edit boundary conditions dialog. Afterwards we choose OpenFOAM® (Grid + solver parameters) from the export menu.
Advanced Program Features
Manual Boundary Code Assignment
If we import a geometry that does not contain boundary codes, for example from gmsh, we need to assign them manually. This is done by pointing the cursor onto each individual patch and pressing P. A tiny red dot will come up on the selected face. S will then open the Set boundary code menu which enables to allocate the selected patch to a boundary code (see Figure 15). The value specified in Feature angle determines the maximum angle between two faces at which both are still allowed to be allocated to the same boundary code. After all boundary codes are specified we continue from the Setting up the boundary conditions section.
Expanding the Fluid Domain
enGrid also offers tools to expand geometries. If we notice that our fluid domain is too short to resolve the wake behind our sphere, we can extrude a volume mesh from the outlet patch by clicking Extrusion from the menu bar. In the dialog the patch to be extruded can be selected on the right (see Figure 16). We select the Layer spacing type simple and the Extrusion type surface normal. The Number of layers is set to 50, the Height of first layer to 0.1 and the Increase factor to 1. This will result in an extrusion of 5 meters with cell layers of 0.1 meters thickness (see Figure 17).
The sides of the newly created "block" are unallocated patches. They have to be assigned to our Front, Back, Top and Bottom boundary codes using the method described in section Manual boundary code assignment.
A - Keyboard Maps
B - Blender Shortcuts
In this following section the shortcuts used in this tutorial are summarized.
|Shift + MMB||Pan|
|Ctrl + MMB||Continuous zoom|
|Shift + MMB (scroll)||Vertical pan|
|Ctrl + MMB (scroll)||Horizontal pan|
|Shift + S → Cursor to selection||Snap cursor to selected object|
|C||Set center of rotation to cursor|
|Shift + RMB||Multiple selection|
|B → LMB||Bounding box selection|
|2x B → LMB||Selection brush (scale with mouse wheel)|
|A||Select everything or nothing|
|Ctrl + Tab||Toggle vertex, edge or face selection|
Modelling in Edit Mode
|N||Open transformation menu|
|W||Open specials menu|
|Shift + F||Triangulate between edges|
|Shift + A||Add new mesh (works in Object mode too)|
Adding Objects in Object Mode
|Shift + A||Add new object|
Check Geometries in Edit Mode
|W → Flip normals||Flip normals|
|Ctrl + N||Calculate normals outside|
|Shift + Ctrl + N||Calculate normals inside|
|Shift + Ctrl + Alt + M||Select leaks in geometry|
|Ctrl + T||Triangulate faces|
|W → Remove doubles||Remove duplicate vertices|
Create Boundary Patches
|P||Separate selected faces from object|
|Ctrl + LMB||Rename Object in Outliner|
C - enGrid Shortcuts
|V||Display / hide patches|
|P||Select boundary faces|
|S||Assign boundary faces to patch|
|E||Edit boundary codes|