WGPU-based 3d viewer
Project description
Octarine is the eighth color of the Discworld's spectrum, which is described as the color of magic itself. Only wizards and cats can see it.
Octarine
A minimalist, easy-to-use, high-performance 3D viewer. Octarine
is build on top of the excellent
pygfx
WGPU rendering engine which does most of the heavy lifting - we're simply
abstracting away some of the boiler plate code for you.
Rationale :thought_balloon:
Why another 3d viewer? There are plenty options out there:
vedo
, ipygany
, polyscope
, napari
, fury
, plotly
or pyvista
to name but a few. All of these are great in their own right but I wanted something (a) without heavy dependencies (i.e. no VTK), (b) that lets me interactively explore my data in both REPL and Jupyter and (c) is very performant. None of the existing solutions ticked all those boxes for me.
Octarine
tries to fill that gap:
- Lightweight with very few direct or indirect dependencies.
- Works in both Jupyter and REPL.
- High performance: a mesh with 15M faces renders with 80 fps at 1080p on a 2023 MacBook Pro.
ToDo :ballot_box_with_check:
This is still a prototype but basic stuff already works (mostly because pygfx
makes it so ridiculously easy).
- basic datatypes: meshes, points, scatter, volumes
- custom keyboard shortcuts
- rudamentary controls + legend
- screenshots
- support for trimesh scenes
- user-defined animations
- documentation
- methods/controls to manipulate image volumes
- tests
Installation :rocket:
pip install octarine3d
In addition you will need to install at least one window manager supported by wgpu-py
:
- qt: PySide6, PyQt6, PySide2, PyQt5 all work but I recommend PySide6 (see below)
- glfw: a lightweight GUI for the desktop
- jupyter_rfb: only needed if you plan on using
Octarine
in Jupyter - wx
Please note that at this point, Octarine
's controls panel requires PySide6
. So if you want GUI controls you have to use PySide6
.
Quickstart :fire:
# Create a Viewer instance
from octarine import Viewer
v = Viewer()
# Add random points as scatter
import numpy as np
points = np.random.rand(10, 3) # 10 random points
v.add(points)
# Clear scene
v.clear()
# Add a mesh
# See also `Viewer.add_mesh`
import pygfx as gfx
m = gfx.geometries.mobius_strip_geometry()
v.add(m, color='b')
# Close the viewer
v.close()
Other selected Viewer
methods:
add()
: generic method to add stuff to the viewer; will call respective specialised methodsadd_lines()
: add line plotadd_mesh()
: add meshes (anything that has.vertices
and.faces
goes)add_points()
: add a scatter plotadd_volume()
: add an image volumecenter_camera()
: center camera on sceneclear()
: clear sceneclose()
: close viewercolorize()
: cycle colors for all objectspop()
: remove last added objectremove_objects()
: remove a given object(s) from the scenescreenshot()
: take (and save) a screenshotset_bgcolor()
: set background colorset_colors()
: set object colors
Hotkeys
The following keyboard shortcuts are hard-coded:
1
: reset view to XY (frontal)2
: reset view to XZ (dorsal)3
: reset view to YZ (lateral)f
: show FPSc
: show control panel (requiresPySide6
)
You can also bind custom functions to keys:
# Bind `x` key to the cycle-colors method
v.key_events['x'] = lambda : v.colorize()
Want to contribute?
We welcome all kinds of contributions. For example:
- reports of bugs, broken examples, etc.
- feature requests
- pull requests with bug fixes or new features
If you already know what needs doing, feel free to open a pull request right away. When in doubt please open an issue so we can discuss the best way to address the issue.
Development :dash:
Tests
TODO
Docs
To generate the documentation:
pip install -e .[docs]
mkdocs build
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for octarine3d-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3ba6d04a733df03def920f4f6917cb8c595a515a622d78181ca5bb8006a726c0 |
|
MD5 | 6bb7b0c74d85c7a1262ec890bdcbb6c6 |
|
BLAKE2b-256 | 20e5bb7f3710eef75d244494b7e390a5309f224211dc43094ce05c2f3ce6beb1 |