plot#

k3d.factory.plot(height: int = 512, antialias: int = 3, logarithmic_depth_buffer: bool = True, background_color: int = 16777215, camera_auto_fit: bool = True, grid_auto_fit: bool = True, grid_visible: bool = True, screenshot_scale: float = 2.0, grid: Tuple[float, float, float, float, float, float] = (-1, -1, -1, 1, 1, 1), grid_color: int = 15132390, label_color: int = 4473924, lighting: float = 1.5, menu_visibility: bool = True, voxel_paint_color: int = 0, colorbar_object_id: int = -1, camera_fov: float = 60.0, time: float = 0.0, depth_peels: int = 0, renderer: str = 'simple', environment: str = 'neutral', environment_rotation: float = 0.0, tone_mapping: str = 'none', ao_radius: float = 0.07, ao_strength: float = 1.8, cinematic_samples: int = 64, cinematic_bounces: int = 6, cinematic_glossy_filter: float = 0.25, cinematic_seed: int | None = None, cinematic_denoise: float = 0.0, cinematic_bokeh_size: float = 0.0, cinematic_focus_distance: float = 0.0, cinematic_aperture_blades: int = 0, axes: List[str] = None, axes_helper: float = 1.0, axes_helper_colors: List[int] = None, camera_mode: str = 'trackball', manipulate_mode: str = 'translate', snapshot_type: str = 'full', render_on_change: bool = True, auto_rendering: bool | None = None, camera_no_zoom: bool = False, camera_no_rotate: bool = False, camera_no_pan: bool = False, camera_rotate_speed: float = 1.0, camera_zoom_speed: float = 1.2, camera_pan_speed: float = 0.3, camera_damping_factor: float = 0.0, camera_up_axis: str = 'none', fps: float = 25.0, minimum_fps: float = -1, fps_meter: bool = False, name: str | None = None, time_speed: float = 1.0, time_interpolation: bool = True, additional_js_code: str = '', custom_data: Dict[str, Any] | None = None, mode: str = 'view', rendering_steps: int = 1, colorbar_scientific: bool = False, camera: List | ndarray | Tuple | None = None, camera_animation: Dict[float, List | ndarray | Tuple] | List | ndarray | Tuple | None = None, clipping_planes: List | ndarray | Tuple | None = None, hidden_object_ids: List[int] | None = None, slice_viewer_object_id: int = -1, slice_viewer_direction: str = 'z', slice_viewer_mask_object_ids: List[int] | None = None) → Plot[source]#

Create a Plot widget, the canvas every drawable is added to.

