fastplotlib · kushalkolar · Oct 17, 2024 · Oct 15, 2024
@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/fastplotlib/fastplotlib/actions/workflows/ci.yml/badge.svg)](https://github.com/fastplotlib/fastplotlib/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/fastplotlib.svg)](https://badge.fury.io/py/fastplotlib)
-[![Documentation Status](https://readthedocs.org/projects/fastplotlib/badge/?version=latest)](https://fastplotlib.readthedocs.io/en/latest/?badge=latest)
+[![Deploy docs](https://github.com/fastplotlib/fastplotlib/actions/workflows/docs-deploy.yml/badge.svg)](https://fastplotlib.org/ver/dev/)
 [![DOI](https://zenodo.org/badge/485481453.svg)](https://zenodo.org/doi/10.5281/zenodo.13365890)
 
 [**Installation**](https://github.com/fastplotlib/fastplotlib#installation) | 
@@ -15,11 +15,11 @@
 [**Examples**](https://github.com/kushalkolar/fastplotlib#examples) | 
 [**Contributing**](https://github.com/kushalkolar/fastplotlib#heart-contributing)
 
-Next-gen plotting library built using the [`pygfx`](https://github.com/pygfx/pygfx) rendering engine that can utilize [Vulkan](https://en.wikipedia.org/wiki/Vulkan), [DX12](https://en.wikipedia.org/wiki/DirectX#DirectX_12), or [Metal](https://developer.apple.com/metal/) via WGPU, so it is very fast! `fastplotlib` is an expressive plotting library that enables rapid prototyping for large scale explorative scientific visualization.
+Next-gen plotting library built using the [`pygfx`](https://github.com/pygfx/pygfx) rendering engine that can utilize [Vulkan](https://en.wikipedia.org/wiki/Vulkan), [DX12](https://en.wikipedia.org/wiki/DirectX#DirectX_12), or [Metal](https://developer.apple.com/metal/) via WGPU, so it is very fast! `fastplotlib` is an expressive plotting library that enables rapid prototyping for large scale exploratory scientific visualization.
 
 > **Note**
 > 
-> `fastplotlib` is currently in the **late alpha stage**, but you're welcome to try it out or contribute! See our [Roadmap](https://github.com/kushalkolar/fastplotlib/issues/55). See this for a discussion on API stability: https://github.com/fastplotlib/fastplotlib/issues/121
+> `fastplotlib` is currently in the **late alpha stage**, but you're welcome to use it or contribute! See our [Roadmap](https://github.com/kushalkolar/fastplotlib/issues/55). See this for a discussion on API stability: https://github.com/fastplotlib/fastplotlib/issues/121
 
 # Supported frameworks
 
@@ -31,18 +31,14 @@ Next-gen plotting library built using the [`pygfx`](https://github.com/pygfx/pyg
 :heavy_check_mark: `wxPython`
 
 **Notes:**\
-:heavy_check_mark: Non-blocking interactive Qt/PySide output is supported in ipython and notebooks, see http://fastplotlib.org/ver/dev/user_guide/guide.html#using-fastplotlib-in-an-interactive-shell \
+:heavy_check_mark: Non-blocking interactive Qt/PySide output is supported in ipython and notebooks, see the [interactive shells section in the user guide](http://fastplotlib.org/ver/dev/user_guide/guide.html#using-fastplotlib-in-an-interactive-shell) \
 :grey_exclamation: We do not officially support `jupyter notebook` through `jupyter_rfb`, this may change with notebook v7\
-:grey_exclamation: We only officially support jupyterlab for use in notebook. This means we do not support vscode notebooks etc. Jupyterlab is the most reliable way to use `fastplotlib` in notebooks.\
+:grey_exclamation: We only support jupyterlab for use in notebooks. This means that we do not support VSCode notebooks or any other python notebook platform. Jupyterlab is the most reliable way to use widget-based libraries in notebooks.\
 :disappointed: [`jupyter_rfb`](https://github.com/vispy/jupyter_rfb) does not work in collab, see https://github.com/vispy/jupyter_rfb/pull/77 
 
-We recommend sticking to jupyter-lab for notebooks. From our experience the usage on other platforms, such as vscode 
-notebooks, is not optimal. 
-
-
 # Documentation
 
-http://www.fastplotlib.org/
+http://www.fastplotlib.org/ver/dev
 
 Questions, issues, ideas? You are welcome to post an [issue](https://github.com/fastplotlib/fastplotlib/issues) or post on the [discussion forum](https://github.com/fastplotlib/fastplotlib/discussions)! :smiley: 
 
@@ -60,7 +56,7 @@ pip install -U fastplotlib
 # with imgui
 pip install -U "fastplotlib[imgui]"
 
-# to use in jupyterlab, no imgui
+# to use in jupyterlab without imgui
 pip install -U "fastplotlib[notebook]"
 ```
 
@@ -76,7 +72,7 @@ Once you have ``libjpeg-turbo``:
 pip install simplejpeg
 ```
 
-> **Note**[guide.rst](docs%2Fsource%2Fuser_guide%2Fguide.rst)
+> **Note**
 >
 > `fastplotlib` and `pygfx` are fast evolving projects, the version available through pip might be outdated, you will need to follow the "For developers" instructions below if you want the latest features. You can find the release history here: https://github.com/fastplotlib/fastplotlib/releases
 
@@ -95,7 +91,7 @@ pip install -e ".[notebook,docs,tests]"
 pip install git+https://github.com/pygfx/pygfx.git@main
 ```
 
-Se [Contributing](https://github.com/fastplotlib/fastplotlib?tab=readme-ov-file#heart-contributing) for more details on development
+See [Contributing](https://github.com/fastplotlib/fastplotlib?tab=readme-ov-file#heart-contributing) for more details on development
 
 # Examples
 
@@ -109,40 +105,13 @@ User guide: http://fastplotlib.org/ver/dev/user_guide/guide.html
 
 The `quickstart.ipynb` tutorial notebook is a great way to get familiar with the API: https://github.com/fastplotlib/fastplotlib/tree/main/examples/notebooks/quickstart.ipynb
 
-## Graphics drivers
-
-You will need a relatively modern GPU, modern integrated graphics are usually fine for many use cases. Generally if your GPU is from 2017 or later it should be fine.
-
-For more detailed information, such as use on cloud computing infrastructure, see: https://wgpu-py.readthedocs.io/en/stable/start.html#platform-requirements
-
-Some more information on GPUs is here: http://fastplotlib.org/ver/dev/user_guide/gpu.html
-
-### Windows:
-Vulkan drivers should be installed by default on Windows 11, but you will need to install your GPU manufacturer's driver package (Nvidia or AMD). If you have an integrated GPU within your CPU, you might still need to install a driver package too, check your CPU manufacturer's info.
-
-### Linux:
-You will generally need a linux distro that is from ~2020 or newer (ex. Ubuntu 18.04 won't work), this is due to the `glibc` requirements of the `wgpu-native` binary.
+## GPU drivers and requirements
 
-Debian based distros:
+Generally if your GPU is from 2017 or later it should be fine. Modern integrated graphics are usually fine for many use cases. The exact requirements will depend on how complex your visualization is and how many objects you need to render.
 
-```bash
-sudo apt install mesa-vulkan-drivers
-# for better performance with the remote frame buffer install libjpeg-turbo
-sudo apt install libjpeg-turbo
-```
-
-For other distros install the appropriate vulkan driver package, and optionally the corresponding `libjpeg-turbo` package for better remote-frame-buffer performance in jupyter notebooks.
-
-#### CPU/software rendering (Lavapipe)
-
-If you do not have a GPU you can perform limited software rendering using lavapipe. This should get you everything you need for that on Debian or Ubuntu based distros:
-
-```bash
-sudo apt install llvm-dev libturbojpeg* libgl1-mesa-dev libgl1-mesa-glx libglapi-mesa libglx-mesa0 mesa-common-dev mesa-vulkan-drivers
-```
+More detailed information on GPUs and drivers is here: http://fastplotlib.org/ver/dev/user_guide/gpu.html
 
-### Mac OSX:
-WGPU uses Metal instead of Vulkan on Mac. You will need at least Mac OSX 10.13. The OS should come with Metal pre-installed, so you should be good to go!
+For more detailed information, such as use on cloud computing infrastructure, see the WGPU docs: https://wgpu-py.readthedocs.io/en/stable/start.html#cloud-compute
 
 # :heart: Contributing
 

@@ -26,11 +26,39 @@ If you aren't able to solve it please post an issue on GitHub. :)
 Drivers
 -------
 
-See the README: https://github.com/fastplotlib/fastplotlib?tab=readme-ov-file#graphics-drivers
-
 If you notice weird graphic artifacts, things not rendering, or other glitches try updating to the latest stable
 drivers.
 
+More information is also available on the WGPU docs: https://wgpu-py.readthedocs.io/en/stable/start.html#platform-requirements
+
+Windows
+^^^^^^^
+
+Vulkan drivers should be installed by default on Windows 11, but you will need to install your GPU manufacturer's driver package (Nvidia or AMD). If you have an integrated GPU within your CPU, you might still need to install a driver package too, check your CPU manufacturer's info.
+
+Linux
+^^^^^
+
+You will generally need a linux distro that is from ~2020 or newer (ex. Ubuntu 18.04 won't work), this is due to the `glibc` requirements of the `wgpu-native` binary.
+
+Install the drivers directly from your GPU manufacturer's website, after that you may still need to install mesa vulkan drivers:
+
+Debian based distros::
+
+    sudo apt install mesa-vulkan-drivers
+
+For other distros install the corresponding vulkan driver package.
+
+Cloud compute
+~~~~~~~~~~~~~
+
+See the WGPU docs: https://wgpu-py.readthedocs.io/en/stable/start.html#cloud-compute
+
+Mac OSX
+^^^^^^^
+
+WGPU uses Metal instead of Vulkan on Mac. You will need at least Mac OSX 10.13. The OS should come with Metal pre-installed, so you should be good to go!
+
 GPU Info
 --------
 
@@ -279,7 +307,7 @@ to ``fpl.select_adapter()``::
 Note that using this function reduces the portability of your code, because
 it's highly specific for your current machine/environment.
 
-The order of the adapters returned by ``wgpu.gpu.enumerate_adapters()`` is
+The order of the adapters returned by ``fpl.enumerate_adapters()`` is
 such that Vulkan adapters go first, then Metal, then D3D12, then OpenGL.
 Within each category, the order as provided by the particular backend is
 maintained. Note that the same device may be present via multiple backends