added a simple program to export files in .vdb format

.github/workflows/gh-ci.yaml

@@ -49,7 +49,7 @@ jobs:
 
     - name: install package deps
       run: |
-        micromamba install numpy scipy mrcfile pytest pytest-cov codecov
+        micromamba install numpy scipy mrcfile pytest pytest-cov codecov openvdb
 
     - name: check install
       run: |

AUTHORS

@@ -29,3 +29,4 @@ Contributors:
 * Andrés Montoya <conradolandia> (logo)
 * Rich Waldo <plethorachutney>
 * Pradyumn Prasad <Pradyumn-cloud>
+* Shreejan Dolai <spyke7>

CHANGELOG

@@ -12,12 +12,20 @@ The rules for this file:
     use tabs but use spaces for formatting
   * accompany each entry with github issue/PR number (Issue #xyz)
 
+------------------------------------------------------------------------------
+01/16/2026 IAlibay, ollyfutur, conradolandia, orbeckst, PlethoraChutney, 
+           Pradyumn-cloud, spyke7
 -------------------------------------------------------------------------------
-??/??/???? orbeckst
+??/??/???? orbeckst, spyke7
 
- * 1.1.1
+ * 1.2.0
 
- Fixes
+ Enhancements
+
+ * Added openVDB format exports (Issue #141, PR #148)
+
+
+  Fixes
 
 
 01/22/2026 IAlibay, ollyfutur, conradolandia, orbeckst, PlethoraChutney,
@@ -35,6 +43,7 @@ The rules for this file:
 
   Enhancements
 
+  * `Grid` now accepts binary operations with any operand that can be 
   * `Grid` now accepts binary operations with any operand that can be
     broadcasted to the grid's shape according to `numpy` broadcasting rules
     (PR #142)

doc/source/gridData/formats.rst

@@ -29,6 +29,7 @@ small number of file formats is directly supported.
    :mod:`~gridData.gOpenMol`    gOpenMol_   plt        x
    :mod:`~gridData.mrc`         CCP4_       ccp4,mrc   x      x      subset implemented
    :class:`~gridData.core.Grid` pickle      pickle     x      x      standard Python pickle of the Grid class
+   :mod:`~gridData.OpenVDB`     OpenVDB_    vdb               x      implemented for Blender visualization
    ============================ ==========  =========  =====  =====  =========================================
 
 
@@ -39,6 +40,7 @@ small number of file formats is directly supported.
 .. _OpenDX: http://www.opendx.org/
 .. _gOpenMol: http://www.csc.fi/gopenmol/
 .. _CCP4: http://www.ccpem.ac.uk/mrc_format/mrc2014.php
+.. _OpenVDB: https://www.openvdb.org/
 
 
 Format-specific modules
@@ -50,3 +52,4 @@ Format-specific modules
    formats/OpenDX
    formats/gOpenMol
    formats/mrc
+   formats/OpenVDB

doc/source/gridData/formats/OpenVDB.rst

@@ -0,0 +1,2 @@
+.. automodule:: gridData.OpenVDb
+

gridData/OpenVDB.py

@@ -0,0 +1,318 @@
+r"""
+:mod:`~gridData.OpenVDB` --- routines to write OpenVDB files
+=============================================================
+
+The `OpenVDB format`_ is used by Blender_ and other VFX software for
+volumetric data.
+
+.. _`OpenVDB format`: https://www.openvdb.org
+.. _Blender: https://www.blender.org/
+
+This module uses the openvdb_ library to write OpenVDB files.
+
+.. _openvdb: https://github.com/AcademySoftwareFoundation/openvdb
+
+.. Note:: This module implements a simple writer for 3D regular grids,
+          sufficient to export density data for visualization in Blender_.
+          See the `Blender volume docs`_ for details on importing VDB files.
+
+.. _`Blender volume docs`: https://docs.blender.org/manual/en/latest/modeling/volumes/introduction.html
+
+The OpenVDB format uses a sparse tree structure to efficiently store
+volumetric data. It is the native format for Blender's volume system.
+
+
+Writing OpenVDB files
+---------------------
+
+If you have a :class:`~gridData.core.Grid` object, you can write it to
+OpenVDB format::
+
+  from gridData import Grid
+  g = Grid("data.dx")
+  g.export("data.vdb")
+
+This will create a file that can be imported directly into Blender
+(File -> Import -> OpenVDB) or (shift+A -> Volume -> Import OpenVDB). See `importing VDB in Blender`_ for details.
+
+.. _`importing VDB in Blender`: https://docs.blender.org/manual/en/latest/modeling/geometry_nodes/input/import/vdb.html
+
+
+Building an OpenVDB field from a numpy array
+---------------------------------------------
+
+If you want to create VDB files without using the Grid class,
+you can directly use the OpenVDB field API. This is useful
+for custom workflows or when integrating with other libraries.
+
+Requires:
+
+grid
+    numpy 3D array
+origin
+    cartesian coordinates of the center of the (0,0,0) grid cell
+delta
+    n x n array with the length of a grid cell along each axis
+
+Example::
+
+  from gridData import Grid
+
+  g = Grid("data.dx")
+  g.export("data.vdb")
+
+
+Classes and functions
+---------------------
+
+"""
+
+import numpy
+import warnings
+from dataclasses import dataclass
+
+try:
+    import openvdb as vdb
+
+except ImportError:
+    vdb = None
+
+
+@dataclass
+class DownCastTo:
+    gridType: str
+
+
+class OpenVDBField(object):
+    """OpenVDB field object for writing volumetric data.
+
+    This class provides a simple interface to write 3D grid data to
+    OpenVDB format, which can be imported into Blender and other
+    VFX software.
+
+    The field object holds grid data and metadata, and can write it
+    to a .vdb file.
+
+    Example
+    -------
+    Create a field and write it::
+
+      import gridData.OpenVDB as OpenVDB
+
+      vdb_field = OpenVDB.OpenVDBField('density')
+      vdb_field.write('output.vdb')
+
+    Or use directly from Grid::
+
+      g = Grid(...)
+      g.export('output.vdb', format='vdb')
+
+    """
+
+    def __init__(
+        self,
+        grid=None,
+        origin=None,
+        delta=None,
+        name="density",
+        tolerance=None,
+        metadata=None,
+    ):
+        """Initialize an OpenVDB field.
+
+        Parameters
+        ----------
+        grid : numpy.ndarray
+            3D numpy array with the data
+        origin : numpy.ndarray
+            Coordinates of the center of grid cell [0,0,0]
+        delta : numpy.ndarray
+            Grid spacing (can be 1D array or diagonal matrix)
+        name : str
+            Name of the grid (will be visible in Blender), default 'density'
+        tolerance : float (optional)
+            Values below this tolerance are treated as background (sparse),
+            default None
+        metadata : dict (optional)
+            Additional metadata to embed in the VDB file.
+
+        Raises
+        ------
+        ImportError
+            If openvdb is not installed
+        ValueError
+            If grid is not 3D, or if delta is not 1D/2D or describes
+            non-orthorhombic cell
+
+        """
+        if vdb is None:
+            raise ImportError(
+                "openvdb is required to write VDB files. "
+                "Install it with: conda install -c conda-forge openvdb"
+            )
+        self.name = name
+        self.tolerance = tolerance
+        if metadata is not None:
+            self.metadata = metadata
+        else:
+            self.metadata = {}
+
+        if grid is not None:
+            self._populate(grid, origin, delta)
+            self.vdb_grid = self._create_openvdb_grid()
+        else:
+            self.grid = None
+            self.origin = None
+            self.delta = None
+            self.vdb_grid = None
+
+    def _populate(self, grid, origin, delta):
+        """Populate the field with grid data.
+
+        Parameters
+        ----------
+        grid : numpy.ndarray
+            3D numpy array with the data
+        origin : numpy.ndarray
+            Coordinates of the center of grid cell [0,0,0]
+        delta : numpy.ndarray
+            Grid spacing (can be 1D array or diagonal matrix)
+
+        Raises
+        ------
+        ValueError
+            If grid is not 3D, or if delta is not 1D/2D or describes
+            non-orthorhombic cell
+
+        """
+        self.grid = numpy.asarray(grid)
+        if grid.ndim != 3:
+            raise ValueError(f"OpenVDB only supports 3D grids, got {grid.ndim}D")
+
+        self.grid = numpy.ascontiguousarray(self.grid)
+
+        self.origin = numpy.asarray(origin)
+
+        # Handle delta: could be 1D array or diagonal matrix
+        delta = numpy.asarray(delta)
+        if delta.ndim == 2:
+            if delta.shape != (3, 3):
+                raise ValueError("delta as a matrix must be 3x3")
+
+            if not numpy.allclose(delta, numpy.diag(numpy.diag(delta))):
+                raise ValueError("Non-orthorhombic cells are not supported")
+
+            self.delta = numpy.diag(delta)
+
+        elif delta.ndim == 1:
+            if len(delta) != 3:
+                raise ValueError("delta must have length-3 for 3D grids")
+            self.delta = delta
+
+        else:
+            raise ValueError(
+                "delta must be either a length-3 vector or a 3x3 diagonal matrix"
+            )
+
+    def _get_best_grid_type(self):
+        """Selects the suitable OpenVDB grid type
+
+        Returns
+        -------
+        openvdb.GridBase
+
+        Raises
+        ------
+        TypeError
+            If dtype is not supported or no suitable grid type is available
+        """
+        datatypes = {
+            numpy.dtype("bool"): ["BoolGrid"],
+            numpy.dtype("int8"): [DownCastTo("Int32Grid"), DownCastTo("FloatGrid")],
+            numpy.dtype("uint8"): [DownCastTo("Int32Grid"), DownCastTo("FloatGrid")],
+            numpy.dtype("int16"): [DownCastTo("Int32Grid"), DownCastTo("FloatGrid")],
+            numpy.dtype("uint16"): [DownCastTo("Int32Grid"), DownCastTo("FloatGrid")],
+            numpy.dtype("int32"): ["Int32Grid", DownCastTo("FloatGrid")],
+            numpy.dtype("uint32"): ["Int32Grid", DownCastTo("FloatGrid")],
+            numpy.dtype("int64"): ["Int64Grid", DownCastTo("FloatGrid")],
+            numpy.dtype("uint64"): ["Int64Grid", DownCastTo("FloatGrid")],
+            numpy.dtype("float16"): [DownCastTo("HalfGrid"), DownCastTo("FloatGrid")],
+            numpy.dtype("float32"): ["FloatGrid"],
+            numpy.dtype("float64"): ["DoubleGrid", DownCastTo("FloatGrid")],
+        }
+
+        try:
+            vdb_gridtypes = datatypes[self.grid.dtype]
+        except KeyError:
+            raise TypeError(f"Data type {self.grid.dtype} not supported for VDB")
+
+        for gridtype_downcast in vdb_gridtypes:
+            if isinstance(gridtype_downcast, DownCastTo):
+                gridtype = gridtype_downcast.gridType
+            else:
+                gridtype = gridtype_downcast
+
+            try:
+                VDB_Grid = getattr(vdb, gridtype)
+            except AttributeError:
+                continue
+            else:
+                if isinstance(gridtype_downcast, DownCastTo):
+                    warnings.warn(
+                        f"Grid type {vdb_gridtypes[0]} not available. Using {gridtype} instead. Data may lose precision.",
+                        UserWarning,
+                    )
+                return VDB_Grid()
+
+        raise TypeError(
+            f"Could not find any VDB grid type for numpy dtype {self.grid.dtype}"
+        )
+
+    def _create_openvdb_grid(self):
+        """Create and populate an OpenVDB grid
+
+        Returns
+        -------
+        openvdb.GridBase
+
+        """
+
+        vdb_grid = self._get_best_grid_type()
+
+        vdb_grid.name = self.name
+
+        vdb_grid.transform = vdb.createLinearTransform()
+        vdb_grid.transform.preScale(self.delta.tolist())
+        vdb_grid.transform.postTranslate(self.origin.tolist())
+
+        if self.metadata:
+            for key, val in self.metadata.items():
+                try:
+                    vdb_grid[key] = val
+                except (TypeError, ValueError) as e:
+                    warnings.warn(f"Could not set metadata '{key}': {e}", UserWarning)
+
+        if isinstance(vdb_grid, vdb.BoolGrid) and (
+            self.tolerance is None or self.tolerance == 0
+        ):
+            vdb_grid.copyFromArray(self.grid)
+            vdb_grid.prune(tolerance=False)
+        else:
+            if self.tolerance is None:
+                vdb_grid.copyFromArray(self.grid)
+            else:
+                vdb_grid.copyFromArray(self.grid, tolerance=self.tolerance)
+
+            vdb_grid.prune()
+
+        return vdb_grid
+
+    def write(self, filename):
+        """Write the field to an OpenVDB file.
+
+        Parameters
+        ----------
+        filename : str
+            Output filename (should end in .vdb)
+        """
+        vdb.write(filename, grids=[self.vdb_grid])

gridData/__init__.py

@@ -110,8 +110,9 @@
 from . import OpenDX
 from . import gOpenMol
 from . import mrc
+from . import OpenVDB
 
-__all__ = ['Grid', 'OpenDX', 'gOpenMol', 'mrc']
+__all__ = ['Grid', 'OpenDX', 'gOpenMol', 'mrc', 'OpenVDB']
 
 from importlib.metadata import version
 __version__ = version("GridDataFormats")