bluemesh2d 0.1.1.dev0__py3-none-any.whl

bluemesh2d/aabb_tree/queryset.py

@@ -0,0 +1,83 @@
+import numpy as np
+
+
+def queryset(tr, tm, fn, *args):
+    """Perform spatial queries on AABB-indexed collections.
+
+    Parameters
+    ----------
+    tr : dict
+        AABB tree from :func:`maketree`, with keys ``"xx"``, ``"ii"``, and
+        ``"ll"``.
+    tm : dict
+        Query-to-tree mapping (typically from :func:`mapvert`), with keys
+        ``"ii"`` (tree node indices) and ``"ll"`` (query indices per node).
+    fn : callable
+        Intersection kernel called as ``pk, ck = fn(pj, cj, *args)``, where
+        ``pj`` and ``cj`` are query and object indices within a node and
+        ``pk``/``ck`` are matching pairs.
+    *args
+        Extra arguments forwarded to ``fn``.
+
+    Returns
+    -------
+    qi : ndarray
+        Indices of query items with at least one intersection.
+    qp : ndarray of shape (N, 2)
+        Pointer ranges into ``qj`` for each entry in ``qi``; intersections
+        for ``qi[i]`` lie in ``qj[qp[i, 0]:qp[i, 1]]``.
+    qj : ndarray
+        Flattened list of intersecting object indices.
+
+    References
+    ----------
+    Translation of the MESH2D function ``QUERYSET``.
+    Original MATLAB source: https://github.com/dengwirda/mesh2d
+    """
+
+    if tr is None or len(tr) == 0:
+        return np.array([]), np.array([]), np.array([])
+    if not isinstance(tr, dict) or not isinstance(tm, dict):
+        raise TypeError("queryset: incorrect input class.")
+    if not all(k in tm for k in ("ii", "ll")):
+        raise ValueError("queryset: invalid aabb-maps obj.")
+    if not all(k in tr for k in ("xx", "ii", "ll")):
+        raise ValueError("queryset: invalid aabb-tree obj.")
+    ic = []
+    jc = []
+
+    for ip in range(len(tm["ii"])):
+        ni = tm["ii"][ip] #  node (in tree)
+
+        qi, qj = fn(
+            tm["ll"][ip],  # query in tile
+            tr["ll"][ni],  # items in tile
+            *args,
+        )
+        ic.append(np.atleast_1d(qi))
+        jc.append(np.atleast_1d(qj))
+
+    if len(ic) == 0 or len(jc) == 0:
+        return np.array([]), np.array([]), np.array([])
+    qi = np.concatenate(ic)
+    qj = np.concatenate(jc)
+
+    if qj.size == 0:
+        return np.array([]), np.array([]), np.array([])
+
+    sort_idx = np.argsort(qi)
+    qi = qi[sort_idx]
+    qj = qj[sort_idx]
+
+    diff_idx = np.nonzero(np.diff(qi) != 0)[0]
+    ni = len(qi)
+
+    qi_unique = np.concatenate((qi[diff_idx], [qi[-1]]))
+    nj = len(qj)
+    ni = len(qi_unique)
+
+    qp = np.zeros((ni, 2), dtype=int)
+    qp[:, 0] = np.concatenate(([0], diff_idx + 1))
+    qp[:, 1] = np.concatenate((diff_idx, [nj - 1]))
+
+    return qi_unique, qp, qj

bluemesh2d/aabb_tree/scantree.py

