quickstart - firetools/blenderfds GitHub Wiki

ℹ️ Updated to BlenderFDS 6.0.x

This wiki page guides the new user to a quick overview on how to use BlenderFDS.

• Before starting
• Overview
• Procedure

Before starting, here are some basic requirements.

You should already have the right version of 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, to complete this quickstart guide.

If not, follow this documentation. In any case, you should already be capable of writing and running simple FDS cases, before learning how to use BlenderFDS to facilitate this complex 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:

• Blender manual
• Blender tutorials

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 Viewport editor,
• the Ouliner tree,
• the Properties panels,
• 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.

On the left-hand side of this editor, you see Blender several editing modes, used for editing different kinds of data. Within BlenderFDS we are going to use just two of them. Unfortunately, it is currently not possible to hide the other ones from the user interface.

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 Mode and Edit 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:

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 Disable in Renders 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 active case, and setup some of its general FDS namelists.

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 Object geometries 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 linked to the active Material. 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 Materials are 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 or the new Gnome Text Editor with this extension.

On MS Windows, I suggest you to install the free and open-source Notepad++ text editor. Here is its extension for syntax highlighting.

On MacOS, you can install Sublime Text and use this 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.fds

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 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 Object and Material instances) can be shared between all your cases, therefore avoiding repetition and errors.

A single .blend file 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.

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.