CSG operation by limited Python API

[Megidd]

Limitation

The OpenVDB Python module is limited:

https://www.openvdb.org/documentation/doxygen/python.html

The Python module exposes most of the functionality of the C++ Grid class, including I/O, metadata management, voxel access and iteration, but almost none of the many tools.

Conda OpenVDB

I'm using this Python package:

https://anaconda.org/channels/conda-forge/packages/openvdb/overview

CSG operation

I'm going to do a CSG difference operation. But there are no API tools for it, like csgDifference. Therefore, I have to do it by a workaround using NumPy:

def boolean_difference(plate_grid, cutter_grid):
    """CSG difference via dense array conversion."""
    import numpy as np

    # 1. Get combined bounding box
    plate_bbox = plate_grid.evalActiveVoxelBoundingBox()
    cutter_bbox = cutter_grid.evalActiveVoxelBoundingBox()

    min_ijk = tuple(min(p, c) for p, c in zip(plate_bbox[0], cutter_bbox[0]))
    max_ijk = tuple(max(p, c) for p, c in zip(plate_bbox[1], cutter_bbox[1]))
    shape = tuple(mx - mn + 1 for mn, mx in zip(min_ijk, max_ijk))

    # 2. Convert to dense arrays
    background = plate_grid.background
    plate_array = np.full(shape, background, dtype=np.float32)
    cutter_array = np.full(shape, background, dtype=np.float32)

    plate_grid.copyToArray(plate_array, ijk=min_ijk)
    cutter_grid.copyToArray(cutter_array, ijk=min_ijk)

    # 3. CSG difference: max(A, -B)
    result_array = np.maximum(plate_array, -cutter_array)

    # 4. Convert back to VDB
    result_grid = plate_grid.deepCopy()
    result_grid.clear()
    result_grid.copyFromArray(result_array, ijk=min_ijk)
    result_grid.prune()

    return result_grid

Question

The Conda OpenVDB package is exposing the API methods listed below. How can I use the following available methods to replace the NumPy trick shown above in my boolean_difference function? Thanks for your help.

The available API methods for FloatGrid are:

(blender_openvdb) C:\Users\m3\repos\jewelry-personalization\flat-carve>conda run -n blender_openvdb python -c "import openvdb as vdb; g = vdb.FloatGrid(); print('\n'.join(sorted([m for m in dir(g) if not m.startswith('_')])))"
activeLeafVoxelCount
activeVoxelCount
addStatsMetadata
background
citerAllValues
citerOffValues
citerOnValues
clear
combine
convertToPolygons
convertToQuads
copy
copyFromArray
copyToArray
createLevelSetFromPolygons
creator
deepCopy
empty
evalActiveVoxelBoundingBox
evalActiveVoxelDim
evalLeafBoundingBox
evalLeafDim
evalMinMax
fill
getAccessor
getConstAccessor
getIndexRange
getStatsMetadata
gridClass
info
iterAllValues
iterOffValues
iterOnValues
iterkeys
leafCount
mapAll
mapOff
mapOn
memUsage
merge
metadata
name
nodeLog2Dims
nonLeafCount
oneValue
prune
pruneInactive
saveFloatAsHalf
sharesWith
signedFloodFill
transform
treeDepth
updateMetadata
valueTypeName
vectorType
zeroValue


(blender_openvdb) C:\Users\m3\repos\jewelry-personalization\flat-carve>

What I have tried

I have tried to use the mapOn and combine methods, like below. However, the problem is that the combine() function only operates on voxels active in BOTH grids. For level sets, active voxels exist only in the narrow band around each surface. Where the bands don’t overlap, the operation is skipped. So, the following mapOn and combine approach is not working for me, resulting in unexpected outputs.

def boolean_difference(plate_grid, cutter_grid):
    """
    Perform CSG difference: plate - cutter using level set math.

    For signed distance fields (level sets):
    - Negative values = inside surface
    - Positive values = outside surface

    CSG Operations:
    - Union:        min(A, B)
    - Intersection: max(A, B)
    - Difference:   max(A, -B)

    Note: combine() empties the second grid.
    """
    # Negate cutter: flip inside/outside by multiplying all values by -1
    cutter_grid.mapOn(lambda x: -x)
    log.debug("Negated cutter grid values")

    # CSG difference = max(plate, -cutter)
    plate_grid.combine(cutter_grid, lambda a, b: max(a, b))
    log.debug("Applied CSG difference via combine(max)")

    return plate_grid

[Megidd]

I have tested the following code. It works fine ✔️ It is using just the available OpenVDB API.

I like this approach more than the NumPy trick I already discussed before.

Any community feedback would be reassuring that I'm on the right track. Thanks.

def boolean_difference(plate_grid, cutter_grid):
    """
    CSG difference: plate - cutter using level set math.

    Formula: result = max(plate_sdf, -cutter_sdf)

    This implementation uses iterators + accessors to handle
    non-overlapping narrow bands correctly.
    """
    import openvdb as vdb

    # 1. Create result as deep copy of plate (preserves all plate's active voxels)
    result_grid = plate_grid.deepCopy()

    # 2. Get accessors for random value access
    result_accessor = result_grid.getAccessor()
    plate_accessor = plate_grid.getConstAccessor()

    # 3. Process every active voxel/tile in cutter grid
    for item in cutter_grid.citerOnValues():
        cutter_val = item.value
        neg_cutter = -cutter_val

        if item.count == 1:
            # Single voxel - direct access
            ijk = item.min
            plate_val = plate_accessor.getValue(ijk)  # Returns background if inactive
            result_val = max(plate_val, neg_cutter)
            result_accessor.setValueOn(ijk, result_val)
        else:
            # Tile (uniform region) - must iterate through all voxels in the tile
            min_coord = item.min
            max_coord = item.max

            for i in range(min_coord[0], max_coord[0] + 1):
                for j in range(min_coord[1], max_coord[1] + 1):
                    for k in range(min_coord[2], max_coord[2] + 1):
                        ijk = (i, j, k)
                        plate_val = plate_accessor.getValue(ijk)
                        result_val = max(plate_val, neg_cutter)
                        result_accessor.setValueOn(ijk, result_val)

    # 4. Flood-fill to fix background topology and prune uniform regions
    result_grid.signedFloodFill()
    result_grid.prune()

    return result_grid