Adding SDF format to kernel.

[meet-brad-ch]

Add SDF (Signed Distance Field) Voxelization Support

Summary

This PR adds support for voxelizing pre-computed Signed Distance Fields (SDF) as an alternative to runtime STL mesh voxelization. SDF voxelization uses GPU-accelerated trilinear interpolation for smoother boundaries and can be faster for complex geometries that are reused across simulations.

Motivation

• Smoother boundaries: Trilinear interpolation of SDF values produces smoother solid boundaries compared to ray-casting STL triangles
• Reusable pre-computation: SDF can be generated once from high-resolution meshes and reused across multiple simulations
• Performance: For complex geometries, loading a pre-computed SDF can be faster than runtime STL voxelization
• API consistency: Follows the same patterns as existing voxelize_stl() methods

Modified Files

src/utilities.hpp (+148 lines)

• Added SDF struct for storing 3D signed distance field data
• Added read_sdf() function to load binary SDF files
• Added transpose() function for float3x3 matrices (needed for inverse rotation)

src/lbm.hpp (+5 lines)

• Added LBM_Domain::voxelize_sdf_on_device() declaration
• Added 4 LBM::voxelize_sdf() overloads matching voxelize_stl() API

src/lbm.cpp (+73 lines)

• Implemented LBM_Domain::voxelize_sdf_on_device() - uploads SDF to GPU and runs kernel
• Implemented 4 LBM::voxelize_sdf() overloads with/without center and rotation parameters

src/kernel.cpp (+88 lines)

• Added voxelize_sdf OpenCL kernel with:
  • Trilinear interpolation of SDF values
  • Full rotation support via inverse rotation matrix
  • Proper coordinate transformation: LBM space → rotated world space → SDF grid space

API

// Full API with center, rotation, and scale
void voxelize_sdf(const string& path, const float3& center, const float3x3& rotation,
                  const float scale=1.0f, const uchar flag=TYPE_S);

// Place in box center with rotation
void voxelize_sdf(const string& path, const float3x3& rotation,
                  const float scale=1.0f, const uchar flag=TYPE_S);

// Custom center, no rotation
void voxelize_sdf(const string& path, const float3& center,
                  const float scale=1.0f, const uchar flag=TYPE_S);

// Place in box center, no rotation (simplest)
void voxelize_sdf(const string& path, const float scale=1.0f, const uchar flag=TYPE_S);

Parameters:

• path: Path to binary SDF file
• center: Position in LBM coordinates where SDF center should be placed
• rotation: 3x3 rotation matrix (same as voxelize_stl)
• scale: Target size of the largest SDF dimension in LBM units
• flag: Voxel flag type (default: TYPE_S for solid)

SDF File Format

Binary format (little-endian, 36-byte header + float array):

Offset	Type	Description
0	int32	Nx (grid dimension X)
4	int32	Ny (grid dimension Y)
8	int32	Nz (grid dimension Z)
12	float32	bounds_min_x
16	float32	bounds_min_y
20	float32	bounds_min_z
24	float32	bounds_max_x
28	float32	bounds_max_y
32	float32	bounds_max_z
36	float32[NxNyNz]	SDF values (negative=inside, positive=outside)

Data layout: data[x + Nx*(y + Ny*z)]

Example Usage

// Simple usage - place SDF centered in simulation box
lbm.voxelize_sdf("model.sdf", 100.0f); // 100 LBM units size

// With rotation (same as voxelize_stl)
const float3x3 rotation = float3x3(float3(1,0,0), radians(180.0f));
lbm.voxelize_sdf("model.sdf", lbm.center(), rotation, lbm_length);

Generating SDF Files

SDF files can be generated from STL meshes using SDFGenFast:

git clone https://github.com/meet-brad-ch/SDFGenFast
cd SDFGenFast/tools
./configure_cmake.bat Release
./build_with_vs.bat SDFGen Release
# Generate SDF with 128 cells in smallest dimension
SDFGen.exe model.stl 128

Testing

• Tested with cow model: 996,355 solid voxels, ~7000 MLUPs performance
• Verified positioning matches original STL-based cow example exactly
• Rotation support verified with 180° rotations matching STL behavior

Backward Compatibility

• No changes to existing APIs
• All existing examples and simulations work unchanged
• New functionality is purely additive

[meet-brad-ch]

This is the example code. The SDF file can be generated from cow.stl.
setup.cpp.txt