Docs update

README.md

@@ -4,11 +4,25 @@
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/k3d/badges/downloads.svg)](https://anaconda.org/conda-forge/k3d)
 [![CodeQL](https://github.com/K3D-tools/K3D-jupyter/workflows/CodeQL/badge.svg)](https://github.com/K3D-tools/K3D-jupyter/actions)
 
-Jupyter notebook extension for 3D visualization.
+<div>
+
+<img src="https://k3d-jupyter.org/_static/logo.png" width="25%" align="right">
+
+K3D lets you create 3D plots backed by WebGL with high-level API (surfaces, isosurfaces, voxels,
+mesh, cloud points, vtk objects, volume renderer, colormaps, etc). The primary aim of K3D-jupyter is
+to be easy for use as stand alone package like matplotlib, but also to allow interoperation with
+existing libraries as VTK. K3D can be run as:
+
+- Jupyter Notebook extension 🚀
+- Jupyter Lab extension 🎉
+- Google Colab extension 🧪 [still experimental]
+- Standalone HTML/JS 📑
 
 Documentation: [https://k3d-jupyter.org](https://k3d-jupyter.org)
+</div>
 
-#### Showcase:
+
+## Showcase:
 
 ![points_cloud](imgs/points_cloud.gif)
 
@@ -18,7 +32,9 @@ Documentation: [https://k3d-jupyter.org](https://k3d-jupyter.org)
 
 ![transfer_function_editor](imgs/tf_edit.gif)
 
-#### YouTube:
+### YouTube:
+
+Click to watch at YouTube:
 
 [![Volume renderer](https://i3.ytimg.com/vi/zCeQ_ZXy_Ps/maxresdefault.jpg)](https://www.youtube.com/watch?v=zCeQ_ZXy_Ps)
 
@@ -28,12 +44,12 @@ Documentation: [https://k3d-jupyter.org](https://k3d-jupyter.org)
 
 [![Volume renderer](https://i3.ytimg.com/vi/wIbBpUlB5vc/maxresdefault.jpg)](https://www.youtube.com/watch?v=wIbBpUlB5vc)
 
-
 ## Try it Now!
 
 Watch: [Interactive showcase gallery](https://k3d-jupyter.org/gallery/index.html)
 
-Jupyter version: [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/K3D-tools/K3D-jupyter/main?filepath=index.ipynb)
+Jupyter
+version: [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/K3D-tools/K3D-jupyter/main?filepath=index.ipynb)
 
 ## Installation
 
@@ -49,6 +65,23 @@ To install from conda-forge use:
 
     $ conda install -c conda-forge k3d
 
+### Google Colab
+
+First you need to install k3d:
+
+    !pip install k3d
+    !jupyter nbextension install --py --user k3d
+    !jupyter nbextension enable --py --user k3d
+
+After that you need to activate custom widgets and switch k3d to text protocol:
+
+    import k3d
+    from google.colab import output
+
+    output.enable_custom_widget_manager()
+
+    k3d.switch_to_text_protocol()
+
 ### Installing directly from GitHub
 
 To install directy from this repository (requires git and node.js + npm to build):
@@ -74,6 +107,7 @@ Then, if required, JupyterLab installation:
     $ jupyter labextension install ./js
 
 ### Code of Conduct
+
 K3D-jupyter follows the Python Software Foundation Code of Conduct in everything we do.
 
 ## Kudos

docs/source/gallery/index.rst

@@ -3,7 +3,7 @@ Gallery
 =======
 
 .. raw:: html
-    
+
     <style>
         .grid-container {
             display: flex;
@@ -33,6 +33,7 @@ Showcase
     showcase/turbine-cfd.rst
     showcase/terrain.rst
     showcase/vtk-cutter.rst
+    showcase/tractogram.rst
 
 .. k3d_plot::
    :filename: showcase/thumbnails/lorenz_system_thumbnail.py
@@ -69,9 +70,14 @@ Showcase
 .. k3d_plot::
    :filename: showcase/thumbnails/vtk_cutter_thumbnail.py
    :screenshot:
-
+
+.. k3d_plot::
+    :filename: showcase/thumbnails/tractogram_thumbnail.py
+    :screenshot:
+
+
 .. raw:: html
-    
+
     <div class="grid-container">
 
 .. image:: lorenz_system_thumbnail.png
@@ -109,9 +115,13 @@ Showcase
 .. image:: vtk_cutter_thumbnail.png
    :width: 155
    :target: showcase/vtk-cutter.html
-
+
+.. image:: tractogram_thumbnail.png
+   :width: 155
+   :target: showcase/tractogram.html
+
 .. raw:: html
-    
+
     </div>
 
 ---
@@ -129,7 +139,7 @@ API
 .. k3d_plot::
    :filename: api/thumbnails/marching_cubes_levels_thumbnail.py
    :screenshot:
-   
+
 .. k3d_plot::
    :filename: api/thumbnails/marching_cubes_sinus_cube_thumbnail.py
    :screenshot:
@@ -187,7 +197,7 @@ API
    :screenshot:
 
 .. raw:: html
-    
+
     <div class="grid-container">
 
 .. image:: line_colormap_thumbnail.png
@@ -201,7 +211,7 @@ API
 .. image:: marching_cubes_levels_thumbnail.png
    :width: 155
    :target: ../reference/factory.marching_cubes.html#levels
-   
+
 .. image:: marching_cubes_sinus_cube_thumbnail.png
    :width: 155
    :target: ../reference/factory.marching_cubes.html#sinus-cube
@@ -257,7 +267,7 @@ API
 .. image:: vtk_colormap_thumbnail.png
    :width: 155
    :target: ../reference/factory.vtk_poly_data.html#colormap
-   
+
 .. raw:: html
-    
+
     </div>

docs/source/gallery/showcase/plots/tractogram_plot.py

@@ -0,0 +1,32 @@
+import numpy as np
+import os
+
+import k3d
+
+
+def generate():
+    filepath = os.path.join(os.path.abspath(os.path.dirname(__file__)),
+                            '../assets/tractogram.npz')
+
+    data = np.load(filepath)['data']
+
+    v = data.copy()
+    v[1:] = (v[1:] - v[:-1])
+    v = np.absolute((v / np.linalg.norm(v, axis=1)[..., np.newaxis]))
+    v = (v * 255).astype(np.int32)
+    colors = np.sum((v * np.array([1, 256, 256 * 256])), axis=1).astype(np.uint32)
+
+    streamlines = k3d.line(data, shader='simple', colors=colors)
+
+    plot = k3d.plot(grid_visible=False,
+                    camera_auto_fit=False,
+                    background_color=0,
+                    screenshot_scale=1.0)
+    plot += streamlines
+
+    plot.camera = [-50.0, 125.0, 40.0,
+                   -1.0, 0.5, -5.0,
+                   0.0, -0.25, 1.0]
+
+    plot.snapshot_type = 'inline'
+    return plot.get_snapshot()

docs/source/gallery/showcase/thumbnails/tractogram_thumbnail.py

@@ -0,0 +1,41 @@
+import numpy as np
+import os
+
+import k3d
+from k3d.headless import k3d_remote, get_headless_driver
+
+
+def generate():
+    filepath = os.path.join(os.path.abspath(os.path.dirname(__file__)),
+                            '../assets/tractogram.npz')
+
+    data = np.load(filepath)['data']
+
+    v = data.copy()
+    v[1:] = (v[1:] - v[:-1])
+    v = np.absolute((v / np.linalg.norm(v, axis=1)[..., np.newaxis]))
+    v = (v * 255).astype(np.int32)
+    colors = np.sum((v * np.array([1, 256, 256 * 256])), axis=1).astype(np.uint32)
+
+    streamlines = k3d.line(data, shader='thick', colors=colors, width=0.005)
+
+    plot = k3d.plot(grid_visible=False,
+                    camera_auto_fit=False,
+                    background_color=0,
+                    screenshot_scale=1.0,
+                    axes_helper=0)
+
+    plot += streamlines
+
+    plot.camera = [-60.0, 135.0, 45.0,
+                   -1.0, 0.5, -5.0,
+                   0.0, -0.25, 1.0]
+
+    headless = k3d_remote(plot, get_headless_driver(), width=800, height=800)
+
+    headless.sync(hold_until_refreshed=True)
+
+    screenshot = headless.get_screenshot()
+    headless.close()
+
+    return screenshot

docs/source/gallery/showcase/tractogram.rst

@@ -0,0 +1,37 @@
+Tractogram
+==========
+
+.. admonition:: References
+
+    - :ref:`plot`
+    - :ref:`lines`
+
+:download:`tractogram.npz <./assets/tractogram.npz>`
+
+.. code-block:: python3
+
+    filepath = os.path.join('tractogram.npz')
+
+    data = np.load(filepath)['data']
+
+    v = data.copy()
+    v[1:] = (v[1:] - v[:-1])
+    v = np.absolute((v / np.linalg.norm(v, axis=1)[..., np.newaxis]))
+    v = (v * 255).astype(np.int32)
+    colors = np.sum((v * np.array([1, 256, 256 * 256])), axis=1).astype(np.uint32)
+
+    streamlines = k3d.line(data, shader='simple', colors=colors)
+
+    plot = k3d.plot(grid_visible=False,
+                    camera_auto_fit=False,
+                    background_color=0,
+                    screenshot_scale=1.0)
+    plot += streamlines
+
+    plot.camera = [-50.0, 125.0, 40.0,
+                   -1.0, 0.5, -5.0,
+                   0.0, -0.25, 1.0]
+    plot.display()
+
+.. k3d_plot ::
+  :filename: plots/tractogram_plot.py