Skip to content

Commit

Permalink
Merge pull request #423 from K3D-tools/devel
Browse files Browse the repository at this point in the history
Docs update
  • Loading branch information
artur-trzesiok committed Jun 1, 2023
2 parents 8cb3120 + 0ab263c commit ffe7143
Show file tree
Hide file tree
Showing 6 changed files with 169 additions and 15 deletions.
44 changes: 39 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)

Expand All @@ -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

Expand All @@ -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):
Expand All @@ -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
Expand Down
30 changes: 20 additions & 10 deletions docs/source/gallery/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Gallery
=======

.. raw:: html

<style>
.grid-container {
display: flex;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>

---
Expand All @@ -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:
Expand Down Expand Up @@ -187,7 +197,7 @@ API
:screenshot:

.. raw:: html

<div class="grid-container">

.. image:: line_colormap_thumbnail.png
Expand All @@ -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
Expand Down Expand Up @@ -257,7 +267,7 @@ API
.. image:: vtk_colormap_thumbnail.png
:width: 155
:target: ../reference/factory.vtk_poly_data.html#colormap

.. raw:: html

</div>
Binary file not shown.
32 changes: 32 additions & 0 deletions docs/source/gallery/showcase/plots/tractogram_plot.py
Original file line number Diff line number Diff line change
@@ -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()
41 changes: 41 additions & 0 deletions docs/source/gallery/showcase/thumbnails/tractogram_thumbnail.py
Original file line number Diff line number Diff line change
@@ -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
37 changes: 37 additions & 0 deletions docs/source/gallery/showcase/tractogram.rst
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit ffe7143

Please sign in to comment.