tessl/pypi-pygmsh
Python frontend for Gmsh mesh generator providing intuitive abstractions for creating complex geometric models and generating high-quality meshes
—
Pending
shape-classes.mddocs/
Shape Classes and Entity Types
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.
Common Shape Attributes
All shape objects in pygmsh share common attributes that provide metadata and enable geometric operations:
# Universal attributes for all shapes
shape.dim: int # Shape dimension (0=point, 1=curve, 2=surface, 3=volume)
shape._id: int # Internal GMSH entity ID
shape.dim_tag: tuple # (dimension, tag) tuple for GMSH operations
shape.dim_tags: list # List of (dimension, tag) tuples for compound shapesBasic Geometric Entities
Point Class
Elementary point entities representing locations in 3D space with optional mesh size specification.
class Point:
"""
Elementary point in 3D space.
Points serve as building blocks for all higher-dimensional entities
and can specify local mesh sizing constraints.
"""
def __init__(self, env, x, mesh_size=None):
"""
Initialize point entity.
Parameters:
- env: geometry environment (automatically provided)
- x: list[float], coordinates [x, y, z]
- mesh_size: float, optional element size constraint at point
Attributes:
- x: array, point coordinates
- dim: int = 0
- _id: int, internal GMSH point ID
- dim_tag: tuple, (0, point_id)
- dim_tags: list, [(0, point_id)]
"""Line Class
Line segments connecting two points, forming the basis for curve construction.
class Line:
"""
Line segment between two points.
Lines are fundamental 1D entities used to construct complex curves,
curve loops, and surface boundaries.
"""
def __init__(self, env, p0, p1):
"""
Initialize line segment.
Parameters:
- env: geometry environment (automatically provided)
- p0: Point, start point
- p1: Point, end point
Attributes:
- points: list[Point], [start_point, end_point]
- dim: int = 1
- _id: int, internal GMSH line ID
- dim_tag: tuple, (1, line_id)
- dim_tags: list, [(1, line_id)]
"""Polygon Class
Multi-sided closed shapes with optional holes and automatic surface generation.
class Polygon:
"""
Polygon with optional holes and surface generation.
Polygons automatically generate curve loops and surfaces, supporting
complex shapes with internal holes and custom mesh sizing.
"""
def __init__(self, host, points, mesh_size=None, holes=None, make_surface=True):
"""
Initialize polygon shape.
Parameters:
- host: geometry environment (automatically provided)
- points: list[list[float]], vertex coordinates [[x1,y1,z1], [x2,y2,z2], ...]
- mesh_size: float, optional element size for polygon boundary
- holes: list[CurveLoop], optional holes to subtract from polygon
- make_surface: bool, create surface from polygon boundary
Attributes:
- points: list[Point], polygon vertices
- curves: list[Line], polygon edges
- lines: list[Line], alias for curves
- curve_loop: CurveLoop, closed boundary
- surface: Surface, polygon surface (if make_surface=True)
- dim: int = 2 (if surface created), 1 (if curve only)
- _id: int, internal GMSH entity ID
- dim_tag: tuple, (dim, entity_id)
- dim_tags: list, entity dimension tags
"""Surface Class
2D entities created from curve loops, representing bounded regions.
class Surface:
"""
Surface generated from curve loop.
Surfaces represent 2D regions bounded by closed curves,
forming the basis for 3D volume construction and 2D meshing.
"""
def __init__(self, env, curve_loop):
"""
Initialize surface entity.
Parameters:
- env: geometry environment (automatically provided)
- curve_loop: CurveLoop, boundary defining surface
Attributes:
- dim: int = 2
- _id: int, internal GMSH surface ID
- dim_tag: tuple, (2, surface_id)
- dim_tags: list, [(2, surface_id)]
"""Volume Class
3D entities created from surface loops, representing solid regions.
class Volume:
"""
Volume from surface loop.
Volumes represent 3D regions bounded by closed surfaces,
used for solid meshing and 3D finite element analysis.
"""
def __init__(self, env, surface_loop):
"""
Initialize volume entity.
Parameters:
- env: geometry environment (automatically provided)
- surface_loop: SurfaceLoop, boundary defining volume
Attributes:
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tag: tuple, (3, volume_id)
- dim_tags: list, [(3, volume_id)]
"""OpenCASCADE Primitive Shapes
Ball Class
Spherical shapes with optional angular restrictions for creating sphere segments.
class Ball:
"""
Sphere with optional angular cuts.
Creates spherical volumes with full control over angular extents,
enabling creation of sphere segments and hemispheres.
"""
def __init__(self, center, radius, angle1=-π/2, angle2=π/2, angle3=2π):
"""
Initialize ball/sphere.
Parameters:
- center: list[float], sphere center coordinates [x, y, z]
- radius: float, sphere radius
- angle1: float, minimum polar angle (default: -π/2, south pole)
- angle2: float, maximum polar angle (default: π/2, north pole)
- angle3: float, azimuthal angle span (default: 2π, full rotation)
Attributes:
- center: array, sphere center
- radius: float, sphere radius
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tag: tuple, (3, volume_id)
- dim_tags: list, [(3, volume_id)]
"""Box Class
Rectangular boxes with specified corner and extent dimensions.
class Box:
"""
Rectangular box.
Creates axis-aligned rectangular volumes with specified corner
position and extent dimensions.
"""
def __init__(self, x0, extents, char_length=None):
"""
Initialize rectangular box.
Parameters:
- x0: list[float], corner point coordinates [x, y, z]
- extents: list[float], box dimensions [dx, dy, dz]
- char_length: float, deprecated (use mesh_size in add_box)
Attributes:
- x0: array, corner coordinates
- extents: array, box dimensions
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tag: tuple, (3, volume_id)
- dim_tags: list, [(3, volume_id)]
"""Cylinder Class
Cylindrical shapes with optional angular openings for creating cylinder segments.
class Cylinder:
"""
Cylinder with optional angular opening.
Creates cylindrical volumes with full control over axis direction
and angular extent, enabling creation of cylinder segments.
"""
def __init__(self, x0, axis, radius, angle=2π):
"""
Initialize cylinder.
Parameters:
- x0: list[float], base center coordinates [x, y, z]
- axis: list[float], cylinder axis direction vector [dx, dy, dz]
- radius: float, cylinder radius
- angle: float, angular opening (default: 2π, full cylinder)
Attributes:
- x0: array, base center
- axis: array, axis direction
- radius: float, cylinder radius
- angle: float, angular opening
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tag: tuple, (3, volume_id)
- dim_tags: list, [(3, volume_id)]
"""Cone Class
Conical shapes with different top and bottom radii for creating cones and truncated cones.
class Cone:
"""
Cone with different top and bottom radii.
Creates conical volumes with independent control over base and top radii,
enabling creation of full cones, truncated cones, and tapered cylinders.
"""
def __init__(self, center, axis, radius0, radius1, angle=2π):
"""
Initialize cone.
Parameters:
- center: list[float], base center coordinates [x, y, z]
- axis: list[float], cone axis direction vector [dx, dy, dz]
- radius0: float, base radius
- radius1: float, top radius
- angle: float, angular opening (default: 2π, full cone)
Attributes:
- center: array, base center
- axis: array, axis direction
- radius0: float, base radius
- radius1: float, top radius
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tag: tuple, (3, volume_id)
- dim_tags: list, [(3, volume_id)]
"""Disk Class
Circular or elliptical flat shapes for creating 2D disk geometries.
class Disk:
"""
Disk or ellipse.
Creates 2D circular or elliptical surfaces with optional
second radius for ellipse creation.
"""
def __init__(self, x0, radius0, radius1=None):
"""
Initialize disk or ellipse.
Parameters:
- x0: list[float], center coordinates [x, y, z]
- radius0: float, primary radius (or circle radius if radius1=None)
- radius1: float, secondary radius for ellipse (optional)
Attributes:
- x0: array, center coordinates
- radius0: float, primary radius
- radius1: float, secondary radius (None for circle)
- dim: int = 2
- _id: int, internal GMSH surface ID
- dim_tag: tuple, (2, surface_id)
- dim_tags: list, [(2, surface_id)]
"""Torus Class
Toroidal shapes with major and minor radii and optional angular restrictions.
class Torus:
"""
Torus with major and minor radii.
Creates toroidal volumes with independent control over tube radius
and torus radius, with optional angular restrictions.
"""
def __init__(self, center, radius0, radius1, alpha=2π):
"""
Initialize torus.
Parameters:
- center: list[float], torus center coordinates [x, y, z]
- radius0: float, minor radius (tube radius)
- radius1: float, major radius (center to tube center distance)
- alpha: float, angular span around major radius (default: 2π)
Attributes:
- center: array, torus center
- radius0: float, minor radius
- radius1: float, major radius
- alpha: float, angular span
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tag: tuple, (3, volume_id)
- dim_tags: list, [(3, volume_id)]
"""Wedge Class
Right angular wedge shapes for creating prismatic volumes with triangular cross-sections.
class Wedge:
"""
Right angular wedge.
Creates wedge-shaped volumes with triangular cross-section,
optionally tapered for complex prismatic shapes.
"""
def __init__(self, x0, extents, top_extent=None):
"""
Initialize wedge.
Parameters:
- x0: list[float], corner coordinates [x, y, z]
- extents: list[float], base dimensions [dx, dy, dz]
- top_extent: list[float], optional top dimensions for tapered wedge
Attributes:
- x0: array, corner coordinates
- extents: array, base dimensions
- top_extent: array, top dimensions (None for uniform wedge)
- dim: int = 3
- _id: int, internal GMSH volume ID
- dim_tags: list, [(3, volume_id)]
"""Rectangle Class
2D rectangular shapes with optional corner rounding for creating planar rectangular regions.
class Rectangle:
"""
2D rectangle with optional corner rounding.
Creates rectangular surfaces with optional rounded corners
for smoother geometric transitions.
"""
def __init__(self, x0, a, b, corner_radius=None):
"""
Initialize rectangle.
Parameters:
- x0: list[float], corner coordinates [x, y, z]
- a: float, width dimension
- b: float, height dimension
- corner_radius: float, optional corner rounding radius
Attributes:
- x0: array, corner coordinates
- a: float, width
- b: float, height
- corner_radius: float, corner radius (None for sharp corners)
- dim: int = 2
- _id: int, internal GMSH surface ID
- dim_tag: tuple, (2, surface_id)
- dim_tags: list, [(2, surface_id)]
"""Usage Examples
Creating Custom Shapes with Detailed Attributes
import pygmsh
with pygmsh.occ.Geometry() as geom:
# Create a complex assembly using various shape classes
# Main body as a box
main_box = geom.add_box([0, 0, 0], [2, 1, 0.5])
print(f"Box ID: {main_box._id}, Dimension: {main_box.dim}")
print(f"Box dim_tag: {main_box.dim_tag}")
# Cylinder for hole
hole_cyl = geom.add_cylinder([1, 0.5, -0.1], [0, 0, 0.7], 0.2)
print(f"Cylinder attributes: dim={hole_cyl.dim}, center={hole_cyl.x0}")
# Create assembly with boolean operations
result = geom.boolean_difference(main_box, hole_cyl)
print(f"Result shape tags: {result.dim_tags}")
mesh = geom.generate_mesh(dim=3)Working with Shape Collections
import pygmsh
with pygmsh.geo.Geometry() as geom:
# Create multiple shapes and manage as collection
shapes = []
for i, radius in enumerate([0.1, 0.15, 0.2]):
circle = geom.add_circle([i * 0.5, 0, 0], radius, mesh_size=0.02)
shapes.append(circle)
# Access shape properties
print(f"Circle {i}: ID={circle._id}, radius={radius}")
print(f" Points: {[p.x for p in circle.points]}")
print(f" Curves: {[c._id for c in circle.curves]}")
if hasattr(circle, 'surface') and circle.surface:
print(f" Surface ID: {circle.surface._id}")
mesh = geom.generate_mesh(dim=2)Advanced Shape Manipulation
import pygmsh
import numpy as np
with pygmsh.occ.Geometry() as geom:
# Create parametric shape family
shapes = []
for i in range(3):
# Create torus with varying parameters
center = [i * 3, 0, 0]
minor_r = 0.3 + i * 0.1
major_r = 0.8 + i * 0.2
torus = geom.add_torus(center, minor_r, major_r, alpha=np.pi * (1.5 + i * 0.2))
shapes.append(torus)
# Print detailed torus information
print(f"Torus {i}:")
print(f" Center: {torus.center}")
print(f" Minor radius: {torus.radius0}")
print(f" Major radius: {torus.radius1}")
print(f" Angular span: {torus.alpha:.2f} rad ({torus.alpha*180/np.pi:.1f}°)")
print(f" GMSH tags: {torus.dim_tags}")
# Union all toruses
if len(shapes) > 1:
union_result = geom.boolean_union(shapes)
print(f"Union result tags: {union_result.dim_tags}")
mesh = geom.generate_mesh(dim=3)Install with Tessl CLI
npx tessl i tessl/pypi-pygmsh