shapemesh 0.1.0__py3-none-any.whl

shapemesh/__init__.py

@@ -0,0 +1,103 @@
+# Copyright (C) 2026 Mads Kruse
+#
+# This file is part of shapemesh.
+#
+# shapemesh is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# shapemesh is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with shapemesh. If not, see <https://www.gnu.org/licenses/>.
+
+"""shapemesh — a Python geometry and meshing library powered by Gmsh."""
+
+from __future__ import annotations
+
+from .builder import build
+from .errors import (
+    BuildError,
+    GeometryError,
+    LabelError,
+    MeshFormatError,
+    ShapeMeshError,
+)
+from .mesh import (
+    ElementBlock,
+    ElementType,
+    EntityRecord,
+    Mesh,
+    MeshMetadata,
+    NodeTable,
+    NumpyElementBlock,
+    NumpyMesh,
+    PhysicalGroup,
+)
+from .settings import Algorithm2D, Algorithm3D, MeshSettings
+from .shapes import (
+    Box,
+    Circle,
+    Cylinder,
+    Difference,
+    Disk,
+    Ellipse,
+    EllipticalDisk,
+    Intersection,
+    Line,
+    Point,
+    Polygon,
+    Polyline,
+    Rectangle,
+    Shape,
+    Sphere,
+    Union,
+    Vec3,
+    Vec3Like,
+)
+
+# Hatchling reads this value; keep it as the single source of truth.
+__version__ = "0.1.0"
+
+__all__ = [
+    "Algorithm2D",
+    "Algorithm3D",
+    "Box",
+    "BuildError",
+    "Circle",
+    "Cylinder",
+    "Difference",
+    "Disk",
+    "ElementBlock",
+    "ElementType",
+    "Ellipse",
+    "EllipticalDisk",
+    "EntityRecord",
+    "GeometryError",
+    "Intersection",
+    "LabelError",
+    "Line",
+    "Mesh",
+    "MeshFormatError",
+    "MeshMetadata",
+    "MeshSettings",
+    "NodeTable",
+    "NumpyElementBlock",
+    "NumpyMesh",
+    "PhysicalGroup",
+    "Point",
+    "Polygon",
+    "Polyline",
+    "Rectangle",
+    "Shape",
+    "ShapeMeshError",
+    "Sphere",
+    "Union",
+    "Vec3",
+    "Vec3Like",
+    "build",
+]

shapemesh/builder.py

