Dev Scripting

ℹ️ Work in progress

This wiki page explains how to manage an FDS case using Python scripting in Blender.

• Introduction
• Create a cube
• Name the FDS case
• Set a GEOM namelist
• Set a MESH namelist
• Discover BFDS properties and operators

Introduction

Blender includes a powerful scripting environment based on Python, which allows you to automate tasks, customize workflows, and extend Blender’s functionality. Almost everything you can do in the user interface can also be controlled through Python scripts.

With scripting you can automate repetitive modeling, access and modify BFDS data.

Blender provides an interactive Python Console and a Text Editor where you can write and run scripts directly inside the application.

The Blender API is accessible through the bpy module, which exposes Blender’s internal data and operators.

Scripting is particularly useful for those who want to automate the precise control over their FDS cases.

See the Blender documentation for Python scripting in Blender.

Create a cube

First of all, open a new Blender file and save it in a working folder of your choice. This is important, because the script is going to generate its output in that folder.

If you do not save the blend file, the example script is not going to work properly

In Blender’s top menu, switch to the Scripting tab. You’ll see a Text Editor, a Python Console, and an Info panel.

In the Text Editor, click New to create a blank script file.

Paste the example code below and run the script by clicking the Run Script button, the play icon in the text editor header.

import bpy

# Remove all existing objects
bpy.ops.object.select_all(action='SELECT')
bpy.ops.object.delete()

# Create a cube
bpy.ops.mesh.primitive_cube_add(size=2, location=(0, 0, 0), rotation=(0, 0, 30))

# Get the Blender context
context = bpy.context

# Get the new cube
ob = context.object

# Change the cube’s name
ob.name = "MyCube"

Your 3D Viewport editor will update: the default objects disappear, and a new cube appears at the origin. In the Outliner, you’ll see the new object named MyCube.

Try running the script multiple times and observe how the scene is reset and rebuilt.

• Change the cube size in primitive_cube_add(size=2, ...).
• Modify the location, for example (2, 0, 0) to shift it along the X-axis.
• Rename it by editing MyCube.

Update the name of the FDS case

Add the following lines to the previous script:

# Get the current Blender Scene
sc = context.scene

# Update the FDS case name from the default
sc.name = "test_case"

If you run the script, you discover that the Blender Scene name has been updated.

Set a GEOM namelist

Add the following lines to the previous script:

# Enable the FDS namelist rendering 
ob.hide_render = False

# Set the type of namelist to GEOM.
ob.bf_namelist_cls = "ON_GEOM"

# Get the predefined INERT material
ma = bpy.data.materials['INERT']

# Add the INERT material to the object slots
ob.data.materials.append(ma)

# Export the FDS code generated by the current scene
bpy.ops.export_scene.fds()

When you run the modified script, the MyCube object is linked to a GEOM namelist. Then the namelist is updated, and the FDS code is exported.

If you browse, to the working directory where you saved the blend file, you will find the test.fds case and the bingeom geometry file.

I know, ob.hide_render = False to enable the FDS namelist exporting is counterintuitive... But BFDS is reusing the Blender settings originally used object rendering. If you want to disable the FDS namelist exporting, set that object property to True.

As in the Property Panel user interface, you can link other types of namelists that need a geometric extent to the current Blender Object: eg. ob.bf_namelist_cls = "ON_OBST". Other possible choices are: ON_DEVC, ON_GEOM, ON_HOLE, ON_INIT, ON_MESH, ON_OBST, ON_other, ON_PROF, ON_SLCF, ON_VENT, ON_ZONE These are the names of the Python classes that define the FDS namelists in BFDS code. Find them in the source/lang folder. For your curiosity, that 'ON' prefix means: 'Object Namelist'.

Set a MESH namelist

The exported FDS case, as it is now, will not run in FDS, because it has no MESH domain. So let's add it.

Append the following code to the previous script.

# Create another cube
bpy.ops.mesh.primitive_cube_add(size=4, location=(0, 0, 0), rotation=(0, 0, 0))

# Get the last created cube
ob = context.object

# Enable the FDS namelist rendering 
ob.hide_render = False

# Change the cube’s name
ob.name = "Domain"

# Set the type of namelist to mesh.
ob.bf_namelist_cls = "ON_MESH"

# Set the GEOM FYI parameter
ob.bf_fyi = "This is a domain"

# Set the GEOM IJK parameter
ob.bf_mesh_ijk = 20, 20, 20

# Export the FDS code generated by the current scene
bpy.ops.export_scene.fds()

When you run the modified script, the Domain object is linked to a MESH namelist.

After the FDS code is exported in your working directory, you can run the FDS case on the console. Open Smokeview and see your first scripted case.

Discover BFDS properties and operators

Python tooltips

In Blender you can see Python tooltips directly in the interface. This is one of the best ways to learn scripting, because Blender shows you the Python command behind almost every button and menu action.

The Python tooltips are not shown by default — you need to enable them in the preferences. Here’s how:

1. Open the Blender preferences with the Edit > Preferences menu.
2. In the left sidebar, click on Interface.
3. Enable Developer Extras and Python Tooltips-

Now, when you hover over buttons, sliders, or checkboxes, the tooltip will also show the Python property or operator you can use in scripts.

The tooltip will show:

• A description of the property or operator.
• Its Python reference (useful for scripting).

See the Blender documentation for further detail.

Python console

In the Scripting workspace, open the Python Console.

You can test Python commands interactively. Use Tab completion to explore available properties. For example, by typing bpy.context. and pressing the Tab key shows all possible options.

See the Blender documentation to learn the wonders of the Python console.