0
# Geometric Primitives
1
2
PyVista provides comprehensive functions for creating basic geometric shapes and parametric surfaces, essential for building 3D scenes and geometric modeling.
3
4
## Capabilities
5
6
### Basic Shapes
7
8
#### Sphere
9
10
Creates spherical meshes with customizable resolution and parameters.
11
12
```python { .api }
13
def Sphere(radius=0.5, center=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 1.0),
14
theta_resolution=30, phi_resolution=30, start_theta=0.0, end_theta=360.0,
15
start_phi=0.0, end_phi=180.0) -> PolyData:
16
"""
17
Create a sphere mesh.
18
19
Parameters:
20
radius (float): Sphere radius
21
center (tuple): Center point coordinates (x, y, z)
22
direction (tuple): Direction vector for sphere orientation
23
theta_resolution (int): Number of points in longitude direction
24
phi_resolution (int): Number of points in latitude direction
25
start_theta (float): Starting longitude angle in degrees
26
end_theta (float): Ending longitude angle in degrees
27
start_phi (float): Starting latitude angle in degrees
28
end_phi (float): Ending latitude angle in degrees
29
30
Returns:
31
PolyData: Spherical mesh
32
"""
33
```
34
35
#### Cube and Box
36
37
Creates cubic and rectangular box meshes.
38
39
```python { .api }
40
def Cube(x_length=1.0, y_length=1.0, z_length=1.0, center=(0.0, 0.0, 0.0)) -> PolyData:
41
"""
42
Create a cube mesh.
43
44
Parameters:
45
x_length (float): Length in x-direction
46
y_length (float): Length in y-direction
47
z_length (float): Length in z-direction
48
center (tuple): Center point coordinates
49
50
Returns:
51
PolyData: Cubic mesh
52
"""
53
54
def Box(bounds=(-1.0, 1.0, -1.0, 1.0, -1.0, 1.0), level=0, quads=True) -> PolyData:
55
"""
56
Create a box mesh from bounds.
57
58
Parameters:
59
bounds (tuple): Bounds (xmin, xmax, ymin, ymax, zmin, zmax)
60
level (int): Subdivision level
61
quads (bool): Generate quadrilaterals instead of triangles
62
63
Returns:
64
PolyData: Box mesh
65
"""
66
```
67
68
#### Cylinder
69
70
Creates cylindrical meshes with customizable caps and resolution.
71
72
```python { .api }
73
def Cylinder(center=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0), radius=0.5,
74
height=1.0, resolution=100, capping=True) -> PolyData:
75
"""
76
Create a cylinder mesh.
77
78
Parameters:
79
center (tuple): Center point of cylinder
80
direction (tuple): Direction vector for cylinder axis
81
radius (float): Cylinder radius
82
height (float): Cylinder height
83
resolution (int): Number of points around circumference
84
capping (bool): Cap the ends of cylinder
85
86
Returns:
87
PolyData: Cylindrical mesh
88
"""
89
```
90
91
#### Cone
92
93
Creates conical meshes with customizable parameters.
94
95
```python { .api }
96
def Cone(center=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0), height=1.0,
97
radius=0.5, capping=True, angle=None, resolution=6) -> PolyData:
98
"""
99
Create a cone mesh.
100
101
Parameters:
102
center (tuple): Center point of cone base
103
direction (tuple): Direction vector from base to apex
104
height (float): Cone height
105
radius (float): Base radius
106
capping (bool): Cap the base
107
angle (float): Cone angle in degrees (alternative to radius)
108
resolution (int): Number of points around base
109
110
Returns:
111
PolyData: Conical mesh
112
"""
113
```
114
115
### Planar Objects
116
117
#### Plane
118
119
Creates planar surfaces with customizable resolution.
120
121
```python { .api }
122
def Plane(center=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 1.0), i_size=1, j_size=1,
123
i_resolution=10, j_resolution=10) -> PolyData:
124
"""
125
Create a plane mesh.
126
127
Parameters:
128
center (tuple): Center point of plane
129
direction (tuple): Normal vector of plane
130
i_size (float): Size in first direction
131
j_size (float): Size in second direction
132
i_resolution (int): Number of points in first direction
133
j_resolution (int): Number of points in second direction
134
135
Returns:
136
PolyData: Planar mesh
137
"""
138
```
139
140
#### Circle and Disc
141
142
Creates circular and disc-shaped meshes.
143
144
```python { .api }
145
def Circle(radius=0.5, resolution=100) -> PolyData:
146
"""
147
Create a circular mesh (line loop).
148
149
Parameters:
150
radius (float): Circle radius
151
resolution (int): Number of points around circumference
152
153
Returns:
154
PolyData: Circular line mesh
155
"""
156
157
def Disc(center=(0.0, 0.0, 0.0), inner=0.25, outer=0.5, normal=(0.0, 0.0, 1.0),
158
r_res=1, c_res=6) -> PolyData:
159
"""
160
Create a disc (annulus) mesh.
161
162
Parameters:
163
center (tuple): Center point
164
inner (float): Inner radius
165
outer (float): Outer radius
166
normal (tuple): Normal vector
167
r_res (int): Radial resolution
168
c_res (int): Circumferential resolution
169
170
Returns:
171
PolyData: Disc mesh
172
"""
173
```
174
175
#### Rectangle and Polygon
176
177
Creates rectangular and arbitrary polygonal shapes.
178
179
```python { .api }
180
def Rectangle(dimensions=(1.0, 1.0), center=(0.0, 0.0, 0.0)) -> PolyData:
181
"""
182
Create a rectangular mesh.
183
184
Parameters:
185
dimensions (tuple): Width and height
186
center (tuple): Center point coordinates
187
188
Returns:
189
PolyData: Rectangular mesh
190
"""
191
192
def Polygon(center=(0.0, 0.0, 0.0), radius=1.0, normal=(0.0, 0.0, 1.0),
193
n_sides=6) -> PolyData:
194
"""
195
Create a regular polygon mesh.
196
197
Parameters:
198
center (tuple): Center point
199
radius (float): Distance from center to vertices
200
normal (tuple): Normal vector
201
n_sides (int): Number of sides
202
203
Returns:
204
PolyData: Polygonal mesh
205
"""
206
207
def Triangle(points=None) -> PolyData:
208
"""
209
Create a triangle from three points.
210
211
Parameters:
212
points (array-like): Three points defining triangle vertices
213
214
Returns:
215
PolyData: Triangular mesh
216
"""
217
218
def Quadrilateral(points=None) -> PolyData:
219
"""
220
Create a quadrilateral from four points.
221
222
Parameters:
223
points (array-like): Four points defining quadrilateral vertices
224
225
Returns:
226
PolyData: Quadrilateral mesh
227
"""
228
229
def Ellipse(semi_major_axis=0.5, semi_minor_axis=0.2, center=(0.0, 0.0, 0.0),
230
normal=(0.0, 0.0, 1.0), resolution=100) -> PolyData:
231
"""
232
Create an ellipse curve.
233
234
Parameters:
235
semi_major_axis (float): Length of semi-major axis
236
semi_minor_axis (float): Length of semi-minor axis
237
center (tuple): Center point of ellipse
238
normal (tuple): Normal vector of ellipse plane
239
resolution (int): Number of points around ellipse
240
241
Returns:
242
PolyData: Elliptical curve
243
"""
244
245
def Pyramid(points=None) -> PolyData:
246
"""
247
Create a pyramid from base points and apex.
248
249
Parameters:
250
points (array-like): Points defining pyramid base and apex
251
252
Returns:
253
PolyData: Pyramid mesh
254
"""
255
```
256
257
### Linear Objects
258
259
#### Line and Multiple Lines
260
261
Creates line segments and polylines.
262
263
```python { .api }
264
def Line(pointa=(-0.5, 0.0, 0.0), pointb=(0.5, 0.0, 0.0), resolution=1) -> PolyData:
265
"""
266
Create a line mesh between two points.
267
268
Parameters:
269
pointa (tuple): Starting point coordinates
270
pointb (tuple): Ending point coordinates
271
resolution (int): Number of intermediate points
272
273
Returns:
274
PolyData: Line mesh
275
"""
276
277
def MultipleLines(points) -> PolyData:
278
"""
279
Create multiple line segments from point arrays.
280
281
Parameters:
282
points (array-like): Points defining line segments
283
284
Returns:
285
PolyData: Multi-line mesh
286
"""
287
288
def CircularArc(pointa=(-1.0, 0.0, 0.0), pointb=(0.0, 1.0, 0.0),
289
center=(0.0, 0.0, 0.0), resolution=20, negative=False) -> PolyData:
290
"""
291
Create a circular arc between two points.
292
293
Parameters:
294
pointa (tuple): Starting point coordinates
295
pointb (tuple): Ending point coordinates
296
center (tuple): Arc center point
297
resolution (int): Number of points along arc
298
negative (bool): Use negative arc direction
299
300
Returns:
301
PolyData: Circular arc mesh
302
"""
303
304
def CircularArcFromNormal(center=(0.0, 0.0, 0.0), resolution=20,
305
normal=(0.0, 0.0, 1.0), polar=(1.0, 0.0, 0.0),
306
angle=90.0) -> PolyData:
307
"""
308
Create a circular arc from normal and polar vectors.
309
310
Parameters:
311
center (tuple): Arc center point
312
resolution (int): Number of points along arc
313
normal (tuple): Normal vector to arc plane
314
polar (tuple): Starting direction vector
315
angle (float): Arc angle in degrees
316
317
Returns:
318
PolyData: Circular arc mesh
319
"""
320
```
321
322
#### Arrow
323
324
Creates arrow-shaped meshes for vector visualization.
325
326
```python { .api }
327
def Arrow(start=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0), tip_length=0.25,
328
tip_radius=0.1, tip_resolution=20, shaft_radius=0.05,
329
shaft_resolution=20, scale=None) -> PolyData:
330
"""
331
Create an arrow mesh.
332
333
Parameters:
334
start (tuple): Starting point of arrow
335
direction (tuple): Direction vector
336
tip_length (float): Length of arrow tip
337
tip_radius (float): Radius of arrow tip
338
tip_resolution (int): Resolution of arrow tip
339
shaft_radius (float): Radius of arrow shaft
340
shaft_resolution (int): Resolution of arrow shaft
341
scale (float): Overall scale factor
342
343
Returns:
344
PolyData: Arrow mesh
345
"""
346
```
347
348
### Complex Shapes
349
350
#### Tube
351
352
Creates tubular meshes along paths.
353
354
```python { .api }
355
def Tube(pointa=(-0.5, 0.0, 0.0), pointb=(0.5, 0.0, 0.0), resolution=1,
356
radius=1.0, n_sides=3) -> PolyData:
357
"""
358
Create a tube mesh along a path.
359
360
Parameters:
361
pointa (tuple): Starting point
362
pointb (tuple): Ending point
363
resolution (int): Number of segments along path
364
radius (float): Tube radius
365
n_sides (int): Number of sides around circumference
366
367
Returns:
368
PolyData: Tubular mesh
369
"""
370
```
371
372
#### Superquadric
373
374
Creates mathematical superquadric surfaces.
375
376
```python { .api }
377
def Superquadric(center=(0.0, 0.0, 0.0), scale=(1.0, 1.0, 1.0), size=0.5,
378
theta_roundness=1.0, phi_roundness=1.0, theta_resolution=16,
379
phi_resolution=16, toroidal=False, thickness=1/3) -> PolyData:
380
"""
381
Create a superquadric mesh.
382
383
Parameters:
384
center (tuple): Center point
385
scale (tuple): Scaling factors for each axis
386
size (float): Overall size
387
theta_roundness (float): Roundness in theta direction
388
phi_roundness (float): Roundness in phi direction
389
theta_resolution (int): Resolution in theta direction
390
phi_resolution (int): Resolution in phi direction
391
toroidal (bool): Create toroidal superquadric
392
thickness (float): Thickness for toroidal shapes
393
394
Returns:
395
PolyData: Superquadric mesh
396
"""
397
```
398
399
#### Text3D
400
401
Creates 3D text meshes.
402
403
```python { .api }
404
def Text3D(string, depth=0.5) -> PolyData:
405
"""
406
Create 3D text mesh.
407
408
Parameters:
409
string (str): Text string to render
410
depth (float): Extrusion depth
411
412
Returns:
413
PolyData: 3D text mesh
414
"""
415
416
def Capsule(center=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0), radius=0.5,
417
cylinder_length=1.0, resolution=30) -> PolyData:
418
"""
419
Create a capsule mesh.
420
421
Parameters:
422
center (tuple): Center point of capsule
423
direction (tuple): Direction vector along capsule axis
424
radius (float): Capsule radius
425
cylinder_length (float): Length of cylindrical section
426
resolution (int): Number of points around circumference
427
428
Returns:
429
PolyData: Capsule mesh
430
"""
431
432
def CylinderStructured(center=(0.0, 0.0, 0.0), direction=(1.0, 0.0, 0.0),
433
radius=0.5, height=1.0, theta_resolution=32,
434
z_resolution=10) -> StructuredGrid:
435
"""
436
Create a structured cylinder grid.
437
438
Parameters:
439
center (tuple): Center point of cylinder
440
direction (tuple): Direction vector for cylinder axis
441
radius (float): Cylinder radius
442
height (float): Cylinder height
443
theta_resolution (int): Circumferential resolution
444
z_resolution (int): Axial resolution
445
446
Returns:
447
StructuredGrid: Structured cylindrical grid
448
"""
449
450
def Wavelet(extent=(-10, 10, -10, 10, -10, 10), center=(0.0, 0.0, 0.0),
451
maximum=255.0, x_freq=60.0, y_freq=30.0, z_freq=40.0,
452
x_mag=10.0, y_mag=18.0, z_mag=5.0, std=0.5,
453
subsample_rate=1) -> ImageData:
454
"""
455
Create a wavelet dataset.
456
457
Parameters:
458
extent (tuple): Data extent (xmin, xmax, ymin, ymax, zmin, zmax)
459
center (tuple): Center point
460
maximum (float): Maximum value
461
x_freq (float): X frequency
462
y_freq (float): Y frequency
463
z_freq (float): Z frequency
464
x_mag (float): X magnitude
465
y_mag (float): Y magnitude
466
z_mag (float): Z magnitude
467
std (float): Standard deviation
468
subsample_rate (int): Subsample rate
469
470
Returns:
471
ImageData: Wavelet dataset
472
"""
473
474
def SolidSphere(radius=0.5, center=(0.0, 0.0, 0.0), u_resolution=6,
475
v_resolution=4, w_resolution=4, start_u=0.0, end_u=6.28318530718,
476
start_v=0.0, end_v=3.14159265359, start_w=0.0,
477
end_w=6.28318530718) -> ImageData:
478
"""
479
Create a solid sphere volume.
480
481
Parameters:
482
radius (float): Sphere radius
483
center (tuple): Center coordinates
484
u_resolution (int): U direction resolution
485
v_resolution (int): V direction resolution
486
w_resolution (int): W direction resolution
487
start_u (float): Start U parameter
488
end_u (float): End U parameter
489
start_v (float): Start V parameter
490
end_v (float): End V parameter
491
start_w (float): Start W parameter
492
end_w (float): End W parameter
493
494
Returns:
495
ImageData: Solid sphere volume
496
"""
497
```
498
499
### Platonic Solids
500
501
Regular polyhedra with equal faces and angles.
502
503
```python { .api }
504
def Tetrahedron(radius=1.0, center=(0.0, 0.0, 0.0)) -> PolyData:
505
"""Create a tetrahedron (4 triangular faces)."""
506
507
def Octahedron(radius=1.0, center=(0.0, 0.0, 0.0)) -> PolyData:
508
"""Create an octahedron (8 triangular faces)."""
509
510
def Dodecahedron(radius=1.0, center=(0.0, 0.0, 0.0)) -> PolyData:
511
"""Create a dodecahedron (12 pentagonal faces)."""
512
513
def Icosahedron(radius=1.0, center=(0.0, 0.0, 0.0)) -> PolyData:
514
"""Create an icosahedron (20 triangular faces)."""
515
516
def Icosphere(radius=1.0, center=(0.0, 0.0, 0.0), nsub=1) -> PolyData:
517
"""
518
Create an icosphere by subdividing an icosahedron.
519
520
Parameters:
521
radius (float): Sphere radius
522
center (tuple): Center coordinates
523
nsub (int): Number of subdivision levels
524
525
Returns:
526
PolyData: Icosphere mesh
527
"""
528
529
def PlatonicSolid(kind='tetrahedron', radius=1.0, center=(0.0, 0.0, 0.0)) -> PolyData:
530
"""
531
Create a platonic solid.
532
533
Parameters:
534
kind (str): Type of solid ('tetrahedron', 'cube', 'octahedron', 'icosahedron', 'dodecahedron')
535
radius (float): Circumscribed radius
536
center (tuple): Center coordinates
537
538
Returns:
539
PolyData: Platonic solid mesh
540
"""
541
```
542
543
### Parametric Surfaces
544
545
Mathematical parametric surfaces for advanced geometric modeling.
546
547
```python { .api }
548
def ParametricTorus(ringradius=1.0, crosssectionradius=0.2, u_res=50,
549
v_res=50, u_min=0.0, u_max=6.283185307179586,
550
v_min=0.0, v_max=6.283185307179586) -> PolyData:
551
"""Create a parametric torus surface."""
552
553
def ParametricEllipsoid(xradius=1.0, yradius=1.0, zradius=1.0, u_res=50,
554
v_res=50, u_min=0.0, u_max=6.283185307179586,
555
v_min=0.0, v_max=3.141592653589793) -> PolyData:
556
"""Create a parametric ellipsoid surface."""
557
558
def ParametricKlein(u_res=50, v_res=50, u_min=0.0, u_max=6.283185307179586,
559
v_min=0.0, v_max=6.283185307179586) -> PolyData:
560
"""Create a Klein bottle surface."""
561
562
def ParametricBoy(zscale=1.0, u_res=50, v_res=50, u_min=0.0,
563
u_max=3.141592653589793, v_min=0.0,
564
v_max=3.141592653589793) -> PolyData:
565
"""Create a Boy's surface."""
566
567
def ParametricBohemianDome(u_res=50, v_res=50) -> PolyData:
568
"""Create a Bohemian dome surface."""
569
570
def ParametricBour(u_res=50, v_res=50) -> PolyData:
571
"""Create a Bour surface."""
572
573
def ParametricCatalanMinimal(u_res=50, v_res=50) -> PolyData:
574
"""Create a Catalan minimal surface."""
575
576
def ParametricConicSpiral(u_res=50, v_res=50) -> PolyData:
577
"""Create a conic spiral surface."""
578
579
def ParametricCrossCap(u_res=50, v_res=50) -> PolyData:
580
"""Create a cross cap surface."""
581
582
def ParametricDini(a=1.0, b=0.2, u_res=50, v_res=50) -> PolyData:
583
"""Create a Dini surface."""
584
585
def ParametricEnneper(u_res=50, v_res=50) -> PolyData:
586
"""Create an Enneper surface."""
587
588
def ParametricFigure8Klein(radius=1.0, u_res=50, v_res=50) -> PolyData:
589
"""Create a Figure-8 Klein bottle."""
590
591
def ParametricHenneberg(u_res=50, v_res=50) -> PolyData:
592
"""Create a Henneberg surface."""
593
594
def ParametricKuen(deltav0=0.001, u_res=50, v_res=50) -> PolyData:
595
"""Create a Kuen surface."""
596
597
def ParametricMobius(radius=1.0, u_res=50, v_res=50) -> PolyData:
598
"""Create a Mobius strip."""
599
600
def ParametricPluckerConoid(n=2, u_res=50, v_res=50) -> PolyData:
601
"""Create a Plucker conoid."""
602
603
def ParametricPseudosphere(u_res=50, v_res=50) -> PolyData:
604
"""Create a pseudosphere."""
605
606
def ParametricRandomHills(u_res=50, v_res=50) -> PolyData:
607
"""Create a random hills surface."""
608
609
def ParametricRoman(radius=1.0, u_res=50, v_res=50) -> PolyData:
610
"""Create a Roman surface."""
611
612
def ParametricSuperEllipsoid(u_res=50, v_res=50) -> PolyData:
613
"""Create a super ellipsoid."""
614
615
def ParametricSuperToroid(u_res=50, v_res=50) -> PolyData:
616
"""Create a super toroid."""
617
```
618
619
### Splines and Curves
620
621
Curve generation and spline interpolation.
622
623
```python { .api }
624
def Spline(points, n_points=None) -> PolyData:
625
"""
626
Create a spline through given points.
627
628
Parameters:
629
points (array-like): Control points for spline
630
n_points (int): Number of points in output spline
631
632
Returns:
633
PolyData: Spline curve
634
"""
635
636
def KochanekSpline(points, tension=0.0, bias=0.0, continuity=0.0,
637
n_points=None) -> PolyData:
638
"""
639
Create a Kochanek spline with tension, bias, and continuity control.
640
641
Parameters:
642
points (array-like): Control points
643
tension (float): Tension parameter
644
bias (float): Bias parameter
645
continuity (float): Continuity parameter
646
n_points (int): Number of output points
647
648
Returns:
649
PolyData: Kochanek spline curve
650
"""
651
```
652
653
## Usage Examples
654
655
### Creating basic shapes
656
657
```python
658
import pyvista as pv
659
660
# Create various geometric primitives
661
sphere = pv.Sphere(radius=1.0, theta_resolution=50, phi_resolution=50)
662
cube = pv.Cube(x_length=2.0, y_length=2.0, z_length=2.0)
663
cylinder = pv.Cylinder(radius=0.5, height=2.0, resolution=20)
664
cone = pv.Cone(radius=1.0, height=2.0, resolution=20)
665
666
# Plot multiple objects
667
plotter = pv.Plotter(shape=(2, 2))
668
plotter.subplot(0, 0)
669
plotter.add_mesh(sphere, color='red')
670
plotter.subplot(0, 1)
671
plotter.add_mesh(cube, color='blue')
672
plotter.subplot(1, 0)
673
plotter.add_mesh(cylinder, color='green')
674
plotter.subplot(1, 1)
675
plotter.add_mesh(cone, color='yellow')
676
plotter.show()
677
```
678
679
### Creating parametric surfaces
680
681
```python
682
import pyvista as pv
683
684
# Create various parametric surfaces
685
torus = pv.ParametricTorus(ringradius=2.0, crosssectionradius=0.5)
686
klein = pv.ParametricKlein()
687
boy = pv.ParametricBoy()
688
689
# Add some coloring based on coordinates
690
torus['x'] = torus.points[:, 0]
691
klein['y'] = klein.points[:, 1]
692
boy['z'] = boy.points[:, 2]
693
694
# Plot with different colormaps
695
plotter = pv.Plotter(shape=(1, 3))
696
plotter.subplot(0, 0)
697
plotter.add_mesh(torus, scalars='x', cmap='coolwarm')
698
plotter.subplot(0, 1)
699
plotter.add_mesh(klein, scalars='y', cmap='plasma')
700
plotter.subplot(0, 2)
701
plotter.add_mesh(boy, scalars='z', cmap='viridis')
702
plotter.show()
703
```