@@ -0,0 +1,301 @@
+# Copyright (C) 2026 Mads Kruse
+#
+# This file is part of shapemesh.
+#
+# shapemesh is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# shapemesh is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with shapemesh. If not, see <https://www.gnu.org/licenses/>.
+
+"""Gmsh build pipeline: shapes + settings -> a validated `Mesh`.
+
+The pipeline validates shapes and settings, realizes them into a Gmsh model,
+fragments overlapping entities to preserve labels, meshes, and reads the
+entity-classified mesh back. Gmsh is imported lazily and a process-wide lock
+serializes builds.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+
+from .constants import GMSH_TERMINAL_SILENT, GMSH_TERMINAL_VERBOSE
+from .errors import BuildError, GeometryError, ShapeMeshError
+from .mesh import (
+    _NODE_COUNT,
+    ElementBlock,
+    ElementType,
+    EntityRecord,
+    Mesh,
+    MeshMetadata,
+    NodeTable,
+    PhysicalGroup,
+)
+from .settings import MeshSettings
+from .shapes import Shape
+
+__all__ = ["build"]
+
+_LOCK = threading.RLock()
+
+_RESERVED_OPTIONS = frozenset(
+    {"General.Terminal", "Mesh.Algorithm", "Mesh.Algorithm3D", "Mesh.ElementOrder"}
+)
+
+
+def build(shapes: Shape | Sequence[Shape], settings: MeshSettings) -> Mesh:
+    """Realize ``shapes`` with Gmsh and return the resulting `Mesh`.
+
+    A single `Shape` is normalized to a one-element sequence. Each shape with a
+    label becomes a physical group of the same name in the resulting mesh.
+
+    Args:
+        shapes: A shape or a sequence of shapes to mesh.
+        settings: The mesh settings.
+
+    Returns:
+        The entity-classified mesh.
+
+    Raises:
+        GeometryError: If ``shapes`` is empty or contains a non-shape.
+        ValueError: If an ``advanced`` option conflicts with an explicit
+            setting.
+        BuildError: If a Gmsh call fails.
+        RuntimeError: If Gmsh must be initialized from a non-main thread.
+    """
+    shape_list = _normalize_shapes(shapes)
+    _validate_build(shape_list)
+    _validate_settings(settings)
+
+    with _LOCK:
+        import gmsh
+
+        owned = not gmsh.isInitialized()
+        if owned:
+            if threading.current_thread() is not threading.main_thread():
+                raise RuntimeError(
+                    "build() must be called from the main thread to initialize Gmsh; "
+                    "initialize Gmsh on the main thread first, or use multiprocessing"
+                )
+            # Keep interruptible=True (the default) so Ctrl-C stops meshing
+            # gracefully; this is also why initialization needs the main thread.
+            gmsh.initialize()
+        added = False
+        saved_options: list[tuple[str, float | int | str]] = []
+        try:
+            if not owned:
+                saved_options = _snapshot_options(gmsh, settings)
+            gmsh.model.add("shapemesh")
+            added = True
+            _apply_settings(gmsh, settings)
+            return _build_mesh(gmsh, shape_list, settings)
+        except ShapeMeshError:
+            raise
+        except Exception as exc:
+            raise BuildError(str(exc), _capture_log(gmsh)) from exc
+        finally:
+            if added:
+                gmsh.model.remove()
+            if owned:
+                gmsh.finalize()
+            else:
+                _restore_options(gmsh, saved_options)
+
+
+def _normalize_shapes(shapes: Shape | Sequence[Shape]) -> list[Shape]:
+    if isinstance(shapes, Shape):
+        return [shapes]
+    if isinstance(shapes, (str, bytes)):
+        raise GeometryError("shapes must be a Shape or a sequence of Shape")
+    return list(shapes)
+
+
+def _validate_build(shapes: Sequence[Shape]) -> None:
+    if not shapes:
+        raise GeometryError("build requires at least one shape")
+    for shape in shapes:
+        if not isinstance(shape, Shape):
+            raise GeometryError(f"build shapes must be Shape instances, got {type(shape).__name__}")
+
+
+def _validate_settings(settings: MeshSettings) -> None:
+    for name, _ in settings.advanced:
+        if name in _RESERVED_OPTIONS:
+            raise ValueError(f"advanced option {name!r} conflicts with an explicit setting")
+
+
+def _configured_options(settings: MeshSettings) -> list[tuple[str, float | int | str]]:
+    options: list[tuple[str, float | int | str]] = [
+        (
+            "General.Terminal",
+            GMSH_TERMINAL_VERBOSE if settings.verbose else GMSH_TERMINAL_SILENT,
+        ),
+        ("Mesh.ElementOrder", settings.order),
+    ]
+    if settings.algorithm_2d is not None:
+        options.append(("Mesh.Algorithm", int(settings.algorithm_2d)))
+    if settings.algorithm_3d is not None:
+        options.append(("Mesh.Algorithm3D", int(settings.algorithm_3d)))
+    options.extend(settings.advanced)
+    return options
+
+
+def _apply_settings(gmsh: Any, settings: MeshSettings) -> None:
+    for name, value in _configured_options(settings):
+        if isinstance(value, str):
+            gmsh.option.setString(name, value)
+        else:
+            gmsh.option.setNumber(name, value)
+
+
+def _snapshot_options(gmsh: Any, settings: MeshSettings) -> list[tuple[str, float | int | str]]:
+    saved: list[tuple[str, float | int | str]] = []
+    for name, value in _configured_options(settings):
+        if isinstance(value, str):
+            previous = gmsh.option.getString(name)
+        else:
+            previous = gmsh.option.getNumber(name)
+        saved.append((name, previous))
+    return saved
+
+
+def _restore_options(gmsh: Any, options: list[tuple[str, float | int | str]]) -> None:
+    for name, value in options:
+        if isinstance(value, str):
+            gmsh.option.setString(name, value)
+        else:
+            gmsh.option.setNumber(name, value)
+
+
+def _capture_log(gmsh: Any) -> str:
+    try:
+        lines = list(gmsh.logger.get())
+    except Exception:
+        lines = []
+    try:
+        last_error = gmsh.logger.getLastError()
+    except Exception:
+        last_error = ""
+    if last_error and last_error not in lines:
+        lines.append(last_error)
+    return "\n".join(lines)
+
+
+# -- pipeline --------------------------------------------------------------
+
+
+def _build_mesh(gmsh: Any, shapes: Sequence[Shape], settings: MeshSettings) -> Mesh:
+    occ = gmsh.model.occ
+    label_map: dict[tuple[str, int], set[tuple[int, int]]] = {}
+    live: list[tuple[int, int]] = []
+    for shape in shapes:
+        dimtags = shape._realize(gmsh)
+        live.extend(dimtags)
+        if shape.label is not None:
+            label_map.setdefault((shape.label, shape.dimension), set()).update(dimtags)
+
+    occ.synchronize()
+    if len(live) > 1:
+        label_map = _fragment_remap(gmsh, live, label_map)
+    occ.synchronize()
+
+    groups = _add_groups(gmsh, label_map)
+    dim = gmsh.model.getDimension()
+    if settings.element_size is not None:
+        gmsh.model.mesh.setSize(gmsh.model.getEntities(0), settings.element_size)
+    gmsh.model.mesh.generate(max(dim, 1))
+    if settings.optimize and not (dim == 0 and settings.order > 1):
+        gmsh.model.mesh.optimize("" if settings.order == 1 else "HighOrder")
+    return _read_mesh(gmsh, groups)
+
+
+def _fragment_remap(
+    gmsh: Any,
+    live: list[tuple[int, int]],
+    label_map: dict[tuple[str, int], set[tuple[int, int]]],
+) -> dict[tuple[str, int], set[tuple[int, int]]]:
+    occ = gmsh.model.occ
+    _, outmap = occ.fragment(live, [], removeObject=True, removeTool=True)
+    occ.synchronize()
+    index = {dimtag: i for i, dimtag in enumerate(live)}
+    remapped: dict[tuple[str, int], set[tuple[int, int]]] = {}
+    for (label, dim), dimtags in label_map.items():
+        outputs: set[tuple[int, int]] = set()
+        for dimtag in dimtags:
+            for out in outmap[index[dimtag]]:
+                if out[0] == dim:
+                    outputs.add(out)
+        remapped[(label, dim)] = outputs
+    return remapped
+
+
+def _add_groups(
+    gmsh: Any, label_map: dict[tuple[str, int], set[tuple[int, int]]]
+) -> list[PhysicalGroup]:
+    groups: list[PhysicalGroup] = []
+    for label, dim in sorted(label_map):
+        dimtags = sorted(label_map[(label, dim)])
+        if not dimtags:
+            continue
+        tags = [tag for _, tag in dimtags]
+        group_tag = gmsh.model.addPhysicalGroup(dim, tags, name=label)
+        groups.append(PhysicalGroup(label, dim, group_tag, tuple(dimtags)))
+    return groups
+
+
+def _read_mesh(gmsh: Any, groups: list[PhysicalGroup]) -> Mesh:
+    entities: list[EntityRecord] = []
+    for dim in range(4):
+        for _, tag in gmsh.model.getEntities(dim):
+            bbox = tuple(gmsh.model.getBoundingBox(dim, tag))
+            boundary = tuple(gmsh.model.getBoundary([(dim, tag)], oriented=True))
+            entities.append(EntityRecord(dim, tag, bbox, boundary))
+
+    node_tags, coords, _ = gmsh.model.mesh.getNodes()
+    node_tags_arr = np.asarray(node_tags, dtype=np.int64)
+    coords_arr = np.asarray(coords, dtype=np.float64).reshape(-1, 3)
+    tag_to_index = {int(t): i for i, t in enumerate(node_tags)}
+    entity_dim = np.full(len(node_tags), -1, dtype=np.int64)
+    entity_tag = np.full(len(node_tags), -1, dtype=np.int64)
+    for dim in range(4):
+        for _, tag in gmsh.model.getEntities(dim):
+            ent_tags, _, _ = gmsh.model.mesh.getNodes(dim, tag)
+            for node_tag in ent_tags:
+                idx = tag_to_index[int(node_tag)]
+                entity_dim[idx] = dim
+                entity_tag[idx] = tag
+
+    blocks: list[ElementBlock] = []
+    for dim in range(4):
+        for _, tag in gmsh.model.getEntities(dim):
+            types, elem_tags, node_tags = gmsh.model.mesh.getElements(dim, tag)
+            for type_code, etags, ntags in zip(types, elem_tags, node_tags, strict=True):
+                element_type = ElementType(int(type_code))
+                k = _NODE_COUNT[element_type]
+                conn = np.asarray(ntags, dtype=np.int64).reshape(-1, k)
+                blocks.append(
+                    ElementBlock(dim, tag, element_type, np.asarray(etags, dtype=np.int64), conn)
+                )
+
+    model_dim = gmsh.model.getDimension()
+    version = gmsh.option.getString("General.Version")
+    metadata = MeshMetadata(dim=model_dim, msh_version="4.1", gmsh_version=version, source=None)
+    return Mesh(
+        NodeTable(node_tags_arr, coords_arr, entity_dim, entity_tag),
+        tuple(blocks),
+        tuple(entities),
+        tuple(groups),
+        metadata,
+    )

shapemesh/constants.py

@@ -0,0 +1,32 @@
+# Copyright (C) 2026 Mads Kruse
+#
+# This file is part of shapemesh.
+#
+# shapemesh is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# shapemesh is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with shapemesh. If not, see <https://www.gnu.org/licenses/>.
+
+"""Central numeric constants for shapemesh."""
+
+# Polygon vertices are considered coplanar when their perpendicular distance
+# from the fitted plane is below this fraction of the bounding-box diagonal.
+PLANARITY_TOLERANCE = 1e-7
+
+# Two polygon edges are considered non-collinear when the sine of the angle
+# between them exceeds this value.
+COLLINEARITY_TOLERANCE = 1e-7
+
+# `General.Terminal` is a gmsh verbosity level (0 = silent, higher = more
+# verbose), not a binary toggle. shapemesh is silent by default and uses
+# gmsh's normal level when `verbose` is set.
+GMSH_TERMINAL_SILENT = 0
+GMSH_TERMINAL_VERBOSE = 1

shapemesh/errors.py

@@ -0,0 +1,62 @@
+# Copyright (C) 2026 Mads Kruse
+#
+# This file is part of shapemesh.
+#
+# shapemesh is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# shapemesh is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with shapemesh. If not, see <https://www.gnu.org/licenses/>.
+
+"""Exception hierarchy for shapemesh.
+
+Every structured library error derives from `ShapeMeshError`. The
+geometry/label/format errors additionally subclass the builtin ``ValueError``
+(and `BuildError` subclasses ``RuntimeError``) so callers can catch them
+with the usual builtins while still having a single library-wide base.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "BuildError",
+    "GeometryError",
+    "LabelError",
+    "MeshFormatError",
+    "ShapeMeshError",
+]
+
+
+class ShapeMeshError(Exception):
+    """Base class for all shapemesh errors."""
+
+
+class GeometryError(ShapeMeshError, ValueError):
+    """Invalid shape or geometry, e.g. an empty boolean result."""
+
+
+class LabelError(ShapeMeshError, ValueError):
+    """Invalid or conflicting physical-group labels."""
+
+
+class MeshFormatError(ShapeMeshError, ValueError):
+    """Corrupt or unsupported MSH file."""
+
+
+class BuildError(ShapeMeshError, RuntimeError):
+    """A Gmsh call failed during a build.
+
+    Attributes:
+        log: The last Gmsh log text, captured before Gmsh was finalized.
+    """
+
+    def __init__(self, message: str, log: str = "") -> None:
+        super().__init__(message)
+        self.log = log