VoxelSieve

VoxelSieve

Open-source tooling for industrial CT volumes, built on OpenVDB.

Reconstructed CT volumes are large, uncompressed raw files in which most voxels are air. VoxelSieve separates the surrounding air from the part, keeps internal voids such as pores, and stores the result as a sparse, bricked VDB dataset that works for scans larger than memory. On top of it, it finds pores and loosened microstructure and writes an inspection report.

All images of the porosity analysis come from one synthetic scan of the sample bell housing, 765 × 765 × 380 voxels of 0.1 mm (445 MB), with the shrinkage cavities and loosened zones where a casting solidifies last: vs-synth --part bellhousing --voxel-size 0.1 --hot-spots --lunker 12 --lunker-radius 0.9 --lunker-spread 0.6 --loosening 3 --loosening-radius 1.5 --noise 500 --cupping 0.08 --blur 0.07 --seed 12. Every lunker volume is found within 2 % of the ground truth (the smallest, 0.06 mm³, within 4 %), the zones deep in the flanges within 2 % and those just below the surface within 10 %, and the part volume within 0.02 %.

Status: early development, latest release 0.3.1 (see CHANGELOG.md). New here? The quickstart takes you from download to a porosity report with an AI assistant, using sample data. The tools:

Build

Dependencies come from vcpkg, pinned in vcpkg.json. On Ubuntu 24.04:

sudo apt-get install cmake ninja-build g++ git curl zip unzip tar autoconf automake libtool pkg-config

tools/setup-vcpkg.sh && export VCPKG_ROOT=~/vcpkg cmake --preset release && cmake --build --preset release && ctest --preset release ./build/release/apps/vs-phantom/vs-phantom --out phantom --dims 256

This writes phantom.raw (uint16, little endian, x fastest) and phantom.json with the format description and the analytic ground truth (pores, wall thickness, material volume).

The first configure builds OpenVDB, Boost and TBB from source, which takes a while; vcpkg keeps the result in its binary cache for later builds. A build directory configured before the switch to vcpkg does not pick up its toolchain; configure it again with --fresh (cmake --preset release --fresh).

On Windows (x64, the MSVC 2022 build tools with the C++ workload, from a Developer PowerShell with Git Bash on the PATH) and macOS (Apple silicon, Xcode command line tools plus brew install ninja autoconf autoconf-archive automake libtool pkg-config), use the preset windows or macos instead of release. On Windows the programs land in build/windows/bin.

Sieve a volume

VoxelSieve writes either a bricked dataset (any size, streamed) or a single .vdb grid (small volumes, in memory).

Bricked dataset for large scans

./build/release/apps/vs-sieve/vs-sieve scan.raw --out scan.vsieve

scan.vsieve/ holds index.json, overview.vdb (the whole volume in one grid of at most 256³ voxels) and level0/, level1/, … with one VDB file per 256³ brick. Bricks that contain only outside air are not written. The input is memory-mapped and processed in two streaming passes, so the scan does not need to fit in RAM. --phantom N sieves a computed N³ phantom instead of a file.

Raw files from CT systems usually start with a proprietary header. VoxelSieve skips it: given the dimensions, everything in the file beyond the voxel data is taken as the header, and the detected size is printed. Use --header when the file also has a footer, --type uint8 for 8-bit data and --big-endian for big-endian 16-bit samples. Check the printed header size: wrong dimensions that are too small also leave extra bytes and would be misread as a header.

The computed phantom is slower because every voxel is evaluated twice; its memory figure shows the sieve's own footprint without mapped input pages.

Programs read a dataset through voxelsieve::Dataset, which loads bricks on demand into an LRU cache with a memory budget:

const auto dataset = voxelsieve::Dataset::open("scan.vsieve", /*cache_bytes=*/4ULL << 30U);

std::optional value = dataset.sample(0, {512, 400, 300}); // nullopt for removed air std::vector slab(512 * 512 * 16); dataset.readRegion(0, {{0, 0, 300}, {512, 512, 316}}, slab); // across brick boundaries dataset.forEachGrid(1, [](const auto& brick, const auto& grid) { /* parallel, uint16/uint8/float */ });

TIFF stacks

./build/release/apps/vs-sieve/vs-sieve slices/ --out scan.vsieve --voxel-size 0.05