Parameters:

  • height (int, optional) – Height of the Widget in pixels, changes have no effect after displaying. Default is 512.

  • antialias (int, optional) – Enable antialiasing in WebGL renderer, changes have no effect after displaying. Default is 3.

  • logarithmic_depth_buffer (bool, optional) – Enables logarithmic_depth_buffer in WebGL renderer. Default is True.

  • background_color (int, optional) – Packed RGB color of the plot background (0xff0000 is red, 0xff is blue), -1 is for transparent. Default is 16777215.

  • camera_auto_fit (bool, optional) – Enable automatic camera setting after adding, removing or changing a plot object. Default is True.

  • grid_auto_fit (bool, optional) – Enable automatic adjustment of the plot grid to contained objects. Default is True.

  • grid_visible (bool, optional) – Enable or disable grid. Default is True.

  • screenshot_scale (float, optional) – Multiplier to screenshot resolution. A screenshot is the plot’s own width and height times this, whatever resolution the interactive view happens to be drawing at. Default is 2.0.

  • grid (array_like, optional) – 6-element tuple specifying the bounds of the plot grid (x0, y0, z0, x1, y1, z1). Default is (-1, -1, -1, 1, 1, 1).

  • grid_color (int, optional) – Packed RGB color of the plot grids (0xff0000 is red, 0xff is blue). Default is 15132390.

  • label_color (int, optional) – Packed RGB color of the labels (0xff0000 is red, 0xff is blue). Default is 4473924.

  • lighting (float, optional) – Lighting factor - the exposure knob. In the advanced renderer the environment carries the shape of the light, lighting scales its energy. Default is 1.5.

  • menu_visibility (Bool, optional) – Whether the panel in the top right corner is shown. Default is True.

  • voxel_paint_color (int, optional) – The (initial) integer value to be inserted when editing voxels. Default is 0.

  • colorbar_object_id (int, optional) – Id of the object whose color map the colorbar shows. -1 picks the first object that has a color range. Default is -1.

  • camera_fov (float, optional) – Camera Field of View. Default is 60.0.

  • time (float, optional) – Time value (used in TimeSeries) Default is 0.0.

  • depth_peels (int, optional) – Set the maximum number of peels to use. Disabled if zero. With peeling on, volumes compose correctly with intersecting meshes (the ray march is split at the layer depths); use depth_peels >= 3, below that the effect is unpredictable. Default is 0.

  • renderer (str, optional) – Rendering pipeline of the plot. Legal values are: ‘simple’ the classic rasteriser with a fixed light rig (default), ‘advanced’ image-based lighting from the environment map, physically based materials and ambient occlusion, ‘cinematic’ progressive path tracing with global illumination. Requires WebGL2 with renderable float textures; when the browser cannot run it, the switch fails with an error instead of falling back to another renderer. Default is ‘simple’.

  • environment (str or array_like, optional) – The light environment of the advanced renderer. Legal values are: ‘neutral’ procedural achromatic gradient with a soft key light (default), ‘studio’ procedural gradient with two soft studio lights, ‘outdoor’ procedural sky with a sun disc and ground, ‘name from k3d.environments.available()’ a photographic HDRI shipped with the package (Poly Haven, CC0), ‘array_like’ a custom (height, width, 3) float32 equirectangular radiance map. Every map is energy-normalised. Default is ‘neutral’.

  • environment_rotation (float, optional) – Rotation of the environment map around the scene’s up axis, in radians. Default is 0.0.

  • tone_mapping (str, optional) – Tone curve applied by the advanced renderer. Legal values are: ‘none’ linear output (default), ‘agx’ AgX filmic curve, ‘aces’ ACES filmic curve. Default is ‘none’.

  • ao_radius (float, optional) – Occlusion radius of the advanced renderer’s ambient occlusion, as a fraction of the scene’s bounding-box diagonal, in (0, 1]. Default 0.07. Dense point clouds and closed interiors usually want a smaller radius. Default is 0.07.

  • ao_strength (float, optional) – Exponent deepening the ambient occlusion shadows, in [0, 10]. 0 disables the darkening, default 1.8. Default is 1.8.

  • cinematic_samples (int, optional) – Sample budget of the cinematic renderer, in [1, 100000]. Default 64, which settles in a moment; raise it for a final render. The interactive view accumulates one sample per animation frame up to this budget, then parks itself; any change to the camera, the scene or the lighting restarts the accumulation from zero. Screenshots always render the full budget. Default is 64.

  • cinematic_bounces (int, optional) – Light bounce count of the cinematic renderer’s path tracing, in [1, 32]. Default 6. Default is 6.

  • cinematic_glossy_filter (float, optional) – How much the cinematic renderer widens a glossy lobe in proportion to the roughness already gathered along a path, in [0, 1]. Default 0.25. It removes fireflies where they live and leaves a specular seen directly untouched; 0 disables it. Default is 0.25.

  • cinematic_seed (int or None, optional) – Seed of the path tracer’s sample sequence, an int in the range [1, 2**31 - 1]. With None every accumulation starts from fresh noise; with a seed the same scene renders the same image every time. 0 is refused, so that “unset” and “seeded” never blur. Default is None.

  • cinematic_denoise (float, optional) – How much of the denoised image the cinematic renderer shows. Default 0 is off, and the only value that leaves the image exactly as it was traced; 1 shows the image Open Image Denoise makes of it. Between the two they are mixed, which is not a strength: OIDN has none, and a mix keeps that share of the grain along with the texture the network smooths - worth it from about 0.7 up. Above 1 is the same as 1. The denoiser runs once the accumulation reaches cinematic_samples - while it accumulates the trace is shown as it is - and needs WebGPU: without it the image is shown undenoised and the console says why. On surfaces it is guided by their albedo and normals; inside a volume by the colour alone. Measured on a CT heart against 2048 samples, 16 samples denoised are as close as 64 filtered by the earlier denoiser and closer than 128 untouched, with no structure added beyond what two 2048-sample renders differ by - but at low budgets it smooths texture one or two pixels across. Default is 0.0.

  • cinematic_bokeh_size (float, optional) – Diameter of the cinematic renderer’s aperture, in scene units. Default 0, a pinhole - everything in focus, and the only value that leaves the image identical to the other renderers. Anything above it defocuses whatever is not at the focus distance, and costs a shader recompile the first time it leaves zero. Default is 0.0.

  • cinematic_focus_distance (float, optional) – How far in front of the camera the cinematic renderer focuses, in scene units. Default 0 means the camera’s own target, so the plot is sharp where you are looking. Ignored while cinematic_bokeh_size is 0. Default is 0.0.

  • cinematic_aperture_blades (int, optional) – How many blades the cinematic renderer’s iris has: 0, the default, is a perfect circle, and 3 to 16 give an aperture of that many sides, which is what makes an out-of-focus highlight read as hexagonal rather than round. Ignored while cinematic_bokeh_size is 0. Default is 0.

  • axes (list, optional) – Axes labels for plot. Default is None.

  • axes_helper (float, optional) – Axes helper size. Default is 1.0.

  • axes_helper_colors (List, optional) – List of triple packed RGB color of the axes helper (0xff0000 is red, 0xff is blue). Default is None.

  • camera_mode (str, optional) – Mode of camera movement. Legal values are: ‘trackball’ orbit around point with dynamic up- vector of camera, ‘orbit’ orbit around point with fixed up-vector of camera, ‘fly’ orbit around point with dynamic up-vector of camera, mouse wheel also moves target point. Default is ‘trackball’.

  • manipulate_mode (str, optional) – Mode of manipulate widgets. Legal values are: ‘translate’ Translation widget, ‘rotate’ Rotation widget, ‘scale’ Scaling widget. Default is ‘translate’.

  • snapshot_type (string, optional) – Can be ‘full’, ‘online’ or ‘inline’. Default is ‘full’.

  • render_on_change (Bool, optional) – Whether adding or updating an object draws a frame on its own. With it off, call plot.render() yourself. It has never controlled a render loop - K3D draws only when something changed. Named auto_rendering before 3.0.0. Default is True.

  • auto_rendering (bool, optional) – Renamed to render_on_change in 3.0.0; passing it warns and sets that instead. Default is None.

  • camera_no_zoom (Bool, optional) – Lock for camera zoom. Default is False.

  • camera_no_rotate (Bool, optional) – Lock for camera rotation. Default is False.

  • camera_no_pan (Bool, optional) – Lock for camera pan. Default is False.

  • camera_rotate_speed (float, optional) – Speed of camera rotation. Default is 1.0.

  • camera_zoom_speed (float, optional) – Speed of camera zoom. Default is 1.2.

  • camera_pan_speed (float, optional) – Speed of camera pan. Default is 0.3.

  • camera_damping_factor (float, optional) – Defines the intensity of damping. Default is 0 (disabled). Default is 0.0.

  • camera_up_axis (str, optional) – Fixed up axis for camera. Legal values are: ‘x’ x axis, ‘y’ y axis, ‘z’ z axis, ‘none’ Handling click_callback and hover_callback on some type of objects. Default is ‘none’.

  • fps (float, optional) – Fps of animation. Default is 25.0.

  • minimum_fps (float, optional) – If negative then disabled. Set target FPS to adaptative resolution. Default is -1.

  • fps_meter (Bool, optional) – Whether to show the frames-per-second counter. It measures animation frames, not draws: an idle plot draws nothing and the meter still ticks. Default is False.

  • name (str, optional) – A name of the object. Default is None.

  • time_speed (float, optional) – Time speed (used in TimeSeries) Default is 1.0.

  • time_interpolation (Bool, optional) – Whether a time series blends between the two nearest keyframes. With it off, playback steps from frame to frame. Default is True.

  • additional_js_code (str, optional) – Additional Js code that will be run after plot is initialized Default is ‘’.

  • custom_data (dict, optional) – An object with custom data attached to object. Default is None.

  • mode (str, optional) – Mode of the plot. Legal values are: ‘view’ plain viewing, ‘add’ clicking adds a voxel, ‘change’ clicking changes a voxel, ‘callback’ clicking or hovering calls the object’s click_callback or hover_callback, ‘manipulate’ objects carry a transform gizmo. Default is ‘view’.

  • rendering_steps (int, optional) – Number of steps a single render is split into, which keeps the browser responsive on heavy scenes. Default is 1.

  • colorbar_scientific (bool, optional) – Format the color bar ticks in scientific notation. Default is False.

  • camera (array_like, optional) – Camera as [position_x, position_y, position_z, target_x, target_y, target_z, up_x, up_y, up_z]. An empty list leaves the camera to camera_auto_fit. Default is [].

  • camera_animation (dict or array_like, optional) – A dictionary of time -> camera keyframes, played back by the plot’s time. Default is [].

  • clipping_planes (array_like, optional) – List of clipping planes, each [A, B, C, D] of Ax + By + Cz + D = 0. Default is [].

  • hidden_object_ids (list, optional) – Ids of objects hidden without changing their visible trait. Default is [].

  • slice_viewer_object_id (int, optional) – Id of the object shown in the slice viewer, -1 for none. Default is -1.

  • slice_viewer_direction (str, optional) – Slicing direction of the slice viewer. Legal values are: ‘x’, ‘y’, ‘z’. Default is ‘z’.

  • slice_viewer_mask_object_ids (list, optional) – Ids of the objects the slice viewer draws as a mask over the slice. Default is [].

