mesh#

Create a Mesh drawable from 3D triangles.

Parameters:

vertices (array_like) – Array of triangle vertices, float (x, y, z) coordinate triplets.
indices (array_like) – Array of vertex indices. int triplets of indices from vertices array.
normals (array_like, optional) – Array of vertex normals: float (x, y, z) coordinate triples. Normals are used when flat_shading is false. If the normals are not specified here, normals will be automatically computed.
color (int, optional) –
Hex color of the mesh. It multiplies colors, the colormap and texture, the way a base colour does in other renderers. By default _default_color, or white when any of them is given.

Changed in version 3.2.0: color used to be ignored when colors, a colormap or a texture was given.
colors (array_like, optional) – Colors per vertex: packed hex ints, or an (N, 3) or (N, 4) array of RGB(A) - floats in 0..1 or integers in 0..255. The fourth column becomes opacities. By default [].
opacities (array_like, optional) – Alpha per vertex, multiplied into the colour; read when alpha_mode is ‘blend’ or ‘mask’, by default [].
attribute (list, optional) – List of values used to apply color_map, by default [].
color_map (list, optional) – List of float quadruplets (attribute value, R, G, B) sorted by attribute value, by default None. The first quadruplet should have value 0.0, the last 1.0; R, G, B are RGB color components in the range 0.0 to 1.0.
color_range (list, optional) – [min_value, max_value] pair determining the levels of color attribute mapped to 0 and 1 in the colormap, by default [].
wireframe (bool, optional) – Display the mesh as wireframe, by default False.
flat_shading (bool, optional) – Display the mesh with flat shading, by default True.
roughness (float.) – Roughness of object material.
metalness (float.) – Metalness of object material.
opacity (float, optional) – Opacity of the mesh, by default 1.0.
texture (bytes, optional) – Image data in a specific format, by default None.
texture_file_format (str, optional) – Format of the data, by default None - read from the data itself. It should be the second part of MIME format of type ‘image/’,e.g. ‘jpeg’, ‘png’, ‘gif’, ‘tiff’.
volume (list, optional) – 3D array of float, by default [].
volume_bounds (list, optional) – 6-element tuple specifying the bounds of the volume data (x0, x1, y0, y1, z0, z1), by default [].
opacity_function (list, optional) – float tuples (attribute value, opacity) sorted by attribute value, by default []. The first tuples should have value 0.0, the last 1.0; opacity is in the range 0.0 to 1.0.
side ({'front', 'back', 'double'}, optional) – Side to render, by default “front”.
uvs (array_like, optional) – float uvs for the texturing corresponding to each vertex, by default None.
uvs2 (array_like, optional) – A second set of uvs, read by occlusion_map alone; it falls back to uvs, by default None.
texture_wrap (str, optional) – What every texture of the mesh does outside 0..1: ‘clamp’, ‘repeat’ or ‘mirror’, or one for u and one for v, e.g. ‘repeat clamp’. By default ‘clamp’. The cinematic renderer repeats every texture.
emissive (int, optional) – Hex color the surface emits, unaffected by lighting, by default 0 (none).
emissive_intensity (float, optional) – Multiplier of emissive, by default 1.0.
emissive_map (bytes, optional) – Image (PNG, JPEG, WebP, GIF) multiplying emissive, by default None.
normal_map (bytes, optional) – Tangent-space normal map image, read with uvs, by default None.
normal_scale (float, optional) – Strength of normal_map, by default 1.0.
metalness_roughness_map (bytes, optional) – Image whose green channel multiplies roughness and blue channel metalness - the glTF layout, by default None.
occlusion_map (bytes, optional) – Image whose red channel darkens the indirect light, read with uvs2 when given, by default None.
occlusion_strength (float, optional) – How much of occlusion_map applies, 0 to 1, by default 1.0.
alpha_mode ({'opaque', 'blend', 'mask'}, optional) – How the alpha of texture and opacities is used: ignored (‘opaque’), blended with what is behind (‘blend’), or cut out below alpha_cutoff (‘mask’). opacity fades the mesh in every mode. By default ‘blend’ when opacities are given, ‘opaque’ otherwise.
alpha_cutoff (float, optional) – Threshold of the ‘mask’ mode, by default 0.5.
transmission (float, optional) – How much light passes through the surface, refracted - glass, water, gems - from 0 to 1, by default 0.
ior (float, optional) – Index of refraction of a transmissive mesh, by default 1.5.
thickness (float, optional) – Thickness of the volume behind a transmissive surface, by default 0 (a thin wall).
attenuation_color (int, optional) – Hex colour light takes on after attenuation_distance in the volume, by default white.
attenuation_distance (float, optional) – Distance after which light has the attenuation_color, by default 0 (no attenuation).
name (str, optional) – Object name, by default None.
group (str, optional) – Name of a group, by default None.
custom_data (dict) – A object with custom data attached to object.
compression_level (int, optional) – Level of data compression [-1, 9], by default 0.
triangles_attribute (list, optional) – Array of float attribute for the color mapping, one value per triangle rather than per vertex; used when attribute is empty, by default [].
slice_planes (list, optional) – Planes [a, b, c, d] the section outline is drawn along, up to eight of them. The outline is drawn in the object colour, without the colormap, by default [].
visible (bool, optional) – Whether the object is drawn. Default is True.
click_callback (callable, optional) – Called with the picking parameters when the object is clicked, while the plot is in mode=’callback’. Default is None.
hover_callback (callable, optional) – Called with the picking parameters when the cursor is over the object, while the plot is in mode=’callback’. Default is None.
**kwargs – For other keyword-only arguments, see process_transform_arguments.

