Skip to content

About

Connected open-cell foam geometry generator for finite element and immersed-boundary tests in Julia.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

FoamGen.jl

CI

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:

  1. Describe the foam with a FoamSpec and generate a VoxelDomain.
  2. Write the domain to VTK or NRRD, optionally compress it into an octree-style block representation, or extract an STL surface.

Example Geometry

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
Octree block grid colored by cell type Occupied and interface voxel cells STL surface

Installation

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.

Quick Start

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.jl

It 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.

How It Works

  1. n_nodes random nodes are placed in the control volume. A minimum spanning tree connects them, and random edges to nearest neighbors add closed foam cells. On :periodic axes, distances use the nearest periodic image, so edges may wrap across the seam. On :boundary_contact axes, anchors at the face centers are connected to their nearest node.
  2. 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.
  3. If volume_fraction is given, the base strut radius is found by bisection so that the volume fraction measured on the sampling grid matches the target.
  4. 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.

Domain Output

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 Output

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.

Parameters

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), default 80.
  • radius: base strut radius, default 0.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, default 1.

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.

Limitations

  • The volume fraction is measured on the sampling grid by counting voxel corners, so it depends on resolution and 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_domain warns 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^3 grid 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.

Public API

The exported API is:

  • FoamSpec
  • VoxelDomain
  • OctreeDomain
  • FoamMesh
  • generate_domain
  • compress_domain
  • surface_mesh
  • write_vtk
  • write_stl
  • estimate_volume_fraction
  • solid_fractions
  • is_connected
  • write_nrrd

FoamGen.jl is released under the MIT License.

About

Connected open-cell foam geometry generator for finite element and immersed-boundary tests in Julia.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages