charliecallahan/charlies_voxel_octree

This is a C++ library for working with voxels, which are tiny 3D cubes used to represent solid shapes, similar to pixels but in three dimensions. It stores voxel data in a structure called a sparse bit octree, a tree shaped format that only records where solid material actually exists, so empty space costs almost no memory. Each leaf voxel takes as little as one bit, and there is also an 8 bit version available for storing extra information per voxel. Branch nodes point to their children using compact 32 bit indices into a memory pool rather than full pointers, which keeps memory use low and makes saving the whole structure to a file as simple as dumping that pool directly. The library's other major piece converts a triangle mesh, the kind of 3D model made of connected flat triangles, into this voxel format. It builds a bounding volume tree over the mesh using a library called tinyBVH, then classifies each candidate voxel as inside, outside, or crossing the mesh surface, subdividing the crossing ones further until it reaches the resolution you asked for. This classification step can run on the GPU using OpenCL for a large speed boost at high resolutions, or fall back to the CPU if OpenCL is not available or not wanted. A bundled command line tool called voxelize_stl takes an STL mesh file and writes out a binary voxel file, with options to set the voxel size, override the tree depth, or force the CPU path. The README shows a Stanford bunny model voxelized at two resolutions, with one finishing in under a tenth of a second and using 174 kilobytes, and the other taking about 8 seconds and using 2.8 megabytes, measured on a Mac M1 GPU. The project also shows a short code example for embedding the library directly in another C++ program. It requires a C++17 compiler, make, and curl to fetch its one dependency, with OpenCL as an optional extra for GPU acceleration. It is released under the MIT license.