Examples
Basic example and precode
By default, the following code will be executed before running each code block.
This allows to use k3d
and np
.
import numpy as np
import k3d
The last command of the of k3d-screenshot
code block must be the K3D
Jupyter plot:
f = lambda r, d: 5 * np.cos(r) * np.exp(-r * d)
x, y = np.mgrid[-7:7:100j, -7:7:100j]
r = np.sqrt(x**2 + y**2)
z = f(r, 0.1)
fig = k3d.plot()
surface = surface = k3d.surface(
z.astype(np.float32), bounds=[-7, 7, -7, 7],
attribute=z.astype(np.float32),
color_map=k3d.colormaps.matplotlib_color_maps.viridis)
fig += surface
fig
(Source code, small.png, large.png, html, pdf)
context
By setting :context: previous
, the new code block will be executed in the
context of the previous ones. To start a new context, set :context: reset
.
In the following example, by setting :context: previous
the previous
variables can be accessed:
fig
(Source code, small.png, large.png, html, pdf)
camera
Sometime it is useful to change the position of the camera, without showing
unnecessart code to the user. We can achieve that with the :camera:
option,
which accepts a list of 9 arguments, namely:
x_camera, y_camera, z_camera: the position of the camera.
x_target, y_target, z_target: the target of the camera (where it is looking at).
x_z_vec, y_z_vec, z_z_vec: the components of the vertical direction of the camera.
For example, the previous code block was written as:
.. k3d-screenshot::
:context: previous
:camera: 8.96, -16.7, -25.63, 0, 0, 0.63, 0.45, -0.72, 0.54
fig
Output Types
By default, the extension will create the following output types: html
,
small.png
, large.png
, pdf
.
The output types can be changed with the following option on conf.py
:
# here we remove "large.png" and "pdf"
k3d_screenshot_formats = ["small.png", "html"]
Function
It is possible to execute a function contained on a module. The function must return a K3D plot.
.. k3d-screenshot:: examples/example.py func
import os
import k3d
import numpy as np
def func():
data = np.load('streamlines_data.npz')
v = data['v']
lines = data['lines']
vertices = data['vertices']
indices = data['indices']
plt_streamlines = k3d.line(lines,
width=0.00007, attribute=v,
color_map=k3d.colormaps.matplotlib_color_maps.Inferno,
color_range=[0, 0.5], shader='mesh')
plt_mesh = k3d.mesh(vertices, indices,
opacity=0.25, wireframe=True, color=0x0002)
plot = k3d.plot(grid_visible=False, screenshot_scale=1.0, axes_helper=0)
plot += plt_streamlines
plot += plt_mesh
return plot
(Source code, small.png, large.png, html, pdf)
include-source
By default, the extension will show the source code of the block being
executed. It is possible to deactive this behavior on a particular code block
by setting the include-source
flag:
.. k3d-screenshot::
:include-source: False
# your code here
To deactive this behavior globally, set the following option on conf.py
:
k3d_screenshot_include_source = False
small-size and large-size
The headless browser is currently incapable of determining the dimensions of the web page, hence proper values should be used to generate the screenshots. The default values are:
small.png
600, 400large.png
1280, 850
To change the size on a code block basis:
.. k3d-screenshot::
:small-size: 700, 400
:large-size: 1920, 1080
To set the size globally, use the following options on conf.py
:
k3d_screenshot_small_size = [700, 400]
k3d_screenshot_large_size = [1920, 1080]
doctest
When using the doctest syntax, we have to:
import the appropriate modules.
the last line must be an assignment to the
myk3d
variable, which is used by the extension to know what to render on the screenshot.
>>> import k3d
>>> import numpy as np
>>> plot = k3d.plot()
>>> isinstance(plot, k3d.Plot)
True
>>> x, y = np.mgrid[-2:2:40j, -2:2:40j]
>>> z = np.cos(x**2 + y**2)
>>> x, y, z = [t.flatten().astype(np.float32) for t in [x, y, z]]
>>> positions = np.vstack([x, y, z]).T
>>> p = k3d.plot()
>>> points = k3d.points(positions=positions, point_size=0.1)
>>> p += points
>>> myk3d = p
(Source code, small.png, large.png, html, pdf)
intercept_code
There might be occasions where the programmer needs to performs edits to the code block being executed, without the final user to be aware of them.
To achieve that, a function accepting the current code and returning the
modified code must be assigned to k3d_screenshot_intercept_code
in
conf.py
.
For example:
def edit_current_block(code):
# use regex and/or ast modules, or other strategies to edit the code
return modified_code
k3d_screenshot_intercept_code = edit_current_block