<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.
## Installation :rocket:
```bash
pip install octarine3d[all]
```
This will install the minimal requirements plus `PySide6` and `jupyter_rfb` as window managers for IPython/shell
and Jupyter, respectively. Check out the [**Install Instructions**](https://schlegelp.github.io/octarine/install/)
for details.
## Status :ballot_box_with_check:
All basic components have been implemented but this is a very young project, which means that the API can still change with each version. We'd love for you to take it for a spin and let us know what you think though!
## 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()
```
> [!NOTE]
> The above example will work in interactive environments such as IPython and Jupyter. When using from the standard
> REPL or when running as a script you will have to additionally start the event loop. Please see corresponding the
> section in the [Introduction](https://schlegelp.github.io/octarine/intro/).
## Want to learn more?
Head over to the [**Documentation**](https://schlegelp.github.io/octarine/)!
## 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/5e/25/a32a6bbff8875b3be95231b745f0562f80288f70c4962f48218900c1b0d6/octarine3d-0.2.5.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## Installation :rocket:\n\n```bash\npip install octarine3d[all]\n```\n\nThis will install the minimal requirements plus `PySide6` and `jupyter_rfb` as window managers for IPython/shell\nand Jupyter, respectively. Check out the [**Install Instructions**](https://schlegelp.github.io/octarine/install/)\nfor details.\n\n## Status :ballot_box_with_check:\nAll basic components have been implemented but this is a very young project, which means that the API can still change with each version. We'd love for you to take it for a spin and let us know what you think though!\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 (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> [!NOTE]\n> The above example will work in interactive environments such as IPython and Jupyter. When using from the standard\n> REPL or when running as a script you will have to additionally start the event loop. Please see corresponding the\n> section in the [Introduction](https://schlegelp.github.io/octarine/intro/).\n\n\n\n## Want to learn more?\nHead over to the [**Documentation**](https://schlegelp.github.io/octarine/)!\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.2.5",
"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": "1b838f5089c458804e4254e76ba9289e7499341a8be0284f3fe9bdf1fe7ff992",
"md5": "2891077a520fc8afb86c1a48a23a488d",
"sha256": "d2c58ad5a0170f602091ce56f85030091e6cd924a4af72c172de5be3a19dd3ee"
},
"downloads": -1,
"filename": "octarine3d-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2891077a520fc8afb86c1a48a23a488d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 39736,
"upload_time": "2024-08-31T09:51:58",
"upload_time_iso_8601": "2024-08-31T09:51:58.521533Z",
"url": "https://files.pythonhosted.org/packages/1b/83/8f5089c458804e4254e76ba9289e7499341a8be0284f3fe9bdf1fe7ff992/octarine3d-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e25a32a6bbff8875b3be95231b745f0562f80288f70c4962f48218900c1b0d6",
"md5": "cc8a2740a066d1507ee68379379a973c",
"sha256": "913c97cf0a3787d5b8dacb9d1e105c6dd2608e019ea9d9e37c36b2aa9c68597e"
},
"downloads": -1,
"filename": "octarine3d-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "cc8a2740a066d1507ee68379379a973c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39067,
"upload_time": "2024-08-31T09:51:59",
"upload_time_iso_8601": "2024-08-31T09:51:59.881383Z",
"url": "https://files.pythonhosted.org/packages/5e/25/a32a6bbff8875b3be95231b745f0562f80288f70c4962f48218900c1b0d6/octarine3d-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-31 09:51:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "schlegelp",
"github_project": "octarine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "octarine3d"
}
JSON
