FoamGen.jl generates connected open-cell foam test geometries for finite element and immersed-boundary computations. The geometry is sampled inside an axis-aligned control volume and can be exported as a voxel/signed-distance domain, as an adaptive block grid, as a CT-like image of per-voxel solid fractions, or as an STL triangle surface.
The package is intentionally small. It has no non-stdlib Julia dependencies and exposes a narrow workflow:
- Describe the foam with a
FoamSpecand generate aVoxelDomain. - Write the domain to VTK or NRRD, optionally compress it into an octree-style block representation, or extract an STL surface.
The images below show the foam of the quick-start example as the compressed octree block grid colored by cell type (outside, interface, solid), the same grid reduced to its interface and solid cells, and the extracted STL surface.
| Octree Block Grid | Occupied/Interface Cells | STL Surface |
|---|---|---|
![]() |
![]() |
![]() |
Install the package directly from the repository:
import Pkg
Pkg.add(url = "https://github.com/schmaeke/FoamGen.jl.git")The package requires Julia 1.10 or newer.
using FoamGen
spec = FoamSpec(
bbox = ((0.0, 0.0, 0.0), (1.0, 1.0, 1.0)),
resolution = (128, 128, 128),
n_nodes = 100,
radius = 0.03,
volume_fraction = 0.12,
boundary = (:periodic, :free, :boundary_contact),
seed = 4,
)
domain = generate_domain(spec)
write_vtk("foam_domain.vtk", domain)
write_nrrd("foam_fraction.nrrd", domain)
tree = compress_domain(domain)
write_vtk("foam_octree.vtk", tree)
mesh = surface_mesh(domain; smoothing = 3)
write_stl("foam.stl", mesh)
compact = surface_mesh(domain; simplify = true, smoothing = 3)
write_stl("foam_compact.stl", compact)The same workflow is available as examples/generate_foam.jl. Run it from the repository root with
julia --project=. examples/generate_foam.jlIt writes its output files next to the script; they are ignored by git. At this resolution the run takes a few seconds and writes about 140 MB.
n_nodesrandom nodes are placed in the control volume. A minimum spanning tree connects them, and random edges to nearest neighbors add closed foam cells. On:periodicaxes, distances use the nearest periodic image, so edges may wrap across the seam. On:boundary_contactaxes, anchors at the face centers are connected to their nearest node.- Each edge becomes a slightly bent strut (a quadratic Bézier curve) that is thicker at its ends than in its middle. Struts are rasterized as a smooth union of tapered cylinders into a signed-distance-like field, and small patches fill acute angles at junctions.
- If
volume_fractionis given, the base strut radius is found by bisection so that the volume fraction measured on the sampling grid matches the target. - All outputs are derived from the sampled field: dense VTK, compressed block VTK, NRRD images of per-voxel solid fractions, and STL surfaces via smoothing and marching tetrahedra.
generate_domain(spec) returns a VoxelDomain. Its field is sampled on a
regular grid over bbox; field <= 0 is solid foam and field > 0 is outside.
is_connected(domain) checks that the occupied voxel cells form one component,
counting connections across periodic faces.
solid_fractions(domain) returns the estimated solid volume fraction of every
voxel cell. Cells crossed by the foam surface are evaluated on a 4 × 4 × 4
sub-grid of the interpolated field (set samples to change this), so the
values resolve where the surface passes through each voxel.
write_vtk(path, domain) writes the full voxelized control volume as a legacy
VTK STRUCTURED_POINTS file. The file contains point data signed_distance and
cell data cell_type plus solid_fraction. Cell types are 0 outside, 1
interface, and 2 solid. This dense file is useful when a finite-element code
wants to read the whole regular grid directly.
write_nrrd(path, domain) writes the solid fractions as an NRRD image volume
with one voxel per voxel cell, similar to a computed-tomography scan of the
foam. Values are Float32 fractions in [0, 1], or 8-bit gray values with
type = UInt8. The header stores spacing and origin, so ParaView, 3D Slicer,
ITK, and similar tools place the image in the control-volume coordinates. At
128^3 grid points the file is about 8 MB.
compress_domain(domain) builds an adaptive octree-style OctreeDomain.
Uniform outside and solid regions are stored as larger hexahedral blocks, while
interface cells remain at voxel resolution. write_vtk(path, tree) writes this
compressed full domain as a legacy VTK UNSTRUCTURED_GRID whose blocks share
corner points; neighboring blocks of different size leave hanging nodes.
surface_mesh(domain) extracts a triangle surface from a smoothed copy of the
signed-distance field. The original voxel domain is not changed, so VTK export
always remains the resolved sampled domain. Triangle normals point out of the
solid, and on periodic axes the surface traces on opposite faces coincide, so
copies of the surface tile without gaps.
Use surface_mesh(domain; smoothing = 0) to disable smoothing or increase the
integer smoothing value for a softer surface. Use simplify = true to resample
the smoothed surface field on a coarser grid before extraction, or set the
spacing of that grid explicitly:
mesh = surface_mesh(domain; smoothing = 3)
compact = surface_mesh(domain; spacing = 0.01, smoothing = 3)write_stl writes binary STL by default; pass binary = false for ASCII STL
with full double precision. STL stores triangle corners directly rather than an
indexed vertex table, so compare length(mesh.faces) or file size when
checking compact output.
FoamSpec keeps the public configuration compact (see ?FoamSpec for details):
bbox: axis-aligned control volume, default unit cube.resolution: number of grid points per axis, default(96, 96, 96).n_nodes: number of graph nodes (strut junctions), default80.radius: base strut radius, default0.035.volume_fraction: optional sampled volume-fraction target. When set, the radius is tuned automatically.boundary: scalar boundary mode or per-axis tuple in(x, y, z)order, default:free.seed: random seed, default1.
Boundary modes are intentionally limited to the robust options:
:free: struts remain inside the control volume.:periodic: branches can wrap across the selected axis.:boundary_contact: face-center anchors force contact on the selected axis.
- The volume fraction is measured on the sampling grid by counting voxel
corners, so it depends on
resolutionand is not an exact solid volume. - Struts need a few grid points across. If they are too thin for the grid, the
sampled foam falls apart and
generate_domainwarns about it. - Surfaces of domains with periodic or boundary-contact axes are open where the foam crosses those faces of the control volume.
- VTK files are written as ASCII legacy VTK. At
128^3grid points the dense file is about 50 MB. - The same seed reproduces the same domain for a given Julia version; random number streams may change between Julia versions.
The exported API is:
FoamSpecVoxelDomainOctreeDomainFoamMeshgenerate_domaincompress_domainsurface_meshwrite_vtkwrite_stlestimate_volume_fractionsolid_fractionsis_connectedwrite_nrrd
FoamGen.jl is released under the MIT License.


