0
# OpenCASCADE Solid Modeling
1

2
The OpenCASCADE geometry kernel (`pygmsh.occ`) provides advanced solid modeling capabilities with boolean operations, primitive shapes, BREP operations, and CAD file import/export. This kernel leverages the full power of OpenCASCADE for complex geometric operations and robust solid modeling workflows.
3

4
## Capabilities
5

6
### Primitive Shape Creation
7

8
Create fundamental 3D shapes that serve as building blocks for complex geometries. All primitive shapes support optional mesh size specification and return geometry objects suitable for boolean operations.
9

10
```python { .api }
11
def add_ball(*args, mesh_size=None, **kwargs):
12
    """
13
    Create a sphere with optional angular cuts.
14
    
15
    Parameters from Ball constructor:
16
    - center: list[float], sphere center coordinates [x, y, z]
17
    - radius: float, sphere radius
18
    - angle1: float, minimum polar angle (default: -π/2)
19
    - angle2: float, maximum polar angle (default: π/2)  
20
    - angle3: float, azimuthal angle span (default: 2π)
21
    - mesh_size: float, optional mesh size at sphere surface
22
    
23
    Returns:
24
    Ball object representing the sphere geometry
25
    """
26

27
def add_box(*args, mesh_size=None, **kwargs):
28
    """
29
    Create a rectangular box.
30
    
31
    Parameters from Box constructor:
32
    - x0: list[float], corner point coordinates [x, y, z]
33
    - extents: list[float], box dimensions [dx, dy, dz]
34
    - char_length: float, optional characteristic length (deprecated, use mesh_size)
35
    - mesh_size: float, optional mesh size at box surfaces
36
    
37
    Returns:
38
    Box object representing the rectangular box geometry
39
    """
40

41
def add_cone(*args, mesh_size=None, **kwargs):
42
    """
43
    Create a cone with different top and bottom radii.
44
    
45
    Parameters from Cone constructor:
46
    - center: list[float], cone base center coordinates [x, y, z]
47
    - axis: list[float], cone axis direction vector [dx, dy, dz]
48
    - radius0: float, base radius
49
    - radius1: float, top radius
50
    - angle: float, angular opening (default: 2π for full cone)
51
    - mesh_size: float, optional mesh size at cone surface
52
    
53
    Returns:
54
    Cone object representing the cone geometry
55
    """
56

57
def add_cylinder(*args, mesh_size=None, **kwargs):
58
    """
59
    Create a cylinder with optional angular opening.
60
    
61
    Parameters from Cylinder constructor:
62
    - x0: list[float], cylinder base center coordinates [x, y, z]
63
    - axis: list[float], cylinder axis direction vector [dx, dy, dz]
64
    - radius: float, cylinder radius
65
    - angle: float, angular opening (default: 2π for full cylinder)
66
    - mesh_size: float, optional mesh size at cylinder surface
67
    
68
    Returns:
69
    Cylinder object representing the cylinder geometry
70
    """
71

72
def add_disk(*args, mesh_size=None, **kwargs):
73
    """
74
    Create a disk or ellipse.
75
    
76
    Parameters from Disk constructor:
77
    - x0: list[float], disk center coordinates [x, y, z]
78
    - radius0: float, first radius (for circle) or X-axis radius (for ellipse)
79
    - radius1: float, optional second radius for ellipse (default: None for circle)
80
    - mesh_size: float, optional mesh size at disk boundary
81
    
82
    Returns:
83
    Disk object representing the disk or ellipse geometry
84
    """
85

86
def add_rectangle(*args, mesh_size=None, **kwargs):
87
    """
88
    Create a rectangle with optional rounded corners.
89
    
90
    Parameters from Rectangle constructor:
91
    - x0: list[float], rectangle corner coordinates [x, y, z]
92
    - a: float, width in X direction
93
    - b: float, height in Y direction  
94
    - corner_radius: float, optional corner radius for rounded rectangle
95
    - mesh_size: float, optional mesh size at rectangle boundary
96
    
97
    Returns:
98
    Rectangle object representing the rectangle geometry
99
    """
100

101
def add_torus(*args, mesh_size=None, **kwargs):
102
    """
103
    Create a torus with inner and outer radii.
104
    
105
    Parameters from Torus constructor:
106
    - center: list[float], torus center coordinates [x, y, z]
107
    - radius0: float, minor radius (tube radius)
108
    - radius1: float, major radius (distance from center to tube center)
109
    - alpha: float, angular span (default: 2π for full torus)
110
    - mesh_size: float, optional mesh size at torus surface
111
    
112
    Returns:
113
    Torus object representing the torus geometry
114
    """
115

116
def add_wedge(*args, mesh_size=None, **kwargs):
117
    """
118
    Create a right angular wedge.
119
    
120
    Parameters from Wedge constructor:
121
    - x0: list[float], wedge corner coordinates [x, y, z]
122
    - extents: list[float], wedge dimensions [dx, dy, dz]
123
    - top_extent: list[float], optional different top dimensions for tapered wedge
124
    - mesh_size: float, optional mesh size at wedge surfaces
125
    
126
    Returns:
127
    Wedge object representing the wedge geometry
128
    """
129

130
def add_ellipsoid(center, radii, mesh_size=None):
131
    """
132
    Create an ellipsoid with specified radii in each direction.
133
    
134
    Parameters:
135
    - center: list[float], ellipsoid center coordinates [x, y, z]
136
    - radii: list[float], radii in [x, y, z] directions [rx, ry, rz]
137
    - mesh_size: float, optional mesh size at ellipsoid surface
138
    
139
    Returns:
140
    Ellipsoid object representing the ellipsoid geometry
141
    """
142
```
143

