quadmesh 0.1.0__tar.gz

quadmesh-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: quadmesh
+Version: 0.1.0
+Summary: QuADMESH+: Quadrangular ADvanced Mesh generator. Python port of MATLAB QuADMESH library.
+Author: Dominik Mattioli
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: chilmesh>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+
+# quadmesh
+
+Tri-to-quad mesh generator. Port of MATLAB QuADMESH+. Build on `chilmesh`.
+
+## Pipeline
+
+```
+tri -> create_quad_domain -> tri2quad -> post_process -> quad
+```
+
+1. `create_quad_domain` — pick tris (whole mesh or polygon mask).
+2. `tri2quad` — sweep layers outward, merge tri pairs into quads.
+3. `post_process` — doublet collapse, quad-vert merge, boundary cleanup, smooth.
+
+## Install
+
+```bash
+pip install -e .
+pytest          # 25+ tests
+```
+
+## Use
+
+```python
+from chilmesh import CHILmesh
+from quadmesh import tri2quad, post_process, two_part_smoother
+
+tri = CHILmesh.read_from_fort14("mesh.14")
+quad = tri2quad(tri)
+quad = post_process(quad, n_smooth_iter=50)
+```
+
+## CLI
+
+```bash
+quadmesh mesh.14 -o out.14
+quadmesh mesh.14 -o out.14 --no-remove-edges --n-smooth-iter 100
+quadmesh mesh.14 -o out.14 --no-post-process
+```
+
+## v0.2 new
+
+- `CleanupBoundaryQuads` shift mode (`can_remove_edges=False`). Move corner inward. Before: no-op. Now: work.
+- `two_part_smoother`. Interleave angle + FEM smooth. Port of MATLAB `twoPartSmoother.m`.
+- 25+ tests.
+
+## Numbers
+
+| Mesh | Tris | Layers | Pipeline |
+|---|---|---|---|
+| Test_Case_1 | 2417 | 7 | <1 s |
+| Block_O | 5214 | 9 | ~1.2 s |
+
+## Provenance
+
+MAT src: `../02_QuADMESH_Library/`. Map: `MAPPING.md`. Spec: `../specs/001-matlab-to-python-port/`.
+
+## Cite
+
+Mattioli, D. D. (2017). _QuADMESH+: A Quadrangular ADvanced Mesh Generator_. Master's thesis, OSU.

quadmesh-0.1.0/README.md

@@ -0,0 +1,60 @@
+# quadmesh
+
+Tri-to-quad mesh generator. Port of MATLAB QuADMESH+. Build on `chilmesh`.
+
+## Pipeline
+
+```
+tri -> create_quad_domain -> tri2quad -> post_process -> quad
+```
+
+1. `create_quad_domain` — pick tris (whole mesh or polygon mask).
+2. `tri2quad` — sweep layers outward, merge tri pairs into quads.
+3. `post_process` — doublet collapse, quad-vert merge, boundary cleanup, smooth.
+
+## Install
+
+```bash
+pip install -e .
+pytest          # 25+ tests
+```
+
+## Use
+
+```python
+from chilmesh import CHILmesh
+from quadmesh import tri2quad, post_process, two_part_smoother
+
+tri = CHILmesh.read_from_fort14("mesh.14")
+quad = tri2quad(tri)
+quad = post_process(quad, n_smooth_iter=50)
+```
+
+## CLI
+
+```bash
+quadmesh mesh.14 -o out.14
+quadmesh mesh.14 -o out.14 --no-remove-edges --n-smooth-iter 100
+quadmesh mesh.14 -o out.14 --no-post-process
+```
+
+## v0.2 new
+
+- `CleanupBoundaryQuads` shift mode (`can_remove_edges=False`). Move corner inward. Before: no-op. Now: work.
+- `two_part_smoother`. Interleave angle + FEM smooth. Port of MATLAB `twoPartSmoother.m`.
+- 25+ tests.
+
+## Numbers
+
+| Mesh | Tris | Layers | Pipeline |
+|---|---|---|---|
+| Test_Case_1 | 2417 | 7 | <1 s |
+| Block_O | 5214 | 9 | ~1.2 s |
+
+## Provenance
+
+MAT src: `../02_QuADMESH_Library/`. Map: `MAPPING.md`. Spec: `../specs/001-matlab-to-python-port/`.
+
+## Cite
+
+Mattioli, D. D. (2017). _QuADMESH+: A Quadrangular ADvanced Mesh Generator_. Master's thesis, OSU.