Returns:

The created Plot object.

Return type:

Plot

Parameters#

The factory forwards everything it is given to the Plot widget, whose traits are the parameters:

class k3d.plot.Plot(*args: t.Any, **kwargs: t.Any)[source]#

Main K3D widget.

antialias#

int: Enable antialiasing in WebGL renderer, changes have no effect after displaying.

logarithmic_depth_buffer#

bool. Enables logarithmic_depth_buffer in WebGL renderer.

height#

int: Height of the Widget in pixels, changes have no effect after displaying.

background_color#

int. Packed RGB color of the plot background (0xff0000 is red, 0xff is blue), -1 is for transparent.

camera_auto_fit#

bool. Enable automatic camera setting after adding, removing or changing a plot object.

grid_auto_fit#

bool. Enable automatic adjustment of the plot grid to contained objects.

grid_color#

int. Packed RGB color of the plot grids (0xff0000 is red, 0xff is blue).

grid_visible#

bool. Enable or disable grid.

screenshot_scale#

Float. Multiplier to screenshot resolution. A screenshot is the plot’s own width and height times this, whatever resolution the interactive view happens to be drawing at.

voxel_paint_color#

int. The (initial) integer value to be inserted when editing voxels.

label_color#

int. Packed RGB color of the labels (0xff0000 is red, 0xff is blue).