144
### Boolean Operations
145

146
Perform robust solid modeling operations to combine, intersect, and subtract geometries. These operations form the foundation of complex solid modeling workflows.
147

148
```python { .api }
149
def boolean_intersection(entities, delete_first=True, delete_other=True):
150
    """
151
    Compute boolean intersection of multiple entities.
152
    
153
    Parameters:
154
    - entities: list, geometry entities to intersect
155
    - delete_first: bool, delete first entity after operation (default: True)
156
    - delete_other: bool, delete other entities after operation (default: True)
157
    
158
    Returns:
159
    New geometry object representing the intersection
160
    """
161

162
def boolean_union(entities, delete_first=True, delete_other=True):
163
    """
164
    Compute boolean union of multiple entities.
165
    
166
    Parameters:
167
    - entities: list, geometry entities to unite
168
    - delete_first: bool, delete first entity after operation (default: True)
169
    - delete_other: bool, delete other entities after operation (default: True)
170
    
171
    Returns:
172
    New geometry object representing the union
173
    """
174

175
def boolean_difference(d0, d1, delete_first=True, delete_other=True):
176
    """
177
    Compute boolean difference (d0 - d1).
178
    
179
    Parameters:
180
    - d0: geometry entity (minuend)
181
    - d1: geometry entity or list of entities (subtrahend)
182
    - delete_first: bool, delete first entity after operation (default: True)
183
    - delete_other: bool, delete other entities after operation (default: True)
184
    
185
    Returns:
186
    New geometry object representing d0 with d1 subtracted
187
    """
188

189
def boolean_fragments(d0, d1, delete_first=True, delete_other=True):
190
    """
191
    Compute boolean fragments (partition entities into non-overlapping pieces).
192
    
193
    Parameters:
194
    - d0: geometry entity or list of entities
195
    - d1: geometry entity or list of entities
196
    - delete_first: bool, delete first entities after operation (default: True)
197
    - delete_other: bool, delete other entities after operation (default: True)
198
    
199
    Returns:
200
    List of geometry objects representing the fragments
201
    """
202
```
203

204
### Mesh Control Properties
205

206
Control mesh generation parameters specific to the OpenCASCADE kernel through geometry properties.
207

208
```python { .api }
209
@property
210
def characteristic_length_min():
211
    """
212
    Get minimum characteristic length for mesh generation.
213
    
214
    Returns:
215
    float: Current minimum characteristic length value
216
    """
217

218
@characteristic_length_min.setter
219
def characteristic_length_min(val):
220
    """
221
    Set minimum characteristic length for mesh generation.
222
    
223
    Parameters:
224
    - val: float, minimum characteristic length
225
    """
226

227
@property  
228
def characteristic_length_max():
229
    """
230
    Get maximum characteristic length for mesh generation.
231
    
232
    Returns:
233
    float: Current maximum characteristic length value
234
    """
235

236
@characteristic_length_max.setter
237
def characteristic_length_max(val):
238
    """
239
    Set maximum characteristic length for mesh generation.
240
    
241
    Parameters:
242
    - val: float, maximum characteristic length
243
    """
244
```
245

