An interactive viewer and editor for OpenFOAM blockMeshDict files. Built with Python, PyVista and PyQt6.

Developed by Gavin Tabor, University of Exeter.

Gavin Tabor, University of Exeter
g.r.tabor@ex.ac.uk
— concept, domain expertise, design, testing

Claude (Anthropic)
— design consultation, architecture, code review

Claude Code (Anthropic)
— implementation

• Displays blockMesh geometry (vertices, blocks, curved edges, boundary patches)
• Supports all curved edge types: arc, spline, polyLine, BSpline
• Arc edges specified by point-on-arc or circle centre (origin format)
• Edit vertices, blocks, edges and patches interactively
• Saves modified blockMeshDict back to file
• Runs blockMesh and checkMesh from within the interface
• Adds boundary layers via snappyHexMesh (wall patches only)
• Generates tetrahedral meshes via tetgen (optional) and converts to OpenFOAM
• Generates 2D triangular meshes via triangle (optional) and extrudes to 1-cell-thick polyMesh
• Loads reference STL/OBJ/VTK/PLY geometry for positioning
• Right-click picking: select vertices, blocks and edges directly in the 3D viewport
• Topology validator: automatically detects orphaned vertices, duplicate vertices, out-of-range indices, crossed/inverted blocks and degenerate blocks
• Cell zone support (for multi-region cases)
• defaultPatch and mergePatchPairs support
• Scale bar and bounding box coordinate display

Python 3.10 or later, plus:

pip install -r requirements.txt

An OpenFOAM installation is required to run blockMesh, checkMesh and snappyHexMesh. Tested against OpenFOAM 2406 (ESI/openfoam.com).

pip install tetgen triangle

blockSketch runs without either package — the relevant tab is disabled with an install hint if the package is not found.

Writing the tet mesh to OpenFOAM format uses tetgenToFoam, and the 2D tri mesh uses extrude2DMesh, both part of a standard OpenFOAM installation.

blockSketch is developed and tested on Linux. Other platforms may work but have not been tested by the authors.

OpenFOAM is commonly used on Windows via WSL (Windows Subsystem for Linux). blockSketch has been reported to have issues in this environment (thanks to Jozsef Nagy for the report). The main difficulties are:

• Display / GUI: PyQt6 and PyVista both require a working display server. Under WSL2 with WSLg this usually works automatically; under WSL1, or WSL2 without WSLg, you need a third-party X server (VcXsrv, Xming, X410, etc.) and DISPLAY set correctly.
• OpenGL / VTK rendering: PyVista uses VTK's OpenGL renderer. WSL's GPU passthrough is improving but can still produce rendering errors or fall back to software rendering, which is slow and may crash on large meshes.
• OpenFOAM utilities: blockMesh, checkMesh, snappyHexMesh, tetgenToFoam and extrude2DMesh are called as subprocesses and must be on the PATH inside the WSL environment. The blockSketch process and OpenFOAM must be running in the same WSL distro.

If you encounter problems on WSL, please report them (see Feedback below) including your WSL version, WSLg status, and any error messages from the terminal — this will help improve support in future releases.

No installation needed — just unzip the directory and run from within it.

Run from your OpenFOAM case directory:

cd /path/to/your/case
python /path/to/blockSketch/main.py

Or specify the blockMeshDict directly:

python main.py path/to/blockMeshDict

blockSketch will look for the blockMeshDict in these locations:

• system/blockMeshDict (modern OF, v6+)
• constant/polyMesh/blockMeshDict (older OF)

If no blockMeshDict is found, you will be prompted to create a new one.

To use blockSketch like any other OpenFOAM command, add an alias to your ~/.bashrc:

alias blockSketch="python /path/to/blockSketch/main.py"

After reloading your shell (source ~/.bashrc), you can launch blockSketch from any case directory with:

cd /path/to/your/case
blockSketch

1. Open a case directory containing a blockMeshDict
2. The 3D viewport shows vertices, blocks and patches automatically
3. Use the six panel buttons to edit different aspects of the mesh:
   • General — scale factor, display options, load reference geometry
   • Vertices — add, move and delete vertices
   • Blocks — define hex blocks, cell counts and grading
   • Edges — add curved edges (arc, spline, polyLine, BSpline)
   • Patches — define boundary patches and face lists
   • Meshing — run blockMesh, checkMesh, boundary layer addition; tet mesh generation (tetgen tab); 2D triangular mesh generation and extrusion to 1-cell-thick polyMesh (2D tri tab, for standard 2D cases)
4. Right-click any vertex, block or edge control point in the 3D viewport to jump directly to that item in the corresponding panel
5. Click Save (or Ctrl+S) to write the modified blockMeshDict

blockSketch can be used to generate tetrahedral meshes independently of blockMesh. Simply define vertices and boundary patches without defining any blocks, then use the tetgen tab in the Meshing panel to generate a tet mesh directly.

Workflow:

1. Define vertices in the Vertices panel
2. Define boundary patches in the Patches panel
3. Switch to Meshing → tetgen tab
4. Select mesh density and click Generate tet mesh
5. Click Write to OpenFOAM to convert to polyMesh format

No block definitions are required for this workflow. Note: the topology validator will show warnings for unreferenced vertices — this is expected when no blocks are defined.

Tested and working:

• RectFlow — single-block square-section straight duct; icoFoam
• RectFlow (sawtooth) — one wall with saw-tooth profile; icoFoam
• bend3d — square-section duct with 90° arc bend; icoFoam