./build/release/apps/vs-sieve/vs-sieve scan.zip --out scan.vsieve # read without extracting ./build/release/apps/vs-sieve/vs-sieve scan.zip --folder target --threshold 0.5 --out labels.vsieve ./build/release/apps/vs-sieve/vs-sieve recon.zip --value-range -0.05,0.3 --out scan.vsieve # float ./build/release/apps/vs-sieve/vs-sieve pipe.zip --air-from xy --out pipe.vsieve # cut at both ends

A directory of slices, a multi-page TIFF or a ZIP archive of either is read directly (voxelsieve::TiffStackSource, ADR 0011). Slices are sorted by name with numbers by value (slice2 before slice10). Supported are classic TIFF and BigTIFF, strips and tiles, uncompressed, LZW, Deflate and PackBits, with or without horizontal predictor, and unsigned 8 or 16 bit samples; 32-bit samples are accepted as long as they fit into 16 bits (label volumes). Float slices (32 or 64 bit, also with the floating-point predictor) are mapped linearly onto grey values 0 to 65535 over a value range, given with --value-range or estimated from 33 slices; the mapping is printed and recorded in the dataset's index.json (value = offset + scale * grey), and values outside the range are clipped and counted (ADR 0015). Colour and signed images are refused. When the first and last slice cut through the part (a pipe, a drill core), --air-from xy lets outside air in only from the sides, so the inside of the part is kept (ADR 0003). When the input holds several folders of slices, the grey values are taken, not a folder named like labels or masks (label*, mask*, seg*, gt, target); the others are printed and can be chosen with --folder. The voxel size comes from an OME-XML image description (PhysicalSizeX, Y, Z), a centimetre resolution, an inch resolution that is not a printing default such as 72 or 300 dpi, or a key=value image description (including its slice spacing), otherwise 1 mm is assumed and printed; set it with --voxel-size. In the GUI this is the operation import_tiff. For a dataset, the slices are first decoded once, on all cores, into a temporary raw file of 2 bytes per voxel in the output directory (elsewhere with --staging-dir), which is removed at the end; --no-staging reads the slices directly, which is much slower for large stacks.

DICOM stacks

./build/release/apps/vs-sieve/vs-sieve dicom/ --out scan.vsieve          # a directory of slices

./build/release/apps/vs-sieve/vs-sieve dicom.zip --out scan.vsieve # the same in a ZIP archive

A directory of DICOM slices, or a ZIP archive of them (read without extracting it, each entry checked against its CRC), is read with DCMTK (voxelsieve::DicomStackSource, ADR 0019): uncompressed or RLE, with or without preamble, sorted along the slice normal by their position. Voxel size and pose come from the files. Signed samples are shifted by 32768 and, with the rescale slope and intercept, recorded as the value mapping, so no value is lost. When a directory holds several series, the largest is read and the others are printed. In the GUI this is the operation import_dicom. When the slices are thinner than their spacing, or much farther apart than the pixels, the import summary warns (warnings), and interpolate_slices (all imports) fills the gaps with slices interpolated between the measured ones.

DICONDE

./build/release/apps/vs-diconde/vs-diconde scan.vsieve --porosity scan.porosity \

--materials scan.materials --order examples/inspection_order.json --out scan.diconde ./build/release/apps/vs-diconde/vs-diconde --info scan.diconde/volume

DICONDE (ASTM E2339) is DICOM for nondestructive evaluation (ADR 0024). VoxelSieve writes a dataset as a series of CT images, one file per slice, with the exact grey values, the voxel size and the position of the object; removed outside air gets the air level. The inspection order becomes the component (part, serial number, drawing, material), the inspection (laboratory, customer, report and order number, inspector, the evaluation against the acceptance limits) and the scan settings. Pores and loosened zones become indications with their position, volume and size, and a material segmentation a second, derived series of labels in the same coordinates. DICONDE files are read like other DICOM slices (vs-sieve, import_dicom), and the import reports their component and indications. In the GUI this is the operation export_diconde.

First look while importing, also from a network share

./build/release/apps/vs-sieve/vs-sieve /mnt/ct-share/part.zip --out part.vsieve --preview first.png

Before the passes, the import reads 64 whole slices spread evenly over the volume and shows them at once: the central sections normal to z, y and x, averaged in-plane to at most 1024 voxels per edge and 32 million voxels in all, and the histogram of those slices with the estimated threshold (ADR 0020). While a staged import copies the rest, the preview gets sharper: it reads the other preview slices coarse to fine, three