glb#

Read a binary glTF (.glb) scene as K3D objects.

Every primitive of every mesh in the scene becomes its own k3d.mesh() - or k3d.points() / k3d.lines() for point and line primitives - with the node’s name, and all of them share group, so the panel shows the model as one folder of parts. They come back together as a k3d.objects.Group: plot += k3d.glb('model.glb') adds the whole model.

Materials map onto mesh parameters: base colour (color, opacity, texture), metallic-roughness, normal, occlusion and emissive maps, alpha_mode and alpha_cutoff, transmission, index of refraction and volume, double-sidedness and the texture wrapping; texture transforms are baked into the uvs. Factors and vertex colours, which glTF stores as linear values, are converted to the display values K3D colours are. Node transforms are kept as a hierarchy of k3d.transform.Transform: each object’s model_matrix is its node’s, and the group’s model_matrix (or transform) moves the whole model.

Draco-compressed geometry is read when DracoPy is installed (pip install DracoPy). Not shown, with one warning naming what was left out: animations, skins (the vertices are shown as stored), cameras and lights, KTX2 textures, and the other material extensions - clearcoat, sheen, dispersion and the like. Meshopt compression is refused. Morph targets are applied with their default weights.

Added in version 3.2.0.

Parameters:

source (str, os.PathLike, bytes or file-like) – Path of a .glb file, or its bytes - a .glb is self-contained, so bytes from anywhere do, e.g. plot.fetch_gltf() output.
scene (int or str, optional) – Index or name of the scene to read, by default the file’s default scene.
up ({'y', 'z'}, optional) – The axis pointing up in the file. glTF is ‘y’ up and K3D ‘z’ up, so by default the model is turned upright; ‘z’ keeps the coordinates as they are - K3D’s own exports are z up.
group (str, optional) – Group of every object in the panel, by default the file name without extension.
compression_level (int, optional) – Level of data compression [-1, 9] of every object, by default 0.
visible (bool, optional) – Whether the objects are drawn, by default True.
**kwargs – translation, rotation, scaling, model_matrix, or transform - placing the whole model, see process_transform_arguments.

Returns:

The objects of the scene.

Return type:

Group

Examples#

A model from a file#

Every part of the truck - body, wheels, glass - is its own object in the panel, in one folder named after the file. up is left at ‘y’, glTF’s own convention, so the model stands upright in K3D’s z-up scene.

# Model: Cesium Milk Truck, (c) 2017 Cesium, CC-BY 4.0,
# https://github.com/KhronosGroup/glTF-Sample-Assets/tree/main/Models/CesiumMilkTruck

import k3d
from k3d.helpers import download

filename = download('https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/'
                    'main/Models/CesiumMilkTruck/glTF-Binary/CesiumMilkTruck.glb')

truck = k3d.glb(filename)

plot = k3d.plot(renderer='advanced')
plot += truck
plot.display()

The parts are ordinary objects#

What comes back is a k3d.objects.Group of plain mesh objects (and points / lines for point and line primitives), so each part is changed like any other K3D object. The group itself has no properties - it only holds them - with one exception: its model_matrix moves the whole model, node hierarchy and all.

for part in truck:
    print(part.name, part.vertices.shape)

truck['Cesium_Milk_Truck/glass'].opacity = 0.3   # a part, by name

truck.model_matrix = k3d.transform(translation=[0, 0, 2]).model_matrix

Materials from the file#

Everything a glTF material carries becomes an ordinary mesh parameter: the colour texture, the normal_map that gives the speaker grille its holes, the metalness_roughness_map that makes the trim chrome and the body plastic, the occlusion_map darkening the creases, and the emissive_map that lights the PLAY button. Each of them can be read, replaced or switched off after reading like any other parameter.

The model is two centimetres wide, so scaling makes it a hundred times larger - the transform arguments of every K3D factory place the whole model. The textures are halved here only because this page carries every one of them inline; read from the file they are used at full size.

# Model: BoomBox, Microsoft, CC0,
# https://github.com/KhronosGroup/glTF-Sample-Assets/tree/main/Models/BoomBox

import k3d
from k3d.helpers import download

filename = download('https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/'
                    'main/Models/BoomBox/glTF-Binary/BoomBox.glb')

boombox = k3d.glb(filename, scaling=[100, 100, 100])

part = boombox[0]
print(part.alpha_mode, hex(part.emissive), len(part.normal_map))

plot = k3d.plot(renderer='advanced', environment='studio', tone_mapping='aces',
                grid_visible=False, background_color=0x1E2126)
plot += boombox
plot.display()

Bytes instead of a file#

A .glb holds everything it needs, so its bytes are enough - from the network, from a database, or from K3D’s own export, which is z-up already:

blob = plot.fetch_gltf()            # what this plot exports
copy = k3d.glb(blob, up='z')