pyglet.model

Loading of 3D scenes and models.

The model module provides an interface for loading 3D “scenes” and models. 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.

The following example loads a "teapot.obj" file. The wavefront format only contains a single model (mesh):

import pyglet

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

scene = pyglet.model.load('teapot.obj')
models = scene.create_models(batch=batch)

@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: GLShaderProgram,
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
matrix: Mat4 = (1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0)
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: GLShaderProgram,
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\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    uniform mat4 model;\n\n    void main()\n    {\n        mat4 mv = window.view * model;\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

Instance of a 3D object.

See the module documentation for usage.

__init__(
vertex_lists: list[VertexList],
groups: list[Group],
batch: GLBatch | None = None,
) → None

Create a model instance.

Parameters:

  • vertex_lists (list[VertexList]) – A list of VertexList or IndexedVertexList.

  • groups (list[Group]) –

    A list of TexturedMaterialGroup, or

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

  • batch (GLBatch | None) – The batch to add the model to. If no batch is provided, the model will maintain its own internal batch.

property batch: GLBatch

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.

property matrix: Mat4
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: GLShaderProgram,
texture: GLTexture,
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\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    uniform mat4 model;\n\n    void main()\n    {\n        mat4 mv = window.view * model;\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() → GLShaderProgram
Return type:

GLShaderProgram

get_default_textured_shader() → GLShaderProgram
Return type:

GLShaderProgram

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