@@ -0,0 +1,124 @@
+import numpy as np
+
+
+def scantree(tr, pi, fn):
+    """Compute tree-to-item and item-to-tree mappings for an AABB tree.
+
+    Parameters
+    ----------
+    tr : dict
+        AABB tree from :func:`maketree`, with keys ``"xx"``, ``"ii"``, and
+        ``"ll"``. ``tr["xx"]`` holds node bounding boxes as ``[pmin, pmax]``;
+        ``tr["ii"]`` holds parent–child indices; ``tr["ll"]`` lists item
+        indices per node.
+    pi : ndarray
+        Query items (e.g. vertices or bounding boxes) to map against the tree.
+    fn : callable
+        Partition function called as ``ki, kj = fn(pj, ni, nj)``, where ``pj``
+        is a subset of items in the current node, ``ni`` and ``nj`` are child
+        node bounding boxes, and ``ki``/``kj`` are boolean masks of items
+        intersecting each child.
+
+    Returns
+    -------
+    tm : dict
+        Tree-to-item mapping with keys ``"ii"`` (node indices) and ``"ll"``
+        (lists of item indices per node).
+    im : dict
+        Item-to-tree mapping with keys ``"ii"`` (item indices) and ``"ll"``
+        (lists of tree node indices per item).
+
+    References
+    ----------
+    Translation of the MESH2D function ``SCANTREE``.
+    Original MATLAB source: https://github.com/dengwirda/mesh2d
+    """
+
+    tm = {"ii": [], "ll": []}
+    im = {"ii": [], "ll": []}
+
+    if pi is None or len(pi) == 0:
+        return tm, im
+    if tr is None or len(tr) == 0:
+        return tm, im
+    if not isinstance(tr, dict) or not isinstance(pi, np.ndarray) or not callable(fn):
+        raise TypeError("scantree: incorrect input class.")
+
+    if not all(k in tr for k in ("xx", "ii", "ll")):
+        raise ValueError("scantree: incorrect AABB struct.")
+
+    n_nodes = tr["ii"].shape[0]
+    tm["ii"] = np.zeros(n_nodes, dtype=int)
+    tm["ll"] = [None] * n_nodes
+
+    ss = np.zeros(n_nodes, dtype=int)
+    sl = [None] * n_nodes
+    sl[0] = np.arange(pi.shape[0])
+
+    tf = np.array([len(x) > 0 for x in tr["ll"]])
+    # Descend tree from root, push items amongst nodes
+    ss[0] = 0
+    ns = 1
+    no = 0
+
+    while ns > 0:
+        ns -= 1
+        ni = ss[ns]  # pop
+
+        if tf[ni]:
+            # push onto tree-item mapping -- non-empty node NI contains items LL
+            tm["ii"][no] = ni
+            tm["ll"][no] = sl[ns]
+            no += 1
+
+        if tr["ii"][ni, 1] != 0:
+            c1 = tr["ii"][ni, 1]
+            c2 = tr["ii"][ni, 1] + 1
+            j1, j2 = fn(pi[sl[ns], :], tr["xx"][c1, :], tr["xx"][c2, :])
+            l1 = sl[ns][j1]
+            l2 = sl[ns][j2]
+
+            if l1.size > 0:
+                ss[ns] = c1
+                sl[ns] = l1
+                ns += 1
+            if l2.size > 0:
+                ss[ns] = c2
+                sl[ns] = l2
+                ns += 1
+
+    tm["ii"] = tm["ii"][:no]
+    tm["ll"] = tm["ll"][:no]
+
+    # Compute inverse map only if desired
+    if tm and im is None:
+        return tm
+
+    # Accumulate pair'd tree-item matches
+    ic = []
+    jc = tm["ll"]
+
+    for ip in range(no):
+        ni = tm["ii"][ip]
+        ic.append(np.full(len(jc[ip]), ni, dtype=int))
+
+    if len(ic) == 0:
+        return tm, im
+
+    ii = np.concatenate(ic)
+    jj = np.concatenate(jc)
+
+    im["ll"] = [None] * pi.shape[0]
+
+    jx = np.argsort(jj)
+    jj = jj[jx]
+    ii = ii[jx]
+
+    diff_idx = np.nonzero(np.diff(jj) != 0)[0]
+    im["ii"] = np.concatenate((jj[diff_idx], [jj[-1]]))
+    bounds = np.concatenate(([0], diff_idx + 1, [len(ii)]))
+    # Distribute single item-tree matches
+    for ip in range(len(im["ii"])):
+        im["ll"][ip] = ii[bounds[ip] : bounds[ip + 1]]
+
+    return tm, im

