0
# Scene Framework
1
2
The scene framework provides the foundation for creating animations in ManimGL. Scenes manage the animation timeline, coordinate system, object lifecycle, and provide the interface for building complex mathematical animations.
3
4
## Capabilities
5
6
### Base Scene Class
7
8
The core Scene class provides the fundamental animation framework with timeline control, object management, and rendering coordination.
9
10
```python { .api }
11
class Scene:
12
def __init__(self, **kwargs):
13
"""
14
Initialize a new scene.
15
16
Parameters:
17
- camera_class: Camera class to use (default: Camera)
18
- skip_animations: bool, skip all animations
19
- leave_progress_bars: bool, keep progress bars after completion
20
"""
21
22
def construct(self):
23
"""
24
Override this method to define the scene's animation sequence.
25
This is where you add objects and animations.
26
"""
27
28
def setup(self):
29
"""
30
Called before construct(). Override for scene initialization.
31
"""
32
33
def play(self, *animations, **kwargs):
34
"""
35
Play one or more animations simultaneously.
36
37
Parameters:
38
- animations: Animation objects to play
39
- run_time: float, duration of animations (default: 1.0)
40
- rate_func: function, timing function for animations
41
- lag_ratio: float, stagger start times when multiple animations
42
43
Returns:
44
None
45
"""
46
47
def wait(self, duration=None, **kwargs):
48
"""
49
Pause the animation for specified duration.
50
51
Parameters:
52
- duration: float, seconds to wait (default: scene's default_wait_time)
53
54
Returns:
55
None
56
"""
57
58
def add(self, *mobjects):
59
"""
60
Add mobjects to the scene without animation.
61
62
Parameters:
63
- mobjects: Mobject instances to add
64
65
Returns:
66
None
67
"""
68
69
def remove(self, *mobjects):
70
"""
71
Remove mobjects from the scene without animation.
72
73
Parameters:
74
- mobjects: Mobject instances to remove
75
76
Returns:
77
None
78
"""
79
80
def bring_to_front(self, *mobjects):
81
"""
82
Bring mobjects to the front of the scene (highest z-index).
83
84
Parameters:
85
- mobjects: Mobject instances to bring forward
86
87
Returns:
88
None
89
"""
90
91
def bring_to_back(self, *mobjects):
92
"""
93
Send mobjects to the back of the scene (lowest z-index).
94
95
Parameters:
96
- mobjects: Mobject instances to send back
97
98
Returns:
99
None
100
"""
101
```
102
103
### Interactive Scene
104
105
Enhanced scene class for real-time development and interaction with mouse and keyboard controls.
106
107
```python { .api }
108
class InteractiveScene(Scene):
109
def __init__(self, **kwargs):
110
"""
111
Initialize interactive scene with real-time controls.
112
113
Additional features:
114
- Mouse interaction
115
- Keyboard shortcuts
116
- Real-time object manipulation
117
- Live scene editing
118
"""
119
120
def on_key_press(self, symbol, modifiers):
121
"""
122
Handle keyboard input during scene playback.
123
124
Parameters:
125
- symbol: Key symbol pressed
126
- modifiers: Modifier keys (Ctrl, Shift, etc.)
127
128
Returns:
129
None
130
"""
131
132
def on_mouse_press(self, point, button, mods):
133
"""
134
Handle mouse clicks during scene playback.
135
136
Parameters:
137
- point: np.array, click position in scene coordinates
138
- button: Mouse button pressed
139
- mods: Modifier keys
140
141
Returns:
142
None
143
"""
144
145
def on_mouse_drag(self, point, d_point, buttons, modifiers):
146
"""
147
Handle mouse dragging.
148
149
Parameters:
150
- point: np.array, current mouse position
151
- d_point: np.array, change in position
152
- buttons: Mouse buttons held
153
- modifiers: Modifier keys
154
155
Returns:
156
None
157
"""
158
```
159
160
### 3D Scene Support
161
162
Specialized scene class optimized for three-dimensional animations with enhanced camera controls and depth management.
163
164
```python { .api }
165
class ThreeDScene(Scene):
166
def __init__(self, **kwargs):
167
"""
168
Initialize 3D scene with specialized camera.
169
170
Parameters:
171
- camera_class: Defaults to ThreeDCamera
172
"""
173
174
def set_camera_orientation(self, phi=None, theta=None, gamma=None, **kwargs):
175
"""
176
Set the 3D camera orientation.
177
178
Parameters:
179
- phi: float, angle around x-axis (latitude)
180
- theta: float, angle around z-axis (longitude)
181
- gamma: float, rotation around viewing axis
182
- **kwargs: Additional camera parameters
183
184
Returns:
185
None
186
"""
187
188
def begin_ambient_camera_rotation(self, rate=0.02):
189
"""
190
Start continuous camera rotation.
191
192
Parameters:
193
- rate: float, rotation speed in radians per frame
194
195
Returns:
196
None
197
"""
198
199
def stop_ambient_camera_rotation(self):
200
"""
201
Stop continuous camera rotation.
202
203
Returns:
204
None
205
"""
206
207
def move_camera(self, phi=None, theta=None, gamma=None, **kwargs):
208
"""
209
Animate camera movement to new orientation.
210
211
Parameters:
212
- phi: float, target latitude angle
213
- theta: float, target longitude angle
214
- gamma: float, target rotation angle
215
- **kwargs: Animation parameters (run_time, rate_func)
216
217
Returns:
218
Animation
219
"""
220
```
221
222
### Camera System
223
224
Camera classes for managing viewport, coordinate transformations, and rendering.
225
226
```python { .api }
227
class Camera:
228
def __init__(self, **kwargs):
229
"""
230
Initialize 2D camera.
231
232
Parameters:
233
- background_color: Color for scene background
234
- frame_height: float, height of viewable area
235
- frame_width: float, width of viewable area
236
"""
237
238
def capture(self, *mobjects, **kwargs):
239
"""
240
Render mobjects to image.
241
242
Parameters:
243
- mobjects: Objects to render
244
245
Returns:
246
PIL.Image
247
"""
248
249
class ThreeDCamera(Camera):
250
def __init__(self, **kwargs):
251
"""
252
Initialize 3D camera with depth and perspective.
253
254
Parameters:
255
- phi: float, initial latitude angle
256
- theta: float, initial longitude angle
257
- distance: float, camera distance from origin
258
"""
259
260
def set_euler_angles(self, phi, theta, gamma):
261
"""
262
Set camera orientation using Euler angles.
263
264
Parameters:
265
- phi: float, rotation around x-axis
266
- theta: float, rotation around z-axis
267
- gamma: float, rotation around viewing axis
268
269
Returns:
270
None
271
"""
272
```
273
274
### Window Management
275
276
Window class for display management and user interaction.
277
278
```python { .api }
279
class Window:
280
def __init__(self, scene, **kwargs):
281
"""
282
Initialize display window.
283
284
Parameters:
285
- scene: Scene instance to display
286
- size: tuple, window dimensions (width, height)
287
- title: str, window title
288
- resizable: bool, whether window can be resized
289
"""
290
291
def show(self):
292
"""
293
Display the window and start the main loop.
294
295
Returns:
296
None
297
"""
298
299
def close(self):
300
"""
301
Close the window.
302
303
Returns:
304
None
305
"""
306
```
307
308
## Usage Examples
309
310
### Basic Scene
311
312
```python
313
from manimgl import *
314
315
class BasicScene(Scene):
316
def construct(self):
317
# Create objects
318
circle = Circle(color=BLUE)
319
text = Text("Hello World")
320
321
# Add to scene
322
self.add(circle, text)
323
self.wait()
324
325
# Animate
326
self.play(FadeOut(circle))
327
self.play(Transform(text, Text("Goodbye!")))
328
self.wait()
329
```
330
331
### Interactive Scene
332
333
```python
334
class InteractiveExample(InteractiveScene):
335
def construct(self):
336
circle = Circle(color=BLUE)
337
self.add(circle)
338
339
def on_key_press(self, symbol, modifiers):
340
if symbol == ord('r'):
341
# Red circle on 'r' key
342
self.mobjects[0].set_color(RED)
343
```
344
345
### 3D Scene
346
347
```python
348
class ThreeDExample(ThreeDScene):
349
def construct(self):
350
axes = ThreeDAxes()
351
surface = ParametricSurface(
352
lambda u, v: [u, v, u**2 + v**2]
353
)
354
355
self.set_camera_orientation(phi=75*DEGREES)
356
self.add(axes, surface)
357
self.begin_ambient_camera_rotation()
358
self.wait(5)
359
```