pyglet.model

Loading of 3D scenes and models.

The model module provides an interface for loading 3D “scenes”. A Scene is a logical container that can contain the data of one or more models, and is closely based on the design of the glTF format.

After loading a Scene, it is uploaded to the GPU (VertexLists created). From there, you can make an instance (or many instances) of the model. Instancing is used internally, with each instance able to be positioned independently.

The following example loads a "teapot.obj" file. The wavefront format only contains a single model in the scene:

import pyglet

window = pyglet.window.Window()
batch = pyglet.graphics.Batch()

# Load and parse the Scene (CPU operation):
scene = pyglet.model.load('teapot.obj')
# Generate Models from the scene (upload to GPU):
models = scene.create_models(batch=batch)
# Create visable Instances of each model (only one in this case):
instances = []
for model in models:
    instance = model.create_instance(translation=Vec3(2.0, 0.0, 5.0))
    instances.append(instance)

@window.event
def on_draw():
    batch.draw()

pyglet.app.run()

You can also load scenes with scene(). See resource for more information.

class BaseMaterialGroup
__init__(
material: SimpleMaterial,
program: ShaderProgram,
order: int = 0,
parent: Group | None = None,
) → None

Initialize a rendering group.

Parameters:

  • order (int) – Set the order to render above or below other Groups. Lower orders are drawn first.

  • parent (Group | None) – Group to contain this Group; its state will be set before this Group’s state.

default_frag_src: str
default_vert_src: str
class Capsule
__init__(
radius=1.0,
height=2.0,
sectors=30,
stacks=16,
color=(1.0, 1.0, 1.0, 1.0),
material=None,
batch=None,
group=None,
program=None,
)

Create a model instance.

Parameters:

  • vertex_lists – A list of VertexList or IndexedVertexList.

  • groups –

    A list of TexturedMaterialGroup, or

    MaterialGroup. Each group corresponds to a vertex list in vertex_lists at the same index.

  • batch – The batch to add the model to. If no batch is provided, the model will maintain its own internal batch.

class Cube
__init__(
width=1.0,
height=1.0,
depth=1.0,
color=(1.0, 1.0, 1.0, 1.0),
material=None,
batch=None,
group=None,
program=None,
)

Create a model instance.

Parameters:

  • vertex_lists – A list of VertexList or IndexedVertexList.

  • groups –

    A list of TexturedMaterialGroup, or

    MaterialGroup. Each group corresponds to a vertex list in vertex_lists at the same index.

  • batch – The batch to add the model to. If no batch is provided, the model will maintain its own internal batch.

class MaterialGroup
__init__(
material: SimpleMaterial,
program: ShaderProgram,
order: int = 0,
parent: Group | None = None,
)

Initialize a rendering group.

Parameters:

  • order (int) – Set the order to render above or below other Groups. Lower orders are drawn first.

  • parent (Group | None) – Group to contain this Group; its state will be set before this Group’s state.

default_frag_src: str = '#version 330 core\n    in vec4 color_0;\n    in vec3 normal;\n    in vec3 position;\n    out vec4 final_colors;\n\n    void main()\n    {\n        float l = dot(normalize(-position), normalize(normal));\n        // 75/25 light ambient\n        final_colors = color_0 * l * 0.75 + color_0 * vec4(0.25);\n    }\n    '
default_vert_src: str = '#version 330 core\n    in vec3 POSITION;\n    in vec3 NORMAL;\n    in vec4 COLOR_0;\n    in vec3 TRANSLATION;\n    in vec4 ROTATION;\n    in vec3 SCALE;\n\n    out vec4 color_0;\n    out vec3 normal;\n    out vec3 position;\n\n    uniform WindowBlock\n    {\n        mat4 projection;\n        mat4 view;\n    } window;\n\n    mat4 quat_to_mat4(vec4 q)\n    {\n        // q is in pyglet order: (w, x, y, z)\n        float w = q.x;\n        float x = q.y;\n        float y = q.z;\n        float z = q.w;\n    \n        float x2 = x + x;\n        float y2 = y + y;\n        float z2 = z + z;\n    \n        float xx = x * x2;\n        float xy = x * y2;\n        float xz = x * z2;\n        float yy = y * y2;\n        float yz = y * z2;\n        float zz = z * z2;\n        float wx = w * x2;\n        float wy = w * y2;\n        float wz = w * z2;\n    \n        return mat4(\n            1.0 - (yy + zz),  xy + wz,         xz - wy,         0.0,\n            xy - wz,          1.0 - (xx + zz), yz + wx,         0.0,\n            xz + wy,          yz - wx,         1.0 - (xx + yy), 0.0,\n            0.0,              0.0,             0.0,             1.0\n        );\n    }\n\n\n    void main()\n    {\n        mat4 m_translation = mat4(1.0);\n        m_translation[3][0] = TRANSLATION.x;\n        m_translation[3][1] = TRANSLATION.y;\n        m_translation[3][2] = TRANSLATION.z;\n\n        mat4 m_rotation = quat_to_mat4(ROTATION);\n\n        mat4 m_scale = mat4(1.0);\n        m_scale[0][0] = SCALE.x;\n        m_scale[1][1] = SCALE.y;\n        m_scale[2][2] = SCALE.z;\n        \n        mat4 mv = window.view * m_translation * m_rotation * m_scale;\n        vec4 pos = mv * vec4(POSITION, 1.0);\n        gl_Position = window.projection * pos;\n        mat3 normal_matrix = transpose(inverse(mat3(mv)));\n\n        position = pos.xyz;\n        color_0 = COLOR_0;\n        normal = normal_matrix * NORMAL;\n    }\n    '
class Model

