Geometries - firetools/blenderfds GitHub Wiki

:information_source: Work in progress

This wiki page explains how the geometries referenced by a Blender Object are exported to FDS geometric namelists.

The Blender Object and its shape

Each Blender Object represents a geometric entity in the Blender Scene 3d space.

While the object data-block acts as a local reference system and contains the item location, rotation, and scale, the Object shape is described by a related Blender Mesh data-block. The mesh is a collection of connected vertices, edges, and faces.

The traditional FDS geometric namelists

The so called geometric FDS namelists extend their effects to volumes, planes, faces, segments, or points in the FDS domain. For example, this namelist generates a box-shaped obstacle to the fluid:

&OBST ID='Example obstacle' XB=-1.0,1.0,-1.0,1.0,-1.0,1.0, /

See the FDS User's Guide for further details.

The more common geometric FDS namelists are: DEVC, HOLE, INIT, MESH, OBST, PROF, SLCF, VENT, and ZONE. Those namelists always require one or more of the following geometric parameters: XB, XYZ, PBX, PBY, or PBZ.

BlenderFDS manages those geometric parameters in the panel related to the active Object in the Properties editor and takes care of exporting/importing the related namelists to FDS as shown in the following paragraphs.

The XB parameter

In FDS, the XB parameter is able to represent a parallelepiped parallel to the reference axis, a flat face perpendicular to one of the reference axis, or any segment in space.

You can select one of the following transformations for the active Object shape to the XB parameter of the exported namelist.

XB Exported as Example
Bounding Box Export one namelist, a parallelepiped corresponding to the bounding box of the shape
Voxels Export many namelists, stair-stepping approximation of the shape volume
Faces Export many namelists, one per face of the shape, set parallel to reference planes
Edges Export many namelists, one per edge of the shape.

If your shape is not an axis oriented box but something else, eg. a cylinder, you can choose the Voxels transformation, that approximates the round shape with many smaller axis oriented boxes.

When stair-stepping the shape volume, the size of the voxel is taken from the Voxel/Pixel Size setting on the FDS Case Config panel. The resolution can be also customized for each object by filling the appropriate setting Custom Voxel/Pixel Size under the XB field.

The Center Voxels/Pixels setting centers the stair-stepping algorithm to the object, instead of the default alignment with other objects voxels. The default alignment prevents the formation of holes between the stair-stepped shapes. The voxel centering improves the fidelity of the stair-stepped geometry to the original shape, eg. for creating a symmetric stair-stepped sphere.

The IDs Suffix setting adds different kinds of suffixes to the object ID parameter, when generating multiple namelists from the same object.

The XYZ parameter

In FDS, the XYZ parameter is able to represent a point in space. BlenderFDS proposes two different transformations for exporting Object shapes to the XYZ parameter.

XYZ Exported as Example
Vertices Export many namelists, one per shape vertex
Center Export one namelist, center point of the object None

For example, if you wish to create a line of thermocouples, add a new an object, set its namelist to DEVC and XYZ parameter to Vertices. Then create the vertices in the appropriate locations.

By setting the IDs Suffix to z you obtain these DEVC namelists with nice ID parameters:

! XYZ Vertices: 7
&DEVC ID='TC_z+0.500' XYZ=1.500000,1.500000,0.500000 QUANTITY='THERMOCOUPLE' /
&DEVC ID='TC_z+0.700' XYZ=1.500000,1.500000,0.700000 QUANTITY='THERMOCOUPLE' /
&DEVC ID='TC_z+0.900' XYZ=1.500000,1.500000,0.900000 QUANTITY='THERMOCOUPLE' /

The PBX, PBY, and PBZ parameters

In FDS, the PB* parameters represents a plane perpendicular to one of the reference axis. BlenderFDS proposes one only transformation of the Object shape to the PB* parameters.

PB* Exported as Example
Planes Export many namelists, one per face of the shape, set parallel to reference planes

For example, if you need to generate several SLCF slice files, add a new an object, set its namelist to SLCF and PB* parameter to Planes. The faces you create in the object are transformed into planes, parallel to reference planes.