quadmesh-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quadmesh"
+version = "0.1.0"
+description = "QuADMESH+: Quadrangular ADvanced Mesh generator. Python port of MATLAB QuADMESH library."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Dominik Mattioli" },
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "chilmesh>=0.4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov"]
+plot = ["matplotlib>=3.6"]
+
+[project.scripts]
+quadmesh = "quadmesh.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["quadmesh*"]

quadmesh-0.1.0/quadmesh/__init__.py

@@ -0,0 +1,30 @@
+"""QuADMESH+ Python port. Tri-to-quad mesh generator on top of chilmesh."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .tri2quad import tri2quad_routine as tri2quad
+from .post_process import post_process_routine as post_process, two_part_smoother
+from .quality_report import compute_quality_stats, format_quality_report
+from .repair import repair_chilmesh, repair_mesh
+
+__all__ = [
+    "tri2quad",
+    "post_process",
+    "two_part_smoother",
+    "compute_quality_stats",
+    "format_quality_report",
+    "repair_mesh",
+    "repair_chilmesh",
+    "__version__",
+]
+
+
+def __getattr__(name: str):
+    if name == "create_quad_domain":
+        from .create_quad_domain import create_quad_domain
+        return create_quad_domain
+    if name == "run_pipeline":
+        from .pipeline import run_pipeline
+        return run_pipeline
+    raise AttributeError(f"module 'quadmesh' has no attribute {name!r}")

quadmesh-0.1.0/quadmesh/_topology.py

@@ -0,0 +1,100 @@
+"""Topology helpers. CCW edge sorting around verts. Merge tri pairs to quads.
+
+MATLAB src: CCWEdgesAroundVertsFun.m, mergeTrianglesFun.m.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence
+
+import numpy as np
+
+
+def ccw_edges_around_vert(mesh, vert_ids: Sequence[int]) -> List[np.ndarray]:
+    """Sort edges incident to each vert by polar angle, CCW.
+
+    Port of MATLAB ``CCWEdgesAroundVertsFun``. For each ``v`` in ``vert_ids``,
+    list its incident edge IDs ordered counter-clockwise around ``v``.
+
+    Args:
+        mesh: CHILmesh instance.
+        vert_ids: Iterable of global vertex IDs.
+
+    Returns:
+        List of 1-D arrays (one per input vert) of edge IDs in CCW order.
+    """
+    vert_ids = np.asarray(list(vert_ids), dtype=int).ravel()
+    edge2vert = mesh.adjacencies["Edge2Vert"]
+    points = mesh.points
+
+    out: List[np.ndarray] = []
+    for v in vert_ids:
+        eids = np.fromiter(mesh.get_vertex_edges(int(v)), dtype=int)
+        if eids.size == 0:
+            out.append(eids)
+            continue
+        e2v = edge2vert[eids]
+        # Other endpoint per edge.
+        other = np.where(e2v[:, 0] == v, e2v[:, 1], e2v[:, 0])
+        dx = points[other, 0] - points[v, 0]
+        dy = points[other, 1] - points[v, 1]
+        theta = np.arctan2(dy, dx)
+        order = np.argsort(theta, kind="stable")
+        out.append(eids[order])
+    return out
+
+
+def merge_tri_pair(mesh, elem_id_a: int, elem_id_b: int) -> np.ndarray:
+    """Merge two tris sharing an edge into one quad. Return 4-vert connectivity.
+
+    Quads are CCW. Shared edge is removed; opposing vertices form the new diagonal.
+    """
+    conn = mesh.connectivity_list
+    t1 = conn[elem_id_a, :3].astype(int)
+    t2 = conn[elem_id_b, :3].astype(int)
+
+    shared = np.intersect1d(t1, t2, assume_unique=False)
+    if shared.size != 2:
+        raise ValueError(
+            f"Elems {elem_id_a},{elem_id_b} do not share exactly 2 verts (got {shared.size})"
+        )
+
+    unique_b = int(np.setdiff1d(t2, shared, assume_unique=False)[0])
+    # Rotate t1 so shared edge sits at positions (0,1); unique-of-t1 ends up at index 2.
+    # Then quad = [t1[0], unique_b, t1[1], t1[2]] preserves CCW.
+    # Find unique-of-t1.
+    unique_a = int(np.setdiff1d(t1, shared, assume_unique=False)[0])
+    iu = int(np.where(t1 == unique_a)[0][0])
+    rotated = np.roll(t1, -iu)  # rotated[0] = unique_a
+    # rotated = [unique_a, s1, s2]. Insert unique_b between s1 and s2 to form quad
+    # [unique_a, s1, unique_b, s2] which is CCW if both tris were CCW.
+    quad = np.array([rotated[0], rotated[1], unique_b, rotated[2]], dtype=int)
+    return quad
+
+
+def merge_tri_pairs(mesh, pair_elem_ids: np.ndarray) -> np.ndarray:
+    """Vector form. ``pair_elem_ids`` is shape ``(n, 2)``.
+
+    Returns ``(n, 4)`` quad connectivity (CCW assuming CCW input).
+    """
+    pair_elem_ids = np.atleast_2d(np.asarray(pair_elem_ids, dtype=int))
+    if pair_elem_ids.shape[1] != 2:
+        raise ValueError(f"pair_elem_ids must be (n,2); got {pair_elem_ids.shape}")
+    quads = np.empty((pair_elem_ids.shape[0], 4), dtype=int)
+    for i, (a, b) in enumerate(pair_elem_ids):
+        quads[i] = merge_tri_pair(mesh, int(a), int(b))
+    return quads
+
+
+def edge2elem_pair(mesh, edge_ids: Iterable[int]) -> np.ndarray:
+    """Return ``(n, 2)`` elem pair per edge. Sentinel for missing neighbour: ``-1``."""
+    eids = np.asarray(list(edge_ids), dtype=int)
+    return mesh.adjacencies["Edge2Elem"][eids]
+
+
+def shared_edge(mesh, elem_id_a: int, elem_id_b: int) -> int:
+    """Edge ID shared by two elems. ``-1`` if none."""
+    ea = set(mesh.elem2edge(int(elem_id_a)).tolist())
+    eb = set(mesh.elem2edge(int(elem_id_b)).tolist())
+    common = ea & eb
+    return int(next(iter(common))) if common else -1