blockSketch can generate a 2D triangular polyMesh from any standard 2D blockMesh case definition. The geometry is defined exactly as for a normal 2D blockMesh case (1 cell thick in z, empty front and back patches) — no changes to vertices, blocks or patches are needed to switch between quad (blockMesh) and tri (2D tri tab) meshing.

Workflow:

1. Set up your case as a normal 2D blockMesh (1-cell-thick, empty front/back patches)
2. In the Patches panel, delete one of the two frontAndBack empty patches so that exactly one empty patch remains
3. Switch to Meshing → 2D tri tab
4. Select mesh density and minimum angle
5. Click Generate 2D mesh — the triangulated surface is displayed in the viewport
6. Click Write 2D polyMesh to extrude to a 1-cell-thick polyMesh and write to constant/polyMesh

Tested and working:

• bend2d — 2D pipe bend with arc edges; icoFoam
• cavity — lid-driven cavity; icoFoam
• pitzDaily — backward-facing step; simpleFoam
• plateHole — plate-with-hole with arc edges; solidDisplacementFoam

• Boundary layer addition tested on OF 2406 ESI only — may need manual adjustment of system/snappyHexMeshDict on other versions
• #include directives in blockMeshDict are not followed

Boundary layer addition uses snappyHexMesh in layers-only mode. Results depend heavily on the mesh geometry and snappyHexMesh's own capabilities and limitations:

Works well:

• Simple geometries with smooth wall patches
• Extruded 2D cases with clear wall boundaries
• Cylindrical/pipe geometries (O-grid blocks)

May produce poor results or fail:

• Complex geometries with sharp concave corners
• T-junctions and highly non-orthogonal patches
• Cases where wall patches share edges at acute angles
• Very thin regions between opposing walls

These are limitations of snappyHexMesh layer addition, not blockSketch. If layer addition fails or produces poor quality layers, consider:

• Adjusting n (fewer layers) and exp (smaller expansion ratio)
• Running checkMesh first to check base mesh quality
• Using a dedicated boundary layer meshing tool

Tested and working:

• Simple duct/pipe cases
• 5-block cylinder O-grid mesh (OF 2406 ESI and OF 12 Foundation)

Known issues:

• T-junction cases: incomplete or malformed layers on some patches

The Tests/ directory contains complete OpenFOAM cases used for development and regression testing, organised by meshing method:

Tests/
├── blockMesh/
│   ├── pitzDaily/            — standard pitzDaily tutorial case from the OpenFOAM
│   │                           installation; tests boundary layer addition
│   ├── SRFProbe/             — rotating sycamore seed geometry; demonstrates loading
│   │                           an STL reference surface in the General panel
│   └── testBlockSketch/      — collection of blockMeshDict files (stored as named
│                               variants in system/) illustrating specific blockSketch
│                               features; copy the desired variant to blockMeshDict
│                               to use it:
│         blockMeshDict.bend          — pipe bend with arc edges
│         blockMeshDict.bfs           — backward-facing step (multi-block)
│         blockMeshDict.cavity        — lid-driven cavity (single block)
│         blockMeshDict.cylinder      — cylinder O-grid
│         blockMeshDict.edges         — all curved edge types (arc/spline/polyLine/BSpline)
│         blockMeshDict.malformed     — parser stress test (incomplete / unusual syntax)
│         blockMeshDict.mergePatchPairs — non-conforming patch connections
│         blockMeshDict.plateHole     — plate-with-hole (arc origin format)
│         blockMeshDict.polyLine      — polyLine edge type
│         blockMeshDict.TJunction     — T-junction (multi-block, non-orthogonal)
│
├── tetgen/
│   ├── bend3d/               — square-section duct with a 90° arc bend; tetgen tet
│   │                           mesh generation and icoFoam run both tested
│   └── RectFlow/             — single-block square-section straight duct; tetgen and
│                               icoFoam tested; blockMeshDict.sawtooth gives one wall
│                               a saw-tooth profile to test meshing of non-planar patches
│
└── triangle2d/
    ├── bend2d/               — 2D version of the bend3d tetgen case; icoFoam
    ├── cavity/               — standard lid-driven cavity tutorial; icoFoam
    ├── pitzDaily/            — standard pitzDaily tutorial; simpleFoam
    └── plateHole/            — stress hole-in-plate tutorial; solidDisplacementFoam
                                (Allrun script provided)

In all triangle2d cases one of the two frontAndBack empty patches has been removed from the blockMeshDict, as required by the 2D tri meshing workflow (the Generate step expects exactly one empty patch).

To use a variant from testBlockSketch, copy it over the active file:

cd Tests/blockMesh/testBlockSketch
cp system/blockMeshDict.bend system/blockMeshDict
python /path/to/blockSketch/main.py

This is a beta release. Please report any issues, crashes or missing features to:

Gavin Tabor g.r.tabor@ex.ac.uk University of Exeter

Please include:

• Your OpenFOAM version
• Operating system
• The blockMeshDict file that caused the issue (if applicable)
• Any error messages from the terminal

Built with:

• PyVista — 3D visualisation
• PyQt6 — GUI framework
• SciPy — BSpline interpolation
• tetgen — tetrahedral mesh generation (optional)
• triangle — 2D triangular mesh generation (optional)

blockSketch is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See the LICENSE file for full details.

This offering is not approved or endorsed by OpenCFD Limited, producer and distributor of the OpenFOAM software via www.openfoam.com, and owner of the OPENFOAM® and OpenCFD® trade marks. blockSketch is an independent community tool and has no affiliation with OpenCFD Limited or the OpenFOAM Foundation.