0
# Shape Classes and Entity Types
1
2
Comprehensive documentation of all shape classes used in pygmsh, covering both geometric entities created through operations and primitive shape classes with their constructors, attributes, and usage patterns.
3
4
## Common Shape Attributes
5
6
All shape objects in pygmsh share common attributes that provide metadata and enable geometric operations:
7
8
```python { .api }
9
# Universal attributes for all shapes
10
shape.dim: int # Shape dimension (0=point, 1=curve, 2=surface, 3=volume)
11
shape._id: int # Internal GMSH entity ID
12
shape.dim_tag: tuple # (dimension, tag) tuple for GMSH operations
13
shape.dim_tags: list # List of (dimension, tag) tuples for compound shapes
14
```
15
16
## Basic Geometric Entities
17
18
### Point Class
19
20
Elementary point entities representing locations in 3D space with optional mesh size specification.
21
22
```python { .api }
23
class Point:
24
"""
25
Elementary point in 3D space.
26
27
Points serve as building blocks for all higher-dimensional entities
28
and can specify local mesh sizing constraints.
29
"""
30
31
def __init__(self, env, x, mesh_size=None):
32
"""
33
Initialize point entity.
34
35
Parameters:
36
- env: geometry environment (automatically provided)
37
- x: list[float], coordinates [x, y, z]
38
- mesh_size: float, optional element size constraint at point
39
40
Attributes:
41
- x: array, point coordinates
42
- dim: int = 0
43
- _id: int, internal GMSH point ID
44
- dim_tag: tuple, (0, point_id)
45
- dim_tags: list, [(0, point_id)]
46
"""
47
```
48
49
### Line Class
50
51
Line segments connecting two points, forming the basis for curve construction.
52
53
```python { .api }
54
class Line:
55
"""
56
Line segment between two points.
57
58
Lines are fundamental 1D entities used to construct complex curves,
59
curve loops, and surface boundaries.
60
"""
61
62
def __init__(self, env, p0, p1):
63
"""
64
Initialize line segment.
65
66
Parameters:
67
- env: geometry environment (automatically provided)
68
- p0: Point, start point
69
- p1: Point, end point
70
71
Attributes:
72
- points: list[Point], [start_point, end_point]
73
- dim: int = 1
74
- _id: int, internal GMSH line ID
75
- dim_tag: tuple, (1, line_id)
76
- dim_tags: list, [(1, line_id)]
77
"""
78
```
79
80
### Polygon Class
81
82
Multi-sided closed shapes with optional holes and automatic surface generation.
83
84
```python { .api }
85
class Polygon:
86
"""
87
Polygon with optional holes and surface generation.
88
89
Polygons automatically generate curve loops and surfaces, supporting
90
complex shapes with internal holes and custom mesh sizing.
91
"""
92
93
def __init__(self, host, points, mesh_size=None, holes=None, make_surface=True):
94
"""
95
Initialize polygon shape.
96
97
Parameters:
98
- host: geometry environment (automatically provided)
99
- points: list[list[float]], vertex coordinates [[x1,y1,z1], [x2,y2,z2], ...]
100
- mesh_size: float, optional element size for polygon boundary
101
- holes: list[CurveLoop], optional holes to subtract from polygon
102
- make_surface: bool, create surface from polygon boundary
103
104
Attributes:
105
- points: list[Point], polygon vertices
106
- curves: list[Line], polygon edges
107
- lines: list[Line], alias for curves
108
- curve_loop: CurveLoop, closed boundary
109
- surface: Surface, polygon surface (if make_surface=True)
110
- dim: int = 2 (if surface created), 1 (if curve only)
111
- _id: int, internal GMSH entity ID
112
- dim_tag: tuple, (dim, entity_id)
113
- dim_tags: list, entity dimension tags
114
"""
115
```
116
117
### Surface Class
118
119
2D entities created from curve loops, representing bounded regions.
120
121
```python { .api }
122
class Surface:
123
"""
124
Surface generated from curve loop.
125
126
Surfaces represent 2D regions bounded by closed curves,
127
forming the basis for 3D volume construction and 2D meshing.
128
"""
129
130
def __init__(self, env, curve_loop):
131
"""
132
Initialize surface entity.
133
134
Parameters:
135
- env: geometry environment (automatically provided)
136
- curve_loop: CurveLoop, boundary defining surface
137
138
Attributes:
139
- dim: int = 2
140
- _id: int, internal GMSH surface ID
141
- dim_tag: tuple, (2, surface_id)
142
- dim_tags: list, [(2, surface_id)]
143
"""
144
```
145
146
### Volume Class
147
148
3D entities created from surface loops, representing solid regions.
149
150
```python { .api }
151
class Volume:
152
"""
153
Volume from surface loop.
154
155
Volumes represent 3D regions bounded by closed surfaces,
156
used for solid meshing and 3D finite element analysis.
157
"""
158
159
def __init__(self, env, surface_loop):
160
"""
161
Initialize volume entity.
162
163
Parameters:
164
- env: geometry environment (automatically provided)
165
- surface_loop: SurfaceLoop, boundary defining volume
166
167
Attributes:
168
- dim: int = 3
169
- _id: int, internal GMSH volume ID
170
- dim_tag: tuple, (3, volume_id)
171
- dim_tags: list, [(3, volume_id)]
172
"""
173
```
174
175
## OpenCASCADE Primitive Shapes
176
177
### Ball Class
178
179
Spherical shapes with optional angular restrictions for creating sphere segments.
180
181
```python { .api }
182
class Ball:
183
"""
184
Sphere with optional angular cuts.
185
186
Creates spherical volumes with full control over angular extents,
187
enabling creation of sphere segments and hemispheres.
188
"""
189
190
def __init__(self, center, radius, angle1=-π/2, angle2=π/2, angle3=2π):
191
"""
192
Initialize ball/sphere.
193
194
Parameters:
195
- center: list[float], sphere center coordinates [x, y, z]
196
- radius: float, sphere radius
197
- angle1: float, minimum polar angle (default: -π/2, south pole)
198
- angle2: float, maximum polar angle (default: π/2, north pole)
199
- angle3: float, azimuthal angle span (default: 2π, full rotation)
200
201
Attributes:
202
- center: array, sphere center
203
- radius: float, sphere radius
204
- dim: int = 3
205
- _id: int, internal GMSH volume ID
206
- dim_tag: tuple, (3, volume_id)
207
- dim_tags: list, [(3, volume_id)]
208
"""
209
```
210
211
### Box Class
212
213
Rectangular boxes with specified corner and extent dimensions.
214
215
```python { .api }
216
class Box:
217
"""
218
Rectangular box.
219
220
Creates axis-aligned rectangular volumes with specified corner
221
position and extent dimensions.
222
"""
223
224
def __init__(self, x0, extents, char_length=None):
225
"""
226
Initialize rectangular box.
227
228
Parameters:
229
- x0: list[float], corner point coordinates [x, y, z]
230
- extents: list[float], box dimensions [dx, dy, dz]
231
- char_length: float, deprecated (use mesh_size in add_box)
232
233
Attributes:
234
- x0: array, corner coordinates
235
- extents: array, box dimensions
236
- dim: int = 3
237
- _id: int, internal GMSH volume ID
238
- dim_tag: tuple, (3, volume_id)
239
- dim_tags: list, [(3, volume_id)]
240
"""
241
```
242
243
### Cylinder Class
244
245
Cylindrical shapes with optional angular openings for creating cylinder segments.
246
247
```python { .api }
248
class Cylinder:
249
"""
250
Cylinder with optional angular opening.
251
252
Creates cylindrical volumes with full control over axis direction
253
and angular extent, enabling creation of cylinder segments.
254
"""
255
256
def __init__(self, x0, axis, radius, angle=2π):
257
"""
258
Initialize cylinder.
259
260
Parameters:
261
- x0: list[float], base center coordinates [x, y, z]
262
- axis: list[float], cylinder axis direction vector [dx, dy, dz]
263
- radius: float, cylinder radius
264
- angle: float, angular opening (default: 2π, full cylinder)
265
266
Attributes:
267
- x0: array, base center
268
- axis: array, axis direction
269
- radius: float, cylinder radius
270
- angle: float, angular opening
271
- dim: int = 3
272
- _id: int, internal GMSH volume ID
273
- dim_tag: tuple, (3, volume_id)
274
- dim_tags: list, [(3, volume_id)]
275
"""
276
```
277
278
### Cone Class
279
280
Conical shapes with different top and bottom radii for creating cones and truncated cones.
281
282
```python { .api }
283
class Cone:
284
"""
285
Cone with different top and bottom radii.
286
287
Creates conical volumes with independent control over base and top radii,
288
enabling creation of full cones, truncated cones, and tapered cylinders.
289
"""
290
291
def __init__(self, center, axis, radius0, radius1, angle=2π):
292
"""
293
Initialize cone.
294
295
Parameters:
296
- center: list[float], base center coordinates [x, y, z]
297
- axis: list[float], cone axis direction vector [dx, dy, dz]
298
- radius0: float, base radius
299
- radius1: float, top radius
300
- angle: float, angular opening (default: 2π, full cone)
301
302
Attributes:
303
- center: array, base center
304
- axis: array, axis direction
305
- radius0: float, base radius
306
- radius1: float, top radius
307
- dim: int = 3
308
- _id: int, internal GMSH volume ID
309
- dim_tag: tuple, (3, volume_id)
310
- dim_tags: list, [(3, volume_id)]
311
"""
312
```
313
314
### Disk Class
315
316
Circular or elliptical flat shapes for creating 2D disk geometries.
317
318
```python { .api }
319
class Disk:
320
"""
321
Disk or ellipse.
322
323
Creates 2D circular or elliptical surfaces with optional
324
second radius for ellipse creation.
325
"""
326
327
def __init__(self, x0, radius0, radius1=None):
328
"""
329
Initialize disk or ellipse.
330
331
Parameters:
332
- x0: list[float], center coordinates [x, y, z]
333
- radius0: float, primary radius (or circle radius if radius1=None)
334
- radius1: float, secondary radius for ellipse (optional)
335
336
Attributes:
337
- x0: array, center coordinates
338
- radius0: float, primary radius
339
- radius1: float, secondary radius (None for circle)
340
- dim: int = 2
341
- _id: int, internal GMSH surface ID
342
- dim_tag: tuple, (2, surface_id)
343
- dim_tags: list, [(2, surface_id)]
344
"""
345
```
346
347
### Torus Class
348
349
Toroidal shapes with major and minor radii and optional angular restrictions.
350
351
```python { .api }
352
class Torus:
353
"""
354
Torus with major and minor radii.
355
356
Creates toroidal volumes with independent control over tube radius
357
and torus radius, with optional angular restrictions.
358
"""
359
360
def __init__(self, center, radius0, radius1, alpha=2π):
361
"""
362
Initialize torus.
363
364
Parameters:
365
- center: list[float], torus center coordinates [x, y, z]
366
- radius0: float, minor radius (tube radius)
367
- radius1: float, major radius (center to tube center distance)
368
- alpha: float, angular span around major radius (default: 2π)
369
370
Attributes:
371
- center: array, torus center
372
- radius0: float, minor radius
373
- radius1: float, major radius
374
- alpha: float, angular span
375
- dim: int = 3
376
- _id: int, internal GMSH volume ID
377
- dim_tag: tuple, (3, volume_id)
378
- dim_tags: list, [(3, volume_id)]
379
"""
380
```
381
382
### Wedge Class
383
384
Right angular wedge shapes for creating prismatic volumes with triangular cross-sections.
385
386
```python { .api }
387
class Wedge:
388
"""
389
Right angular wedge.
390
391
Creates wedge-shaped volumes with triangular cross-section,
392
optionally tapered for complex prismatic shapes.
393
"""
394
395
def __init__(self, x0, extents, top_extent=None):
396
"""
397
Initialize wedge.
398
399
Parameters:
400
- x0: list[float], corner coordinates [x, y, z]
401
- extents: list[float], base dimensions [dx, dy, dz]
402
- top_extent: list[float], optional top dimensions for tapered wedge
403
404
Attributes:
405
- x0: array, corner coordinates
406
- extents: array, base dimensions
407
- top_extent: array, top dimensions (None for uniform wedge)
408
- dim: int = 3
409
- _id: int, internal GMSH volume ID
410
- dim_tags: list, [(3, volume_id)]
411
"""
412
```
413
414
### Rectangle Class
415
416
2D rectangular shapes with optional corner rounding for creating planar rectangular regions.
417
418
```python { .api }
419
class Rectangle:
420
"""
421
2D rectangle with optional corner rounding.
422
423
Creates rectangular surfaces with optional rounded corners
424
for smoother geometric transitions.
425
"""
426
427
def __init__(self, x0, a, b, corner_radius=None):
428
"""
429
Initialize rectangle.
430
431
Parameters:
432
- x0: list[float], corner coordinates [x, y, z]
433
- a: float, width dimension
434
- b: float, height dimension
435
- corner_radius: float, optional corner rounding radius
436
437
Attributes:
438
- x0: array, corner coordinates
439
- a: float, width
440
- b: float, height
441
- corner_radius: float, corner radius (None for sharp corners)
442
- dim: int = 2
443
- _id: int, internal GMSH surface ID
444
- dim_tag: tuple, (2, surface_id)
445
- dim_tags: list, [(2, surface_id)]
446
"""
447
```
448
449
## Usage Examples
450
451
### Creating Custom Shapes with Detailed Attributes
452
453
```python
454
import pygmsh
455
456
with pygmsh.occ.Geometry() as geom:
457
# Create a complex assembly using various shape classes
458
459
# Main body as a box
460
main_box = geom.add_box([0, 0, 0], [2, 1, 0.5])
461
print(f"Box ID: {main_box._id}, Dimension: {main_box.dim}")
462
print(f"Box dim_tag: {main_box.dim_tag}")
463
464
# Cylinder for hole
465
hole_cyl = geom.add_cylinder([1, 0.5, -0.1], [0, 0, 0.7], 0.2)
466
print(f"Cylinder attributes: dim={hole_cyl.dim}, center={hole_cyl.x0}")
467
468
# Create assembly with boolean operations
469
result = geom.boolean_difference(main_box, hole_cyl)
470
print(f"Result shape tags: {result.dim_tags}")
471
472
mesh = geom.generate_mesh(dim=3)
473
```
474
475
### Working with Shape Collections
476
477
```python
478
import pygmsh
479
480
with pygmsh.geo.Geometry() as geom:
481
# Create multiple shapes and manage as collection
482
shapes = []
483
484
for i, radius in enumerate([0.1, 0.15, 0.2]):
485
circle = geom.add_circle([i * 0.5, 0, 0], radius, mesh_size=0.02)
486
shapes.append(circle)
487
488
# Access shape properties
489
print(f"Circle {i}: ID={circle._id}, radius={radius}")
490
print(f" Points: {[p.x for p in circle.points]}")
491
print(f" Curves: {[c._id for c in circle.curves]}")
492
493
if hasattr(circle, 'surface') and circle.surface:
494
print(f" Surface ID: {circle.surface._id}")
495
496
mesh = geom.generate_mesh(dim=2)
497
```
498
499
### Advanced Shape Manipulation
500
501
```python
502
import pygmsh
503
import numpy as np
504
505
with pygmsh.occ.Geometry() as geom:
506
# Create parametric shape family
507
shapes = []
508
509
for i in range(3):
510
# Create torus with varying parameters
511
center = [i * 3, 0, 0]
512
minor_r = 0.3 + i * 0.1
513
major_r = 0.8 + i * 0.2
514
515
torus = geom.add_torus(center, minor_r, major_r, alpha=np.pi * (1.5 + i * 0.2))
516
shapes.append(torus)
517
518
# Print detailed torus information
519
print(f"Torus {i}:")
520
print(f" Center: {torus.center}")
521
print(f" Minor radius: {torus.radius0}")
522
print(f" Major radius: {torus.radius1}")
523
print(f" Angular span: {torus.alpha:.2f} rad ({torus.alpha*180/np.pi:.1f}°)")
524
print(f" GMSH tags: {torus.dim_tags}")
525
526
# Union all toruses
527
if len(shapes) > 1:
528
union_result = geom.boolean_union(shapes)
529
print(f"Union result tags: {union_result.dim_tags}")
530
531
mesh = geom.generate_mesh(dim=3)
532
```