Here are the SLCF namelists you obtain:

! PB* Planes: 2
&SLCF ID='Temp slice_x+0.000' PBX=0.000000 QUANTITY='TEMPERATURE' VECTOR=T CELL_CENTERED=T /
&SLCF ID='Temp slice_y-0.000' PBY=-0.000000 QUANTITY='TEMPERATURE' VECTOR=T CELL_CENTERED=T /

The GEOM namelist

Recent FDS versions propose an additional geometric namelist named GEOM. This namelist extends the traditional OBST box-shaped obstacle to a generic-shaped obstacle in the fluid domain. The GEOM namelist requires other geometric parameters as VERTS, FACES, VOLUS, or the reference to an external .bingeom binary file referenced from the BINGEOM_FILE parameter, to describe the shape of its effect on the fluid domain.

Here are examples of both types:

&GEOM ID='Example' SURF_ID='S1','S2',...
      VERTS=-1.0,1.0,-1.0,... FACES=1,2,1,1,...
      /

&GEOM ID='Example' SURF_ID='S1','S2',...
      BINGEOM_FILE='~/example.bingeom'
      /

BlenderFDS imports both formats, but exports only the more compact bingeom format.

As already said, the shape of a Blender Object is made of vertices, edges, and faces. It is exactly the same representation used by the GEOM namelist in FDS. So the shapes of the objects can be exported/imported as they are without transformation.

The GEOM properties panel

The GEOM panel in the Properties editor proposes several settings.

First of all, FDS has strict requirements on the quality of the triangulated surface of GEOM namelists. When representing a solid obstacle in space, the surface shall be manifold and closed. So BlenderFDS performs a series of automatic sanity checks while exporting. If they are too intrusive for your use case, these checks can be disabled by toggling the Check Sanity While Exporting parameter.

You can optionally set the filename and the path of the .bingeom file that is going to be created upon export. The default filename is taken from the name of the Blender Mesh, that describes the shape of the active Blender Object.

If the Object shape is shared with other Object instances, eg. several identical chairs around a table sharing the same Blender Mesh shape, the exported .bingeom file is going to be shared between the genrated GEOM namelists, and a MOVE namelist is going to be added to each GEOM to take care of the positions, rotations, and scales of each entity, in our example the chairs.

The IS_TERRAIN and EXTEND_TERRAIN toggles are used when the GEOM namelist represents vast terrains for wildfire or smoke dispersion of fire pollutants simulations Look at the FDS documentation for advice on application.

Remeber also that there is another companion tool for terrains. The qgis2fds tool is an open QGIS plugin that exports terrains and landuse from geographical data for wildfire simulation and atmospheric dispersion of fire pollutants. The FDS file generated by qgis2fds can be imported to BlenderFDS for further customization.

The GEOM tool sidebar

The GEOM sidebar offers several tools for checking and fixing the triangulated surfaces, before exporting them to FDS.

When the 3D Viewport editor is in Object Mode:

  • if you click on the Check Sanity button, the selected object triangulated surface is checked for manifoldness;

  • clicking on the Check Intersections button, you verify the existance of intersections between the current active object and all the selected objects geometries;

  • if you untoggle the Protect Original setting, when checking geometry sanity or intersections BlenderFDS selects the offending elements in the 3D Viewport after changing the editor mode to Edit Mode. Note that in this case the checked geometry has to be triangulated, thus modified from the original state.

When the 3D Viewport editor is in Edit Mode, a Clean Up panel is shown, where selection tools and cleanup tools are offered.

Remeshing panel

Remeshing is a technique that automatically rebuilds the geometry with a more uniform topology, and is often used to fix bad geometries by generating a new manifold mesh from the current geometry. It produces a mesh with perfectly even distributed topology.

The BlenderFDS Remesh panel is a convenience copy of the same panel used in Blender in Sculpting Mode. Read its documentation here.

See also the Blender Remesh Modifier for a different approach to the same technique, here is its documentation.