bluemesh2d/dependencies.py

@@ -0,0 +1,83 @@
+"""Runtime dependency checks for the staged meshing pipeline."""
+from __future__ import annotations
+
+
+
+
+def check_dependencies():
+    """Check that the required runtime dependencies are importable.
+
+    ``xarray`` is not needed (the UGRID NetCDF is written directly with
+    ``netCDF4``) and ``triangle`` is optional (without it, ``deltri`` falls
+    back to the pure-scipy conforming Delaunay) -- see
+    :func:`optional_dependencies`.
+
+    Returns
+    -------
+    missing : list of str
+        Names of required packages that failed to import. Empty if all are
+        present.
+    """
+    missing = []
+    # contourpy is matplotlib's contouring backend, used by the stage-1
+    # coastline extraction; some QGIS bundles (macOS vcpkg builds) ship
+    # matplotlib without it, so it is checked explicitly.
+    # NOTE: keep this list in sync with REQUIRED in the QGIS plugin's
+    # deps_installer.py (kept separate on purpose: the installer must load
+    # even when this package is broken or missing).
+    # pyproj deliberately BEFORE rasterio: importing a pip rasterio wheel
+    # first loads its own libproj and breaks pyproj afterwards.
+    for mod in ("numpy", "scipy", "pyproj", "shapely", "rasterio",
+                "matplotlib", "contourpy", "netCDF4"):
+        try:
+            __import__(mod)
+        except Exception:
+            missing.append(mod)
+    return missing
+
+
+def optional_dependencies():
+    """Check for optional packages that only affect speed or quality.
+
+    Returns
+    -------
+    missing : list of str
+        Names of optional packages that failed to import. Empty if all are
+        present.
+    """
+    missing = []
+    try:
+        __import__("triangle")
+    except Exception:
+        missing.append("triangle")
+    return missing
+
+
+def smood_dependencies():
+    """Check for packages required only when ``smood`` (orthogonalization)
+    is used.
+
+    ``bluemesh2d.smood`` always builds an in-memory ``xarray.Dataset`` (via
+    ``ortho_merge_iterate_tria`` / ``adcirc2DFlowFM``) regardless of the
+    ``merge_small_links`` option, so ``xarray`` is required to call it even
+    though it is not needed anywhere else in this plugin (the UGRID NetCDF
+    exports write directly with ``netCDF4``).
+
+    Returns
+    -------
+    missing : list of str
+        Names of packages required by ``smood`` that failed to import. Empty
+        if all are present.
+    """
+    missing = []
+    try:
+        __import__("xarray")
+    except Exception:
+        missing.append("xarray")
+    return missing
+
+
+# ===========================================================================
+# Stage 1: raster -> water-domain polygon
+# ===========================================================================
+

bluemesh2d/feedback.py