lighting#

Float. Lighting factor - the exposure knob. In the advanced renderer the environment carries the shape of the light, lighting scales its energy.

renderer#

str. Rendering pipeline of the plot.

Legal values are:

Simple:

the classic rasteriser with a fixed light rig (default),

Advanced:

image-based lighting from the environment map, physically based materials and ambient occlusion,

Cinematic:

progressive path tracing with global illumination. Requires WebGL2 with renderable float textures; when the browser cannot run it, the switch fails with an error instead of falling back to another renderer.

environment#

str or array_like. The light environment of the advanced renderer.

Legal values are:

Neutral:

procedural achromatic gradient with a soft key light (default),

Studio:

procedural gradient with two soft studio lights,

Outdoor:

procedural sky with a sun disc and ground,

Name from k3d.environments.available():

a photographic HDRI shipped with the package (Poly Haven, CC0),

Array_like:

a custom (height, width, 3) float32 equirectangular radiance map. Every map is energy-normalised.

environment_rotation#

float. Rotation of the environment map around the scene’s up axis, in radians.

tone_mapping#

str. Tone curve applied by the advanced renderer.

Legal values are:

None:

linear output (default),

Agx:

AgX filmic curve,

Aces:

ACES filmic curve.

ao_radius#

float. Occlusion radius of the advanced renderer’s ambient occlusion, as a fraction of the scene’s bounding-box diagonal, in (0, 1]. Default 0.07. Dense point clouds and closed interiors usually want a smaller radius.

