Python API: Interactive 3D Rendering Method (`PyVista`)

[jameslehoux]

Labels: enhancement, visualization, phase:1-battery
Priority: Medium

Description

While yt is excellent for 2D slicing of massive datasets on disk, users frequently want to visually inspect their 3D binarized pore networks and transport streamlines interactively before running a heavy solve.

We should extend the VoxelImage Python class with a native .plot_3d() convenience method. This method will use PyVista (specifically the pyvista.trame backend) to render a fast, interactive 3D widget directly inline within a Jupyter Notebook.

Implementation Constraints

• Downsampling: Trying to render $1000^3$ voxels in a browser will crash the Jupyter kernel. The plot_3d() method must accept a downsample_factor argument (defaulting to something safe, like rendering a maximum of $256^3$ voxels).
• Trame Backend: Ensure the method uses the jupyter_backend='trame' argument so it utilizes server-side rendering, keeping the browser lightweight.

Acceptance Criteria

• Implement VoxelImage.plot_3d(downsample_factor=2, show_edges=False).
• Implement TortuositySolver.plot_flux_streamlines(downsample_factor=2).
• Add pyvista and trame to the [project.optional-dependencies.jupyter] list in pyproject.toml.
• Update the profiling_and_tuning.ipynb notebook to demonstrate calling .plot_3d() to inspect the domain before solving.