Base instance of a 3D object.

See the module documentation for usage.

__init__(
vertex_lists: list[InstanceVertexList | InstanceIndexedVertexList],
groups: list[Group],
batch: Batch | None = None,
) → None

Create a model instance.

Parameters:
create_instance(
translation: Vec3 = (0.0, 0.0, 0.0),
rotation: Quaternion = (1.0, 0.0, 0.0, 0.0),
scale: Vec3 = (1.0, 1.0, 1.0),
)
property batch: Batch

The graphics Batch that the Model belongs to.

The Model can be migrated from one batch to another, or removed from a batch (for individual drawing). If not part of any batch, the Model will keep its own internal batch. Note that batch migration can be an expensive operation.

class ModelInstance
__init__(*vertex_instances: VertexInstance)
property rotation
property scale
property translation
class Sphere
__init__(
radius=1.0,
stacks=30,
sectors=30,
color=(1.0, 1.0, 1.0, 1.0),
material=None,
batch=None,
group=None,
program=None,
)

Create a model instance.

Parameters:

  • vertex_lists – A list of VertexList or IndexedVertexList.

  • groups –

    A list of TexturedMaterialGroup, or

    MaterialGroup. Each group corresponds to a vertex list in vertex_lists at the same index.

  • batch – The batch to add the model to. If no batch is provided, the model will maintain its own internal batch.

class TexturedMaterialGroup
__init__(
material: SimpleMaterial,
program: ShaderProgram,
texture: Texture,
order: int = 0,
parent: Group | None = None,
)

Initialize a rendering group.

Parameters:

  • order (int) – Set the order to render above or below other Groups. Lower orders are drawn first.

  • parent (Group | None) – Group to contain this Group; its state will be set before this Group’s state.

default_frag_src: str = '#version 330 core\n    in vec4 color_0;\n    in vec3 normal;\n    in vec2 texcoord_0;\n    in vec3 position;\n    out vec4 final_colors;\n\n    uniform sampler2D our_texture;\n\n    void main()\n    {\n        float l = dot(normalize(-position), normalize(normal));\n        vec4 tex_color = texture(our_texture, texcoord_0) * color_0;\n        // 75/25 light ambient\n        final_colors = tex_color * l * 0.75 + tex_color * vec4(0.25);\n    }\n    '
default_vert_src: str = '#version 330 core\n    in vec3 POSITION;\n    in vec3 NORMAL;\n    in vec2 TEXCOORD_0;\n    in vec4 COLOR_0;\n    in vec3 TRANSLATION;\n    in vec4 ROTATION;\n    in vec3 SCALE;\n\n    out vec3 position;\n    out vec3 normal;\n    out vec2 texcoord_0;\n    out vec4 color_0;    \n\n    uniform WindowBlock\n    {\n        mat4 projection;\n        mat4 view;\n    } window;\n\n    mat4 quat_to_mat4(vec4 q)\n    {\n        // q is in pyglet order: (w, x, y, z)\n        float w = q.x;\n        float x = q.y;\n        float y = q.z;\n        float z = q.w;\n    \n        float x2 = x + x;\n        float y2 = y + y;\n        float z2 = z + z;\n    \n        float xx = x * x2;\n        float xy = x * y2;\n        float xz = x * z2;\n        float yy = y * y2;\n        float yz = y * z2;\n        float zz = z * z2;\n        float wx = w * x2;\n        float wy = w * y2;\n        float wz = w * z2;\n    \n        return mat4(\n            1.0 - (yy + zz),  xy + wz,         xz - wy,         0.0,\n            xy - wz,          1.0 - (xx + zz), yz + wx,         0.0,\n            xz + wy,          yz - wx,         1.0 - (xx + yy), 0.0,\n            0.0,              0.0,             0.0,             1.0\n        );\n    }\n\n    void main()\n    {\n        mat4 m_translation = mat4(1.0);\n        m_translation[3][0] = TRANSLATION.x;\n        m_translation[3][1] = TRANSLATION.y;\n        m_translation[3][2] = TRANSLATION.z;\n\n        mat4 m_rotation = quat_to_mat4(ROTATION);\n\n        mat4 m_scale = mat4(1.0);\n        m_scale[0][0] = SCALE.x;\n        m_scale[1][1] = SCALE.y;\n        m_scale[2][2] = SCALE.z;\n\n        mat4 mv = window.view * m_translation * m_rotation * m_scale;\n        vec4 pos = mv * vec4(POSITION, 1.0);\n        gl_Position = window.projection * pos;\n        mat3 normal_matrix = transpose(inverse(mat3(mv)));\n\n        position = pos.xyz;\n        normal = normal_matrix * NORMAL;\n        texcoord_0 = TEXCOORD_0;\n        color_0 = COLOR_0;\n    }\n    '
get_default_shader() → ShaderProgram
Return type:

ShaderProgram

get_default_textured_shader() → ShaderProgram
Return type:

ShaderProgram

load(
filename: str,
file: BinaryIO | TextIO | None = None,
decoder: ModelDecoder | None = None,
) → Scene

Load a 3D scene from a file.

Parameters:

  • filename (str) – Used to guess the scene format, or to load the file if file is unspecified.

  • file (BinaryIO | TextIO | None) – An open file containing the source of the scene data in any supported format.

  • decoder (ModelDecoder | None) – The specific decoder to use to load the Scene. If None, use default decoders that match the filename extension.

Return type:

Scene