Returns:

Mesh Drawable

Return type:

Mesh

Examples#

Basic#

import k3d

vertices = [[1, 1, 1], [1, -1, -1], [-1, 1, -1], [-1, -1, 1]]
indices = [[0, 1, 2], [0, 2, 3], [0, 3, 1], [3, 2, 1]]

plt_tetra = k3d.mesh(vertices, indices,
                     colors=[0x32ff31, 0x37d3ff, 0xbc53ff, 0xffc700])

plot = k3d.plot()
plot += plt_tetra
plot.display()

Colormap#

Attention

color_map must be used along with attribute and color_range in order to work correctly.

import k3d
import numpy as np
from k3d.colormaps import matplotlib_color_maps
from matplotlib.tri import Triangulation

n_radii = 8
n_angles = 36

radii = np.linspace(0.125, 1.0, n_radii, dtype=np.float32)
angles = np.linspace(0, 2 * np.pi, n_angles, endpoint=False, dtype=np.float32)[..., np.newaxis]

x = np.append(np.float32(0), (radii * np.cos(angles)).flatten())
y = np.append(np.float32(0), (radii * np.sin(angles)).flatten())
z = np.sin(-x * y)

vertices = np.vstack([x, y, z]).T
indices = Triangulation(x, y).triangles.astype(np.uint32)

plt_mesh = k3d.mesh(vertices, indices,
                    color_map=matplotlib_color_maps.Jet,
                    attribute=z,
                    color_range=[-1.1, 2.01])

plot = k3d.plot()
plot += plt_mesh
plot.display()

Materials#

Added in version 3.2.0.

Besides a colour texture a mesh takes a normal map, a metalness-roughness map, an occlusion map and an emissive colour with its own map - images given as their encoded bytes, read with uvs. alpha_mode decides what the alpha of the texture and of opacities does: nothing (‘opaque’), blending (‘blend’) or cutting out below alpha_cutoff (‘mask’). transmission with ior, thickness and the attenuation makes glass, water or gems, refracted for real by the Cinematic rendering renderer.

import io

import numpy as np
from PIL import Image

import k3d


def png(pixels):
    buffer = io.BytesIO()
    Image.fromarray(pixels.astype(np.uint8)).save(buffer, format='PNG')
    return buffer.getvalue()


vertices = np.array([[0, 0, 0], [1, 0, 0], [1, 0, 1], [0, 0, 1]], np.float32)
indices = np.array([[0, 1, 2], [0, 2, 3]], np.uint32)
uvs = np.array([[0, 1], [1, 1], [1, 0], [0, 0]], np.float32)

y, x = (np.mgrid[0:128, 0:128] + 0.5) / 32 % 1.0 - 0.5
r = np.hypot(x, y)

inside = r < 0.4
nx, ny = np.where(inside, x / 0.4, 0), np.where(inside, -y / 0.4, 0)
nz = np.sqrt(np.clip(1 - nx ** 2 - ny ** 2, 0, 1))
bumps = (np.stack([nx, ny, nz], -1) * 0.5 + 0.5) * 255

rings = np.where(np.abs(r - 0.3) < 0.06, 255, 0)[..., None] * np.array([1.0, 0.6, 0.2])
discs = np.dstack([np.full(r.shape, 60), np.full(r.shape, 140), np.full(r.shape, 230),
                   np.where(r < 0.35, 0, 255)])

plot = k3d.plot(renderer='advanced', grid_visible=False)

plot += k3d.mesh(vertices, indices, uvs=uvs, color=0xB0B8C0, metalness=0.6,
                 roughness=0.3, normal_map=png(bumps), flat_shading=False)
plot += k3d.mesh(vertices + [1.1, 0, 0], indices, uvs=uvs, color=0x202020,
                 emissive=0xFFFFFF, emissive_map=png(rings), emissive_intensity=1.5)
plot += k3d.mesh(vertices + [2.2, 0, 0], indices, uvs=uvs, texture=png(discs),
                 alpha_mode='mask', side='double')
plot.display()

Colours multiply#

Changed in version 3.2.0.

color multiplies colors, the colormap and the texture - the way a base colour does in other renderers - where it used to be ignored next to any of them. Left out, it is white when one of them is given, so a mesh coloured per vertex looks as it always did; given, it tints them.