ao_strength#

float. Exponent deepening the ambient occlusion shadows, in [0, 10]. 0 disables the darkening, default 1.8.

cinematic_samples#

int. Sample budget of the cinematic renderer, in [1, 100000]. Default 64, which settles in a moment; raise it for a final render. The interactive view accumulates one sample per animation frame up to this budget, then parks itself; any change to the camera, the scene or the lighting restarts the accumulation from zero. Screenshots always render the full budget.

cinematic_bounces#

int. Light bounce count of the cinematic renderer’s path tracing, in [1, 32]. Default 6.

grid#

array_like. 6-element tuple specifying the bounds of the plot grid (x0, y0, z0, x1, y1, z1).

camera#

array_like. 9-element list or array specifying camera position.

camera_no_rotate#

Bool. Lock for camera rotation.

camera_no_zoom#

Bool. Lock for camera zoom.

camera_no_pan#

Bool. Lock for camera pan.

camera_rotate_speed#

Float. Speed of camera rotation.

camera_zoom_speed#

Float. Speed of camera zoom.

camera_pan_speed#

Float. Speed of camera pan.

camera_fov#

Float. Camera Field of View.

camera_damping_factor#

Float. Defines the intensity of damping. Default is 0 (disabled).

camera_up_axis#

str. Fixed up axis for camera.

Legal values are:

X:

x axis,

Y:

y axis,

Z:

z axis,

None:

no fixed up axis - the camera is free to roll.

snapshot_type#

string. Can be ‘full’, ‘online’ or ‘inline’.

axes#

list. Axes labels for plot.

axes_helper#

Float. Axes helper size.

axes_helper_colors#

List. List of triple packed RGB color of the axes helper (0xff0000 is red, 0xff is blue).

time#

float. Time value (used in TimeSeries)

time_speed#

float. Time speed (used in TimeSeries)

name#

string. Name of the plot. Used to filenames of snapshot/screenshot etc.

mode#

str. Mode of K3D viewer.

Legal values are:

View:

No interaction with objects,

Add:

On voxels objects adding mode,

Change:

On voxels objects edit mode,

Callback:

Handling click_callback and hover_callback on some type of objects,

Manipulate:

Enable object transform widget.

camera_mode#

str. Mode of camera movement.

Legal values are:

Trackball:

orbit around point with dynamic up-vector of camera,

Orbit:

orbit around point with fixed up-vector of camera,

Fly:

orbit around point with dynamic up-vector of camera, mouse wheel also moves target point.

manipulate_mode#

str. Mode of manipulate widgets.

Legal values are:

Translate:

Translation widget,

Rotate:

Rotation widget,

Scale:

Scaling widget.

depth_peels#

int. Set the maximum number of peels to use. Disabled if zero. With peeling on, volumes compose correctly with intersecting meshes (the ray march is split at the layer depths); use depth_peels >= 3, below that the effect is unpredictable.

