https://github.com/bjoernbethge/bpy-widget
Interactive Blender 3D viewport widget for notebooks with real-time Eevee Next rendering.
https://github.com/bjoernbethge/bpy-widget
3d-visualization blender cycles eevee interactive-visualization jupyter jupyter-widget marimo notebook python
Last synced: 24 days ago
JSON representation
Interactive Blender 3D viewport widget for notebooks with real-time Eevee Next rendering.
- Host: GitHub
- URL: https://github.com/bjoernbethge/bpy-widget
- Owner: bjoernbethge
- License: other
- Created: 2025-07-08T07:08:40.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-08T20:36:35.000Z (3 months ago)
- Last Synced: 2026-01-04T02:32:53.315Z (about 1 month ago)
- Topics: 3d-visualization, blender, cycles, eevee, interactive-visualization, jupyter, jupyter-widget, marimo, notebook, python
- Language: Python
- Homepage:
- Size: 27.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# bpy-widget
Interactive Blender 3D viewport widget for Jupyter notebooks with real-time rendering powered by Blender 4.5+.
[](https://pypi.org/project/bpy-widget/)
[](https://github.com/bjoernbethge/bpy-widget)
[](https://github.com/bjoernbethge/bpy-widget/issues)
## Features
- 🎨 **Interactive 3D Viewport** - Real-time camera controls with mouse/touch gestures
- âš¡ **EEVEE Next & Cycles** - Switch between render engines on the fly
- 🚀 **Vulkan Backend** - High-performance GPU acceleration (Blender 4.5+)
- 🎬 **Post-Processing** - Bloom, vignette, color correction, depth of field, and more
- 📊 **Data Visualization** - Import CSV/Parquet data as 3D objects (point clouds, curves)
- 🔄 **Live Updates** - Changes render immediately with optimized debouncing
- 📦 **Import/Export** - Support for GLTF, USD, Alembic formats
- 🧩 **Extension Management** - Manage Blender extensions and addons (Blender 4.2+)
## Installation
```bash
uv add bpy-widget
```
**Requirements:**
- Python 3.11+ (required by Blender 4.5)
- Blender 4.5.4+ as Python module (installed automatically via pip)
**Optional:**
- Modern GPU with [Vulkan](https://www.vulkan.org/) support (for improved performance with `VULKAN` backend)
- **NVIDIA**: Driver 550+ (see [NVIDIA Vulkan Drivers](https://www.nvidia.com/Download/index.aspx))
- **AMD**: Latest drivers recommended
- **Intel Arc**: Supported on modern Intel GPUs
## Quick Start
```python
from bpy_widget import BpyWidget
# Create widget
widget = BpyWidget(width=800, height=600)
# Enable Vulkan for better performance (Blender 4.5+)
widget.set_gpu_backend("VULKAN")
# Display in notebook (Jupyter/Marimo)
widget
```
The widget automatically initializes with a test scene. You can interact with it immediately:
- **Drag** to rotate camera
- **Scroll** to zoom
- **Touch** gestures on mobile
**Performance:** Vulkan backend provides 10-15% faster rendering compared to OpenGL.
## Detailed Usage
### Scene Setup
```python
# Clear and setup new scene
widget.clear_scene()
widget.setup_lighting(sun_energy=3.0, add_fill_light=True)
widget.setup_world_background(color=(0.05, 0.05, 0.1))
# Create objects
cube = widget.create_test_cube(location=(0, 0, 0))
suzanne = widget.create_suzanne(location=(0, 0, 2))
torus = widget.create_torus(location=(3, 0, 0))
```
### Material System
```python
# Use material presets
gold_mat = widget.create_preset_material("MyGold", "gold")
glass_mat = widget.create_preset_material("MyGlass", "glass")
# Or create custom materials
custom = widget.create_material(
"Custom",
base_color=(0.8, 0.2, 0.2),
metallic=0.5,
roughness=0.4,
emission_strength=0.1
)
# Apply to objects
widget.assign_material(suzanne, gold_mat)
```
Available presets: `gold`, `silver`, `copper`, `chrome`, `glass`, `water`, `diamond`, `rubber`, `plastic`, `wood`, `concrete`, `neon_red`, `neon_blue`, `neon_green`
### Data Import
```python
# Import point cloud
widget.import_data("data.csv", as_type="points", point_size=0.1)
# Import as curve
widget.import_data("timeseries.csv", as_type="curve")
# Import multiple series
widget.import_data(
"multi_series.csv",
as_type="series",
value_columns=["col1", "col2", "col3"]
)
# Batch import
widget.batch_import(["*.csv", "*.parquet"], as_type="points")
```
### Post-Processing Effects
```python
# Setup compositor with effects
widget.setup_extended_compositor()
# Add individual effects
widget.add_bloom_glare(intensity=0.8, threshold=0.8)
widget.add_color_correction(brightness=0.1, contrast=0.1, saturation=1.1)
widget.add_vignette(amount=0.2)
widget.add_film_grain(amount=0.03)
widget.add_chromatic_aberration(amount=0.001)
widget.add_sharpen(amount=0.1)
# Camera effects
widget.add_depth_of_field(focus_distance=5.0, fstop=2.8)
widget.add_motion_blur(samples=8, shutter=0.5)
```
### Import/Export 3D Formats
```python
# GLTF/GLB
objects = widget.import_gltf("model.glb")
widget.export_gltf("output.glb")
# USD/USDZ
objects = widget.import_usd("scene.usd")
widget.export_usd("output.usd")
# Alembic
objects = widget.import_alembic("animation.abc")
widget.export_alembic("output.abc")
# Scene as Parquet (for data analysis)
widget.export_scene_as_parquet("scene_data.parquet")
objects = widget.import_scene_from_parquet("scene_data.parquet")
```
### Extension Management (Blender 4.5+)
```python
# List repositories and extensions
repos = widget.list_repositories()
extensions = widget.list_extensions()
# Enable/disable extensions (by package ID)
widget.enable_extension("molecularnodes") # Auto-finds repository
widget.disable_extension("molecularnodes")
# Or specify repository module explicitly
widget.enable_extension("molecularnodes", repo_module="bl_ext")
# Install extension (universal method - handles ID, URL, or file)
widget.install_extension("molecularnodes") # Install by package ID (searches online)
# Install from URL
widget.install_extension(
"https://extensions.blender.org/download/...",
pkg_id="molecularnodes"
)
# Install from local file
widget.install_extension("/path/to/extension.zip", pkg_id="my_extension")
# Or use dedicated file installer
widget.install_extension_from_file("my_extension.zip")
# Sync and upgrade
widget.sync_repositories() # Sync all repositories
widget.upgrade_extensions() # Upgrade all extensions
widget.upgrade_extensions(active_only=True) # Upgrade only active extensions
# Legacy addon support (pre-4.2 addons)
legacy_addons = widget.list_legacy_addons()
widget.enable_legacy_addon("space_view3d_copy_attributes")
```
### Performance Settings
```python
# Enable Vulkan backend for improved performance (Blender 4.5+)
widget.set_gpu_backend("VULKAN") # or "OPENGL" (default)
print(f"Current backend: {widget.get_gpu_backend()}") # VULKAN
# Switch render engines
widget.set_render_engine("CYCLES") # or "BLENDER_EEVEE_NEXT"
widget.render_device = "GPU" # For Cycles (requires GPU support)
# Adjust resolution
widget.set_resolution(1920, 1080)
# Optimize for speed
widget.scene.eevee.taa_render_samples = 8
widget.scene.eevee.use_raytracing = False
```
**Performance Tips:**
- Use **Vulkan backend** for 10-15% faster rendering with EEVEE Next
- **EEVEE Next** is faster for interactive work (~200ms at 512x512)
- **Cycles** provides higher quality but is slower (suitable for final renders)
- Lower resolution for interactive editing, increase for final output
## Convenience Properties
Access Blender internals directly without `bpy.context`:
```python
# Scene access
scene = widget.scene
scene.frame_set(1)
scene.render.fps = 30
# Context access (for advanced operations)
widget.context.view_layer.update()
# Data access
objects = widget.objects # bpy.data.objects
materials = widget.data.materials # bpy.data.materials
# Camera access
camera = widget.camera # bpy.context.scene.camera
# Active object
active = widget.active_object # bpy.context.active_object
selected = widget.selected_objects # bpy.context.selected_objects
# Operations access
widget.ops.mesh.primitive_uv_sphere_add(location=(0, 0, 5))
widget.data.objects["Sphere"].scale = (2, 2, 2)
```
**Note:** These properties work in headless Blender environments and safely handle cases where UI contexts aren't available.
## Development
```bash
# Clone repository
git clone https://github.com/bjoernbethge/bpy-widget.git
cd bpy-widget
# Install with dev dependencies
uv sync --dev
# Run example notebooks (set PYTHONPATH for local development)
# PowerShell:
$env:PYTHONPATH = "D:\bpy-widget\src"; uv run marimo edit examples/basic_usage.py
# Bash:
export PYTHONPATH="$(pwd)/src" && uv run marimo edit examples/basic_usage.py
# Frontend development with HMR
cd frontend
npm install
npm run dev # Starts Vite dev server on localhost:5173
# In another terminal, run notebook with HMR enabled:
$env:ANYWIDGET_HMR="1"; $env:PYTHONPATH="D:\bpy-widget\src"; uv run marimo edit examples/basic_usage.py
```
See `examples/` directory for complete usage examples.
## Examples
See the `examples/` directory for complete working examples:
- `simple_widget.py` - Minimal example to get started quickly
- `basic_usage.py` - Interactive notebook with all features (materials, post-processing, scene controls, Vulkan)
- `data_import.py` - Data visualization with CSV/Parquet import as point clouds and curves
## API Reference
### Core Methods
**Rendering:**
- `widget.set_gpu_backend("VULKAN")` - Set GPU backend (VULKAN/OPENGL)
- `widget.get_gpu_backend()` - Get current GPU backend
- `widget.set_render_engine("BLENDER_EEVEE_NEXT")` - Set render engine
- `widget.set_resolution(width, height)` - Set render resolution
- `widget.render()` - Force immediate render
**Scene Management:**
- `widget.clear_scene()` - Clear all objects
- `widget.setup_lighting()` - Setup default lighting
- `widget.setup_world_background(color, strength)` - Set world background
**Objects:**
- `widget.create_test_cube()`, `create_suzanne()`, `create_torus()`, etc.
- `widget.import_gltf()`, `import_usd()`, `import_alembic()` - Import 3D files
**Materials:**
- `widget.create_material()` - Create custom material
- `widget.create_preset_material()` - Use material presets
- `widget.assign_material()` - Apply material to object
**Data Import:**
- `widget.import_data()` - Import CSV/Parquet as points or curves
- `widget.batch_import()` - Import multiple files
## Troubleshooting
### Import Errors
- Ensure Python 3.11 is installed (required by Blender 4.5)
- Check `bpy` module: `pip show bpy` (should be 4.5.x)
### Rendering Issues
- **EEVEE Next** requires OpenGL or Vulkan support (Vulkan recommended for better performance)
- For headless servers without GPU: `widget.set_render_engine("CYCLES")` and `widget.render_device = "CPU"`
- If Vulkan rendering fails, fallback to OpenGL: `widget.set_gpu_backend("OPENGL")`
### GPU Backend
- Vulkan backend requires compatible GPU drivers:
- **NVIDIA**: [Driver 550+](https://www.nvidia.com/Download/index.aspx)
- **AMD**: [Latest drivers](https://www.amd.com/en/support)
- **Intel Arc**: [Supported GPUs](https://www.intel.com/content/www/us/en/products/docs/discrete-gpus/arc/software/vulkan.html)
- If Vulkan is unavailable, OpenGL is used automatically
- Check current backend: `widget.get_gpu_backend()`
- Learn more: [Vulkan API](https://www.vulkan.org/), [Blender Vulkan Support](https://developer.blender.org/docs/release_notes/4.5/eevee/)
### Material Colors
- Always use RGB or RGBA tuples: `(1.0, 0.5, 0.0)` or `(1.0, 0.5, 0.0, 1.0)`
- Values should be 0.0-1.0 range
## Version
Current version: **0.1.1**
## License
MIT License - see LICENSE file for details.
## Credits
Built with:
- [Blender](https://www.blender.org/) - 3D creation suite (4.5.4+)
- [anywidget](https://anywidget.dev/) - Custom Jupyter widgets
- [Vulkan API](https://www.vulkan.org/) - High-performance GPU rendering
## Related Links
**Project:**
- [GitHub Repository](https://github.com/bjoernbethge/bpy-widget) - Source code and issues
- [PyPI Package](https://pypi.org/project/bpy-widget/) - Install from PyPI
- [Report Issues](https://github.com/bjoernbethge/bpy-widget/issues) - Bug reports and feature requests
**Documentation & Resources:**
- [Blender Documentation](https://docs.blender.org/) - Official Blender docs
- [Blender 4.5 Release Notes](https://www.blender.org/download/releases/4-5/) - What's new in Blender 4.5
- [Blender Python API](https://docs.blender.org/api/current/) - bpy API reference
- [Vulkan API Documentation](https://www.vulkan.org/learn) - Learn about Vulkan
- [anywidget Documentation](https://anywidget.dev/) - Widget framework docs
**GPU Driver Downloads (for Vulkan support):**
- [NVIDIA Drivers](https://www.nvidia.com/Download/index.aspx) - Driver 550+ required for Vulkan
- [AMD Drivers](https://www.amd.com/en/support) - Latest drivers recommended
- [Intel Arc Drivers](https://www.intel.com/content/www/us/en/download/726609/intel-arc-graphics-windows-dch-driver.html) - For Intel Arc GPUs
- [Vulkan Hardware Database](https://vulkan.gpuinfo.org/) - Check GPU Vulkan support