AcademySoftwareFoundation
diff --git a/‎.github/workflows/nanovdb.yml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/nanovdb.yml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎nanovdb/nanovdb/GridHandle.h‎
Lines changed: 39 additions & 14 deletions b/‎nanovdb/nanovdb/GridHandle.h‎
Lines changed: 39 additions & 14 deletions
diff --git a/‎nanovdb/nanovdb/Readme.md‎
Lines changed: 1 addition & 0 deletions b/‎nanovdb/nanovdb/Readme.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎nanovdb/nanovdb/python/BuildTypes.def‎
Lines changed: 141 additions & 0 deletions b/‎nanovdb/nanovdb/python/BuildTypes.def‎
Lines changed: 141 additions & 0 deletions
diff --git a/‎nanovdb/nanovdb/python/CMakeLists.txt‎
Lines changed: 59 additions & 2 deletions b/‎nanovdb/nanovdb/python/CMakeLists.txt‎
Lines changed: 59 additions & 2 deletions
@@ -120,6 +120,9 @@ jobs:
     - name: install
       shell: powershell
       run: .\ci\install_windows.ps1
+    - name: install_numpy
+      shell: powershell
+      run: .\ci\install_windows_numpy.ps1
     - name: build
     # nvcc doesn't set _WIN32 when run in bash so we need to set it manually
       shell: bash
 
@@ -495,35 +495,60 @@ splitGrids(const GridHandle<BufferT> &handle, const BufferT* other = nullptr)
 
 /// @brief Combines (or merges) multiple GridHandles into a single GridHandle containing all grids
 /// @tparam BufferT Type of the input and output grid buffers
-/// @param handles Vector of GridHandles to be combined
+/// @param handles array of non-owning pointers to the GridHandles to be combined
+/// @param count number of pointers in @a handles
 /// @param pool optional pool used for allocation of output GridHandle
 /// @return single GridHandle containing all input grids
-template<typename BufferT, template <class, class...> class VectorT>
+/// @note This overload borrows the input handles, so it can be used when the
+///       handles are owned elsewhere (e.g. by a language binding) and can be
+///       neither moved from nor cheaply copied.
+template<typename BufferT>
 inline GridHandle<BufferT>
