Source code for pyrockfall._model

"""
model.py
===========

Base class :class:`Model` for storing and manipulating rockface geometries.
Provides translation, rotation, clipping, centroid computation, and slicing
utilities. Subclasses must implement storage and I/O logic.
"""
from __future__ import annotations

import os
from abc import ABC, abstractmethod
from typing import Iterable, List, Tuple, Union, Optional, Mapping, Sequence, Dict

import numpy as np
from scipy.optimize import minimize
from numpy.typing import NDArray

from ._geometry import Geometry
from ._frame import CurvilinearFrame
from ._filesystem import read_properties, write_ply_with_attrs, write_npz_full_fidelity, write_xyz_ascii, write_pcd_minimal
from ._utils import rotationAlign2x

[docs] class Model(ABC): """ Base class for geometric data used in rockfall workflows. This class stores and manipulates point coordinates (2D or 3D) and provides general-purpose geometric utilities (translate, rotate, centroid, bounding box). Simulation-agnostic. Subclasses are responsible for concrete storage, loading/saving, and any topology (e.g., faces/triangles). ### Subclassing requirements - You **must** implement: - `points` property (getter & setter): returns/sets an array of shape (N, D), D in {2, 3}. - `save(output_file)`: persist model to disk in your preferred format. - `segment(dx, du)`: produce windowed segments as model objects. - `split(dx, minPerc)`: split into two model objects using your rule. - `slice(direction, increment, **kwargs)`: return extracted `Geometry` objects. - You **may** override: - `clip(min_val, max_val)`: default raises NotImplementedError because clipping model may require updating topology; base class cannot guess that. """ # ---------------------------- # Construction & core storage # ---------------------------- def __init__(self) -> None: # Arbitrary per-point attribute map: name -> array of shape (N,) or (N, k) self._attrs: dict[str, np.ndarray] = {} self._normal: Optional[NDArray[np.float64]] = None # cache for normalVector() self._frame: Optional[CurvilinearFrame] = None # cache for the curvilinear frame self._removed: Optional[NDArray[np.float64]] = None # xyz of points dropped by removePoints() # ---------------------------- # Abstract point storage API # ---------------------------- @property @abstractmethod def points(self) -> np.ndarray: """(N, D) array view of point coordinates.""" raise NotImplementedError @points.setter @abstractmethod def points(self, value: np.ndarray) -> None: """Replace all points; subclasses must call _on_points_replaced(oldN, newN).""" raise NotImplementedError # ---------------------------- # Attribute dict API # ---------------------------- @property def attrs(self) -> Mapping[str, np.ndarray]: """ Read-only mapping of per-point attributes: name -> ndarray. Each value has shape (N,) or (N, k) where N == number of points. """ return self._attrs
[docs] def has_attr(self, name: str) -> bool: return name in self._attrs
[docs] def get_attr(self, name: str) -> np.ndarray: """Return the attribute array (by reference). Raises KeyError if missing.""" return self._attrs[name]
[docs] def set_attr(self, name: str, value: Optional[np.ndarray]) -> None: """ Set/replace a per-point attribute. `value` must have first dimension N. Accepts (N,), (N, k) with any dtype. Use None or empty to remove. Stores by reference (no forced copy). """ if value is None or (isinstance(value, np.ndarray) and value.size == 0): self._attrs.pop(name, None) return arr = np.asarray(value) self._check_attr_size(name, arr) self._attrs[name] = arr
[docs] def del_attr(self, name: str) -> None: """Remove an attribute if present.""" self._attrs.pop(name, None)
[docs] def list_attrs(self) -> list[str]: """List available attribute names.""" return list(self._attrs.keys())
[docs] def attr_shape(self, name: str) -> tuple[int, ...]: return tuple(self._attrs[name].shape)
[docs] def attr_dtype(self, name: str): return self._attrs[name].dtype
def _check_attr_size(self, name: str, arr: np.ndarray) -> None: """ Check if tentative attribute has appropriate size. `arr` must have first dimension N. Accepts (N,), (N, k) with any dtype. """ pts = self.points if pts.size == 0: raise ValueError("Set points before attaching attributes.") if arr.shape[0] != pts.shape[0]: raise ValueError(f"Attribute '{name}' length {arr.shape[0]} " f"!= number of points {pts.shape[0]}.") # ---------------------------- # Keeping attributes in sync # ---------------------------- def _on_points_replaced(self) -> None: """ Default policy when points array is replaced. If any attribute length != number of points, clear them all. """ n = self.points.shape[0] for k, arr in list(self._attrs.items()): if arr.shape[0] != n: self.del_attr(k) self._invalidate_caches() def _invalidate_caches(self, normal: bool = True) -> None: """ Forget everything derived from the point coordinates: the fitted plane normal, the curvilinear frame and the positions remembered by :meth:`removePoints`. Called whenever the points are replaced or moved. """ if normal: self._normal = None self._frame = None self._removed = None
[docs] def apply_point_mask_(self, mask: np.ndarray) -> None: """ Keep only points[mask]. Subclasses must override to update *topology*; this base method only handles attributes. """ mask = np.asarray(mask, dtype=bool) pts = self.points if mask.shape != (pts.shape[0],): raise ValueError("Mask must be boolean with length N points.") # Reindex attributes consistently for k, arr in list(self._attrs.items()): self._attrs[k] = arr[mask] # A subset lives in the same space: keep the frame and removed positions frame, removed = self._frame, self._removed self.points = pts[mask] # triggers _on_points_replaced self._frame, self._removed = frame, removed
[docs] def apply_point_index_map_(self, new_index_of_old: np.ndarray, new_N: Optional[int] = None) -> None: """ Reorder/duplicate/drop points according to an index map. new_index_of_old[i] = j means old point i goes to new row j. If new_N is omitted, it is inferred as max(j)+1. This supports decimation, duplication, or arbitrary reindexing. """ idx = np.asarray(new_index_of_old, dtype=np.int64) old_N = self.points.shape[0] if idx.shape != (old_N,): raise ValueError("new_index_of_old must have shape (N_old,)") if new_N is None: new_N = int(idx.max()) + 1 if idx.min() < 0 or idx.max() >= new_N: raise ValueError("Index map contains out-of-range target indices.") # Build new arrays pts_old = self.points D = pts_old.shape[1] pts_new = np.empty((new_N, D), dtype=pts_old.dtype) pts_new[idx] = pts_old self.points = pts_new # triggers _on_points_replaced # Reindex attributes for k, arr in list(self._attrs.items()): # shape (N, ...) → shape (new_N, ...) new_shape = (new_N,) + arr.shape[1:] new_arr = np.empty(new_shape, dtype=arr.dtype) new_arr[idx] = arr self._attrs[k] = new_arr
# ---------------------------- # I/O # ----------------------------
[docs] def save( self, filename: str, attributes: Sequence[str] | str | None = '*', *, overwrite: bool = False, allow_lossy: bool = False, # if True, permit dropping attrs unsupported by target format comments: dict[str, str] | None = None, # extra PLY comments (units, CRS, etc.) ) -> None: """ Save model to various formats. Parameters ---------- filename : str Path with extension: .ply, .npz, .xyz, .pcd (limited), ... attributes : {'*', None, sequence of names} Which attributes from self._attrs to include (when supported). - '*': include all attributes - None: include none - sequence: include only those present overwrite : bool Overwrite target file if exists. allow_lossy : bool If False (default), refuse formats that would drop attributes. tri_reduce : {'mean','mode',None} For Mesh only: reduce per-triangle attributes to per-vertex before saving PLY/XYZ. comments : dict[str,str] | None Stored as PLY comments (e.g., {'units':'m','crs':'EPSG:28356'}). """ ext = os.path.splitext(filename)[1].lower() if not overwrite and os.path.exists(filename): raise FileExistsError(f"{filename} exists. Use overwrite=True.") core = self._save_core_dict() # Collect selected attrs if attributes == '*': attrs = dict(self._attrs) elif attributes is None: attrs = {} else: attrs = {k: self._attrs[k] for k in attributes if k in self._attrs} # Route by extension if ext == ".ply": write_ply_with_attrs(filename, core, attrs, comments=comments) elif ext == ".npz": write_npz_full_fidelity(filename, core, self._attrs) elif ext == ".xyz": write_xyz_ascii(filename, core, attrs, allow_lossy=allow_lossy) elif ext == ".pcd": # Minimal writer (xyz + optional rgb) — warn if losing attrs write_pcd_minimal(filename, core, attrs, allow_lossy=allow_lossy) else: raise ValueError(f"Unsupported extension: {ext}. Prefer .ply or .npz")
@abstractmethod def _save_core_dict(self, **kwargs) -> dict[str, np.ndarray]: """ Return the minimal set of arrays that represent this model. The base class will merge these with any selected attributes and write them. Examples: - PointCloud -> {"points": (N,3)} - Mesh -> {"points": (N,3), "faces": (M,3)} or {"points","tris"/"quads"} """ raise NotImplementedError
[docs] @classmethod def load( cls, filename: str, attributes: Sequence[str] | None = None, **kwargs ) -> "Model": """ 1) Build a minimal instance via subclass hook. 2) If `attributes` requested, read & attach them post-construction. """ if isinstance(attributes, str): attributes = [attributes] obj = cls._load_core(filename, **kwargs) # subclass returns a ready instance if attributes: attrs = read_properties(filename, list(attributes)) obj._attrs.update(attrs) return obj
@classmethod @abstractmethod def _load_core(cls, filename: str, **kwargs) -> "Model": """Subclasses construct and return an instance (points/topology etc.).""" raise NotImplementedError # ---------------------------- # Spatial utilities # ----------------------------
[docs] def clip(self, min_val: np.ndarray, max_val: np.ndarray) -> None: """ Clip the model to an axis-aligned bounding box (AABB). NOTE: The base class cannot safely implement this because clipping often requires updating topology (faces/edges). Subclasses should implement their own logic (e.g., remove points outside AABB and rebuild connectivity, or perform polygon/mesh clipping). Parameters ---------- min_val : array-like (D,) Minimum coordinates of the AABB. max_val : array-like (D,) Maximum coordinates of the AABB. """ raise NotImplementedError("Model.clip(): implement in subclass to handle topology safely.")
[docs] def boundingBox(self) -> Tuple[NDArray[np.float64], NDArray[np.float64]]: """ Compute the axis-aligned bounding box of the current points. Returns ------- (min_corner, max_corner) : tuple of np.ndarray Each is shape (D,). Raises ValueError if there are no points. """ v = self.points if v.size == 0: raise ValueError("Cannot compute bounding box: no points.") return v.min(axis=0), v.max(axis=0)
[docs] def centroid(self) -> NDArray[np.float64]: """ Compute the centroid (arithmetic mean) of the points. Returns ------- np.ndarray Shape (D,). Raises ValueError if there are no points. """ v = self.points if v.size == 0: raise ValueError("Cannot compute centroid: no points.") return np.mean(v, axis=0)
# ---------------------------- # Rigid transforms # ----------------------------
[docs] def translate(self, value: Union[float, Iterable, np.ndarray], direction: str = "xyz") -> None: """ Translate the model along specified axes. Parameters ---------- value : float | array-like If scalar, applied to all axes listed in `direction`. If array-like, it is zipped with `direction` (1:1). direction : str Axes along which to translate, subset of {'x','y','z'}. For 2D data, only 'x' and 'y' are meaningful. Notes ----- - If `value` is scalar and `direction='xyz'` on a 2D model, the 'z' component is ignored. - Values are applied in the order given by `direction`. """ v = self.points if v.size == 0: return D = v.shape[1] allowed = "xy" if D == 2 else "xyz" for d in direction: if d not in allowed: raise ValueError(f"Direction '{d}' not valid for {D}D model.") vals = np.asarray(value, float).ravel() if vals.size == 1: vals = np.repeat(vals, len(direction)) if vals.size != len(direction): raise ValueError("Length of `value` must match number of axes in `direction`.") t = np.zeros(D, dtype=v.dtype) idx = {"x":0, "y":1, "z":2} for val, d in zip(vals, direction): t[idx[d]] = val # in-place, single pass v += t self._invalidate_caches(normal=False) # a translation keeps the plane normal
[docs] def rotate(self, theta: float, axis: str = "z") -> None: """ Rotate the model by an angle around a principal axis (in-place). Parameters ---------- theta : float Rotation angle in degrees. axis : {'x','y','z'} Axis of rotation. For 2D data, only 'z' is meaningful. Notes ----- - Rotation is performed about the origin. If you want to rotate about the centroid, call `c = centroid(); translate(-c); rotate(...); translate(c)`. """ v = self.points if v.size == 0: return c, s = np.cos(np.radians(theta)), np.sin(np.radians(theta)) D = v.shape[1] if D == 2: if axis != "z": raise ValueError("2D model can only rotate around 'z'.") x = v[:, 0].copy() # temp to avoid aliasing y = v[:, 1] v[:, 0] = c * x - s * y v[:, 1] = s * x + c * y return # 3D case if axis not in {"x","y","z"}: raise ValueError("Axis must be one of {'x','y','z'}.") x, y, z = v[:, 0], v[:, 1], v[:, 2] if axis == "x": y0 = y.copy() v[:, 1] = c * y0 - s * z v[:, 2] = s * y0 + c * z elif axis == "y": x0 = x.copy() v[:, 0] = c * x0 + s * z v[:, 2] = -s * x0 + c * z else: # 'z' x0 = x.copy() v[:, 0] = c * x0 - s * y v[:, 1] = s * x0 + c * y self._invalidate_caches()
# ---------------------------- # Orientation utilities # ----------------------------
[docs] def normalVector(self) -> NDArray[np.float64]: """ Fit a plane ``z = a x + b y + d``. Returns ------- np.ndarray ``plane_normal``: unit normal vector (-a, -b, 1) normalized. Orientation is adjusted to have a positive Z component (for stable convention). Notes ----- - For 2D data, this method is not defined and raises a ``ValueError``. - Plane is fit in the least squares sense. """ if self._normal is None: v = self.points if v.shape[1] != 3 or v.shape[0] < 3: raise ValueError("normalVector() needs >=3 points in 3D.") # Work in float64 and centre to improve conditioning. P = np.asarray(v, dtype=np.float64) Pc = P - P.mean(axis=0, keepdims=True) x, y, z = Pc[:, 0], Pc[:, 1], Pc[:, 2] # Design matrix and least-squares solve: [a, b, d_c] # (intercept is relative to the centred coords) A = np.column_stack([x, y, np.ones_like(x)]) coef, *_ = np.linalg.lstsq(A, z, rcond=None) a, b, d_c = coef # Unit normal is proportional to (a, b, -1) n = np.array([-a, -b, 1.0], dtype=np.float64) n /= np.linalg.norm(n) self._normal = n return self._normal
[docs] def dip(self, return_normal: bool = False) -> float: """ Dip angle of the fitted plane ``z = a x + b y + d``. Returns ------- float Dip angle in degrees, defined as ``atan(b)`` where ``z ≈ a x + b y + d``. This follows the convention of tilt along Y used in the original implementation. Notes ----- - For 2D data, this method is not defined and raises a ``ValueError``. - Plane is fit in the least squares sense. """ n = self.normalVector() # unit normal n_xy = np.hypot(n[0], n[1]) alpha = np.arctan2(n[2], n_xy) # angle between n and horizontal plane return float(90.0 - np.degrees(alpha))
[docs] def dipDirection(self) -> float: """ Dip direction of the fitted plane ``z = a x + b y + d``. Returns ------- float Dip direction in degrees, defined as ``atan2(a, b)`` where ``z ≈ a x + b y + d``. """ n = self.normalVector() # unit normal angle = 180 - np.degrees(np.arctan2(n[0], -n[1])) if angle < 0: angle += 360.0 return float(angle % 360)
[docs] def alignWithX(self, sense: int = 1) -> None: """ Rotate model in the XY-plane so that the fitted plane’s horizontal strike vector aligns with X. Parameters ---------- sense : {1, -1} Sense of direction: 1 = X+, -1 = X-. Notes ----- - The plane is fit as ``z = a x + b y + d`` (vertical least squares) via :meth:`normalVector`. - The plane’s unit normal is projected into XY. Its perpendicular (strike) is rotated onto +X using a single atan2. - If the fitted normal points downward (n_z < 0), it is flipped upward for consistency. - Translation to and from the centroid is applied so that rotation is about the global origin. """ if self.points.shape[1] != 3: raise ValueError("alignWithX() requires 3D model.") # Translate to origin for a stable rotation about Z c = self.centroid() self.translate(-c) # Fit plane and get its unit normal n = self.normalVector() direction = np.array([-n[1], n[0], 0.0]) norm = np.linalg.norm(direction) if norm > 1e-12: direction /= norm direction *= float(sense) R = rotationAlign2x(direction) self.points = self.points @ R.T # Restore original position self.translate(c)
[docs] def coneApproximation(self) -> Tuple[float, float, float, float]: if self.points.size == 0: return 0.0, 0.0, 0.0, 0.0 c = self.centroid() self.translate(-c) # Fit plane and get its unit normal n = self.normalVector() direction = np.array([-n[1], n[0], 0.0]) direction /= np.linalg.norm(direction) direction *= float(-1) R = rotationAlign2x(direction) # Restore original position v = self.points.copy() self.translate(c) v = v @ R.T z_min = v.min(axis=0)[2] v[:, 2] -= z_min x = v[:, 0] y = v[:, 1] z = v[:, 2] def lin_fit(p, return_func=True, return_grad=False, return_coeff=False, eps=1e-12): x0, y0 = p dx = x - x0 dy = y - y0 rho = np.sqrt(dx*dx + dy*dy) rho_safe = np.maximum(rho, eps) # avoid division by zero A = np.column_stack((np.ones_like(rho), rho)) ab, _, _, _ = np.linalg.lstsq(A, z, rcond=None) a, b = ab r = z - (a + b * rho) out = [] if return_func: f = float(r @ r) out.append(f) if return_grad: drho_dx0 = (x0 - x) / rho_safe drho_dy0 = (y0 - y) / rho_safe gx0 = -2.0 * b * np.sum(r * drho_dx0) gy0 = -2.0 * b * np.sum(r * drho_dy0) g = np.array([gx0, gy0], dtype=float) out.append(g) if return_coeff: out.append(a) out.append(b) if len(out) == 1: return out[0] return out x0_init = 0.0 y0_init = (x.min() - x.max()) * 0.25 p0 = np.array([x0_init, y0_init], dtype=float) res = minimize( fun=lambda p: lin_fit(p, return_func=True, return_grad=True), x0=p0, jac=True, method="BFGS", options=dict(gtol=1e-8, maxiter=500) ) x0, y0 = res.x # Recover cone parameters a, b = lin_fit((x0, y0), return_func=False, return_coeff=True) height = a radius = np.nan if abs(b) > 1e-14: radius = -a / b # Get cone center cone_center = np.array((x0, y0, 0.0)) cone_center = cone_center @ R cone_center += c # cone_center[2] += z_min return cone_center[0], cone_center[1], height, radius
# ---------------------------- # Curvilinear coordinates: (s, d, e) and (u, v, w) # ---------------------------- def _steep_mask(self, max_nz: float = 0.7) -> Optional[NDArray[np.bool_]]: """ Points that belong to the face rather than to the floor or berms, i.e. whose normal is far from vertical (``|nz| < max_nz``). Used to fit the polyline of the curvilinear frame. The base implementation reads the ``"normals"`` attribute and returns ``None`` when it is missing. Subclasses with topology may compute normals. """ if not self.has_attr("normals"): return None nrm = np.asarray(self.get_attr("normals"), dtype=float) if nrm.ndim != 2 or nrm.shape != (self.points.shape[0], 3): return None length = np.linalg.norm(nrm, axis=1) return (length > 0) & (np.abs(nrm[:, 2]) < max_nz * length)
[docs] def fitFrame( self, *, tol: float = 1.0, res: float = 0.5, corner_length: Union[str, float, None] = "auto", **kwargs, ) -> CurvilinearFrame: """ Fit the curvilinear frame of the model and keep it as :attr:`frame`. A plan-view polyline is fitted along the wall and the points are unrolled along it, which gives the coordinates returned by :meth:`sde` and :meth:`uvw`. Parameters ---------- tol : float How far the centreline of the wall may stray from each straight segment of the polyline (model units). res : float Bin width along the wall used by the fit (model units). corner_length : {"auto", float, None} Length either side of each bend over which the slicing direction turns. ``None`` spreads the turn along each whole segment. **kwargs : Passed to :meth:`CurvilinearFrame.fit`. Returns ------- CurvilinearFrame """ v = self.points if v.ndim != 2 or v.shape[1] != 3 or v.shape[0] < 3: raise ValueError("fitFrame() needs >=3 points in 3D.") self._frame = CurvilinearFrame.fit( v, steep=self._steep_mask(), tol=tol, res=res, corner_length=corner_length, **kwargs ) return self._frame
@property def frame(self) -> CurvilinearFrame: """ Curvilinear frame of the model. Fitted with default settings on first use (see :meth:`fitFrame`). It can also be assigned, e.g. a frame loaded with :meth:`CurvilinearFrame.load` or shared with another model. """ if self._frame is None: self.fitFrame() return self._frame @frame.setter def frame(self, value: Optional[CurvilinearFrame]) -> None: if value is not None and not isinstance(value, CurvilinearFrame): raise TypeError("frame must be a CurvilinearFrame or None.") self._frame = value
[docs] def sde(self, store: bool = False) -> NDArray[np.float64]: """ Curvilinear coordinates of the points. Returns ------- np.ndarray Shape (N, 3): ``s`` distance along the strike, ``d`` distance along the dip direction (increasing down-dip) and ``e`` elevation (equal to z). Points outside the invertible region of the frame are NaN. Parameters ---------- store : bool Also store the columns as attributes ``"strike"``, ``"dip_direction"`` and ``"elevation"``. """ sde = self.frame.xyz_to_sde(self.points) if store: for name, col in zip(("strike", "dip_direction", "elevation"), sde.T): self.set_attr(name, np.ascontiguousarray(col)) return sde
[docs] def uvw(self, store: bool = False) -> NDArray[np.float64]: """ Principal coordinates of the unrolled points. Returns ------- np.ndarray Shape (N, 3): ``u`` and ``v`` span the best-fit plane of ``(s, d, e)`` (``u`` along the strike, ``v`` up-dip) and ``w`` is the height above it. Parameters ---------- store : bool Also store the columns as attributes ``"U"``, ``"V"`` and ``"W"``. """ frame = self.frame sde = frame.xyz_to_sde(self.points) if frame.pca_axes is None: frame.fit_pca(sde) uvw = frame.sde_to_uvw(sde) if store: for name, col in zip(("U", "V", "W"), uvw.T): self.set_attr(name, np.ascontiguousarray(col)) return uvw
def _slicing_coords( self, direction: Optional[NDArray[np.float64]] = None, frame: Optional[CurvilinearFrame] = None, ) -> Tuple[NDArray[np.float64], Optional[CurvilinearFrame]]: """ Coordinates in which slices are planes of constant first column. - ``frame`` given, or neither given: ``(s, d, e)`` of that frame (default: the model's own frame), i.e. slices follow the strike of the wall. - ``direction`` given: the points rotated so that ``direction`` is the first axis, i.e. parallel slices normal to a fixed direction. Returns the coordinates (N, 3) and the frame used (``None`` for a fixed direction). """ if frame is None and direction is not None: R = rotationAlign2x(direction) return self.points @ R.T, None frame = self.frame if frame is None else frame return frame.xyz_to_sde(self.points), frame # ---------------------------- # Removing points and filling the holes left behind # ----------------------------
[docs] def removePoints(self, mask_or_attr: Union[str, np.ndarray], value=None) -> int: """ Remove points, either flagged by a boolean mask or selected by the value of an attribute (in-place). The positions of the removed points are remembered, so that :meth:`fillHoles` can rebuild the parts left empty, including those that reach the edge of the model. Parameters ---------- mask_or_attr : str | array-like of bool Name of a per-point attribute, or a boolean mask of length N that is True for the points to remove. value : scalar | sequence, optional With an attribute name: the value, or values, to remove. Returns ------- int Number of points removed. Examples -------- >>> pc.removePoints("Material", 0) # one class >>> pc.removePoints("Material", [0, 3]) # several classes >>> pc.removePoints(pc.get_attr("height") > 2) # any condition """ n = self.points.shape[0] if isinstance(mask_or_attr, str): if value is None: raise ValueError("Give the attribute value(s) to remove.") if not self.has_attr(mask_or_attr): raise ValueError(f"Attribute '{mask_or_attr}' not found.") arr = np.asarray(self.get_attr(mask_or_attr)) if arr.ndim == 2 and arr.shape[1] == 1: arr = arr[:, 0] if arr.ndim != 1 or arr.shape[0] != n: raise ValueError(f"Attribute '{mask_or_attr}' must hold one value per point.") mask = np.zeros(n, dtype=bool) for v in np.atleast_1d(value): if np.issubdtype(arr.dtype, np.floating): mask |= np.isclose(arr, v) else: mask |= arr == v else: mask = np.asarray(mask_or_attr) if mask.dtype != bool or mask.shape != (n,): raise ValueError("Mask must be boolean with length N points.") n_removed = int(np.count_nonzero(mask)) if n_removed == 0: return 0 removed = self.points[mask].copy() previous = self._removed self.apply_point_mask_(~mask) self._removed = removed if previous is None else np.vstack([previous, removed]) return n_removed
[docs] def fillHoles(self, attributes: Sequence[str] | str = (), **kwargs) -> "Model": """ Create points in the missing parts of the model and krige their coordinates and the selected attributes. See :meth:`PointCloud.fillHoles`. Not available for this type of model: convert it to a point cloud (:func:`mesh2PointCloud`), fill the holes and triangulate again (:func:`pointCloud2Mesh`). """ raise NotImplementedError( f"{self.__class__.__name__}.fillHoles() is not implemented; " "use mesh2PointCloud() -> PointCloud.fillHoles() -> pointCloud2Mesh()." )
def _split_position(self, s: NDArray[np.float64], minPerc: float = 0.05, min_turn: float = 5.0) -> float: """ Position along the strike at which to split the model in two. Returns ``s`` of the polyline vertex with the largest turning angle (at least `min_turn` degrees) that leaves a fraction `minPerc` of the given ``s`` values on each side; the median of ``s`` if there is no such bend. """ frame = self.frame fin = s[np.isfinite(s)] if fin.size == 0: return np.nan n_min = int(max(1, minPerc * fin.size)) turn = frame.turning_angles() for i in np.argsort(-turn): if turn[i] < np.radians(min_turn): break cut = float(frame.S0[i + 1]) n_left = int(np.count_nonzero(fin <= cut)) if n_min <= n_left <= fin.size - n_min: return cut return float(np.median(fin)) # ---------------------------- # Higher-level operations (abstract) — return project-specific types # ----------------------------
[docs] @abstractmethod def segment(self, dx: float, du: float = 0.0) -> List["Model"]: """ Segment the model into smaller sections/windows. Parameters ---------- dx : float Window width (project-specific meaning). du : float, default 0 Overlap between segments (same units as dx). Returns ------- list[Model] New model objects representing each segment/window. """ raise NotImplementedError
[docs] @abstractmethod def split(self, dx: float = 0.5, minPerc: float = 0.05) -> List["Model"]: """ Split the model into two parts according to your rule. Parameters ---------- dx : float, default 0.5 Cutting distance/parameter controlling the split. minPerc : float, default 0.05 Minimum fraction of points allowed in either output to avoid degenerate splits. Returns ------- list[Model] Two model objects (or potentially more, per your design). """ raise NotImplementedError
[docs] @abstractmethod def slice( self, direction: Optional[NDArray[np.float64]] = None, increment: Optional[float] = None, label: Optional[str] = None, **kwargs, ) -> Tuple[List["Geometry"], NDArray]: """ Slice the model into 2D profiles. Parameters ---------- direction : np.ndarray, optional ``None`` (default) slices along the strike of the wall using the curvilinear frame: slices are surfaces of constant ``s`` and the profile coordinates are ``(d, e)``. A vector instead cuts parallel slices normal to that fixed direction. increment : float Spacing between consecutive slices. label : str Name of the attribute containing material IDs. **kwargs : Implementation-specific options (e.g. ``frame`` to use a frame other than the model's own). Returns ------- list[Geometry] Extracted profiles as `Geometry` type. ndarray The slice positions (``s``, or the distance along ``direction``). """ raise NotImplementedError
[docs] def section( self, increment: float, label: str, *, frame: Optional[CurvilinearFrame] = None, **kwargs, ) -> Tuple[List["Geometry"], "Model"]: """ Extract 2D profiles along the strike of the model, and their points in 3D. This is :meth:`slice` along the strike (slices of constant ``s`` in the curvilinear frame), with each profile also mapped back to world coordinates. The model itself is not modified. Parameters ---------- increment : float Spacing between consecutive sections along the strike. label : str Name of the attribute holding material IDs. frame : CurvilinearFrame, optional Frame to slice in. Defaults to the frame of the model. **kwargs : Passed to :meth:`slice` of the subclass. Returns ------- profiles : list[Geometry] One 2D profile per section, ordered from crest to toe, with node coordinates given as (horizontal distance from the crest node, height above the lowest node) and material IDs per segment as attributes. sections_pc : PointCloud All section nodes as one point cloud in the model's coordinates, with the material attribute (`label`, one value per node) and a ``"Profile"`` attribute numbering the sections along the strike. Raises ------ ValueError If no valid sections are found. """ from ._pointcloud import PointCloud # here to avoid a circular import frame = self.frame if frame is None else frame slices, positions = self.slice(None, increment, label, frame=frame, **kwargs) if len(slices) == 0: raise ValueError("No valid sections found. Try adjusting parameters.") profiles = [] section_pts = [] section_mat = [] section_id = [] for k, (prof, s_k) in enumerate(zip(slices, positions)): d, e = prof.nodes[:, 0], prof.nodes[:, 1] mats = np.asarray(prof.attributes) if e[0] < e[-1]: # crest first d, e, mats = d[::-1], e[::-1], mats[::-1] # World coordinates of the section nodes sde = np.column_stack([np.full(d.shape, s_k), d, e]) section_pts.append(frame.sde_to_xyz(sde)) section_mat.append(np.append(mats, mats[-1])) # one material per node section_id.append(np.full(d.shape[0], k, dtype=int)) # Profile relative to the crest node and the base of the section dist = np.abs(d - d[np.argmax(e)]) profiles.append(Geometry(nodes=np.column_stack([dist, e - e.min()]), attributes=mats)) sections_pc = PointCloud(points=np.concatenate(section_pts, axis=0)) sections_pc.set_attr(label, np.concatenate(section_mat, axis=0)) sections_pc.set_attr("Profile", np.concatenate(section_id, axis=0)) return profiles, sections_pc
def __repr__(self) -> str: cls = self.__class__.__name__ txt = f"{cls}(" try: v = self.points shape = tuple(v.shape) dtype = v.dtype txt += f"points_shape={shape}, dtype={dtype}, " except Exception: pass n_attrs = len(self._attrs) return txt + f"n_attrs={n_attrs})"