kneemesh 0.1.0__py3-none-any.whl

kneemesh/__init__.py

@@ -0,0 +1,10 @@
+"""kneemesh: B-rep geometry and meshes of knee structures from segmented images."""
+
+from importlib.metadata import version
+
+from loguru import logger
+
+__version__ = version("kneemesh")
+
+# A library stays silent unless its user opts in with logger.enable("kneemesh").
+logger.disable("kneemesh")

kneemesh/brep.py

@@ -0,0 +1,214 @@
+"""B-rep values, gmsh sessions, and B-spline construction shared by every structure."""
+
+import tempfile
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from itertools import pairwise
+from pathlib import Path
+
+import gmsh
+import numpy as np
+from loguru import logger
+from scipy.interpolate import BSpline, make_interp_spline
+from vtkmodules.util.numpy_support import numpy_to_vtk
+from vtkmodules.vtkCommonCore import vtkPoints
+from vtkmodules.vtkCommonDataModel import vtkCellArray, vtkPolyData, vtkPolyLine
+
+from kneemesh.vol import ContourSlice
+
+MAX_SPLINE_ORDER = 25  # Open Cascade's limit on B-spline degree.
+
+
+@dataclass(frozen=True)
+class BRep:
+    """A B-rep shape held as the text of an Open Cascade .brep file."""
+
+    text: str
+
+
+@contextmanager
+def gmsh_session() -> Iterator[None]:
+    """Run a block on a temporary gmsh model, leaving gmsh as it was found."""
+    owns_gmsh = not gmsh.isInitialized()
+    if owns_gmsh:
+        gmsh.initialize(readConfigFiles=False, interruptible=False)
+        gmsh.option.setNumber("General.Terminal", 0)
+    previous_model = gmsh.model.getCurrent()
+    gmsh.model.add(f"kneemesh-{uuid.uuid4().hex}")
+    try:
+        yield
+    finally:
+        gmsh.model.remove()
+        if owns_gmsh:
+            gmsh.finalize()
+        else:
+            gmsh.model.setCurrent(previous_model)
+
+
+def export_brep() -> BRep:
+    """Return the current gmsh model's highest-dimension shapes as a BRep. Call inside gmsh_session."""
+    with tempfile.TemporaryDirectory() as directory:
+        path = Path(directory) / "shape.brep"
+        gmsh.write(str(path))
+        text = path.read_text(encoding="utf-8")
+    counts = [len(gmsh.model.getEntities(dim)) for dim in range(4)]
+    logger.debug("B-rep has {} vertices, {} edges, {} faces, and {} volumes ({} kB)", *counts, len(text) // 1024)
+    return BRep(text)
+
+
+def chord_parameters(points: np.ndarray) -> np.ndarray:
+    """Return parameters from 0 to 1 proportional to chord length around a closed contour, ending at the repeated first point."""
+    closed = np.vstack((points, points[:1]))
+    lengths = np.concatenate(([0.0], np.cumsum(np.linalg.norm(np.diff(closed, axis=0), axis=1))))
+    return lengths / lengths[-1]
+
+
+def periodic_spline(points: np.ndarray, spline_order: int) -> BSpline:
+    """Return a periodic B-spline through points, over parameters 0 to 1 proportional to chord length."""
+    return make_interp_spline(chord_parameters(points), np.vstack((points, points[:1])), k=spline_order, bc_type="periodic")
+
+
+def open_chord_parameters(points: np.ndarray) -> np.ndarray:
+    """Return parameters from 0 to 1 proportional to chord length along an open sequence of points."""
+    lengths = np.concatenate(([0.0], np.cumsum(np.linalg.norm(np.diff(points, axis=0), axis=1))))
+    return lengths / lengths[-1]
+
+
+def clamped_interpolation(parameters: np.ndarray, points: np.ndarray, degree: int) -> tuple[np.ndarray, np.ndarray]:
+    """Return the knots and poles of a clamped B-spline through points at parameters.
+
+    Averaged knots make this work at any degree. Both ends are pinned to the
+    exact end points, so curves fitted to the same end points meet exactly.
+    """
+    if degree == 1:
+        knots = np.concatenate(([parameters[0]], parameters, [parameters[-1]]))
+    else:
+        interior = [parameters[index + 1 : index + degree + 1].mean() for index in range(len(parameters) - degree - 1)]
+        knots = np.concatenate(([parameters[0]] * (degree + 1), interior, [parameters[-1]] * (degree + 1)))
+    poles = np.array(make_interp_spline(parameters, points, k=degree, t=knots).c)
+    poles[0], poles[-1] = points[0], points[-1]
+    return knots, poles
+
+
+def add_bspline_curve(knots: np.ndarray, poles: np.ndarray, degree: int) -> int:
+    """Add an open B-spline curve from scipy-style full knots and poles, returning its tag."""
+    unique_knots, multiplicities = np.unique(knots, return_counts=True)
+    tags = [gmsh.model.occ.addPoint(*pole.tolist()) for pole in poles]
+    return gmsh.model.occ.addBSpline(tags, degree=degree, knots=unique_knots.tolist(), multiplicities=multiplicities.tolist())
+
+
+def add_swept_surface(rows: list[tuple[np.ndarray, np.ndarray]], degree: int, along: np.ndarray, along_degree: int) -> int:
+    """Add a B-spline surface through section curves sharing one knot vector, returning its tag.
+
+    Each column of poles is interpolated along the curve at the same
+    parameters, so a surface's edge depends only on that edge's points and
+    matches its neighbor's exactly.
+    """
+    knots = rows[0][0]
+    grid = np.array([poles for _, poles in rows])
+    columns = [clamped_interpolation(along, grid[:, column], along_degree) for column in range(grid.shape[1])]
+    along_knots = columns[0][0]
+    poles = np.stack([column_poles for _, column_poles in columns], axis=1)
+    unique_knots, multiplicities = np.unique(knots, return_counts=True)
+    unique_along, along_multiplicities = np.unique(along_knots, return_counts=True)
+    return gmsh.model.occ.addBSplineSurface(
+        [gmsh.model.occ.addPoint(*pole.tolist()) for row in poles for pole in row],
+        poles.shape[1],
+        degreeU=degree,
+        degreeV=along_degree,
+        knotsU=unique_knots.tolist(),
+        knotsV=unique_along.tolist(),
+        multiplicitiesU=multiplicities.tolist(),
+        multiplicitiesV=along_multiplicities.tolist(),
+    )
+
+
+def periodic_poles_and_knots(spline: BSpline, point_count: int) -> tuple[np.ndarray, list[float]]:
+    """Return a periodic spline's poles and knots as Open Cascade takes them."""
+    # Scipy repeats the first poles at the end of its coefficients and pads its
+    # knots on both sides. Open Cascade takes each only once.
+    return spline.c[:point_count], spline.t[spline.k : len(spline.t) - spline.k].tolist()
+
+
+def add_closed_wire(spline: BSpline, point_count: int) -> int:
+    """Add a closed wire of one periodic B-spline, returning its tag."""
+    poles, knots = periodic_poles_and_knots(spline, point_count)
+    # Repeating the first tag is how gmsh is told the curve is periodic.
+    curve = gmsh.model.occ.addBSpline(add_closed_points(poles), degree=spline.k, knots=knots, multiplicities=[1] * len(knots))
+    return gmsh.model.occ.addWire([curve], checkClosed=True)
+
+
+def split_periodic_spline(spline: BSpline, parameters: np.ndarray) -> list[BSpline]:
+    """Split a periodic spline exactly into clamped splines at parameters.
+
+    parameters must be sorted, distinct, and start at 0, so the last piece ends at 1.
+    """
+    degree = spline.k
+    splits = [float(parameter) for parameter in parameters] + [1.0]
+
+    # Raising a knot's multiplicity to the degree makes the curve pass through
+    # a pole there, so the poles between two such knots define that piece alone.
+    refined = BSpline(spline.t, spline.c, degree)
+    for split in splits:
+        missing = degree - int(np.sum(refined.t == split))
+        if missing > 0:
+            refined = refined.insert_knot(split, missing)
+    # Index from a start knot's last copy and an end knot's first, which also
+    # holds where scipy clamps the ends of a degree 1 spline instead of padding.
+    pieces = []
+    for start, end in pairwise(splits):
+        after_start = int(np.flatnonzero(refined.t == start)[-1]) + 1
+        at_end = int(np.flatnonzero(refined.t == end)[0])
+        knots = np.concatenate(([start] * (degree + 1), refined.t[after_start:at_end], [end] * (degree + 1)))
+        pieces.append(BSpline(knots, refined.c[after_start - 1 - degree : at_end], degree))
+    return pieces
+
+
+def add_closed_points(poles: np.ndarray) -> list[int]:
+    """Add a point per pole, returning their tags with the first repeated at the end.
+
+    gmsh treats a B-spline whose first and last point tags match as periodic.
+    """
+    tags = [gmsh.model.occ.addPoint(*pole.tolist()) for pole in poles]
+    return [*tags, tags[0]]
+
+
+def contours_to_polydata(slices: list[ContourSlice]) -> vtkPolyData:
+    """Assemble contour slices into a single poly data of closed polylines.
+
+    Args:
+        slices: Contours from slice_isocontour.
+
+    Returns:
+        A vtkPolyData with one vtkPolyLine per slice, in the order given. Each
+        polyline ends on its own first point id to close the contour, so no
+        point is duplicated.
+
+    Raises:
+        ValueError: If slices is empty.
+    """
+    if not slices:
+        raise ValueError("No contour slices to assemble")
+
+    points = vtkPoints()
+    points.SetData(numpy_to_vtk(np.vstack([contour.points for contour in slices]), deep=True))
+
+    lines = vtkCellArray()
+    first_id = 0
+    for contour in slices:
+        count = len(contour.points)
+        polyline = vtkPolyLine()
+        ids = polyline.GetPointIds()
+        ids.SetNumberOfIds(count + 1)
+        for index in range(count):
+            ids.SetId(index, first_id + index)
+        ids.SetId(count, first_id)
+        lines.InsertNextCell(polyline)
+        first_id += count
+
+    poly_data = vtkPolyData()
+    poly_data.SetPoints(points)
+    poly_data.SetLines(lines)
+    return poly_data

kneemesh/config.py

@@ -0,0 +1,178 @@
+"""Configuration models and parsing them from JSON."""
+
+from os import PathLike
+from pathlib import Path
+from typing import Annotated, Any, Literal, Self
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from kneemesh.tet_meshing import Algorithm2D, Algorithm3D
+from kneemesh.vol import DEFAULT_SMOOTHING_ITERATIONS, DEFAULT_SMOOTHING_PASS_BAND
+
+
+class BaseConfig(BaseModel):
+    """Base class for configuration models.
+
+    Unknown fields are rejected so that misspelled options fail at load time
+    instead of being silently ignored.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    @classmethod
+    def from_json(cls, path: str | PathLike[str]) -> Self:
+        """Parse and validate a configuration from a JSON file."""
+        return cls.model_validate_json(Path(path).read_bytes())
+
+
+def _none_from_text(value: Any) -> Any:
+    """Read "none" or "null" as None, so command-line overrides can clear optional values."""
+    return None if isinstance(value, str) and value.strip().lower() in ("none", "null") else value
+
+
+OptionalFloat = Annotated[float | None, BeforeValidator(_none_from_text)]
+
+
+class LabelMapBrep(BaseConfig):
+    """Settings every B-rep pipeline shares: the LabelMap to read, the structure's label in it, and the file to write."""
+
+    label_map: Path = Field(default=Path("label_map.nii"), description="LabelMap to read: .nii, .nrrd, or .mhd")
+    output: Path = Field(default=Path("structure.brep"), description="B-rep file to write")
+    label: int = Field(default=1, description="Value of the structure in the LabelMap")
+
+
+class BrepMesh(BaseConfig):
+    """Settings every meshing pipeline shares: the B-rep to read, the mesh file to write, and the element order."""
+
+    brep: Path = Field(default=Path("structure.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("structure.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+    element_order: int = Field(default=1, description="Polynomial order of the elements")
+    second_order_incomplete: bool = Field(default=False, description="Omit face and interior nodes from high-order elements")
+
+
+class MeniscusBrep(LabelMapBrep):
+    """Settings for building a meniscus B-rep from a segmented LabelMap, with the defaults of each step."""
+
+    output: Path = Field(default=Path("meniscus.brep"), description="B-rep file to write")
+    sigma: OptionalFloat = Field(
+        default=None,
+        description="Gaussian smoothing of the distance field in physical units. None spans 3 voxel edges per axis, 0 disables",
+    )
+    level: float = Field(default=0.0, description="Distance of the surface from the label boundary; positive is outside")
+    smoothing_iterations: int = Field(
+        default=DEFAULT_SMOOTHING_ITERATIONS, ge=0, description="Windowed sinc smoothing iterations on the surface before slicing; 0 disables"
+    )
+    smoothing_pass_band: float = Field(
+        default=DEFAULT_SMOOTHING_PASS_BAND, gt=0, le=2, description="Windowed sinc pass band in (0, 2]; lower smooths and shrinks more"
+    )
+    spacing: float = Field(default=5.0, description="Arc-length distance between slices along the centerline, in physical units")
+    points_per_slice: int = Field(default=32, description="Points on each slice contour. Use about 10 for hexahedral blocks")
+    spline_order: int = Field(default=3, description="Polynomial degree of the B-spline geometry")
+    cap: Literal["none", "planar", "smooth"] = Field(default="planar", description="How to close the ends; ignored for hexahedral blocks")
+    cap_offset: OptionalFloat = Field(
+        default=None, description="Apex offset of smooth caps in physical units. None is a quarter of the equivalent radius"
+    )
+    hex_blocks: bool = Field(default=False, description="Build the five-block butterfly solid with planar caps that hexahedral meshing needs")
+
+
+class MeniscusMesh(BrepMesh):
+    """Settings for meshing a meniscus B-rep, with the defaults of each meshing function."""
+
+    brep: Path = Field(default=Path("meniscus.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("meniscus.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+    element: Literal["tetrahedral", "hexahedral"] = Field(
+        default="tetrahedral", description="Element shape. Hexahedral needs a B-rep built with hex_blocks"
+    )
+    min_size: float = Field(default=0.0, description="Smallest tetrahedron size in physical units")
+    max_size: OptionalFloat = Field(default=None, description="Largest tetrahedron size in physical units. None lets gmsh choose")
+    elements_per_circle: int = Field(default=0, description="Tetrahedra per circle of surface curvature; 0 disables curvature sizing")
+    algorithm_2d: Algorithm2D = Field(default=Algorithm2D.FRONTAL_DELAUNAY, description="gmsh surface algorithm for tetrahedral meshing")
+    algorithm_3d: Algorithm3D = Field(default=Algorithm3D.DELAUNAY, description="gmsh volume algorithm for tetrahedral meshing")
+    elements_per_edge: int = Field(default=4, description="Hexahedra along each edge of a cap")
+    elements_along: int = Field(default=20, description="Hexahedra along the solid between the caps")
+
+
+class TibialCartilageBrep(LabelMapBrep):
+    """Settings for building a tibial cartilage B-rep from a segmented LabelMap. Not implemented yet."""
+
+    output: Path = Field(default=Path("tibial_cartilage.brep"), description="B-rep file to write")
+    name: str = Field(
+        default="tibial_cartilage",
+        description="Name of the cartilage plate, such as lateral or medial. Both plates share one B-rep and meshing strategy",
+    )
+
+
+class TibialCartilageMesh(BrepMesh):
+    """Settings for meshing a tibial cartilage B-rep. Not implemented yet."""
+
+    brep: Path = Field(default=Path("tibial_cartilage.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("tibial_cartilage.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+    name: str = Field(
+        default="tibial_cartilage",
+        description="Name of the cartilage plate, such as lateral or medial. Both plates share one B-rep and meshing strategy",
+    )
+
+
+class FemoralCartilageBrep(LabelMapBrep):
+    """Settings for building a femoral cartilage B-rep from a segmented LabelMap. Not implemented yet."""
+
+    output: Path = Field(default=Path("femoral_cartilage.brep"), description="B-rep file to write")
+
+
+class FemoralCartilageMesh(BrepMesh):
+    """Settings for meshing a femoral cartilage B-rep. Not implemented yet."""
+
+    brep: Path = Field(default=Path("femoral_cartilage.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("femoral_cartilage.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+
+
+class PatellarCartilageBrep(LabelMapBrep):
+    """Settings for building a patellar cartilage B-rep from a segmented LabelMap. Not implemented yet."""
+
+    output: Path = Field(default=Path("patellar_cartilage.brep"), description="B-rep file to write")
+
+
+class PatellarCartilageMesh(BrepMesh):
+    """Settings for meshing a patellar cartilage B-rep. Not implemented yet."""
+
+    brep: Path = Field(default=Path("patellar_cartilage.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("patellar_cartilage.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+
+
+class TibiaBrep(LabelMapBrep):
+    """Settings for building a tibia B-rep from a segmented LabelMap. Not implemented yet."""
+
+    output: Path = Field(default=Path("tibia.brep"), description="B-rep file to write")
+
+
+class TibiaMesh(BrepMesh):
+    """Settings for meshing a tibia B-rep. Not implemented yet."""
+
+    brep: Path = Field(default=Path("tibia.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("tibia.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+
+
+class FemurBrep(LabelMapBrep):
+    """Settings for building a femur B-rep from a segmented LabelMap. Not implemented yet."""
+
+    output: Path = Field(default=Path("femur.brep"), description="B-rep file to write")
+
+
+class FemurMesh(BrepMesh):
+    """Settings for meshing a femur B-rep. Not implemented yet."""
+
+    brep: Path = Field(default=Path("femur.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("femur.msh"), description="Mesh file to write; gmsh infers the format from the extension")
+
+
+class PatellaBrep(LabelMapBrep):
+    """Settings for building a patella B-rep from a segmented LabelMap. Not implemented yet."""
+
+    output: Path = Field(default=Path("patella.brep"), description="B-rep file to write")
+
+
+class PatellaMesh(BrepMesh):
+    """Settings for meshing a patella B-rep. Not implemented yet."""
+
+    brep: Path = Field(default=Path("patella.brep"), description="B-rep file to read")
+    output: Path = Field(default=Path("patella.msh"), description="Mesh file to write; gmsh infers the format from the extension")

kneemesh/disk.py

@@ -0,0 +1,160 @@
+"""Reading and writing LabelMaps as .nii, .nrrd, or .mhd + .raw, poly data as .vtp, and B-reps as .brep, and writing meshes."""
+
+from os import PathLike
+from pathlib import Path
+
+import gmsh
+import numpy as np
+import SimpleITK as sitk
+from loguru import logger
+from vtkmodules.vtkCommonDataModel import vtkPolyData
+from vtkmodules.vtkIOXML import vtkXMLPolyDataReader, vtkXMLPolyDataWriter
+
+from kneemesh.brep import BRep, gmsh_session
+from kneemesh.tet_meshing import Mesh
+from kneemesh.vol import LABEL_MAP_PIXEL_IDS
+
+SUPPORTED_SUFFIXES = frozenset({".nii", ".nrrd", ".mhd"})
+POLY_DATA_SUFFIXES = frozenset({".vtp"})
+BREP_SUFFIXES = frozenset({".brep"})
+
+
+def read_label_map(path: str | PathLike[str]) -> sitk.Image:
+    """Read a segmented LabelMap from disk.
+
+    For a .mhd file, the .raw file it references must also exist.
+
+    Raises:
+        ValueError: If the file format is unsupported or the image is not
+            sitkUInt8, sitkUInt16, or sitkInt16.
+    """
+    path = _validated_path(path)
+    image = sitk.ReadImage(str(path))
+    _require_label_map(image)
+    logger.debug("Read {} LabelMap of size {} and spacing {} from {}", image.GetPixelIDTypeAsString(), image.GetSize(), image.GetSpacing(), path)
+    return image
+
+
+def write_label_map(image: sitk.Image, path: str | PathLike[str]) -> None:
+    """Write a segmented LabelMap to disk, overwriting any existing file.
+
+    A .mhd path also writes a .raw file alongside it.
+
+    Raises:
+        ValueError: If the file format is unsupported or the image is not
+            sitkUInt8, sitkUInt16, or sitkInt16.
+    """
+    path = _validated_path(path)
+    _require_label_map(image)
+    sitk.WriteImage(image, str(path), useCompression=False)
+
+
+def read_poly_data(path: str | PathLike[str]) -> vtkPolyData:
+    """Read poly data from a VTK XML .vtp file.
+
+    Raises:
+        ValueError: If the suffix is not .vtp or the file is not VTK XML poly data.
+        FileNotFoundError: If the file does not exist.
+    """
+    path = _validated_path(path, POLY_DATA_SUFFIXES)
+    if not path.is_file():
+        raise FileNotFoundError(f"No such file: {path}")
+
+    # The reader logs failures and returns empty output without any error state.
+    reader = vtkXMLPolyDataReader()
+    if not reader.CanReadFile(str(path)):
+        raise ValueError(f"Not a VTK XML poly data file: {path}")
+    reader.SetFileName(str(path))
+    reader.Update()
+    return reader.GetOutput()
+
+
+def write_poly_data(poly_data: vtkPolyData, path: str | PathLike[str]) -> None:
+    """Write poly data to a VTK XML .vtp file, overwriting any existing file.
+
+    Raises:
+        ValueError: If the suffix is not .vtp.
+        OSError: If the file cannot be written.
+    """
+    path = _validated_path(path, POLY_DATA_SUFFIXES)
+
+    writer = vtkXMLPolyDataWriter()
+    writer.SetFileName(str(path))
+    writer.SetInputData(poly_data)
+    if not writer.Write():
+        raise OSError(f"Could not write poly data to {path}")
+
+
+def read_brep(path: str | PathLike[str]) -> BRep:
+    """Read a B-rep from an Open Cascade .brep file.
+
+    Raises:
+        ValueError: If the suffix is not .brep or the file holds no valid shape.
+        FileNotFoundError: If the file does not exist.
+    """
+    path = _validated_path(path, BREP_SUFFIXES)
+    if not path.is_file():
+        raise FileNotFoundError(f"No such file: {path}")
+
+    with gmsh_session():
+        try:
+            shapes = gmsh.model.occ.importShapes(str(path))
+        except Exception as error:  # gmsh raises only the bare Exception type.
+            raise ValueError(f"Not a valid B-rep file: {path}") from error
+    if not shapes:
+        raise ValueError(f"Not a valid B-rep file: {path}")
+    return BRep(path.read_text(encoding="utf-8"))
+
+
+def write_brep(brep: BRep, path: str | PathLike[str]) -> None:
+    """Write a B-rep to an Open Cascade .brep file, overwriting any existing file.
+
+    Raises:
+        ValueError: If the suffix is not .brep.
+        OSError: If the file cannot be written.
+    """
+    path = _validated_path(path, BREP_SUFFIXES)
+    path.write_text(brep.text, encoding="utf-8")
+    logger.debug("Wrote B-rep to {}", path)
+
+
+def write_mesh(mesh: Mesh, path: str | PathLike[str]) -> None:
+    """Write a mesh in the format gmsh infers from the extension, overwriting any existing file.
+
+    Volume formats include .msh, .vtk, .inp, .unv, .bdf, .med, .mesh, and
+    .su2. The mesh has only volume elements, so surface formats such as .stl
+    hold no elements.
+
+    Raises:
+        ValueError: If gmsh does not recognize the extension.
+        OSError: If the file cannot be written.
+    """
+    path = Path(path)
+    with gmsh_session():
+        volume = gmsh.model.addDiscreteEntity(3)
+        gmsh.model.mesh.addNodes(3, volume, np.arange(1, len(mesh.nodes) + 1).tolist(), mesh.nodes.ravel().tolist())
+        first_tag = 1
+        for name, connectivity in mesh.elements.items():
+            element_tags = np.arange(first_tag, first_tag + len(connectivity))
+            gmsh.model.mesh.addElementsByType(volume, mesh.element_types[name], element_tags.tolist(), (connectivity + 1).ravel().tolist())
+            first_tag += len(connectivity)
+        try:
+            gmsh.write(str(path))
+        except Exception as error:  # gmsh raises only the bare Exception type.
+            if "Unknown output file format" in str(error):
+                raise ValueError(f"gmsh cannot write meshes in the format of {path.name!r}") from error
+            raise OSError(f"Could not write mesh to {path}") from error
+    logger.debug("Wrote mesh to {}", path)
+
+
+def _validated_path(path: str | PathLike[str], suffixes: frozenset[str] = SUPPORTED_SUFFIXES) -> Path:
+    path = Path(path)
+    if path.suffix.lower() not in suffixes:
+        supported = ", ".join(sorted(suffixes))
+        raise ValueError(f"Unsupported file format {path.name!r}; expected one of: {supported}")
+    return path
+
+
+def _require_label_map(image: sitk.Image) -> None:
+    if image.GetPixelID() not in LABEL_MAP_PIXEL_IDS:
+        raise ValueError(f"LabelMap must be sitkUInt8, sitkUInt16, or sitkInt16, got {image.GetPixelIDTypeAsString()}")

kneemesh/geo/__init__.py

@@ -0,0 +1 @@
+"""B-rep generation for each knee structure, one module per structure."""

kneemesh/geo/femur.py

@@ -0,0 +1 @@
+"""B-rep generation for the femoral cartilage and the femur. Not implemented yet."""