@@ -0,0 +1,142 @@
+"""Feedback plumbing shared by the staged meshing pipeline (QGIS-free)."""
+from __future__ import annotations
+
+import io
+import sys
+
+
+
+class MeshCanceled(Exception):
+    """Exception raised when a run is cancelled.
+
+    Raised when ``feedback.isCanceled()`` becomes ``True`` mid-run.
+    """
+
+
+class _NullFeedback:
+    """No-op feedback so the facade runs without QGIS.
+
+    Writes to ``sys.__stdout__`` (the interpreter's real stdout) rather than
+    via ``print``, so it stays safe while ``refine``/``smooth`` output is
+    captured by ``contextlib.redirect_stdout`` (printing to the redirected
+    stdout would recurse).
+    """
+
+    def isCanceled(self):
+        return False
+
+    def pushInfo(self, msg):
+        sys.__stdout__.write(str(msg) + "\n")
+
+    def pushWarning(self, msg):
+        sys.__stdout__.write("WARNING: " + str(msg) + "\n")
+
+    def setProgress(self, pct):
+        pass
+
+
+class _LogWriter(io.TextIOBase):
+    """File-like object that forwards captured stdout lines to feedback.
+
+    Parameters
+    ----------
+    feedback : object
+        Feedback sink exposing ``pushInfo(str)``, e.g. a
+        ``QgsProcessingFeedback`` or :class:`_NullFeedback`.
+    """
+
+    def __init__(self, feedback):
+        self._fb = feedback
+        self._buf = ""
+
+    def write(self, s):
+        self._buf += s
+        while "\n" in self._buf:
+            line, self._buf = self._buf.split("\n", 1)
+            if line.strip():
+                self._fb.pushInfo(line)
+        return len(s)
+
+    def flush(self):
+        if self._buf.strip():
+            self._fb.pushInfo(self._buf)
+        self._buf = ""
+
+
+def _check(feedback):
+    if feedback.isCanceled():
+        raise MeshCanceled()
+
+
+class _SubProgress:
+    """Feedback proxy mapping a sub-task's 0-100 progress into [lo, hi].
+
+    Lets a stage function report absolute progress while a multi-stage
+    caller (``generate_mesh``) keeps a monotonic overall bar.
+    """
+
+    def __init__(self, feedback, lo, hi):
+        self._fb = feedback
+        self._lo, self._hi = float(lo), float(hi)
+
+    def isCanceled(self):
+        return self._fb.isCanceled()
+
+    def pushInfo(self, msg):
+        self._fb.pushInfo(msg)
+
+    def pushWarning(self, msg):
+        self._fb.pushWarning(msg)
+
+    def setProgress(self, pct):
+        self._fb.setProgress(
+            self._lo + (self._hi - self._lo) * float(pct) / 100.0)
+
+
+def _available_ram_bytes():
+    """Available system RAM in bytes, or ``None`` when it cannot be found."""
+    try:
+        import psutil
+        return int(psutil.virtual_memory().available)
+    except Exception:
+        pass
+    try:  # Linux fallback, no psutil needed
+        with open("/proc/meminfo") as f:
+            for line in f:
+                if line.startswith("MemAvailable:"):
+                    return int(line.split()[1]) * 1024
+    except Exception:
+        pass
+    return None
+
+
+def _warn_if_ram_risk(feedback, nbytes, what, hint=None):
+    """Warn when an estimated allocation may exhaust the available RAM.
+
+    Parameters
+    ----------
+    feedback : object
+        Feedback sink exposing ``pushWarning``.
+    nbytes : float
+        Estimated memory need (bytes).
+    what : str
+        Short description of the allocation, used in the message.
+    hint : str or None, optional
+        Extra sentence suggesting how to reduce the memory need.
+
+    Returns
+    -------
+    risky : bool
+        ``True`` when a warning was emitted.
+    """
+    avail = _available_ram_bytes()
+    if avail is None or nbytes < 0.5 * avail:
+        return False
+    msg = (f"{what} needs roughly {nbytes / 1e9:.1f} GB "
+           f"(~{avail / 1e9:.1f} GB of RAM available). QGIS may become "
+           "unresponsive or crash.")
+    if hint:
+        msg += " " + hint
+    feedback.pushWarning(msg)
+    return True
+

bluemesh2d/geom_util/boundary_util.py

