Greenwander VDB Exporter

Greenwander is an optimized Python and C++ fluid advection and volumetric rendering pipeline that evaluates extremely large-scale spatial datasets (e.g. Gaussian distributions and velocity vectors) and writes them out physically to OpenVDB (.vdb) sequences ready to be imported into professional DCC tools like Blender.

Overview

This repository provides a high-performance bridging mechanism to generate sequences of complex volumetric data across Apple Silicon hardware.

It tackles critical bottlenecks that typically plague native Python processing of spatial structures:

1. Zero-Copy Interprocess Communication (IPC): Bypasses the storage disk entirely by writing raw 3D scalar arrays physically into Virtual POSIX Shared Memory segments mapped seamlessly into a custom high-speed C++ OpenVDB binary compiler backend.
2. Mac-Optimized Multiprocessing: Leverages explicitly spawned PyTorch Native OpenMP thread limits with multi-core pools spanning Apple Silicon, generating millions of query points in seconds.
3. Optimized Einsum Evaluation: Translates generic dense math operators into Accelerated broadcast matmuls executing directly on the underlying BLAS linear algebra library.

Project Structure

• src/main.py - Application entry point. Synthesizes advection frames, spawns parallel worker pools, and evaluates points via gaussian formulas.
• src/vdb_export.py - Pipeline logic for allocating native OS Virtual RAM segments and orchestrating data handover to the C++ compiler.
• src/vdb_exporter_backend.cpp - A blazing fast OpenVDB ingestion interface. Creates POSIX shm_open memory maps directly from string endpoints instead of allocating temporary std::vector heap blocks to build OpenVDB FloatGrids and Vec3SGrids.
• src/gaussian_eval.py - Linear calculation library mapped meticulously against Apple local matrix evaluation paths.
• output_sequence/ - Destination folder for raw generated sequence .vdb payloads.

Hardware & Environment Requirements

• Apple Silicon (M-Series recommended)
• uv Python package manager
• macOS System Compiler Toolchains (C++17)
• openvdb and tbb packages via Homebrew:

brew install openvdb tbb

Usage

1. Installation

Install the required Python dependencies tracked inside the lockfile through the package manager:

uv sync

2. Execution

Run the entire simulation locally to evaluate advection behaviors across CPU threads in real-time. The framework will automatically build the standalone C++ helper process and initiate the processing sequence:

uv run python src/main.py

Note: Due to optimized zero-copy configurations, execution leaves no artifacts or temp caches on disk.

3. Review Render Output

Import the exported .vdb series directly into Blender using Add > Volume > Import OpenVDB.

• The Z-up axis layout natively targets Blender’s physical structure (meaning standard translation rules apply inherently without 90-degree rotational quirks).
• Density threshold layers are inherently trimmed to 0.05 via backend evaluation filters to maximize active tree build efficiency on noise masks.