🔬 Cavity Detection Pipeline

From CIF file to 3D void visualization — SDF + Fill & Spread + Marching Cubes

Main Step
Optimization
Parallel Processing
Critical Step
Channel Detection
PHASE 1: Initialization Load CIF, symmetry expansion, atom preparation 📄 Load CIF File Parse structure file Unit cell: a, b, c, α, β, γ Space group, symmetry ops 🔁 Symmetry Expansion Generate all equivalents Apply space group operations Max 48 symmetry ops ⚛️ Atoms + Neighbors Full atom list for scanning VdW radii with multiplier (0.8–2.0) Neighbor margin: 2.0 Å ⚡ Fast Atom Cache Optimized atom storage FastAtom[] struct array Sorted by X coordinate ⚡ 30-45% speedup PHASE 2: SDF — Signed Distance Function Compute distance from each voxel to nearest atom surface 📊 Voxel Grid Creation Crystal-aligned grid Resolution: 108–154 per axis Voxel size: 0.10–0.30 Å 🧮 SDF Calculation minDist² to all atoms SDF = distance to surface Negative = inside atom ⚡ Fast Rejection 3D Binary search + 3D rejection Only 5% atoms reach full dist² Culling, local variables 🔧 Fill Gaps 3 iterative passes Fill SDF holes Smooth density 🔴 Critical for quality ⚡ 85-95% speedup PHASE 3: Buffer Split — Two Separate Grids One for rendering (with walls), one for detection (periodic) 🎨 Graphic Density (for Rendering) WITH artificial walls for Marching Cubes Wall thickness: 4 voxels Closed mesh generation 🔄 Periodic Density (for Detection) WITHOUT walls — periodic boundary conditions Copy center + borders from supercell Open boundaries for tunnel detection 🔷 Enables cross-boundary cavity detection PHASE 4: Fill & Spread — Cavity Detection Identify connected void regions on periodic grid 🌊 Flood Fill Spread through empty voxels 6 directions (±X, ±Y, ±Z) Periodic boundary wrap Queue-based BFS 📦 Cavity Regions Voxel list, volume, center Bounding box calculation Min volume filtering Min voxel count: 100 🧱 Walls & Tunnels Touches X-/X+ Y-/Y+ Z-/Z+ Channel detection: XX, YY, ZZ BFS connection check (no wrap) Topology = wall connections 🔗 Periodic Groups Merge duplicate cavities PeriodicGroupId IsPeriodicDuplicate flag Color grouping 🔮 Channel: XX, YY, ZZ, XXYY, XXZZ, YYZZ, XXYYZZ ⚡ 40-60% speedup (parallel per cavity) PHASE 5: Marching Cubes — Mesh Generation Convert density grid to triangle mesh (parallel per cavity) 🎭 Apply Mask Use VoxelMask from detection Only cavity voxels = empty Outside = -10.0f (wall) 🔺 Triangle Generation Marching Cubes lookup EdgeTable + TriTable Parallel per cavity 🧭 Normals Computation Gradient from atoms → cavity -gradient (points from cavity to atoms) FixTriangleWinding disabled ✂️ Clip to Cell Remove outside triangles Vector4.Transform SnapSharedVertices 🔴 Most expensive step ⚡ 35-60% speedup (stackalloc, long keys) 🔷 Vector4.Transform optimized PHASE 6: Rendering — Visualization Display cavities on screen with lighting and info 🖥️ Draw Modes VoxelPoints / MarchingCubesWireframe MarchingCubesMesh / CavityColorMap TopologyColorMap 💡 Lighting BasicEffect with normals 2 directional lights Ambient + Diffuse + Specular 📊 Info Panel Cavity statistics on screen Volume, Surface Area, Sphericity Channels: XX, YY, ZZ, XXYY... PHASE 7: Repeat Cells — Supercell Construction Build repeated cavities with correct skew angles 📐 Vector A vecA = (a, 0, 0) Along X axis 📐 Vector B vecB = (b·cosγ, b·sinγ, 0) Angle γ between a and b 📐 Vector C vecC = (c·cosβ, c·(cosα−cosβ·cosγ)/sinγ, c·√(...)) Angles α, β, γ included 🔁 Shift Formula shift = x·vecA + y·vecB + z·vecC Supports all crystal systems 🔴 Critical for non-orthogonal cells ⚡ OPTIMIZATIONS: Cache · bool[] · Parallel.For · BFS no-wrap · stackalloc · Dictionary ✅ OUTPUT: Cavity data ready for analysis Voxels · Surface Points · Marching Cubes Mesh · Volume · Surface Area · Channels · Sphericity
CIF Program • Cavity Detection Pipeline • 2026 • Optimized for speed and accuracy