@@ -0,0 +1,216 @@
+"""Stage 3: water polygon + hfun -> resampled boundary and PSLG."""
+from __future__ import annotations
+
+
+from ..feedback import _NullFeedback, _check
+
+
+def _fixed_part_from_z(poly):
+    """Split a Z-flagged polygon into 2D geometry + resample ``part`` lists.
+
+    Stage 1 marks vertices lying on the extent polygon boundary with Z=1
+    (Z=0 elsewhere; the user can toggle any vertex in the Vertex Editor).
+    Each arc of edges between two consecutive flagged vertices becomes one
+    part, so every flagged vertex -- contiguous run or isolated -- is a part
+    junction that ``resample_polygon_hfun`` keeps exactly. Rings holding
+    flagged vertices are rotated to start at one, so the part junctions
+    line up with the ring seam. Returns ``(poly, None)`` for 2D polygons.
+    """
+    import numpy as np
+    from shapely.geometry import Polygon
+
+    if not getattr(poly, "has_z", False):
+        return poly, None
+
+    rings = [np.asarray(poly.exterior.coords)]
+    rings += [np.asarray(r.coords) for r in poly.interiors]
+    part = []
+    rings2d = []
+    offset = 0
+    for r in rings:
+        pts = r[:-1] if len(r) > 1 and np.allclose(r[0, :2], r[-1, :2]) else r
+        flag = pts[:, 2] > 0.5 if pts.shape[1] > 2 else np.zeros(len(pts), bool)
+        n = len(pts)
+        fidx = np.flatnonzero(flag)
+        if fidx.size == 0:
+            rings2d.append(pts[:, :2])
+            offset += n
+            continue
+        # start the ring at a flagged vertex so arcs don't cross the seam
+        k0 = int(fidx[0])
+        pts = np.roll(pts, -k0, axis=0)
+        fidx = np.flatnonzero(np.roll(flag, -k0))  # fidx[0] == 0
+        bounds = list(fidx) + [n]
+        for a, b in zip(bounds[:-1], bounds[1:]):
+            part.append(np.arange(offset + a, offset + b))
+        rings2d.append(pts[:, :2])
+        offset += n
+    poly2d = Polygon(rings2d[0], rings2d[1:])
+    return poly2d, (part if part else None)
+
+
+def resample_boundary(poly, hfuns, min_angle_deg=25.0, min_hole_vertices=15,
+                      feedback=None):
+    """Resample the water polygon to the size function and build the PSLG.
+
+    `poly` may be a Polygon or MultiPolygon (each part is resampled
+    independently).
+
+    Parameters
+    ----------
+    poly : shapely.geometry.Polygon or shapely.geometry.MultiPolygon
+        Water domain polygon (working CRS), e.g. from
+        :func:`extract_water_polygon`.
+    hfuns : callable
+        Element-size function, ``hfuns(xy) -> h``.
+    min_angle_deg : float, optional
+        Minimum interior angle (deg) enforced during resampling. Default is
+        25.0.
+    min_hole_vertices : int, optional
+        Minimum vertex count for a hole to be kept. Default is 15.
+    feedback : object or None, optional
+        Feedback sink, see :func:`extract_water_polygon`.
+
+    Returns
+    -------
+    poly_comput : shapely.geometry.Polygon or shapely.geometry.MultiPolygon
+        Resampled polygon.
+    node : ndarray of shape (N, 2)
+        PSLG node coordinates.
+    edge : ndarray of shape (E, 2)
+        PSLG edges (0-based node indices).
+    """
+    feedback = feedback or _NullFeedback()
+    from shapely.geometry import MultiPolygon
+
+    from bluemesh2d.geom_util.poly_util import polygon_to_node_edge, resample_polygon_hfun
+
+    if poly.geom_type == "Polygon":
+        parts = [poly]
+    else:
+        parts = [g for g in poly.geoms if g.geom_type == "Polygon"]
+    if not parts:
+        raise RuntimeError("No polygon parts to resample.")
+    feedback.pushInfo(f"Water region(s) to mesh: {len(parts)}")
+
+    resampled = []
+    n_fixed_total = 0
+    for part in parts:
+        part2d, fixed_part = _fixed_part_from_z(part)
+        if fixed_part is not None:
+            # each fixed edge is its own part: every flagged vertex is a
+            # part junction and survives the resampling exactly
+            n_fixed_total += len(fixed_part)
+        rp = resample_polygon_hfun(part2d, hfuns,
+                                   min_angle_deg=min_angle_deg,
+                                   min_hole_vertices=min_hole_vertices,
+                                   part=fixed_part)
+        # drop parts that degenerate (smaller than the local element size)
+        if rp is not None and not rp.is_empty and rp.geom_type == "Polygon" \
+                and len(rp.exterior.coords) >= 4:
+            resampled.append(rp)
+        _check(feedback)
+    if not resampled:
+        raise RuntimeError(
+            "All water polygons are smaller than the requested element size; "
+            "decrease the minimum element size.")
+    if len(resampled) < len(parts):
+        feedback.pushInfo(
+            f"Dropped {len(parts) - len(resampled)} water region(s) smaller "
+            "than the local element size.")
+
+    if n_fixed_total:
+        feedback.pushInfo(
+            f"Fixed vertices preserved exactly: {n_fixed_total}")
+
+    poly_comput = resampled[0] if len(resampled) == 1 else MultiPolygon(resampled)
+    node, edge = polygon_to_node_edge(poly_comput)
+    feedback.pushInfo(f"Boundary: {len(node)} nodes, {len(edge)} edges")
+    return poly_comput, node, edge
+
+
+def pslg_from_segments(segments, tol=1e-3, close_rings=True):
+    """Rebuild a PSLG (node, edge) from a boundary lines layer.
+
+    Every consecutive vertex pair of each polyline becomes an edge. Vertices
+    closer than `tol` are snapped to a single node, so nodes moved, added or
+    deleted while editing in QGIS reconnect cleanly. Zero-length edges and
+    duplicates are dropped.
+
+    Parameters
+    ----------
+    segments : iterable of array_like of shape (N, 2)
+        Boundary polylines (coordinates in the working CRS).
+    tol : float, optional
+        Snapping tolerance (m) for merging close vertices into one node.
+        Default is 1e-3.
+    close_rings : bool, optional
+        If ``True`` (default), each polyline is treated as a closed boundary
+        ring: when its two endpoints are distinct nodes, a closing edge is
+        added. Already-closed rings (duplicate end vertex) and 2-point
+        segments are unaffected, so both ring-style and segment-style layers
+        work.
+
+    Returns
+    -------
+    node : ndarray of shape (N, 2)
+        PSLG node coordinates.
+    edge : ndarray of shape (E, 2)
+        PSLG edges (0-based node indices).
+
+    Raises
+    ------
+    RuntimeError
+        If fewer than 3 edges result, or if the boundary does not form closed
+        loops (a node touches a number of edges other than two).
+    """
+    import numpy as np
+
+    nodes = []
+    index = {}
+
+    def node_id(pt):
+        key = (round(pt[0] / tol), round(pt[1] / tol))
+        i = index.get(key)
+        if i is None:
+            i = len(nodes)
+            index[key] = i
+            nodes.append((float(pt[0]), float(pt[1])))
+        return i
+
+    edges = set()
+    for seg in segments:
+        seg = np.atleast_2d(np.asarray(seg, dtype=float))
+        first = last = None
+        for a, b in zip(seg[:-1], seg[1:]):
+            i, j = node_id(a), node_id(b)
+            if first is None:
+                first = i
+            last = j
+            if i != j:
+                edges.add((min(i, j), max(i, j)))
+        if close_rings and first is not None and last is not None and first != last:
+            edges.add((min(first, last), max(first, last)))
+
+    if len(edges) < 3:
+        raise RuntimeError("Boundary edges layer yields fewer than 3 edges.")
+    node = np.asarray(nodes, dtype=float)
+    edge = np.asarray(sorted(edges), dtype=int)
+
+    # the mesher needs closed loops: every node on exactly 2 edges
+    counts = np.bincount(edge.ravel(), minlength=len(node))
+    bad = np.flatnonzero(counts != 2)
+    if bad.size:
+        sample = ", ".join(
+            f"({node[b][0]:.1f}, {node[b][1]:.1f})" for b in bad[:5])
+        raise RuntimeError(
+            f"{bad.size} boundary node(s) are dangling ends or junctions "
+            f"(not closed loops), e.g. near {sample} (working CRS, m). "
+            "Fix the edges layer: every vertex must join exactly two segments.")
+    return node, edge
+
+
+# ===========================================================================
+# Stage 4: PSLG + hfun -> mesh -> UGRID NetCDF
+# ===========================================================================
+