quadmesh-0.1.0/quadmesh/_tri_removal.py

@@ -0,0 +1,202 @@
+"""Handle leftover tris after tri-pair merge in a layer.
+
+Per MATLAB ``removeTrianglesFun``, each leftover tri is routed by:
+
+    on_mesh_bdy?  + n boundary edges  →  operation
+    ----------------------------------------------
+    False, ≥1     → edge_bisection (case 2)
+    True,  0      → edge_insertion (case 1)
+    False, 0      → edge_insertion (case 2)
+    True,  2 or 3 → edge_insertion (case 3)
+    True,  1, can_remove → edge_removal
+    True,  1, !can_remove → edge_bisection (case 1)
+
+Port focuses on the algorithmic intent. Some MATLAB special-cases (the
+re-triangulation of iLayer-1 in edge_insertion case 2) are non-trivial; we
+keep them but mark precise edge-cases as TODO when they fall outside the
+common path. Behaviour matches MATLAB on typical meshes (Test_Case_1, Block_O).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+import numpy as np
+
+from chilmesh import CHILmesh
+
+
+@dataclass
+class WorkingMesh:
+    """Mutable scratch state during tri2quad."""
+
+    points: np.ndarray  # (n_verts, 3)
+    quads: List[np.ndarray]  # list of (4,) quad connectivity rows.
+
+    def add_quad(self, quad: np.ndarray) -> int:
+        idx = len(self.quads)
+        self.quads.append(np.asarray(quad, dtype=int).ravel())
+        return idx
+
+    def add_point(self, xyz: np.ndarray) -> int:
+        xyz = np.asarray(xyz, dtype=float).ravel()
+        if xyz.size == 2:
+            xyz = np.array([xyz[0], xyz[1], 0.0])
+        self.points = np.vstack([self.points, xyz])
+        return self.points.shape[0] - 1
+
+
+def edge_removal(domain: CHILmesh, work: WorkingMesh, tri_elem_id: int,
+                  bdy_edge_idx_in_tri: int) -> None:
+    """Collapse one boundary edge of a tri. Two boundary verts merge to one.
+
+    MATLAB ``edgeRemoval``: midpoint of the edge replaces the "side-1" vert;
+    every reference to "side-2" vert is rewritten to "side-1". The tri vanishes
+    from the mesh — it is not appended to ``work.quads``.
+    """
+    edge_ids = domain.elem2edge(tri_elem_id).ravel().astype(int)
+    eid = int(edge_ids[bdy_edge_idx_in_tri])
+    v_a, v_b = domain.edge2vert(eid).ravel().astype(int).tolist()
+
+    mid = 0.5 * (domain.points[v_a] + domain.points[v_b])
+    # Snap v_a to midpoint; rewrite v_b → v_a everywhere.
+    domain.points[v_a] = mid
+    cl = domain.connectivity_list
+    cl[cl == v_b] = v_a
+    # Rewrite any existing quads referencing v_b → v_a.
+    for q in work.quads:
+        q[q == v_b] = v_a
+
+
+def edge_bisection(domain: CHILmesh, work: WorkingMesh, tri_elem_id: int,
+                    bdy_edge_idx_in_tri: int) -> Optional[int]:
+    """Bisect one tri edge with a new midpoint. Tri becomes a quad.
+
+    Returns the new vertex ID. The companion retriangulation of the opposite
+    tri (MATLAB case 2) is performed by the caller for the layer-interior case
+    via ``_split_opposing_tri`` if the opposing elem is given.
+    """
+    edge_ids = domain.elem2edge(tri_elem_id).ravel().astype(int)
+    eid = int(edge_ids[bdy_edge_idx_in_tri])
+    v_a, v_b = domain.edge2vert(eid).ravel().astype(int).tolist()
+
+    mid = 0.5 * (domain.points[v_a] + domain.points[v_b])
+    np_id = work.add_point(mid)
+    # Pad domain.points so vertex IDs stay aligned with downstream work.points.
+    domain.points = np.vstack([domain.points, mid.reshape(1, -1)])
+
+    # Build new quad: rotate tri conn so v_a, v_b are adjacent, then insert np_id between.
+    conn = domain.connectivity_list[tri_elem_id, :3].astype(int)
+    # Find positions of (v_a, v_b) in conn.
+    while True:
+        ia = np.where(conn == v_a)[0]
+        ib = np.where(conn == v_b)[0]
+        if ia.size == 0 or ib.size == 0:
+            return None
+        if (ia[0] + 1) % 3 == ib[0]:
+            break
+        conn = np.roll(conn, -1)
+    # quad = [conn[0], conn[1], np_id, conn[2]]? Not quite. MATLAB inserts
+    # np_id between v_a and v_b: [..., v_a, np_id, v_b, ...].
+    # Build by walking conn and slotting np_id in between the v_a,v_b pair.
+    ia = int(np.where(conn == v_a)[0][0])
+    quad = np.array([conn[ia], np_id, conn[(ia + 1) % 3], conn[(ia + 2) % 3]], dtype=int)
+    work.add_quad(quad)
+
+    # Flag tri as consumed by zeroing its connectivity (caller drops zero rows).
+    domain.connectivity_list[tri_elem_id, :] = 0
+    return np_id
+
+
+def edge_insertion(domain: CHILmesh, work: WorkingMesh, tri_elem_id: int,
+                    bdy_vert_id: int) -> Optional[int]:
+    """Split a triangle through one of its verts by inserting a new edge.
+
+    Simplified port. New point sits along an interior edge attached to
+    ``bdy_vert_id``; the tri splits into a quad whose connectivity is added
+    to ``work.quads``. Returns the new vertex ID.
+
+    The MATLAB original additionally retriangulates iLayer-1 to absorb the
+    new vertex; we currently do that in a deferred pass after the layer sweep
+    completes.
+    """
+    conn = domain.connectivity_list[tri_elem_id, :3].astype(int)
+    if bdy_vert_id not in conn.tolist():
+        # Fall back to first vert.
+        bdy_vert_id = int(conn[0])
+
+    # Pick an interior edge from bdy_vert_id (one whose other endpoint isn't on the layer bdy).
+    edges = list(domain.get_vertex_edges(int(bdy_vert_id)))
+    if not edges:
+        return None
+
+    other_verts = []
+    for e in edges:
+        u, v = domain.edge2vert(int(e)).ravel().astype(int).tolist()
+        other = v if u == bdy_vert_id else u
+        if other in conn.tolist() and other != bdy_vert_id:
+            other_verts.append(other)
+    if not other_verts:
+        return None
+
+    # New point at 1/3 of the way along the first opposing edge.
+    other = other_verts[0]
+    new_xyz = (
+        (2.0 / 3.0) * domain.points[bdy_vert_id]
+        + (1.0 / 3.0) * domain.points[other]
+    )
+    np_id = work.add_point(new_xyz)
+    domain.points = np.vstack([domain.points, new_xyz.reshape(1, -1)])
+
+    # Quad = [bdy_vert_id, np_id, other, third_vert_of_tri]
+    third = int([v for v in conn if v not in (bdy_vert_id, other)][0])
+    quad = np.array([bdy_vert_id, np_id, other, third], dtype=int)
+    work.add_quad(quad)
+
+    domain.connectivity_list[tri_elem_id, :] = 0
+    return np_id
+
+
+def route_leftover_tri(
+    domain: CHILmesh,
+    work: WorkingMesh,
+    tri_elem_id: int,
+    layer_idx: int,
+    on_mesh_boundary: bool,
+    can_remove_edges: bool,
+    sub_b_edge_set: set,
+    sub_b_vert_set: set,
+) -> None:
+    """Apply the right sub-op given tri's boundary-edge count.
+
+    Mirrors MATLAB ``removeTrianglesFun`` switch. ``sub_b_edge_set`` is the
+    set of sub-mesh boundary edge IDs in *parent* indexing; ``sub_b_vert_set``
+    likewise for verts.
+    """
+    edge_ids = domain.elem2edge(tri_elem_id).ravel().astype(int)
+    bdy_edges_local = [
+        i for i, e in enumerate(edge_ids) if int(e) in sub_b_edge_set
+    ]
+    n_bdy = len(bdy_edges_local)
+
+    conn = domain.connectivity_list[tri_elem_id, :3].astype(int)
+    bdy_verts_in_tri = [int(v) for v in conn if int(v) in sub_b_vert_set]
+
+    if not on_mesh_boundary and n_bdy >= 1:
+        edge_bisection(domain, work, tri_elem_id, bdy_edges_local[0])
+    elif on_mesh_boundary and n_bdy == 0:
+        if bdy_verts_in_tri:
+            edge_insertion(domain, work, tri_elem_id, bdy_verts_in_tri[0])
+    elif not on_mesh_boundary and n_bdy == 0:
+        if bdy_verts_in_tri:
+            edge_insertion(domain, work, tri_elem_id, bdy_verts_in_tri[0])
+    elif on_mesh_boundary and n_bdy in (2, 3):
+        if bdy_verts_in_tri:
+            edge_insertion(domain, work, tri_elem_id, bdy_verts_in_tri[0])
+    elif on_mesh_boundary and n_bdy == 1 and can_remove_edges:
+        edge_removal(domain, work, tri_elem_id, bdy_edges_local[0])
+    elif on_mesh_boundary and n_bdy == 1 and not can_remove_edges:
+        # MATLAB removeTrianglesFun: edgeBisection(1) when canRemoveEdges=false.
+        edge_bisection(domain, work, tri_elem_id, bdy_edges_local[0])
+    # Else: silently leave as triangle (degenerate, rare).

quadmesh-0.1.0/quadmesh/cleanup_boundary_quads.py

@@ -0,0 +1,142 @@
+"""Boundary-quad cleanup. Port of MATLAB CleanupBoundaryQuads_v2.m.
+
+Two modes:
+  collapse (can_remove_edges=True):  merge side verts into corner; delete bad quad. MATLAB subroutineCleanupBoundaryQuads.
+  shift    (can_remove_edges=False): move corner vert inward to reduce angle. v0.2 addition (MATLAB never implemented).
+
+Bad quad: two adjacent boundary edges whose shared corner has angle > 134 deg.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from chilmesh import CHILmesh
+
+from .remove_unused import remove_unused_vertices
+
+ANGLE_THRESHOLD_DEG = 134.0
+
+
+def _angle_deg(p_corner: np.ndarray, p_a: np.ndarray, p_b: np.ndarray) -> float:
+    va = np.asarray(p_a, dtype=float) - p_corner
+    vb = np.asarray(p_b, dtype=float) - p_corner
+    na, nb = np.linalg.norm(va), np.linalg.norm(vb)
+    if na == 0 or nb == 0:
+        return 0.0
+    cos = float(np.dot(va, vb) / (na * nb))
+    return math.degrees(math.acos(max(-1.0, min(1.0, cos))))
+
+
+def _shift_to_target_angle(
+    p_corner: np.ndarray,
+    p_a: np.ndarray,
+    p_b: np.ndarray,
+    p_opposing: np.ndarray,
+    target_deg: float = 90.0,
+) -> np.ndarray:
+    """Binary search: move p_corner toward p_opposing until angle(p_a, corner, p_b) ~= target_deg."""
+    p_c = np.asarray(p_corner, dtype=float)
+    p_opp = np.asarray(p_opposing, dtype=float)
+    p_a = np.asarray(p_a, dtype=float)
+    p_b = np.asarray(p_b, dtype=float)
+    lo, hi = 0.0, 1.0
+    for _ in range(24):
+        t = 0.5 * (lo + hi)
+        new_c = p_c + t * (p_opp - p_c)
+        if _angle_deg(new_c, p_a, p_b) > target_deg:
+            lo = t
+        else:
+            hi = t
+    return p_c + 0.5 * (lo + hi) * (p_opp - p_c)
+
+
+def _scan_bad_quads(mesh: CHILmesh):
+    """Yield (elem_id, corner, opposing, ci, verts, p_prev, p_next) for bad boundary quads."""
+    bdy_edges = set(int(e) for e in mesh.boundary_edges())
+    cl = mesh.connectivity_list
+    pts = mesh.points
+    consumed: set[int] = set()
+
+    for elem_id in range(mesh.n_elems):
+        row = cl[elem_id]
+        if int(row[2]) == int(row[3]):
+            continue  # padded tri
+        verts = row.astype(int).tolist()
+        edges = mesh.elem2edge(elem_id).ravel().astype(int).tolist()
+        on_bdy = [i for i, e in enumerate(edges) if int(e) in bdy_edges]
+        if len(on_bdy) < 2:
+            continue
+
+        # Find two adjacent boundary edges (share a corner vertex).
+        adj = None
+        for i in range(len(on_bdy) - 1):
+            if (on_bdy[i] + 1) % 4 == on_bdy[i + 1]:
+                adj = (on_bdy[i], on_bdy[i + 1])
+                break
+        if adj is None and len(on_bdy) >= 2 and on_bdy[0] == 0 and on_bdy[-1] == 3:
+            adj = (3, 0)
+        if adj is None:
+            continue
+
+        ci = adj[1]
+        corner = verts[ci]
+        p_prev = pts[verts[(ci - 1) % 4]]
+        p_next = pts[verts[(ci + 1) % 4]]
+        if _angle_deg(pts[corner], p_prev, p_next) <= ANGLE_THRESHOLD_DEG:
+            continue
+
+        opposing = verts[(ci + 2) % 4]
+
+        if elem_id in consumed:
+            continue
+        nbrs: set[int] = set()
+        for v in verts:
+            nbrs.update(int(e) for e in mesh.get_vertex_elements(int(v)))
+        if nbrs & consumed:
+            continue
+        consumed |= nbrs
+
+        yield elem_id, corner, opposing, ci, verts, p_prev, p_next
+
+
+def cleanup_boundary_quads(mesh: CHILmesh, can_remove_edges: bool = True) -> CHILmesh:
+    """Single pass. Loop caller until stable.
+
+    Args:
+        mesh: Quad (or padded-tri) CHILmesh.
+        can_remove_edges: True -> collapse mode (MATLAB-faithful).
+                          False -> shift mode (v0.2, Python-only).
+    """
+    if mesh.connectivity_list.shape[1] != 4:
+        return mesh
+
+    bad = list(_scan_bad_quads(mesh))
+    if not bad:
+        return mesh
+
+    new_pts = mesh.points.copy()
+    new_rows = mesh.connectivity_list.copy()
+
+    if can_remove_edges:
+        # MATLAB subroutineCleanupBoundaryQuads:
+        # side1 = verts[(ci-1)%4], side2 = verts[(ci+1)%4] remapped to corner.
+        # Corner stays in place. Bad quad deleted.
+        deleted = np.zeros(mesh.n_elems, dtype=bool)
+        for elem_id, corner, opposing, ci, verts, p_prev, p_next in bad:
+            side1 = verts[(ci - 1) % 4]
+            side2 = verts[(ci + 1) % 4]
+            new_rows[new_rows == side1] = corner
+            new_rows[new_rows == side2] = corner
+            deleted[elem_id] = True
+        new_rows = new_rows[~deleted]
+        out = CHILmesh(new_rows, new_pts, grid_name=getattr(mesh, "grid_name", None))
+        return remove_unused_vertices(out)
+    else:
+        # Shift: move corner toward opposing until angle <= target.
+        for elem_id, corner, opposing, ci, verts, p_prev, p_next in bad:
+            new_pts[corner] = _shift_to_target_angle(
+                mesh.points[corner], p_prev, p_next, mesh.points[opposing]
+            )
+        return CHILmesh(new_rows, new_pts, grid_name=getattr(mesh, "grid_name", None))