0
# 3D Model Loading
1

2
Load and render 3D models in various formats.
3

4
## Quick Reference
5

6
```python
7
import pyglet
8
from pyglet import model
9

10
# Load model
11
scene = model.load('model.obj', batch=batch)
12

13
# Or specific file
14
model_obj = model.load('character.obj', file=open('character.obj', 'rb'))
15

16
# Render
17
@window.event
18
def on_draw():
19
    window.clear()
20
    scene.draw()
21
```
22

23
## Model Loading
24

25
```python
26
def pyglet.model.load(filename, file=None, decoder=None, batch=None) -> Scene:
27
    """
28
    Load 3D model or scene.
29

30
    Args:
31
        filename: Path to model file
32
        file: File-like object (optional)
33
        decoder: Specific decoder (optional)
34
        batch: Batch for rendering (optional)
35

36
    Returns:
37
        Scene: Loaded scene with models and nodes
38

39
    Supported formats: .obj, .gltf, .glb (with pyglet.model.codecs.gltf)
40
    """
41
```
42

43
## Scene
44

45
```python
46
class pyglet.model.Scene:
47
    """3D scene with models and scene graph"""
48

49
    # Properties
50
    models: list  # Model instances
51
    nodes: dict  # Scene graph nodes
52
    batch: Batch  # Rendering batch
53

54
    # Methods
55
    def draw()  # Render all models
56
```
57

58
## Model
59

60
```python
61
class pyglet.model.Model:
62
    """3D model instance"""
63

64
    # Properties
65
    vertex_lists: list  # Vertex data
66
    material: Material  # Material properties
67
    batch: Batch
68

69
    # Methods
70
    def draw()  # Render model
71
```
72

73
## Material
74

75
```python
76
class pyglet.model.Material:
77
    """Material properties"""
78

79
    # Properties
80
    name: str
81
    diffuse: tuple  # Diffuse color RGBA
82
    ambient: tuple  # Ambient color RGBA
83
    specular: tuple  # Specular color RGBA
84
    emission: tuple  # Emission color RGBA
85
    shininess: float  # Specular exponent
86
    texture: Texture | None  # Diffuse texture
87
```
88

89
## Examples
90

91
### Load and Display
92
```python
93
import pyglet
94
from pyglet import model
95
from pyglet.gl import *
96

97
window = pyglet.window.Window(width=800, height=600)
98
batch = pyglet.graphics.Batch()
99

100
# Load model
101
scene = model.load('spaceship.obj', batch=batch)
102

103
# Setup camera
104
@window.event
105
def on_resize(width, height):
106
    glViewport(0, 0, width, height)
107
    glMatrixMode(GL_PROJECTION)
108
    glLoadIdentity()
109
    gluPerspective(60.0, width/height, 0.1, 100.0)
110
    glMatrixMode(GL_MODELVIEW)
111

112
@window.event
113
def on_draw():
114
    window.clear()
115

116
    glLoadIdentity()
117
    glTranslatef(0, 0, -5)  # Move back to see model
118

119
    scene.draw()
120

121
pyglet.app.run()
122
```
123

124
### Rotating Model
125
```python
126
rotation = 0
127

128
def update(dt):
129
    global rotation
130
    rotation += dt * 45  # 45 degrees per second
131

132
pyglet.clock.schedule_interval(update, 1/60)
133

134
@window.event
135
def on_draw():
136
    window.clear()
137

138
    glLoadIdentity()
139
    glTranslatef(0, 0, -5)
140
    glRotatef(rotation, 0, 1, 0)  # Rotate around Y axis
141

142
    scene.draw()
143
```
144

145
### Multiple Models
146
```python
147
models = {
148
    'player': model.load('player.obj', batch=batch),
149
    'enemy': model.load('enemy.obj', batch=batch),
150
    'item': model.load('item.obj', batch=batch),
151
}
152

153
@window.event
154
def on_draw():
155
    window.clear()
156
    glLoadIdentity()
157
    glTranslatef(0, 0, -10)
158

159
    # Draw player
160
    glPushMatrix()
161
    glTranslatef(-2, 0, 0)
162
    models['player'].draw()
163
    glPopMatrix()
164

165
    # Draw enemy
166
    glPushMatrix()
167
    glTranslatef(2, 0, 0)
168
    models['enemy'].draw()
169
    glPopMatrix()
170

171
    # Draw item
172
    glPushMatrix()
173
    glTranslatef(0, 2, 0)
174
    glRotatef(time * 90, 0, 1, 0)
175
    models['item'].draw()
176
    glPopMatrix()
177
```
178

179
## Performance Tips
180

181
1. **Use batching**: Pass batch to load() for efficient rendering
182
2. **Preload models**: Load during initialization
183
3. **LOD**: Use lower-poly models for distant objects
184
4. **Culling**: Don't draw offscreen models
185
5. **Instancing**: For many copies of same model
186

187
## Common Issues
188

189
1. **Model not visible**: Check camera position and model scale
190
2. **Texture missing**: Ensure texture files in correct path
191
3. **Format support**: Limited to OBJ by default, GLTF requires additional codecs
192
4. **Coordinate system**: Different formats use different conventions
193
5. **Lighting**: Models may need proper OpenGL lighting setup
194

195
For advanced 3D rendering, consider using a dedicated 3D engine or pyglet with custom shaders.
196