k3d-tools / k3d-jupyter

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 Jupyter

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

Showcase:

YouTube:

Click to watch at YouTube:

Try it Now!

Watch: Interactive showcase gallery

Jupyter version:

Installation

PyPI

To install from PyPI use pip:

$ pip install k3d

Conda/Anaconda

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):

$ pip install git+https://github.com/K3D-tools/K3D-jupyter

This also makes possible installing the most up-to-date development version (same requirements):

$ pip install git+https://github.com/K3D-tools/K3D-jupyter@devel

To install any historical version, replace devel above with any tag or commit hash.

Source

For a development installation (requires npm and node.js),

$ git clone https://github.com/K3D-tools/K3D-jupyter.git
$ cd K3D-jupyter
$ pip install -e .

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

• Travis is ❤️
• OpenDreamKit is 🚀
• Three.js is 🥇

Acknowledgments

Research Infrastructure project This package was created as part of the Horizon 2020 European OpenDreamKit (grant agreement #676541).

k3d-jupyter's Issues

Widget not respoding when data update is too large

Info box on the js widget

Version + perhaps some memory usage should be displayed,

Changing an attribute of an object resets the camera

To reproduce (with current devel branch, 3142b54)

• open examples/line.ipynb
• run the first cell
• zoom in with camera
• click slider widget or run the next cell
  The camera resets on both line.line_width = width and line.color = 0xFFFF00.

Individual size of Vectors in VectorField

A typical feature for vector field plots is to have the vectors scale as a function of some vector field value (e.g. flow rate). Here, both the arrow length and the arrow head would typically scale together (see e.g. matlab's quiver plot: https://mathworks.com/help/matlab/ref/quiver.html).

Latex labels cannot be removed interactively

Default directed light is not suitable for objective scientific visualization

A directed light source that makes one side of an object shaded differently from the other side even if the color is the same all over makes objective inspection of colors vs color maps impossible. I have a constant blue colored cube surface mesh that looks almost black on one side and almost white on another. Ambient light would be preferrable, in particular since I see no way to adjust the light?

Screenshot dosen't take into account 2d layer

It should install in SageMath 7.6

When installing in SageMath 7.6, one gets:

Collecting numpy>=1.11.0 (from k3d)
Downloading numpy-1.12.1.zip (4.8MB)
100% |################################| 4.8MB 225kB/s
Collecting ipython>=4.0.0 (from ipywidgets>=6.0.0->k3d)
Downloading ipython-6.0.0.tar.gz (5.1MB)
100% |################################| 5.1MB 200kB/s
Complete output from command python setup.py egg_info:

IPython 6.0+ does not support Python 2.6, 2.7, 3.0, 3.1, or 3.2.
When using Python 2.7, please install IPython 5.x LTS Long Term Support version.
Beginning with IPython 6.0, Python 3.3 and above is required.

See IPython `README.rst` file for more information:

    https://github.com/ipython/ipython/blob/master/README.rst

Python sys.version_info(major=2, minor=7, micro=13, releaselevel='final', serial=0) detected.
Your pip version is out of date, please install pip >= 9.0.1. pip 8.1.2 detected.


----------------------------------------

Command "python setup.py egg_info" failed with error code 1 in /private/var/folders/8f/j1h8qzsj6fzc6kdws2r4qw6c0000gn/T/pip-build-OfJtMo/ipython/
You are using pip version 8.1.2, however version 9.0.1 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.
(sage-sh)

screenshots or it didn't happen!

t's what everybody is looking for the first time

Setup framework to autogenerate API documentation from docstrings

• Wait for decision on project name change or not.
• Setup a page using the new name on https://readthedocs.io
• Follow https://docs.readthedocs.io/en/latest/getting_started.html to get a basic index page up.
• Configure autogenerated api docs.
• Agree on docstring format (make a single well written example).
• Then of course write docstrings for the entire user-level API.

UnicodeDecodeError: 'ascii' codec can't decode byte 0xc4 in position 76: ordinal not in range(128)

Traceback (most recent call last):
File "", line 20, in
File "/tmp/pip-35wbg1lf-build/setup.py", line 14, in
k3d_version = get_version('k3d_widget/lib/k3d/bower.json')
File "/tmp/pip-35wbg1lf-build/setup.py", line 10, in get_version
return json.load(bower)['version']
File "/opt/conda/lib/python3.4/json/init.py", line 265, in load
return loads(fp.read(),
File "/opt/conda/lib/python3.4/encodings/ascii.py", line 26, in decode
return codecs.ascii_decode(input, self.errors)[0]
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc4 in position 76: ordinal not in range(128)

Fix special Polish characters here too:
- K3D-tools/K3D/bower.json,
- K3D-tools/K3D/package.json,
- K3D-tools/K3D-shim/bower.json,
- K3D-tools/K3D-shim/package.json.

Static html examples gallery

Use binary buffer transfers instead of base64

The upcoming release of ipywidgets 7 has improved binary buffer serialisation that K3D should use.

separating the window kills communication

Python part refactor

validation of arraylike parameters

Consider renaming the project

Sorry if you feel attached to the name! But...

Searching for K3D on google gives lots of hits on 3D software, but not this project.
The links all relate to an old project for 3D modeling found here:
https://github.com/K-3D/k3d

They already own the k3d name in Ubuntu:

martinal:~$ apt search k3d
Sorting... Done
Full Text Search... Done
k3d/xenial 0.8.0.5-1 amd64
  3D modeling and animation system, binary files

k3d-data/xenial,xenial 0.8.0.5-1 all
  3D modeling and animation system, data files

It's easier to rename now than later.

line_width = width has no effect

Arrowhead tips should be adjusted with increasing line width

To see the problem, open vector_animation_k3d.ipynb, run the first cell and then set

vector_plot.line_width = 4

The arrow tips need some adjustment.

CPU load on client

E.g. in points example, following code make notebook tab to take 100% of CPU load, even if output is steady. On the contrary seting points_number in original code to 20^3 works better.

In general there should be no significant CPU load then scene is not moving and objects not manipulated.

N=20
print N*_3
a=random.randint(0,10)_10
for i in range(N):
for j in range(N):
for k in range(N):
plot += K3D.points(view_matrix, ((a+i,j,k),), ((1.,random.uniform(0, 1),random.uniform(0, 1)),), point_size=3)

K3D cannot be embedded inside Box widgets

For building GUIs that show interactive manipulation of geometry, it would be nice if the K3D widget could be put inside the Box widgets (VBox, HBox and the various tabs and accordions).

Right now, it looks like this:

Haven't had a chance to dig into it, but figured I'd open it as a ticket after working on #8.

Improve handling of context loss

While creating lots of test plots in a notebook, I notice that the initial plots behaves strangely. The plot contents and grid is gone, but the numbers and letters on the xyz axes are still there and interaction works. I'm not sure exactly what's needed to reproduce yet, but I'm guessing it's related to webgl context loss.

README

Development installation as in README does not work

UnicodeDecodeError: 'ascii' codec can't decode byte 0xc4 in position 78: ordinal not in range(128)

Please fix one line fromK3D-jupyter/bower.json file:
From::

"Artur Trzęsiok <[email protected]>"

to::

"Artur Trzesiok <[email protected]>"

Typo in detached mode message

"K3D work in deatatch mode" -> "K3D works in detached mode"

Add an abstraction for transforms

Here's a suggestion for a design change and/or enhancement.
I think it will make the framework much more flexible at a fairly low cost.

The association of model_matrix (formerly view_matrix) with each object is a pretty low level feature and leaves a lot of both power and responsibility up to the user in terms of placing objects in the scene.

Traditionally scene graphs are used to position objects and groups of objects relative to each other, but K3D uses a flat list of objects which does have its merits in terms of simplicity.

If, instead of having a model_matrix attribute, each object had a transform attribute, which is a reference to an instance of e.g. a Transform class (widget), then one transform can be shared by many objects, and changes to that transform can automatically be propagated to the relevant objects.

If the Transform class has a reference to a child transform, we can effectively get back the composability of a full scene graph while keeping the objects in a flat list.

Example python/pseudo-code:

class Transform(Widget):
    translation = array((3,))  representing translation
    rotation = array((4,))  representing quarternion
    scaling = array((3,))  representing scaling
    custom = 4x4 array defaulting to identity
    child = Instance(Transform)  allowing null

    def compute_matrix(self):
        "Compose transformations, for use on python side (client side duplicates this)."
        T = compute_translation_matrix(self.translation)
        R = compute_rotation_matrix(self.rotation)
        S = compute_scaling_matrix(self.scaling)
        H = self.custom
        C = self.child or identity
        M  = T * R * S * H * C
        return M

The translate/rotate/scale options are for more convenient construction of the matrix, the custom matrix is an escape hatch for full flexibility (could for example be used to set up a custom projection to a plane), and the child reference is what makes it possible to compose these transforms like a standard scene graph.

Then you can setup e.g. a shared rotation transform and separate translations of subfigures, then update the rotation and have the effects propagate:

R = K3D.transform(rotate=[...])

T00 = K3D.transform(translate=[-10,-10,0], child=R)
T10 = K3D.transform(translate=[+10,-10,0], child=R)
T01 = K3D.transform(translate=[-10,10,0], child=R)
T11 = K3D.transform(translate=[+10,10,0], child=R)

plot += K3d.someobject(..., transform=T00)
plot += K3d.someobject(..., transform=T10)
plot += K3d.someobject(..., transform=T01)
plot += K3d.someobject(..., transform=T11)

R.rotate = [...]  # propagates to Txy and to objects in plot

What do you think?

Consider splitting Factory out of K3D class

Tab completion on the K3D object includes lots of names from the widget base class, a situation which would be much better if the factory part was available as a separate object.

What is really the advantage of having Factory as a base class of K3D?

What is really the advantage of making Factory a class in the first place?

Having a collection of factory functions can also be achieved by placing them in a submodule.

Rename view_matrix attribute of objects to model_matrix?

Isn't usually the "view matrix" associated with the camera?
In that light it seems like unusual convention to associate a view matrix with each object.
Maybe rename the object matrices to "model_matrix"?

I haven't reviewed whether this is consistent everywhere, just a thought that struck me going through examples.

VectorsFields is strange grammar

Proper plural forms: one "vector field", several "vector fields".

Use xor method for decrease transfer rate during array update

install

make install: cannot assume sudo, it should be expected to be run as root and/or in user directory

Import K3D from Sage

Hello,
Is it possible to import K3D in a SageMath notebook (-n jupyter)
Or I have to install it directly in sage folder?
Do you know how to do that (or reference)?

Best regards,
Marco

Use traitlets/widgets more?

Is there a particular reason why you define a separate _Attribute class instead of using the traitlets package? They seem to solve mostly the same problem. In addition to being a mature python package, the latter offer the benefit of better integration with existing Jupyter environment.

Also, would it make sense to make Drawable/SingleObject classes inherit ipywidgets.Widget? This would allow direct use of ipywidgets' sync and serialization code (including binary buffers). Are there any performance concerns?

I could help out with any of these tasks if you find that it would make sense.

read/write a camera position

make possible to read as well as change the camera position

Coordinate axes should show the +- extents

Currently the coordinate axes only show where 0 is for x,y,z, but not what the max/min values of x,y,z are. This is crucial information. Is it possible to show it today? I think it should be default behaviour.

Button to close widget

It would be nice with an X button in the corner to "close" the widget if that's possible.

Use instancing to render glyphs more efficiently

I see in vectors.js that you do:

            useHead ? new THREE.Geometry().copy(singleConeGeometry) : null,

i.e. you make a copy of the cone head for each glyph.

A possible optimization is to use instanced rendering, avoiding duplication of the glyph model.

https://threejs.org/docs/#api/core/InstancedBufferGeometry

Consider this if deciding to pursue an improved glyph model as I suggested in
#38

jupyterhub - resources not found

If notebook is spawned by juputerhub, some js resources are not found and no output is produced.

Allow displaying drawables directly in notebook

For simple plots and testing, a simple and convenient feature would be to display any drawable by creating a K3D plot object, adding itself, and displaying the plot object.

I have a pull request coming up doing this.

Grid size doesn't work as expected

Displaying a simple

K3D(grid=[0,0,0,1,1,1], grid_auto_fit=False)

doesn't show as expected. Originally I thought it was the autofit that tried to include some space around my model (too much space for my taste), but even without any data and without autofit the grid size is not respected.

Piecewise constant mesh colors

It would be nice to be able to write

K3D.mesh(vertices, indices, cell_scalars=array)

where array contains values per triangle, i.e., len(array) == len(indices)//3.

This can also be worked around by duplicating vertices and using duplicated vertex scalars.

camera manipulation from Python side

Passing scalars + color map instead of colors

I'd rather be passing my scalar values and then adjust the color map of the plot than computing my own colors. At least points and lines take a direct colors argument. I.e. I'd like to write lines like

plot += K3D.points([0,0,0, 1,1,1], values=[-2.3, 5.7])
plot += K3D.points([0,0,0, 1,1,1], values=[-2.3, 5.7], colormap=...)
plot += K3D.points([0,0,0, 1,1,1], values=[-2.3, 5.7], colormap=..., valuerange=[-3, 6])

Are there plans to improve the color mapping features? What's the intended usage?
I don't quite understand what the intention is with the K3D.matplotlib_color_maps.

Also I suggest changing default colors in the api from color=255 to at least color=0x0000ff to make it more visible what the expected format is, or better allow color='blue' and do a lookup in a suitable color collection if it's a string.

I guess it would be best to use existing color mapping features from something mature like matplotlib.

Plot objects persist

If one has a plot with e.g. single object, then it cannot be removed:

from k3d import K3D
plot = K3D()
plot += K3D.text("HEY",(1,1,1))
print("Expect one object",plot.objects )
plot = K3D()
print("Shold be empty list:",plot.objects)

text (GL version) should have a fontsize

Add Text2dViewport support

Volume rendering support

vtk

vtk should take scalar field and color function

Tooltips over the icons

Would be nice to have, not critical.

Passing wrong types to vectors(colors=...) hides the plot with hard to see error

I tried passing colors=... in the K3D.vectors(...) call in vector_animation_k3d.ipynb.

It took a few tries before arriving at this format

colors = np.zeros(z.shape + (2,), dtype='uint32')

although I did understand it quickly after I spotted the error message.

It's somewhat unconventional to show errors with overlays in the corner of a notebook and require looking at the browser console. Would you consider displaying the error in the output field? Also I believe this kind of dimension mismatch could be caught in the factory functions on the python side instead of going all the way to javascript.

This also highlights the need for documentation.

plot.display()

One cannot redisplay a plot without recreating a K3D object.