0
# 3D Objects and Surfaces
1
2
ManimGL provides comprehensive 3D object support including parametric surfaces, geometric solids, and specialized 3D mathematical constructs. These objects integrate with the 3D camera system for creating immersive mathematical visualizations with depth and perspective.
3
4
## Capabilities
5
6
### Base 3D Surface Class
7
8
Foundation class for all 3D surface objects with lighting and shading support.
9
10
```python { .api }
11
class Surface(VMobject):
12
def __init__(self, func=None, **kwargs):
13
"""
14
Base class for 3D surfaces.
15
16
Parameters:
17
- func: callable, surface function (u, v) -> (x, y, z)
18
- u_range: tuple, (u_min, u_max) parameter range
19
- v_range: tuple, (v_min, v_max) parameter range
20
- resolution: tuple, (u_res, v_res) surface resolution
21
- surface_piece_config: dict, styling for surface pieces
22
- fill_color: surface interior color
23
- fill_opacity: float, surface opacity (0-1)
24
- checkerboard_colors: list, alternating surface colors
25
- stroke_color: surface outline color
26
- stroke_width: float, outline thickness
27
- should_make_jagged: bool, add surface roughness
28
- pre_function_handle_to_anchor_scale_factor: float, scaling factor
29
"""
30
31
def set_fill_by_checkerboard(self, *colors, opacity=None):
32
"""
33
Set checkerboard pattern fill.
34
35
Parameters:
36
- colors: Color arguments for checkerboard pattern
37
- opacity: float, pattern opacity
38
39
Returns:
40
Surface (self)
41
"""
42
43
def set_fill_by_value(self, axes, func, **kwargs):
44
"""
45
Set fill color based on function values.
46
47
Parameters:
48
- axes: Axes object for coordinate reference
49
- func: callable, function for color mapping (x, y, z) -> float
50
- colorscale: str, color scale name ('viridis', 'plasma', etc.)
51
- alpha: float, opacity
52
53
Returns:
54
Surface (self)
55
"""
56
57
class ParametricSurface(Surface):
58
def __init__(self, func, u_range=(0, 1), v_range=(0, 1), **kwargs):
59
"""
60
Parametric surface defined by r(u, v) = (x(u,v), y(u,v), z(u,v)).
61
62
Parameters:
63
- func: callable, parametric function (u, v) -> (x, y, z)
64
- u_range: tuple, u parameter range
65
- v_range: tuple, v parameter range
66
- checkerboard_colors: list, alternating colors for surface patches
67
- resolution: tuple, (u_resolution, v_resolution)
68
"""
69
70
def get_point_from_function(self, u, v):
71
"""
72
Get 3D point at parameter values (u, v).
73
74
Parameters:
75
- u: float, u parameter value
76
- v: float, v parameter value
77
78
Returns:
79
np.array, 3D point on surface
80
"""
81
82
class TexturedSurface(Surface):
83
def __init__(self, surface, image_file, **kwargs):
84
"""
85
Surface with image texture mapping.
86
87
Parameters:
88
- surface: Surface object to apply texture to
89
- image_file: str, path to texture image file
90
- alpha: float, texture opacity
91
"""
92
```
93
94
### Geometric Solids
95
96
Standard 3D geometric shapes and solids.
97
98
```python { .api }
99
class Sphere(ParametricSurface):
100
def __init__(self, radius=1, **kwargs):
101
"""
102
3D sphere surface.
103
104
Parameters:
105
- radius: float, sphere radius
106
- u_range: tuple, latitude parameter range (default: (0, TAU))
107
- v_range: tuple, longitude parameter range (default: (0, PI))
108
- resolution: tuple, surface resolution
109
"""
110
111
class Cube(VGroup):
112
def __init__(self, side_length=2, **kwargs):
113
"""
114
3D cube made of square faces.
115
116
Parameters:
117
- side_length: float, edge length
118
- fill_opacity: float, face opacity
119
- stroke_color: edge color
120
- stroke_width: float, edge thickness
121
"""
122
123
def get_face_by_index(self, index):
124
"""
125
Get cube face by index.
126
127
Parameters:
128
- index: int, face index (0-5)
129
130
Returns:
131
Square, cube face
132
"""
133
134
class Prism(Cube):
135
def __init__(self, dimensions=(3, 2, 1), **kwargs):
136
"""
137
Rectangular prism/cuboid.
138
139
Parameters:
140
- dimensions: tuple, (width, height, depth)
141
"""
142
143
class Cone(ParametricSurface):
144
def __init__(self, height=2, base_radius=1, **kwargs):
145
"""
146
3D cone surface.
147
148
Parameters:
149
- height: float, cone height
150
- base_radius: float, base circle radius
151
- u_range: tuple, radial parameter range
152
- v_range: tuple, height parameter range
153
"""
154
155
class Cylinder(ParametricSurface):
156
def __init__(self, height=2, radius=1, **kwargs):
157
"""
158
3D cylinder surface.
159
160
Parameters:
161
- height: float, cylinder height
162
- radius: float, cylinder radius
163
- u_range: tuple, angular parameter range (default: (0, TAU))
164
- v_range: tuple, height parameter range
165
"""
166
167
class Torus(ParametricSurface):
168
def __init__(self, major_radius=3, minor_radius=1, **kwargs):
169
"""
170
3D torus (donut shape).
171
172
Parameters:
173
- major_radius: float, distance from center to tube center
174
- minor_radius: float, tube radius
175
- u_range: tuple, major circle parameter range
176
- v_range: tuple, minor circle parameter range
177
"""
178
```
179
180
### Mathematical Surfaces
181
182
Specialized surfaces for mathematical visualization and education.
183
184
```python { .api }
185
class SurfaceFromFunction(ParametricSurface):
186
def __init__(self, function, x_range=(-3, 3), y_range=(-3, 3), **kwargs):
187
"""
188
Surface defined by z = f(x, y).
189
190
Parameters:
191
- function: callable, height function f(x, y) -> z
192
- x_range: tuple, x domain
193
- y_range: tuple, y domain
194
- resolution: tuple, sampling resolution
195
"""
196
197
class Paraboloid(SurfaceFromFunction):
198
def __init__(self, **kwargs):
199
"""
200
Paraboloid surface z = x² + y².
201
202
Parameters:
203
- x_range: tuple, x domain
204
- y_range: tuple, y domain
205
"""
206
207
class Hyperboloid(ParametricSurface):
208
def __init__(self, **kwargs):
209
"""
210
Hyperboloid of one sheet.
211
212
Parameters:
213
- u_range: tuple, first parameter range
214
- v_range: tuple, second parameter range
215
"""
216
217
class Klein_Bottle(ParametricSurface):
218
def __init__(self, **kwargs):
219
"""
220
Klein bottle surface (non-orientable).
221
222
Parameters:
223
- u_range: tuple, first parameter range
224
- v_range: tuple, second parameter range
225
"""
226
227
class Mobius_Strip(ParametricSurface):
228
def __init__(self, **kwargs):
229
"""
230
Möbius strip surface (non-orientable).
231
232
Parameters:
233
- u_range: tuple, length parameter range
234
- v_range: tuple, width parameter range
235
"""
236
237
class ParametricSurface3D(ParametricSurface):
238
def __init__(self, func, **kwargs):
239
"""
240
General 3D parametric surface with advanced options.
241
242
Parameters:
243
- func: callable, surface function (u, v) -> (x, y, z)
244
- normal_nudge: float, normal vector adjustment
245
- depth_test: bool, enable depth testing
246
- gloss: float, surface shininess (0-1)
247
- shadow: float, shadow intensity (0-1)
248
"""
249
```
250
251
### 3D Curves and Lines
252
253
Three-dimensional curves and line objects.
254
255
```python { .api }
256
class ParametricCurve3D(VMobject):
257
def __init__(self, func, t_range=(0, 1), **kwargs):
258
"""
259
3D parametric curve r(t) = (x(t), y(t), z(t)).
260
261
Parameters:
262
- func: callable, curve function t -> (x, y, z)
263
- t_range: tuple, parameter range
264
- dt: float, parameter sampling step
265
- stroke_width: float, curve thickness
266
- stroke_color: curve color
267
"""
268
269
class CurvesAsSubmobjects(VGroup):
270
def __init__(self, *curves, **kwargs):
271
"""
272
Group of 3D curves as submobjects.
273
274
Parameters:
275
- curves: ParametricCurve3D objects
276
"""
277
278
class Line3D(ParametricCurve3D):
279
def __init__(self, start, end, **kwargs):
280
"""
281
3D line segment.
282
283
Parameters:
284
- start: np.array, starting point in 3D
285
- end: np.array, ending point in 3D
286
"""
287
288
class Arrow3D(Line3D):
289
def __init__(self, start, end, **kwargs):
290
"""
291
3D arrow with 3D arrowhead.
292
293
Parameters:
294
- start: np.array, arrow start point
295
- end: np.array, arrow end point
296
- thickness: float, arrow shaft thickness
297
- height: float, arrowhead height
298
"""
299
```
300
301
### Point Clouds and 3D Collections
302
303
Collections of 3D objects and point-based representations.
304
305
```python { .api }
306
class DotCloud(PMobject):
307
def __init__(self, *points, **kwargs):
308
"""
309
Cloud of 3D dots/points.
310
311
Parameters:
312
- points: np.array points or list of points in 3D space
313
- color: dot color
314
- radius: float, dot size
315
- density: int, dots per unit area
316
"""
317
318
def add_points(self, points):
319
"""
320
Add more points to the cloud.
321
322
Parameters:
323
- points: np.array, additional 3D points
324
325
Returns:
326
DotCloud (self)
327
"""
328
329
class Point3D(Dot):
330
def __init__(self, location=ORIGIN, **kwargs):
331
"""
332
Single 3D point with depth.
333
334
Parameters:
335
- location: np.array, 3D coordinates
336
- radius: float, point size
337
- color: point color
338
"""
339
340
class Dot3D(Point3D):
341
def __init__(self, point=ORIGIN, **kwargs):
342
"""
343
3D dot that maintains consistent size regardless of depth.
344
345
Parameters:
346
- point: np.array, 3D location
347
- radius: float, dot radius
348
- stroke_width: float, outline thickness
349
"""
350
```
351
352
### 3D Text and Labels
353
354
Text objects positioned in 3D space.
355
356
```python { .api }
357
class Text3D(Text):
358
def __init__(self, text, **kwargs):
359
"""
360
3D text object with depth and perspective.
361
362
Parameters:
363
- text: str, text content
364
- depth: float, text extrusion depth
365
- font_size: float, text size
366
- perspective_factor: float, perspective scaling
367
"""
368
369
class Tex3D(Tex):
370
def __init__(self, *tex_strings, **kwargs):
371
"""
372
3D LaTeX mathematical expressions.
373
374
Parameters:
375
- tex_strings: str arguments, LaTeX content
376
- depth: float, extrusion depth
377
- shading: float, 3D shading intensity
378
"""
379
```
380
381
## Usage Examples
382
383
### Basic 3D Surface
384
385
```python
386
from manimgl import *
387
388
class SurfaceExample(ThreeDScene):
389
def construct(self):
390
# Create parametric surface
391
surface = ParametricSurface(
392
lambda u, v: np.array([
393
u,
394
v,
395
0.5 * (u**2 + v**2)
396
]),
397
u_range=(-2, 2),
398
v_range=(-2, 2),
399
checkerboard_colors=[BLUE_D, BLUE_E],
400
resolution=(20, 20)
401
)
402
403
# Set camera angle
404
self.set_camera_orientation(phi=75*DEGREES, theta=45*DEGREES)
405
406
self.play(ShowCreation(surface))
407
self.begin_ambient_camera_rotation(rate=0.1)
408
self.wait(5)
409
```
410
411
### 3D Geometric Solids
412
413
```python
414
class SolidsExample(ThreeDScene):
415
def construct(self):
416
# Create various 3D solids
417
sphere = Sphere(radius=1, color=RED).shift(LEFT * 3)
418
cube = Cube(side_length=1.5, color=BLUE)
419
cone = Cone(height=2, base_radius=1, color=GREEN).shift(RIGHT * 3)
420
421
solids = VGroup(sphere, cube, cone)
422
423
self.set_camera_orientation(phi=60*DEGREES, theta=45*DEGREES)
424
self.play(ShowCreation(solids))
425
self.begin_ambient_camera_rotation(rate=0.05)
426
self.wait(3)
427
```
428
429
### Mathematical Surface Function
430
431
```python
432
class MathSurfaceExample(ThreeDScene):
433
def construct(self):
434
# Mathematical function surface
435
def wave_function(u, v):
436
return np.array([
437
u,
438
v,
439
np.sin(u) * np.cos(v)
440
])
441
442
surface = ParametricSurface(
443
wave_function,
444
u_range=(-PI, PI),
445
v_range=(-PI, PI),
446
resolution=(30, 30)
447
)
448
449
# Color by height
450
surface.set_fill_by_value(
451
axes=None,
452
func=lambda x, y, z: z,
453
colorscale="viridis"
454
)
455
456
self.set_camera_orientation(phi=70*DEGREES)
457
self.play(ShowCreation(surface))
458
self.wait()
459
```
460
461
### 3D Curve Animation
462
463
```python
464
class Curve3DExample(ThreeDScene):
465
def construct(self):
466
# 3D parametric curve (helix)
467
helix = ParametricCurve3D(
468
lambda t: np.array([
469
np.cos(t),
470
np.sin(t),
471
0.3 * t
472
]),
473
t_range=(0, 4*PI),
474
stroke_width=4,
475
color=YELLOW
476
)
477
478
self.set_camera_orientation(phi=75*DEGREES, theta=45*DEGREES)
479
self.play(ShowCreation(helix), run_time=3)
480
self.begin_ambient_camera_rotation(rate=0.1)
481
self.wait(3)
482
```
483
484
### Interactive 3D Scene
485
486
```python
487
class Interactive3DExample(InteractiveScene, ThreeDScene):
488
def construct(self):
489
# Create surface that can be manipulated
490
surface = ParametricSurface(
491
lambda u, v: np.array([u, v, u*v]),
492
u_range=(-2, 2),
493
v_range=(-2, 2),
494
color=BLUE
495
)
496
497
self.add(surface)
498
self.set_camera_orientation(phi=60*DEGREES)
499
500
def on_key_press(self, symbol, modifiers):
501
if symbol == ord('r'):
502
# Rotate surface on 'r' key
503
self.play(Rotate(self.mobjects[0], PI/4, axis=UP))
504
```
505
506
### Textured 3D Object
507
508
```python
509
class TexturedExample(ThreeDScene):
510
def construct(self):
511
# Create sphere
512
sphere = Sphere(radius=2, resolution=(50, 50))
513
514
# Apply texture (requires image file)
515
# textured_sphere = TexturedSurface(sphere, "earth_texture.jpg")
516
517
self.set_camera_orientation(phi=60*DEGREES, theta=30*DEGREES)
518
self.play(ShowCreation(sphere))
519
self.begin_ambient_camera_rotation(rate=0.02)
520
self.wait(5)
521
```
522
523
### 3D Point Cloud
524
525
```python
526
class PointCloudExample(ThreeDScene):
527
def construct(self):
528
# Generate random 3D points
529
points = [
530
np.array([
531
2 * (np.random.random() - 0.5),
532
2 * (np.random.random() - 0.5),
533
2 * (np.random.random() - 0.5)
534
])
535
for _ in range(1000)
536
]
537
538
cloud = DotCloud(*points, color=BLUE, radius=0.05)
539
540
self.set_camera_orientation(phi=75*DEGREES, theta=45*DEGREES)
541
self.play(ShowCreation(cloud))
542
self.begin_ambient_camera_rotation(rate=0.1)
543
self.wait(3)
544
```