246
### Advanced Operations
247

248
Perform advanced solid modeling operations including revolution, CAD import/export, and surface normal correction.
249

250
```python { .api }
251
def revolve(*args, **kwargs):
252
    """
253
    Revolve entity around axis to create surfaces or volumes.
254
    
255
    Note: For occ kernel, revolution angle must be < 2π (360 degrees).
256
    
257
    Parameters depend on input entity type:
258
    - input_entity: curve, surface, or volume to revolve
259
    - point_on_axis: point on revolution axis
260
    - axis_direction: revolution axis direction vector
261
    - angle: revolution angle in radians (must be < 2π)
262
    
263
    Returns:
264
    Revolved entity (surface from curve, volume from surface)
265
    """
266

267
def import_shapes(filename):
268
    """
269
    Import shapes from CAD files (STEP, IGES, BREP, etc.).
270
    
271
    Parameters:
272
    - filename: str, path to CAD file to import
273
    
274
    Returns:
275
    List of imported geometry objects
276
    """
277

278
def force_outward_normals(tag):
279
    """
280
    Force outward orientation of surface normals.
281
    
282
    Parameters:
283
    - tag: int, surface tag to correct normals
284
    
285
    Returns:
286
    None (modifies surface in-place)
287
    """
288
```
289

290
## Usage Examples
291

292
### Creating Complex Geometry with Boolean Operations
293

294
```python
295
import pygmsh
296

297
with pygmsh.occ.Geometry() as geom:
298
    # Create primary shapes
299
    main_box = geom.add_box([0, 0, 0], [2, 2, 2])
300
    
301
    # Create holes
302
    hole1 = geom.add_cylinder([0.5, 0.5, -0.1], [0, 0, 1], 0.2)
303
    hole2 = geom.add_cylinder([1.5, 1.5, -0.1], [0, 0, 1], 0.2)
304
    
305
    # Create final geometry with boolean operations
306
    box_with_holes = geom.boolean_difference(main_box, [hole1, hole2])
307
    
308
    # Add a protruding feature
309
    protrusion = geom.add_cylinder([1, 1, 2], [0, 0, 1], 0.3)
310
    final_shape = geom.boolean_union([box_with_holes, protrusion])
311
    
312
    mesh = geom.generate_mesh(dim=3)
313
```
314

315
### Working with Imported CAD Geometry
316

317
```python
318
import pygmsh
319

320
with pygmsh.occ.Geometry() as geom:
321
    # Import shapes from CAD file
322
    imported_shapes = geom.import_shapes("mechanical_part.step")
323
    
324
    # Create additional geometry
325
    mounting_holes = [
326
        geom.add_cylinder([x, y, -1], [0, 0, 1], 0.1)
327
        for x, y in [(10, 10), (50, 10), (50, 50), (10, 50)]
328
    ]
329
    
330
    # Subtract mounting holes from imported geometry
331
    final_part = geom.boolean_difference(imported_shapes[0], mounting_holes)
332
    
333
    # Force outward normals for proper meshing
334
    geom.force_outward_normals(final_part.id)
335
    
336
    mesh = geom.generate_mesh(dim=3)
337
```
338

339
### Precision Control for Complex Geometries
340

341
```python
342
import pygmsh
343

344
with pygmsh.occ.Geometry() as geom:
345
    # Set mesh size bounds for complex geometry
346
    geom.characteristic_length_min = 0.01
347
    geom.characteristic_length_max = 1.0
348
    
349
    # Create geometry with varying feature sizes
350
    large_sphere = geom.add_ball([0, 0, 0], 10.0, mesh_size=1.0)
351
    
352
    small_features = [
353
        geom.add_ball([x, 0, 0], 0.5, mesh_size=0.05)
354
        for x in [-8, -4, 4, 8]
355
    ]
356
    
357
    # Boolean union with automatic mesh size transition
358
    complex_geometry = geom.boolean_union([large_sphere] + small_features)
359
    
360
    mesh = geom.generate_mesh(dim=3)
361
```
362

363
## Primitive Shape Classes
364

365
### Ball Class
366

