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, this 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 this 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 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. If the installation of the BlenderFDS addon and the following configuration went smoothly here is what you will see.
Before going on, I am going to show you where to find the general BlenderFDS settings.
Click on the Edit > Preferences menu and the preferences panel opens up.
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. This is also true for any other user interface widget.
Blender provides a number of different editors for displaying and modifying different aspects of data. In BlenderFDS we generally use only some of them:
- the
3D Viewporteditor, - the
Oulinertree, - the
Propertiespanels, - and the
Text Editor.
Let's have a look at 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;
- by dragging over the first two of the grey buttons you zoom or pan the view.
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 Modeis the default mode, and it is dedicated to object data-block editing (eg. position, rotation, size, ...). -
Edit Modeis dedicated to object shape editing (eg. creating/moving/linking vertices/edges/faces). In Blender the object shape is called theBlender Mesh.
On the right-hand side of the 3D Viewport you see the Sidebar,
that has a specific tab FDS for BlenderFDS related activities.
In the following picture, you see:
- the
FDS Case Utilspanel offering general tools for your FDS case. See the Running FDS wiki page for further detail on how to run your FDS case. - a panel of tools for the selected
Blender Objectlinked namelist, in this case aMESHnamelist; - the
Remeshpanel, that collects several tools used to fix malformed geometries and make them manifold (eg. the triangulated surfaces required by theGEOMnamelist); - the
Geolocationpanel, with tools that allow the 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 further detail on how to run your FDS case.
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 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.
Objects can be moved to collections by dropping on the name or contents of a collection.
See the Blender datablocks wiki page for further detail on Blender datablocks and their properties.
Collections are a way BlenderFDS uses to organize the FDS case.
The exported namelists are first ordered by collection, then by ID parameter alphabetic order.
See the Organize cases wiki page for further detail on how to organize your FDS case.
The Properties editor shows and allows editing of 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 Blender Scene tab contains several panels.
The first is the FDS Case Config where you find the case general configuration.
For example, 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 Blender Scene.
The Copy To button next to the case filename is used to copy the FDS properties from a scene to another.
In the following panels you can edit the parameters of some FDS namelists
that configure general aspects of your case, as HEAD, TIME, MISC, REAC, ...
Each of these panel manages several of the most common parameters of the related namelist;
any parameter that is not directly managed by the interface
can be entered in the generic Other Parameters widget at the very bottom of each panel.
At the bottom of the tab, the Units panel allows you to set your preferred length units: metric or imperial.
The Blender Object tab hosts a panel used for specifing the linked FDS namelist
(such as OBST, VENT, GEOM, SLCF, ...) and its parameters.
A Blender Object should always refer to FDS namelist groups having
any kind of geometric extension (such as XB, XYZ, PB, VERTS, FACES, ...).
See this wiki page for further details on
how Blender Object geometries are exported to the FDS case.
At the top of the panel, you 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.
Next to the namelist selection, a Copy To button is used
to copy the parameters values from the currently active object to other selected objects.
The panel changes depending on the linked FDS namelist, and manages several of its most common 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.
The following pictures shows the tab for a Blender Object linked to one or more MESH namelists.
The Blender Material tab is used for editing the FDS boundary conditions
in the SURF namelist, related to the currently selected Blender Object.
At the top of the tab, you find the Show FDS Code button; when clicked,
it displays the exported FDS code.
Next to the namelist selection, a Copy To button is used
to copy the parameters values from the currently active material to another.
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.
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 other non-geometrical or unmanaged namelists
(eg. MATL, BNDF, ...) to the FDS case.
The choice of the Free Text file to be attached to the FDS case
and its position in the exported file is specified in the FDS Case Config panel
of the Blender Scene tab.
After exploring the BlenderFDS user interface,
it is time to save the .blend file of this default example case to a local directory.
Click on the File > Save As menu, name the file as example.blend,
and save it locally on your computer because BlenderFDS needs
an absolute reference for the relative paths you may have configured.
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 click on the File > Export > NIST FDS menu,
and export the FDS case you just explored to a newly created directory.
You can always modify later the case 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,
you can double click on the Example_case.fds file, and see what is inside.
Here I am opening the Example_case.fds file with the GEdit text editor on a Linux computer.
Notice the nice syntax-highlighting that is provided by GEdit
with the FDS extension.
On MS Windows you can install the free and open-source Notepad++ with its FDS extension.
On macOS, you can install Sublime Text and use SublimeFDS for syntax highlighting.
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, I open a terminal window, move to the appropriate directory,
and type fds Example_case.fds to run the solver on the Example_case.fds
that was just exported from BlenderFDS.
While the case is being solved, I can have a peek on what is going on by running Smokeview from another Linux terminal window.
The 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 this wiki page for further detail on how to run your FDS case from within BlenderFDS.
While your computer is running the Example_case.fds you just created,
you can go back to BlenderFDS and try another useful feature.
Click on the File > Import > NIST FDS menu, and import any of your FDS cases.
The new case is being imported into a new Blender Scene,
as each scene of a .blend file refers to a different FDS case.
The .blend file can contain many scenes, and the scenes can share data-block assets
(eg. Blender Objects, Materials).
So you can have one .blend file containing all the variations
of your many FDS cases related to the same project or research.
Here I am importing the couch.fds case.
This case is included in the official FDS package, inside the FDS/FDS6/Examples/Fires directory.
If you want to quickly, navigate between the scenes click on the pop-down menu 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.