<p align="center">
<i>
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.
</i>
</p>
[](https://schlegelp.github.io/octarine/)
# Octarine
A minimalist, easy-to-use, high-performance 3D viewer. `Octarine` is build on top of the excellent
[`pygfx`](https://github.com/pygfx/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`](https://github.com/marcomusy/vedo), [`ipygany`](https://github.com/jupyter-widgets-contrib/ipygany), [`polyscope`](https://github.com/nmwsharp/polyscope), [`napari`](https://github.com/napari/napari), [`fury`](https://github.com/fury-gl/fury), [`plotly`](https://github.com/plotly/plotly.py) or [`pyvista`](https://github.com/pyvista/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:
1. _Lightweight_ with very few direct or indirect dependencies.
2. Works in both _Jupyter_ and _REPL_.
3. _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).
- [x] basic datatypes: meshes, points, scatter, volumes
- [x] custom keyboard shortcuts
- [x] rudamentary controls + legend
- [x] screenshots
- [x] support for trimesh scenes
- [x] user-defined animations
- [x] documentation
- [ ] methods/controls to manipulate image volumes
- [ ] tests
## Installation :rocket:
```bash
pip install octarine3d
```
In addition you will need to install at least one window manager supported by [`wgpu-py`](https://github.com/pygfx/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:
```python
# 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 methods
- `add_lines()`: add line plot
- `add_mesh()`: add meshes (anything that has `.vertices` and `.faces` goes)
- `add_points()`: add a scatter plot
- `add_volume()`: add an image volume
- `center_camera()`: center camera on scene
- `clear()`: clear scene
- `close()`: close viewer
- `colorize()`: cycle colors for all objects
- `pop()`: remove last added object
- `remove_objects()`: remove a given object(s) from the scene
- `screenshot()`: take (and save) a screenshot
- `set_bgcolor()`: set background color
- `set_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 FPS
- `c`: show control panel (requires `PySide6`)
You can also bind custom functions to keys:
```python
# 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](https://github.com/schlegelp/octarine/issues)
so we can discuss the best way to address the issue.
## Development :dash:
### Tests
TODO
### Docs
To generate the documentation:
```bash
pip install -e .[docs]
mkdocs build
```
Raw data
{
"_id": null,
"home_page": "https://github.com/schlegelp/octarine",
"name": "octarine3d",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "3D viewer WGPU pygfx",
"author": "Philipp Schlegel",
"author_email": "pms70@cam.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/40/22/c79ede3020949a75b3e9478bee9499a65df4cb199437a8338b3e1adbc23e/octarine3d-0.1.1.tar.gz",
"platform": null,
"description": "\n<p align=\"center\">\n<i>\nOctarine 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.\n</i>\n</p>\n\n[](https://schlegelp.github.io/octarine/)\n\n# Octarine\nA minimalist, easy-to-use, high-performance 3D viewer. `Octarine` is build on top of the excellent\n[`pygfx`](https://github.com/pygfx/pygfx) WGPU rendering engine which does most of the heavy lifting - we're simply\nabstracting away some of the boiler plate code for you.\n\n## Rationale :thought_balloon:\nWhy another 3d viewer? There are plenty options out there:\n[`vedo`](https://github.com/marcomusy/vedo), [`ipygany`](https://github.com/jupyter-widgets-contrib/ipygany), [`polyscope`](https://github.com/nmwsharp/polyscope), [`napari`](https://github.com/napari/napari), [`fury`](https://github.com/fury-gl/fury), [`plotly`](https://github.com/plotly/plotly.py) or [`pyvista`](https://github.com/pyvista/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.\n\n`Octarine` tries to fill that gap:\n1. _Lightweight_ with very few direct or indirect dependencies.\n2. Works in both _Jupyter_ and _REPL_.\n3. _High performance_: a mesh with 15M faces renders with 80 fps at 1080p on a 2023 MacBook Pro.\n\n## ToDo :ballot_box_with_check:\nThis is still a prototype but basic stuff already works (mostly because `pygfx` makes it so ridiculously easy).\n\n- [x] basic datatypes: meshes, points, scatter, volumes\n- [x] custom keyboard shortcuts\n- [x] rudamentary controls + legend\n- [x] screenshots\n- [x] support for trimesh scenes\n- [x] user-defined animations\n- [x] documentation\n- [ ] methods/controls to manipulate image volumes\n- [ ] tests\n\n## Installation :rocket:\n\n```bash\npip install octarine3d\n```\n\nIn addition you will need to install at least one window manager supported by [`wgpu-py`](https://github.com/pygfx/wgpu-py):\n- qt: PySide6, PyQt6, PySide2, PyQt5 all work but I recommend PySide6 (see below)\n- glfw: a lightweight GUI for the desktop\n- jupyter_rfb: only needed if you plan on using `Octarine` in Jupyter\n- wx\n\nPlease note that at this point, `Octarine`'s controls panel requires `PySide6`. So if you want GUI controls you have to use `PySide6`.\n\n## Quickstart :fire:\n\n```python\n# Create a Viewer instance\nfrom octarine import Viewer\nv = Viewer()\n\n# Add random points as scatter\nimport numpy as np\npoints = np.random.rand(10, 3) # 10 random points\nv.add(points)\n\n# Clear scene\nv.clear()\n\n# Add a mesh\n# See also `Viewer.add_mesh`\nimport pygfx as gfx\nm = gfx.geometries.mobius_strip_geometry()\nv.add(m, color='b')\n\n# Close the viewer\nv.close()\n```\n\n\n\nOther selected `Viewer` methods:\n- `add()`: generic method to add stuff to the viewer; will call respective specialised methods\n- `add_lines()`: add line plot\n- `add_mesh()`: add meshes (anything that has `.vertices` and `.faces` goes)\n- `add_points()`: add a scatter plot\n- `add_volume()`: add an image volume\n- `center_camera()`: center camera on scene\n- `clear()`: clear scene\n- `close()`: close viewer\n- `colorize()`: cycle colors for all objects\n- `pop()`: remove last added object\n- `remove_objects()`: remove a given object(s) from the scene\n- `screenshot()`: take (and save) a screenshot\n- `set_bgcolor()`: set background color\n- `set_colors()`: set object colors\n\n### Hotkeys\nThe following keyboard shortcuts are hard-coded:\n- `1`: reset view to XY (frontal)\n- `2`: reset view to XZ (dorsal)\n- `3`: reset view to YZ (lateral)\n- `f`: show FPS\n- `c`: show control panel (requires `PySide6`)\n\nYou can also bind custom functions to keys:\n\n```python\n# Bind `x` key to the cycle-colors method\nv.key_events['x'] = lambda : v.colorize()\n```\n\n## Want to contribute?\nWe welcome all kinds of contributions. For example:\n\n- reports of bugs, broken examples, etc.\n- feature requests\n- pull requests with bug fixes or new features\n\nIf you already know what needs doing, feel free to open a pull request\nright away. When in doubt please open an [issue](https://github.com/schlegelp/octarine/issues)\nso we can discuss the best way to address the issue.\n\n## Development :dash:\n\n### Tests\nTODO\n\n### Docs\n\nTo generate the documentation:\n\n```bash\npip install -e .[docs]\nmkdocs build\n```\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "WGPU-based 3d viewer",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/schlegelp/octarine/releases",
"Documentation": "https://schlegelp.github.io/octarine/",
"Homepage": "https://github.com/schlegelp/octarine",
"Source": "https://github.com/schlegelp/octarine"
},
"split_keywords": [
"3d",
"viewer",
"wgpu",
"pygfx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "20e5bb7f3710eef75d244494b7e390a5309f224211dc43094ce05c2f3ce6beb1",
"md5": "6bb7b0c74d85c7a1262ec890bdcbb6c6",
"sha256": "3ba6d04a733df03def920f4f6917cb8c595a515a622d78181ca5bb8006a726c0"
},
"downloads": -1,
"filename": "octarine3d-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6bb7b0c74d85c7a1262ec890bdcbb6c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26910,
"upload_time": "2024-04-07T11:37:29",
"upload_time_iso_8601": "2024-04-07T11:37:29.504391Z",
"url": "https://files.pythonhosted.org/packages/20/e5/bb7f3710eef75d244494b7e390a5309f224211dc43094ce05c2f3ce6beb1/octarine3d-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4022c79ede3020949a75b3e9478bee9499a65df4cb199437a8338b3e1adbc23e",
"md5": "f1f7f5b898a13f61ef2e436c00da940f",
"sha256": "145d4d6c93501ef7cd9d5ab7923ddcbbb98e393c784477dc83cb8b74d349b8f7"
},
"downloads": -1,
"filename": "octarine3d-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f1f7f5b898a13f61ef2e436c00da940f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27245,
"upload_time": "2024-04-07T11:37:31",
"upload_time_iso_8601": "2024-04-07T11:37:31.112134Z",
"url": "https://files.pythonhosted.org/packages/40/22/c79ede3020949a75b3e9478bee9499a65df4cb199437a8338b3e1adbc23e/octarine3d-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-07 11:37:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "schlegelp",
"github_project": "octarine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pygfx",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "pypng",
"specs": []
},
{
"name": "six",
"specs": []
},
{
"name": "cmap",
"specs": []
},
{
"name": "jupyter_rfb",
"specs": []
},
{
"name": "PySide6",
"specs": []
},
{
"name": "ipywidgets",
"specs": []
},
{
"name": "sidecar",
"specs": []
},
{
"name": "mkdocs",
"specs": []
},
{
"name": "mkdocs-material",
"specs": []
},
{
"name": "mkdocstrings-python",
"specs": []
},
{
"name": "mkdocs-minify-plugin",
"specs": []
},
{
"name": "mkdocs-literate-nav",
"specs": []
},
{
"name": "mkdocs-gen-files",
"specs": []
}
],
"lcname": "octarine3d"
}
JSON
