{"id":37075809,"url":"https://github.com/bjoernbethge/bpy-widget","last_synced_at":"2026-01-14T08:55:16.066Z","repository":{"id":303680798,"uuid":"1015879982","full_name":"bjoernbethge/bpy-widget","owner":"bjoernbethge","description":"Interactive Blender 3D viewport widget for notebooks with real-time Eevee Next rendering.","archived":false,"fork":false,"pushed_at":"2025-11-08T20:36:35.000Z","size":28681,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-04T02:32:53.315Z","etag":null,"topics":["3d-visualization","blender","cycles","eevee","interactive-visualization","jupyter","jupyter-widget","marimo","notebook","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bjoernbethge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-08T07:08:40.000Z","updated_at":"2025-11-08T20:35:11.000Z","dependencies_parsed_at":"2025-07-08T21:41:52.326Z","dependency_job_id":"a2d381f8-def2-4c48-be96-e9c5123ad7fd","html_url":"https://github.com/bjoernbethge/bpy-widget","commit_stats":null,"previous_names":["bjoernbethge/bpy-widget"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bjoernbethge/bpy-widget","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoernbethge%2Fbpy-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoernbethge%2Fbpy-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoernbethge%2Fbpy-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoernbethge%2Fbpy-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjoernbethge","download_url":"https://codeload.github.com/bjoernbethge/bpy-widget/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoernbethge%2Fbpy-widget/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-visualization","blender","cycles","eevee","interactive-visualization","jupyter","jupyter-widget","marimo","notebook","python"],"created_at":"2026-01-14T08:55:15.415Z","updated_at":"2026-01-14T08:55:16.027Z","avatar_url":"https://github.com/bjoernbethge.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bpy-widget\n\nInteractive Blender 3D viewport widget for Jupyter notebooks with real-time rendering powered by Blender 4.5+.\n\n![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)\n![Blender](https://img.shields.io/badge/Blender-4.5.4+-orange.svg)\n[![PyPI](https://img.shields.io/pypi/v/bpy-widget.svg)](https://pypi.org/project/bpy-widget/)\n![License](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Vulkan](https://img.shields.io/badge/Vulkan-Supported-purple.svg)\n\n[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?logo=github)](https://github.com/bjoernbethge/bpy-widget)\n[![Issues](https://img.shields.io/badge/GitHub-Issues-blue?logo=github)](https://github.com/bjoernbethge/bpy-widget/issues)\n\n## Features\n\n- 🎨 **Interactive 3D Viewport** - Real-time camera controls with mouse/touch gestures\n- ⚡ **EEVEE Next \u0026 Cycles** - Switch between render engines on the fly  \n- 🚀 **Vulkan Backend** - High-performance GPU acceleration (Blender 4.5+)\n- 🎬 **Post-Processing** - Bloom, vignette, color correction, depth of field, and more\n- 📊 **Data Visualization** - Import CSV/Parquet data as 3D objects (point clouds, curves)\n- 🔄 **Live Updates** - Changes render immediately with optimized debouncing\n- 📦 **Import/Export** - Support for GLTF, USD, Alembic formats\n- 🧩 **Extension Management** - Manage Blender extensions and addons (Blender 4.2+)\n\n## Installation\n\n```bash\nuv add bpy-widget\n```\n\n**Requirements:**\n- Python 3.11+ (required by Blender 4.5)\n- Blender 4.5.4+ as Python module (installed automatically via pip)\n\n**Optional:**\n- Modern GPU with [Vulkan](https://www.vulkan.org/) support (for improved performance with `VULKAN` backend)\n  - **NVIDIA**: Driver 550+ (see [NVIDIA Vulkan Drivers](https://www.nvidia.com/Download/index.aspx))\n  - **AMD**: Latest drivers recommended\n  - **Intel Arc**: Supported on modern Intel GPUs\n\n## Quick Start\n\n```python\nfrom bpy_widget import BpyWidget\n\n# Create widget\nwidget = BpyWidget(width=800, height=600)\n\n# Enable Vulkan for better performance (Blender 4.5+)\nwidget.set_gpu_backend(\"VULKAN\")\n\n# Display in notebook (Jupyter/Marimo)\nwidget\n```\n\nThe widget automatically initializes with a test scene. You can interact with it immediately:\n- **Drag** to rotate camera\n- **Scroll** to zoom  \n- **Touch** gestures on mobile\n\n**Performance:** Vulkan backend provides 10-15% faster rendering compared to OpenGL.\n\n## Detailed Usage\n\n### Scene Setup\n\n```python\n# Clear and setup new scene\nwidget.clear_scene()\nwidget.setup_lighting(sun_energy=3.0, add_fill_light=True)\nwidget.setup_world_background(color=(0.05, 0.05, 0.1))\n\n# Create objects\ncube = widget.create_test_cube(location=(0, 0, 0))\nsuzanne = widget.create_suzanne(location=(0, 0, 2))\ntorus = widget.create_torus(location=(3, 0, 0))\n```\n\n### Material System\n\n```python\n# Use material presets\ngold_mat = widget.create_preset_material(\"MyGold\", \"gold\")\nglass_mat = widget.create_preset_material(\"MyGlass\", \"glass\")\n\n# Or create custom materials\ncustom = widget.create_material(\n    \"Custom\",\n    base_color=(0.8, 0.2, 0.2),\n    metallic=0.5,\n    roughness=0.4,\n    emission_strength=0.1\n)\n\n# Apply to objects\nwidget.assign_material(suzanne, gold_mat)\n```\n\nAvailable presets: `gold`, `silver`, `copper`, `chrome`, `glass`, `water`, `diamond`, `rubber`, `plastic`, `wood`, `concrete`, `neon_red`, `neon_blue`, `neon_green`\n\n### Data Import\n\n```python\n# Import point cloud\nwidget.import_data(\"data.csv\", as_type=\"points\", point_size=0.1)\n\n# Import as curve\nwidget.import_data(\"timeseries.csv\", as_type=\"curve\")\n\n# Import multiple series\nwidget.import_data(\n    \"multi_series.csv\", \n    as_type=\"series\",\n    value_columns=[\"col1\", \"col2\", \"col3\"]\n)\n\n# Batch import\nwidget.batch_import([\"*.csv\", \"*.parquet\"], as_type=\"points\")\n```\n\n### Post-Processing Effects\n\n```python\n# Setup compositor with effects\nwidget.setup_extended_compositor()\n\n# Add individual effects\nwidget.add_bloom_glare(intensity=0.8, threshold=0.8)\nwidget.add_color_correction(brightness=0.1, contrast=0.1, saturation=1.1)\nwidget.add_vignette(amount=0.2)\nwidget.add_film_grain(amount=0.03)\nwidget.add_chromatic_aberration(amount=0.001)\nwidget.add_sharpen(amount=0.1)\n\n# Camera effects\nwidget.add_depth_of_field(focus_distance=5.0, fstop=2.8)\nwidget.add_motion_blur(samples=8, shutter=0.5)\n```\n\n### Import/Export 3D Formats\n\n```python\n# GLTF/GLB\nobjects = widget.import_gltf(\"model.glb\")\nwidget.export_gltf(\"output.glb\")\n\n# USD/USDZ\nobjects = widget.import_usd(\"scene.usd\")\nwidget.export_usd(\"output.usd\")\n\n# Alembic\nobjects = widget.import_alembic(\"animation.abc\")\nwidget.export_alembic(\"output.abc\")\n\n# Scene as Parquet (for data analysis)\nwidget.export_scene_as_parquet(\"scene_data.parquet\")\nobjects = widget.import_scene_from_parquet(\"scene_data.parquet\")\n```\n\n### Extension Management (Blender 4.5+)\n\n```python\n# List repositories and extensions\nrepos = widget.list_repositories()\nextensions = widget.list_extensions()\n\n# Enable/disable extensions (by package ID)\nwidget.enable_extension(\"molecularnodes\")  # Auto-finds repository\nwidget.disable_extension(\"molecularnodes\")\n\n# Or specify repository module explicitly\nwidget.enable_extension(\"molecularnodes\", repo_module=\"bl_ext\")\n\n# Install extension (universal method - handles ID, URL, or file)\nwidget.install_extension(\"molecularnodes\")  # Install by package ID (searches online)\n\n# Install from URL\nwidget.install_extension(\n    \"https://extensions.blender.org/download/...\",\n    pkg_id=\"molecularnodes\"\n)\n\n# Install from local file\nwidget.install_extension(\"/path/to/extension.zip\", pkg_id=\"my_extension\")\n\n# Or use dedicated file installer\nwidget.install_extension_from_file(\"my_extension.zip\")\n\n# Sync and upgrade\nwidget.sync_repositories()  # Sync all repositories\nwidget.upgrade_extensions()  # Upgrade all extensions\nwidget.upgrade_extensions(active_only=True)  # Upgrade only active extensions\n\n# Legacy addon support (pre-4.2 addons)\nlegacy_addons = widget.list_legacy_addons()\nwidget.enable_legacy_addon(\"space_view3d_copy_attributes\")\n```\n\n### Performance Settings\n\n```python\n# Enable Vulkan backend for improved performance (Blender 4.5+)\nwidget.set_gpu_backend(\"VULKAN\")  # or \"OPENGL\" (default)\nprint(f\"Current backend: {widget.get_gpu_backend()}\")  # VULKAN\n\n# Switch render engines\nwidget.set_render_engine(\"CYCLES\")  # or \"BLENDER_EEVEE_NEXT\"\nwidget.render_device = \"GPU\"  # For Cycles (requires GPU support)\n\n# Adjust resolution\nwidget.set_resolution(1920, 1080)\n\n# Optimize for speed\nwidget.scene.eevee.taa_render_samples = 8\nwidget.scene.eevee.use_raytracing = False\n```\n\n**Performance Tips:**\n- Use **Vulkan backend** for 10-15% faster rendering with EEVEE Next\n- **EEVEE Next** is faster for interactive work (~200ms at 512x512)\n- **Cycles** provides higher quality but is slower (suitable for final renders)\n- Lower resolution for interactive editing, increase for final output\n\n## Convenience Properties\n\nAccess Blender internals directly without `bpy.context`:\n\n```python\n# Scene access\nscene = widget.scene\nscene.frame_set(1)\nscene.render.fps = 30\n\n# Context access (for advanced operations)\nwidget.context.view_layer.update()\n\n# Data access\nobjects = widget.objects  # bpy.data.objects\nmaterials = widget.data.materials  # bpy.data.materials\n\n# Camera access\ncamera = widget.camera  # bpy.context.scene.camera\n\n# Active object\nactive = widget.active_object  # bpy.context.active_object\nselected = widget.selected_objects  # bpy.context.selected_objects\n\n# Operations access\nwidget.ops.mesh.primitive_uv_sphere_add(location=(0, 0, 5))\nwidget.data.objects[\"Sphere\"].scale = (2, 2, 2)\n```\n\n**Note:** These properties work in headless Blender environments and safely handle cases where UI contexts aren't available.\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/bjoernbethge/bpy-widget.git\ncd bpy-widget\n\n# Install with dev dependencies\nuv sync --dev\n\n# Run example notebooks (set PYTHONPATH for local development)\n# PowerShell:\n$env:PYTHONPATH = \"D:\\bpy-widget\\src\"; uv run marimo edit examples/basic_usage.py\n\n# Bash:\nexport PYTHONPATH=\"$(pwd)/src\" \u0026\u0026 uv run marimo edit examples/basic_usage.py\n\n# Frontend development with HMR\ncd frontend\nnpm install\nnpm run dev  # Starts Vite dev server on localhost:5173\n\n# In another terminal, run notebook with HMR enabled:\n$env:ANYWIDGET_HMR=\"1\"; $env:PYTHONPATH=\"D:\\bpy-widget\\src\"; uv run marimo edit examples/basic_usage.py\n```\n\nSee `examples/` directory for complete usage examples.\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- `simple_widget.py` - Minimal example to get started quickly\n- `basic_usage.py` - Interactive notebook with all features (materials, post-processing, scene controls, Vulkan)\n- `data_import.py` - Data visualization with CSV/Parquet import as point clouds and curves\n\n## API Reference\n\n### Core Methods\n\n**Rendering:**\n- `widget.set_gpu_backend(\"VULKAN\")` - Set GPU backend (VULKAN/OPENGL)\n- `widget.get_gpu_backend()` - Get current GPU backend\n- `widget.set_render_engine(\"BLENDER_EEVEE_NEXT\")` - Set render engine\n- `widget.set_resolution(width, height)` - Set render resolution\n- `widget.render()` - Force immediate render\n\n**Scene Management:**\n- `widget.clear_scene()` - Clear all objects\n- `widget.setup_lighting()` - Setup default lighting\n- `widget.setup_world_background(color, strength)` - Set world background\n\n**Objects:**\n- `widget.create_test_cube()`, `create_suzanne()`, `create_torus()`, etc.\n- `widget.import_gltf()`, `import_usd()`, `import_alembic()` - Import 3D files\n\n**Materials:**\n- `widget.create_material()` - Create custom material\n- `widget.create_preset_material()` - Use material presets\n- `widget.assign_material()` - Apply material to object\n\n**Data Import:**\n- `widget.import_data()` - Import CSV/Parquet as points or curves\n- `widget.batch_import()` - Import multiple files\n\n## Troubleshooting\n\n### Import Errors\n- Ensure Python 3.11 is installed (required by Blender 4.5)\n- Check `bpy` module: `pip show bpy` (should be 4.5.x)\n\n### Rendering Issues\n- **EEVEE Next** requires OpenGL or Vulkan support (Vulkan recommended for better performance)\n- For headless servers without GPU: `widget.set_render_engine(\"CYCLES\")` and `widget.render_device = \"CPU\"`\n- If Vulkan rendering fails, fallback to OpenGL: `widget.set_gpu_backend(\"OPENGL\")`\n\n### GPU Backend\n- Vulkan backend requires compatible GPU drivers:\n  - **NVIDIA**: [Driver 550+](https://www.nvidia.com/Download/index.aspx)\n  - **AMD**: [Latest drivers](https://www.amd.com/en/support)\n  - **Intel Arc**: [Supported GPUs](https://www.intel.com/content/www/us/en/products/docs/discrete-gpus/arc/software/vulkan.html)\n- If Vulkan is unavailable, OpenGL is used automatically\n- Check current backend: `widget.get_gpu_backend()`\n- Learn more: [Vulkan API](https://www.vulkan.org/), [Blender Vulkan Support](https://developer.blender.org/docs/release_notes/4.5/eevee/)\n\n### Material Colors\n- Always use RGB or RGBA tuples: `(1.0, 0.5, 0.0)` or `(1.0, 0.5, 0.0, 1.0)`\n- Values should be 0.0-1.0 range\n\n## Version\n\nCurrent version: **0.1.1**\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Credits\n\nBuilt with:\n- [Blender](https://www.blender.org/) - 3D creation suite (4.5.4+)\n- [anywidget](https://anywidget.dev/) - Custom Jupyter widgets\n- [Vulkan API](https://www.vulkan.org/) - High-performance GPU rendering\n\n## Related Links\n\n**Project:**\n- [GitHub Repository](https://github.com/bjoernbethge/bpy-widget) - Source code and issues\n- [PyPI Package](https://pypi.org/project/bpy-widget/) - Install from PyPI\n- [Report Issues](https://github.com/bjoernbethge/bpy-widget/issues) - Bug reports and feature requests\n\n**Documentation \u0026 Resources:**\n- [Blender Documentation](https://docs.blender.org/) - Official Blender docs\n- [Blender 4.5 Release Notes](https://www.blender.org/download/releases/4-5/) - What's new in Blender 4.5\n- [Blender Python API](https://docs.blender.org/api/current/) - bpy API reference\n- [Vulkan API Documentation](https://www.vulkan.org/learn) - Learn about Vulkan\n- [anywidget Documentation](https://anywidget.dev/) - Widget framework docs\n\n**GPU Driver Downloads (for Vulkan support):**\n- [NVIDIA Drivers](https://www.nvidia.com/Download/index.aspx) - Driver 550+ required for Vulkan\n- [AMD Drivers](https://www.amd.com/en/support) - Latest drivers recommended\n- [Intel Arc Drivers](https://www.intel.com/content/www/us/en/download/726609/intel-arc-graphics-windows-dch-driver.html) - For Intel Arc GPUs\n- [Vulkan Hardware Database](https://vulkan.gpuinfo.org/) - Check GPU Vulkan support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjoernbethge%2Fbpy-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjoernbethge%2Fbpy-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjoernbethge%2Fbpy-widget/lists"}