367
```python { .api }
368
class Ball:
369
    """Sphere with optional angular cuts."""
370
    
371
    def __init__(self, center, radius, angle1=-π/2, angle2=π/2, angle3=2π):
372
        """
373
        Initialize sphere.
374
        
375
        Parameters:
376
        - center: list[float], sphere center [x, y, z]
377
        - radius: float, sphere radius
378
        - angle1: float, minimum polar angle (default: -π/2)
379
        - angle2: float, maximum polar angle (default: π/2)
380
        - angle3: float, azimuthal span (default: 2π)
381
        """
382
```
383

384
### Box Class
385

386
```python { .api }
387
class Box:
388
    """Rectangular box."""
389
    
390
    def __init__(self, x0, extents, char_length=None):
391
        """
392
        Initialize rectangular box.
393
        
394
        Parameters:
395
        - x0: list[float], corner coordinates [x, y, z]
396
        - extents: list[float], dimensions [dx, dy, dz]
397
        - char_length: float, optional characteristic length (deprecated)
398
        """
399
```
400

401
### Cone Class
402

403
```python { .api }
404
class Cone:
405
    """Cone with different top and bottom radii."""
406
    
407
    def __init__(self, center, axis, radius0, radius1, angle=2π):
408
        """
409
        Initialize cone.
410
        
411
        Parameters:
412
        - center: list[float], base center [x, y, z]
413
        - axis: list[float], axis direction [dx, dy, dz]
414
        - radius0: float, base radius
415
        - radius1: float, top radius
416
        - angle: float, angular opening (default: 2π)
417
        """
418
```
419

420
### Cylinder Class
421

422
```python { .api }
423
class Cylinder:
424
    """Cylinder with optional angular opening."""
425
    
426
    def __init__(self, x0, axis, radius, angle=2π):
427
        """
428
        Initialize cylinder.
429
        
430
        Parameters:
431
        - x0: list[float], base center [x, y, z]
432
        - axis: list[float], axis direction [dx, dy, dz]
433
        - radius: float, cylinder radius
434
        - angle: float, angular opening (default: 2π)
435
        """
436
```
437

438
### Disk Class
439

440
```python { .api }
441
class Disk:
442
    """Disk or ellipse."""
443
    
444
    def __init__(self, x0, radius0, radius1=None):
445
        """
446
        Initialize disk or ellipse.
447
        
448
        Parameters:
449
        - x0: list[float], center coordinates [x, y, z]
450
        - radius0: float, first radius
451
        - radius1: float, optional second radius for ellipse
452
        """
453
```
454

455
### Rectangle Class
456

457
```python { .api }
458
class Rectangle:
459
    """Rectangle with optional rounded corners."""
460
    
461
    def __init__(self, x0, a, b, corner_radius=None):
462
        """
463
        Initialize rectangle.
464
        
465
        Parameters:
466
        - x0: list[float], corner coordinates [x, y, z]
467
        - a: float, width in X direction
468
        - b: float, height in Y direction
469
        - corner_radius: float, optional corner radius
470
        """
471
```
472

473
### Torus Class
474

475
```python { .api }
476
class Torus:
477
    """Torus with inner and outer radii."""
478
    
479
    def __init__(self, center, radius0, radius1, alpha=2π):
480
        """
481
        Initialize torus.
482
        
483
        Parameters:
484
        - center: list[float], torus center [x, y, z]
485
        - radius0: float, minor radius (tube radius)
486
        - radius1: float, major radius (center to tube center)
487
        - alpha: float, angular span (default: 2π)
488
        """
489
```
490

491
### Wedge Class
492

493
```python { .api }
494
class Wedge:
495
    """Right angular wedge."""
496
    
497
    def __init__(self, x0, extents, top_extent=None):
498
        """
499
        Initialize wedge.
500
        
501
        Parameters:
502
        - x0: list[float], corner coordinates [x, y, z]
503
        - extents: list[float], base dimensions [dx, dy, dz]
504
        - top_extent: list[float], optional top dimensions for tapered wedge
505
        """
506
```
507

508
### Common Shape Attributes
509

510
All OCC shape classes share the following attributes after creation:
511

512
```python { .api }
513
# Common attributes for all shapes
514
shape.dim: int          # Shape dimension (0=point, 1=curve, 2=surface, 3=volume) 
515
shape._id: int          # Internal GMSH entity ID
516
shape.dim_tag: tuple    # (dimension, tag) tuple for GMSH operations
517
shape.dim_tags: list    # List of (dimension, tag) tuples for compound shapes
518
```