Quickstart
ℹ️ Updated to BlenderFDS 6.0.x
This wiki page guides the new user to a quick overview on how to use BlenderFDS.
Before starting, here are some basic requirements.
You should already have the Blender application installed on your computer, and the BlenderFDS addon enabled.
If not, the Install wiki page explains how to do that.
You should also have FDS and Smokeview installed on your computer.
If not, follow this documentation. In any case, you should already be capable of writing and running simple FDS cases, before using BlenderFDS to facilitate the task. BlenderFDS does not hide the FDS complexity from you!
If you are completely new to Blender, I suggest you to study the beginner donut tutorial from Blender Guru.
And, when in doubt, a glimpse to the official Blender documentation is very useful as well:
We are going to open Blender, explore the BlenderFDS interface,
and inspect the default example FDS case.
Then we will export the case, and run it within the FDS solver.
After that we are going to import one of your existing FDS cases,
and discover that many FDS cases can coexist in the same .blend file,
and share common assets.
So, let's start!
Open the Blender application. After installing and configuring the BlenderFDS addon this is what you should expect.
Before going on, I am showing you where to find the general BlenderFDS settings.
Select Edit > Preferences in the main menu and the preferences panel opens up.
Then click on the Add-ons tab on the left, and find the BlenderFDS addon preferences panel.
If you hover your cursor over any of the settings, an help popup appears providing an explanation message.
This is also true for any other BlenderFDS user interface widget.
Blender provides a number of different editors for displaying and modifying different aspects of the data. In BlenderFDS we generally use only some of them:
- the
3D Viewporteditor, - the
Oulinertree, - the
Propertiespanels, - and the
Text Editor.
Let's explore those editors one by one.
The 3D Viewport editor is used to interact with the 3D scene for modeling.
The navigation gizmo can be found in the top right of the editor. From top to bottom:
- by dragging the colored gizmo you orbit the view around;
- when clicking any of the axis labels you align to that view;
- you zoom the view by dragging over the magnifying glass icon;
- for panning, drag over the hand icon;
magnifying glass.
On the left-hand side of this editor, you see its several editing modes, used for editing different kinds of data. In BlenderFDS we are going to use just two of them:
-
Object Mode: it is the default mode, dedicated to object data-block editing (eg. changing position/rotation/size). -
Edit Mode: dedicated to object shape editing (eg. creating/moving/linking vertices/edges/faces).
In Blender the object shape is called the
Blender Mesh.
If you studied at least the first part of the beginner donut tutorial from Blender Guru, you know very well how to create new geometry, and then move, rotate, scale, extrude it in
Object ModeandEdit Mode. Therefore I am not repeating that.
On the right-hand side of the 3D Viewport you see the Sidebar.
In its FDS tab you find all the panels that offer tools for BlenderFDS related activities.
In particular:
| Panel | Description | Further details |
|---|---|---|
FDS Case Utils |
This panel offers general tools for your FDS case, as for running your FDS case or importing code snippets. | See the Running FDS wiki page for the details. |
FDS Namelist Utils |
This panel offers tools for the selected Blender Object linked namelist. In the previous picture you see the panel for the MESH namelist. |
|
Remesh |
This panel collects several tools used to fix malformed geometries and make them manifold (eg. the triangulated surfaces required by the GEOM namelist). |
See the Remesh wiki page for the details. |
Geolocation |
This panel offers the tools for precise geographic positiong of objects on the calculation domain, an useful feature when dealing with terrains in wildfire simulation cases or fire smoke pollution dispersion studies. | See the Geolocation wiki page for the details. |
The Outliner is a tree that organizes the data of the blend file:
Blender Scenes, Collections, Objects, Meshes, and Materials.
This editor is used to view, select, manage the data in the selected Scene.
Each row in the Outliner shows a data-block, and what other data-blocks it contains.
Data-blocks can be dragged and dropped to manage data relations.
For example, in the following picture you see a Blender Collection named Domain containing two Objects:
Domain and Domain bcs.
The Domain bcs contains the reference to its Domain bcs geometric shape, the so called Blender Mesh.
At the bottom of the tree, the Domain bcs shape has a reference to a Blender Material named OPEN.
Collections are a way BlenderFDS uses to organize the exported FDS case.
Objects can be moved to collections by dropping on the name or contents of a collection.
The exported namelists are first ordered by collection, then by ID parameter alphabetic order.
By toggling the camera icon of the data-block you can decide
whether exporting the related FDS namelist.
See the Organize cases wiki page for the details.
The Properties editor shows and allows editing of the many active data properties.
This editor has several categories, which can be chosen via tabs, the icons column to its left.
Each tab regroups properties and settings of a specific data type,
such as Blender Scene, Object, and Material.
Let's explore each of them.
The Scene tab contains several panels that configure your case,
and setup some of the general FDS namelists.
| Panel | Description |
|---|---|
FDS Case Config |
This panel is used for the general configuration of your FDS case. Here you set the Case Filename and its exporting Case Directory. At the top of this panel, you find the button Show FDS Code used to display the FDS code that is going to be exported from the selected Scene. |
FDS HEAD |
The FDS HEAD panel configures the HEAD namelist parameters: CHID and TITLE. Sometimes you want to export a partial FDS case and do not need the HEAD namelist. In this case use the toggle preceding the panel header to decide whether exporting that namelist. |
FDS TIME |
The FDS TIME panel configures the TIME namelist managed parameters: T_BEGIN and T_END. Any parameter that is not directly managed by the interface can be just typed in the generic Other Parameters widget at the very bottom of each panel. Just add a new parameter with the + button and enter what you need, for example WALL_INCREMENT=1. |
The other panels work the same way and are used to setup the other general namelists. Remember that, if you hover your cursor over any of the settings, an help popup appears providing an explanation.
At the bottom of the tab, the Units panel allows you to set your preferred length units: metric or imperial.
The Object tab panels can link any managed geometric FDS namelist,
such as OBST, VENT, GEOM, SLCF, ..., to the active Blender Object.
These namelists are called geometric, because they express their effect on a geometric entity,
such as a volume, face, point, or plane, by means of an FDS geometric parameter,
for example: XB, XYZ, PB, VERTS, FACES.
See the Geometries wiki page for the details on how
Blender Objectgeometries are exported to the FDS case.
The panel changes depending on the parameters of the linked FDS namelist.
The following picture shows the tab for an OBST namelist.
At the top of the panel, you always find two buttons: Show FDS Geometry and Show FDS Code.
Clicking the first button creates a temporary geometry in the 3D Viewport that shows
how the Blender Object is going to be exported to a namelist geometry in the FDS case,
according to the choosen geometry type (eg. XB, XYZ, PB, ...).
Clicking the second button displays its exported FDS code.
The Material tab can link one or more FDS SURF boundary conditions to the active Blender Object.
At the top of the SURF panel, you find the Show FDS Code button. When clicked,
it displays the exported FDS code.
The panel manages several common SURF parameters. Any parameter
that is not directly managed by the interface can be entered
in the generic Other Parameters widget at the very bottom of the panel,
as in the picture for HRRPUA=500.000 and TAU_Q=1.0.
See the Boundary conditions wiki page for the details on how
Blender Materialsare used to set the boundary conditions for your FDS namelists.
The Text Editor is used to type in a text file containing namelists and comments,
that BlenderFDS directly attaches to the exported FDS case.
This feature is used to append to your FDS case other non-geometrical
or unmanaged namelists (eg. MATL, BNDF, ...), that do not fit
elsewhere in Blender Scene, Object, or Material instances.
The choice of the Free Text file to be attached to your FDS case
and its position in the exported file is specified in the FDS Case Config panel
of the Blender Scene tab.
Note that BlenderFDS also allows the use of an external file as Free Text.
After exploring the BlenderFDS user interface,
it is time to save the .blend file of this default example case to a local directory,
because BlenderFDS needs an absolute reference for the relative paths you may have configured.
Select File > Save As in the main menu, name the file example.blend,
and save it locally on your computer.
It is always preferred to export the FDS case to a new empty directory,
so that all the resulting calculation output files will be neatly organized.
So, now select File > Export > NIST FDS Case in the main menu,
and export the FDS case you just explored to an empty directory.
If you want to create a new directory, click on the folder icon.
Next time, you can preset the case name and its destination directory,
in the FDS Case Config panel of the Blender Scene tab.
The Example_case.fds file was exported. If you have a proper text editor installed on your computer,
open the Example_case.fds file, and see what is inside.
In the following picture, I am opening the Example_case.fds file with the GEdit text editor on a Linux computer.
Notice the nice syntax-highlighting!
On any Linux distribution, this is provided by GEdit with this FDS extension.
On MS Windows, I suggest you to install the free and open-source Notepad++ text editor. Here is its FDS extension for syntax highlighting.
On MacOS, you can install Sublime Text and use this FDS extension.
Depending on the installed operating system on your computer, there are different ways of running the FDS solver. Look at the FDS User's Guide if you need help on that.
On Linux, to run the solver on the Example_case.fds that was just exported from BlenderFDS,
I open a terminal window, move to the appropriate directory, and type:
fds Example_case.fds
While the case is being solved, I can have a peek on what is going on by running Smokeview. Open another terminal window, move to the appropriate directory, and type:
smokeview Example_case.fdsThe newly opened Smokeview window displays all the wonders of the calculation we are performing.
Now that you know for sure that your computer is well configured to run FDS, let's perform the same calculation from within BlenderFDS.
First, stop the calculation you previously launched,
so not to overwhelm your computer with two heavy processes.
Then go back to BlenderFDS and click on the Run FDS button, in the FDS sidebar tab.
An asynchronous command prompt is opened and FDS is run on your case.
See the Run FDS wiki page for the details.
While your computer is running the Example_case.fds you just created,
you can go back to BlenderFDS and try another useful feature.
Select File > Import > NIST FDS Case in the main menu, and import any of your existing FDS cases.
Your case is imported into a new Blender Scene,
because each Scene of a .blend file represents a different FDS case.
The assets you create (eg.
Blender ObjectandMaterialinstances) can be shared between all your cases, therefore avoiding repetition and errors.
A single
.blendfile can act as a container of all the variations of your many FDS cases related to the same project.
In the following picture, I imported the thouse5.fds case,
that is included in the official FDS package, inside the FDS/FDS6/Examples/Visualization directory.
If you want to quickly navigate between your cases use the Blender Scene pop-down
that you find on the right-hand side of the main menu bar, as shown in the following picture.
After such a long journey, you are now ready to enjoy BlenderFDS, the free and open-source user interface for FDS. Many more features are offered by its interface, described in detail by the other wiki pages.