cinematic_glossy_filter#

Float. How much the cinematic renderer widens a glossy lobe in proportion to the roughness already gathered along a path, in [0, 1]. Default 0.25. It removes fireflies where they live and leaves a specular seen directly untouched; 0 disables it.

cinematic_seed#

int or None. Seed of the path tracer’s sample sequence, an int in the range [1, 2**31 - 1]. With None every accumulation starts from fresh noise; with a seed the same scene renders the same image every time. 0 is refused, so that “unset” and “seeded” never blur.

cinematic_denoise#

Float. How much of the denoised image the cinematic renderer shows. Default 0 is off, and the only value that leaves the image exactly as it was traced; 1 shows the image Open Image Denoise makes of it. Between the two they are mixed, which is not a strength: OIDN has none, and a mix keeps that share of the grain along with the texture the network smooths - worth it from about 0.7 up. Above 1 is the same as 1. The denoiser runs once the accumulation reaches cinematic_samples - while it accumulates the trace is shown as it is - and needs WebGPU: without it the image is shown undenoised and the console says why. On surfaces it is guided by their albedo and normals; inside a volume by the colour alone. Measured on a CT heart against 2048 samples, 16 samples denoised are as close as 64 filtered by the earlier denoiser and closer than 128 untouched, with no structure added beyond what two 2048-sample renders differ by - but at low budgets it smooths texture one or two pixels across.

cinematic_bokeh_size#

Float. Diameter of the cinematic renderer’s aperture, in scene units. Default 0, a pinhole - everything in focus, and the only value that leaves the image identical to the other renderers. Anything above it defocuses whatever is not at the focus distance, and costs a shader recompile the first time it leaves zero.

cinematic_focus_distance#

Float. How far in front of the camera the cinematic renderer focuses, in scene units. Default 0 means the camera’s own target, so the plot is sharp where you are looking. Ignored while cinematic_bokeh_size is 0.

cinematic_aperture_blades#

Int. How many blades the cinematic renderer’s iris has: 0, the default, is a perfect circle, and 3 to 16 give an aperture of that many sides, which is what makes an out-of-focus highlight read as hexagonal rather than round. Ignored while cinematic_bokeh_size is 0.

menu_visibility#

Bool. Whether the panel in the top right corner is shown.

colorbar_object_id#

int. Id of the object whose color map the colorbar shows. -1 picks the first object that has a color range.

fps_meter#

Bool. Whether to show the frames-per-second counter. It measures animation frames, not draws: an idle plot draws nothing and the meter still ticks.

time_interpolation#

Bool. Whether a time series blends between the two nearest keyframes. With it off, playback steps from frame to frame.

custom_data#

dict. Anything you want to travel with the plot. K3D neither reads nor validates it.

render_on_change#

Bool. Whether adding or updating an object draws a frame on its own. With it off, call plot.render() yourself. It has never controlled a render loop - K3D draws only when something changed. Named auto_rendering before 3.0.0.

fps#

Float. Fps of animation.

minimum_fps#

Float. If negative then disabled. Set target FPS to adaptative resolution.

objects#

list. List of k3d.objects.Drawable currently included in the plot, not to be changed directly.

Type:

List[k3d.objects.base.Drawable]

additional_js_code#

str. Additional Js code that will be run after plot is initialized

Examples#

Coloring#

import k3d

plot = k3d.plot(background_color=0x1e1e1e,
                grid_color=0xd2d2d2,
                label_color=0xf0f0f0)

plot.display()

Axes and bounds#

import k3d

plot = k3d.plot(grid=(0, 0, 0, 60, 20, 50),
                axes=['Time', 'Mass', 'Temperature'])

plot.display()

Static#

import k3d

plot = k3d.plot(camera_no_pan=True,
                camera_no_rotate=True,
                camera_no_zoom=True,
                menu_visibility=False)

plot.display()