-mergeGrids(const VectorT<GridHandle<BufferT>> &handles, const BufferT* pool = nullptr)
+mergeGrids(const GridHandle<BufferT>* const* handles, size_t count, const BufferT* pool = nullptr)
 {
     uint64_t size = 0u;
     uint32_t counter = 0u, gridCount = 0u;
-    for (auto &h : handles) {
-        gridCount += h.gridCount();
-        for (uint32_t n=0; n<h.gridCount(); ++n) size += h.gridSize(n);
+    for (size_t i = 0; i < count; ++i) {
+        gridCount += handles[i]->gridCount();
+        for (uint32_t n=0; n<handles[i]->gridCount(); ++n) size += handles[i]->gridSize(n);
     }
+    // Return an empty handle when there is nothing to merge: BufferT::create(0)
+    // can produce a non-null zero-byte region, from which the GridHandle
+    // constructor would attempt to read a GridData header.
+    if (gridCount == 0u) return GridHandle<BufferT>();
     auto buffer = BufferT::create(size, pool);
     void *dst = buffer.data();
-    for (auto &h : handles) {
-        const void *src = h.data();
+    for (size_t i = 0; i < count; ++i) {
+        const GridHandle<BufferT> &h = *handles[i];
         for (uint32_t n=0; n<h.gridCount(); ++n) {
-            std::memcpy(dst, src, h.gridSize(n));
-            GridData *data = reinterpret_cast<GridData*>(dst);
-            NANOVDB_ASSERT(data->isValid());
-            tools::updateGridCount(data, counter++, gridCount);
-            dst = util::PtrAdd(dst, data->mGridSize);
-            src = util::PtrAdd(src, data->mGridSize);
+            // gridData(n) applies the per-grid offset, so padded (non-contiguous)
+            // source buffers are copied correctly.
+            const GridData *src = h.gridData(n);
+            NANOVDB_ASSERT(src && src->isValid());
+            const uint64_t gridSize = h.gridSize(n);
+            std::memcpy(dst, src, gridSize);
+            tools::updateGridCount(reinterpret_cast<GridData*>(dst), counter++, gridCount);
+            dst = util::PtrAdd(dst, gridSize);
         }
     }
     return GridHandle<BufferT>(std::move(buffer));
 }// mergeGrids
 
+/// @brief Combines (or merges) multiple GridHandles into a single GridHandle containing all grids
+/// @tparam BufferT Type of the input and output grid buffers
+/// @param handles Vector of GridHandles to be combined
+/// @param pool optional pool used for allocation of output GridHandle
+/// @return single GridHandle containing all input grids
+template<typename BufferT, template <class, class...> class VectorT>
+inline GridHandle<BufferT>
+mergeGrids(const VectorT<GridHandle<BufferT>> &handles, const BufferT* pool = nullptr)
+{
+    std::vector<const GridHandle<BufferT>*> ptrs;
+    ptrs.reserve(handles.size());
+    for (auto &h : handles) ptrs.push_back(&h);
+    return mergeGrids<BufferT>(ptrs.data(), ptrs.size(), pool);
+}// mergeGrids
+
 } // namespace nanovdb
 
 #if defined(__CUDACC__)
 
@@ -7,6 +7,7 @@ A lightweight GPU friendly version of VDB initially targeting rendering applicat
 * [Frequently asked questions](../../doc/nanovdb/FAQ.md)
 * [Source tree](../../doc/nanovdb/SourceTree.md)
 * [Examples](../../doc/nanovdb/HelloWorld.md)
+* [Python examples](python/examples/)
 
 ### Copyright Contributors to the OpenVDB Project
 ### SPDX-License-Identifier: Apache-2.0
 
@@ -0,0 +1,141 @@
+// Copyright Contributors to the OpenVDB Project
+// SPDX-License-Identifier: Apache-2.0
+//
+// X-macro list of NanoVDB BuildT types currently exposed to Python.
+//
+// NanoVDB coding style says "avoid macro functions; use inline and templates
+// instead" (docs/codingstyle.txt). This file is a deliberate exception: it
+// must emit top-level template instantiations and binding registrations into
+// several translation units from one canonical list, which a C++ template
+// cannot do. The pattern is contained to this file plus the matching
+// per-consumer macro definitions; no runtime behavior is hidden behind a
+// macro function.
+//
+// Consumers define one or more of the kind-specific macros below before
+// including this file. Each macro is invoked once per matching type; any
+// macro the consumer does not define is treated as a no-op and reset after
+// the file is processed. This is the single point that must be edited when
+// adding (or removing) a Python-visible BuildT.
+//
+// Macros:
+//   NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(T, Suffix, GridTypeEnum)
+//       Scalar value types with arithmetic semantics — exposed with full
+//       NodeInfo + setVoxel accessors. Suffix forms Python class names
+//       (e.g. "Float" -> "FloatGrid"). GridTypeEnum names the
+//       nanovdb::GridType:: enumerator a grid of this BuildT carries
+//       (used by the polymorphic handle.grid(n) dispatch).
+//
+//   NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(T, Suffix, AccessorName, GridTypeEnum)
+//       Vector value types — exposed with a setVoxel accessor but no
+//       NodeInfo. AccessorName is passed explicitly because the legacy
+//       Python class names for the original two (Vec3f, RGBA8) are
+//       inconsistent — kept as-is for backwards compatibility.
+//
+//   NANOVDB_PY_FOR_EACH_POINT_BUILDT(T, Suffix, GridTypeEnum)
+//       The nanovdb::Point build type — exposed with a bare accessor.
+//       Point grids carry GridType::PointIndex (NOT a GridType::Point;
+//       that enumerator doesn't exist), so GridTypeEnum is given
+//       explicitly. Polymorphic dispatch routes PointIndex grids to
+//       NanoGrid<Point>.
+//
+//   NANOVDB_PY_FOR_EACH_READONLY_BUILDT(T, Suffix, GridTypeEnum)
+//       BuildTs whose nanovdb::SetVoxel<T> is unavailable (bool, the
+//       quantized Fp4/Fp8/Fp16/FpN types, the index types ValueIndex /
+//       ValueOnIndex, and ValueMask). nanovdb::BuildTraits<T>::is_special
+//       is true for all of these. Exposed with a bare accessor only — no
+//       setVoxel, no NodeInfo. The Python accessor's getValue() returns
+//       the type given by nanovdb::BuildToValueMap<T>::Type — float for
+//       Fp4 / Fp8 / Fp16 / FpN, uint64 for ValueIndex / ValueOnIndex,
+//       bool for ValueMask and for the BuildT=bool (Boolean) grid.
+//
+//   NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT(T, Suffix)
+//       Subset that has C++ sampler specializations (used by PyMath
+//       samplers and PyCreateNanoGrid create*Grid factories).
+
+#ifndef NANOVDB_PY_FOR_EACH_SCALAR_BUILDT
+#define NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(T, Suffix, GridTypeEnum)
+#define NANOVDB_PY_LOCAL_DEFINED_SCALAR
+#endif
+#ifndef NANOVDB_PY_FOR_EACH_VECTOR_BUILDT
+#define NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(T, Suffix, AccessorName, GridTypeEnum)
+#define NANOVDB_PY_LOCAL_DEFINED_VECTOR
+#endif
+#ifndef NANOVDB_PY_FOR_EACH_POINT_BUILDT
+#define NANOVDB_PY_FOR_EACH_POINT_BUILDT(T, Suffix, GridTypeEnum)
+#define NANOVDB_PY_LOCAL_DEFINED_POINT
+#endif
+#ifndef NANOVDB_PY_FOR_EACH_READONLY_BUILDT
+#define NANOVDB_PY_FOR_EACH_READONLY_BUILDT(T, Suffix, GridTypeEnum)
+#define NANOVDB_PY_LOCAL_DEFINED_READONLY
+#endif
+#ifndef NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT
+#define NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT(T, Suffix)
+#define NANOVDB_PY_LOCAL_DEFINED_SAMPLEABLE
+#endif
+
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(float,    Float,  Float)
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(double,   Double, Double)
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(int16_t,  Int16,  Int16)
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(int32_t,  Int32,  Int32)
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(int64_t,  Int64,  Int64)
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(uint8_t,  UInt8,  UInt8)
+NANOVDB_PY_FOR_EACH_SCALAR_BUILDT(uint32_t, UInt32, UInt32)
+// nanovdb::Half is intentionally not bound. The source declares it as
+// `class Half{};` (an empty placeholder for IEEE 754 half-precision, see
+// NanoVDB.h around line 180) and the C++ ProbeValue<Half> chain is
+// inconsistent — leaf storage carries Half but the ProbeValue specialization
+// expects float, causing a type mismatch during instantiation. When the
+// upstream Half implementation lands this can be added in a follow-up.
+
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::Vec3f, Vec3f,
+                                  "Vec3fReadVectorAccessor", Vec3f)
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::Vec3d, Vec3d,
+                                  "Vec3dReadAccessor", Vec3d)
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::Vec4f, Vec4f,
+                                  "Vec4fReadAccessor", Vec4f)
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::Vec4d, Vec4d,
+                                  "Vec4dReadAccessor", Vec4d)
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::Vec3u8, Vec3u8,
+                                  "Vec3u8ReadAccessor", Vec3u8)
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::Vec3u16, Vec3u16,
+                                  "Vec3u16ReadAccessor", Vec3u16)
+NANOVDB_PY_FOR_EACH_VECTOR_BUILDT(::nanovdb::math::Rgba8, RGBA8,
+                                  "RGBA8ReadAccessor", RGBA8)
+
+NANOVDB_PY_FOR_EACH_POINT_BUILDT(::nanovdb::Point, Point, PointIndex)
+
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(bool,                  Boolean,     Boolean)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::Fp4,        Fp4,         Fp4)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::Fp8,        Fp8,         Fp8)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::Fp16,       Fp16,        Fp16)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::FpN,        FpN,         FpN)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::ValueIndex, Index,       Index)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::ValueOnIndex, OnIndex,   OnIndex)
+NANOVDB_PY_FOR_EACH_READONLY_BUILDT(::nanovdb::ValueMask,  Mask,        Mask)
+
+NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT(float,            Float)
+NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT(double,           Double)
+NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT(int32_t,          Int32)
+NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT(::nanovdb::Vec3f, Vec3f)
+
+#ifdef NANOVDB_PY_LOCAL_DEFINED_SCALAR
+#undef NANOVDB_PY_LOCAL_DEFINED_SCALAR
+#endif
+#ifdef NANOVDB_PY_LOCAL_DEFINED_VECTOR
+#undef NANOVDB_PY_LOCAL_DEFINED_VECTOR
+#endif
+#ifdef NANOVDB_PY_LOCAL_DEFINED_POINT
+#undef NANOVDB_PY_LOCAL_DEFINED_POINT
+#endif
+#ifdef NANOVDB_PY_LOCAL_DEFINED_READONLY
+#undef NANOVDB_PY_LOCAL_DEFINED_READONLY
+#endif
+#ifdef NANOVDB_PY_LOCAL_DEFINED_SAMPLEABLE
+#undef NANOVDB_PY_LOCAL_DEFINED_SAMPLEABLE
+#endif
+
+#undef NANOVDB_PY_FOR_EACH_SCALAR_BUILDT
+#undef NANOVDB_PY_FOR_EACH_VECTOR_BUILDT
+#undef NANOVDB_PY_FOR_EACH_POINT_BUILDT
+#undef NANOVDB_PY_FOR_EACH_READONLY_BUILDT
+#undef NANOVDB_PY_FOR_EACH_SAMPLEABLE_BUILDT
@@ -4,8 +4,19 @@ option(NANOVDB_BUILD_PYTHON_UNITTESTS [=[
   "Include the NanoVDB Python unit test. Requires a python interpreter]=]
 ${NANOVDB_BUILD_UNITTESTS})
 
+# Stubs are only consumed from an installed wheel (they ship next to the .so
+# in nanovdb/), so default ON only when SKBUILD is driving the build. In an
+# in-source dev / OpenVDB-CI build the .pyi is not used and stub generation
+# can be skipped — which also dodges the macOS CI's sanitizer-runtime
+# DYLD_INSERT_LIBRARIES wrapper, under which Python dlopen'ing the .so
+# triggers TSan "Interceptors are not working" and aborts stubgen.
+option(NANOVDB_BUILD_PYTHON_STUBS
+  "Generate .pyi type stubs for the nanovdb Python module (requires nanobind 2.x or newer)."
+  ${SKBUILD})
+
 nanobind_add_module(nanovdb_python NB_STATIC
     NanoVDBModule.cc
+    PyBuildGrid.cc
     PyCreateNanoGrid.cc
     PyGridChecksum.cc
     PyGridHandle.cc
@@ -18,6 +29,8 @@ nanobind_add_module(nanovdb_python NB_STATIC
     PyPrimitives.cc
     PySampleFromVoxels.cc
     PyTools.cc
+    PyTree.cc
+    PyVoxelBlockManager.cc
     cuda/PyDeviceBuffer.cc
     cuda/PyDeviceGridHandle.cu
     cuda/PyPointsToGrid.cu
@@ -33,10 +46,47 @@ if(SKBUILD)
   set_target_properties(nanovdb_python PROPERTIES INSTALL_RPATH "$ORIGIN/../../openvdb/lib")
   install(TARGETS nanovdb_python DESTINATION ${NANOVDB_INSTALL_LIBDIR})
   install(FILES __init__.py DESTINATION nanovdb)
+  # Ship the nanovdb C/C++ headers inside the Python wheel so downstream
+  # extension authors can compile against the same NanoVDB the wheel was
+  # built with. nanovdb.get_include() resolves to this directory at runtime.
+  install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../
+          DESTINATION nanovdb/include/nanovdb
+          FILES_MATCHING
+            PATTERN "*.h"
+            PATTERN "*.cuh"
+            PATTERN "python" EXCLUDE
+            PATTERN "examples" EXCLUDE
+            PATTERN "unittest" EXCLUDE
+            PATTERN "cmd" EXCLUDE
+            PATTERN "docs" EXCLUDE)
 else()
   install(TARGETS nanovdb_python DESTINATION ${VDB_PYTHON_INSTALL_DIRECTORY})
 endif()
 
+# .pyi type stubs for IDE / type-checker support. Driven by the CMake helper
+# that ships with nanobind 2.x; silently skipped on older nanobind where the
+# helper does not exist.
+if(NANOVDB_BUILD_PYTHON_STUBS AND COMMAND nanobind_add_stub)
+  set(NANOVDB_STUB_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}")
+  nanobind_add_stub(nanovdb_python_stub
+    MODULE nanovdb
+    OUTPUT "${NANOVDB_STUB_OUTPUT_DIR}/nanovdb.pyi"
+    PYTHON_PATH $<TARGET_FILE_DIR:nanovdb_python>
+    DEPENDS nanovdb_python
+    MARKER_FILE "${NANOVDB_STUB_OUTPUT_DIR}/py.typed"
+    INCLUDE_PRIVATE)
+  if(SKBUILD)
+    install(FILES
+        "${NANOVDB_STUB_OUTPUT_DIR}/nanovdb.pyi"
+        "${NANOVDB_STUB_OUTPUT_DIR}/py.typed"
+      DESTINATION nanovdb)
+  endif()
+elseif(NANOVDB_BUILD_PYTHON_STUBS)
+  message(STATUS
+    "NANOVDB_BUILD_PYTHON_STUBS is ON but nanobind_add_stub is unavailable "
+    "(nanobind >= 2.0 required). Skipping stub generation.")
+endif()
+
 # pytest
 if(NANOVDB_BUILD_PYTHON_UNITTESTS)
 
@@ -49,12 +99,19 @@ if(NANOVDB_BUILD_PYTHON_UNITTESTS)
     COMMAND ${Python_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/TestNanoVDB.py -v
     WORKING_DIRECTORY "${NANOVDB_PYTHON_WORKING_DIR}")
 
+  # Smoke-run every example script (they self-skip when optional
+  # dependencies such as NumPy or OpenVDB are unavailable).
+  add_test(NAME pytest_nanovdb_examples
+    COMMAND ${Python_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/TestExamples.py -v
+    WORKING_DIRECTORY "${NANOVDB_PYTHON_WORKING_DIR}")
+  set_tests_properties(pytest_nanovdb_examples PROPERTIES TIMEOUT 300)
+
   if(WIN32)
     set(PYTHONPATH "$ENV{PYTHONPATH};${NANOVDB_PYTHON_WORKING_DIR}")
     string(REPLACE "\\;" ";" PYTHONPATH "${PYTHONPATH}")
     string(REPLACE ";" "\\;" PYTHONPATH "${PYTHONPATH}")
-    set_tests_properties(pytest_nanovdb PROPERTIES ENVIRONMENT "PYTHONPATH=${PYTHONPATH}")
+    set_tests_properties(pytest_nanovdb pytest_nanovdb_examples PROPERTIES ENVIRONMENT "PYTHONPATH=${PYTHONPATH}")
   else()
-    set_tests_properties(pytest_nanovdb PROPERTIES ENVIRONMENT "PYTHONPATH=$ENV{PYTHONPATH}:${NANOVDB_PYTHON_WORKING_DIR}")
+    set_tests_properties(pytest_nanovdb pytest_nanovdb_examples PROPERTIES ENVIRONMENT "PYTHONPATH=$ENV{PYTHONPATH}:${NANOVDB_PYTHON_WORKING_DIR}")
   endif()
 endif()