# _geometry3d.py
# ===========
from __future__ import annotations
from typing import Optional, Union, Tuple, Sequence
from numpy.typing import NDArray
import numpy as np
from ._geometry import Geometry
from ._utils import (
build_neighbours_mesh,
getTriPoints,
isInsideTriangle,
timeClosest,
timeParabolaPlane,
timeRaySegment,
)
ArrayF = NDArray[np.floating]
ArrayI = NDArray[np.integer]
[docs]
class Geometry3D(Geometry):
"""3D triangular geometry with 3D intersection helpers (exit time & parabola hit).
This subclass keeps :class:`~.Geometry`’s nodes/sampling logic and
only overrides:
- :meth:`exitTime` (ray–directed-edge on the current triangle plane)
- :meth:`intersectParabola` (parabola–triangle via neighbour walk)
Args:
nodes: Node coordinates of shape ``(N, 3)``.
elements: Triangle connectivity of shape ``(E, 3)`` (0-based).
materialIDs: Optional per-element IDs into `materials` (when `materials` is a table).
nodes_std: Optional node std-devs, shape ``(N, 3)``.
neighbours: Optional directed-edge neighbours array of shape ``(E, 3)``.
If omitted, it will be computed lazily on first access.
Raises:
ValueError: If nodes are not 3D, elements are not triangles, or
provided `neighbours` has an invalid shape/index range.
"""
def __init__(
self,
nodes: NDArray[np.floating],
*,
elements: Optional[NDArray[np.integer]] = None,
nodes_std: Optional[NDArray[np.floating]] = None,
attributes: Optional[Union[Sequence[int], NDArray[np.integer]]] = None,
neighbours: Optional[NDArray[np.integer]] = None,
) -> None:
# Delegate core setup to Geometry
super().__init__(
nodes=nodes,
nodes_std=nodes_std,
elements=elements,
attributes = attributes,
neighbours = neighbours,
)
# --------------------------
# Neighbours
# --------------------------
@property
def neighbours(self) -> np.ndarray:
"""np.ndarray of shape (E, 3): Directed-edge neighbours per triangle.
Convention: for triangle ``[v0, v1, v2]``,
``neighbours[e, 0]`` is across the directed edge ``v0→v1``,
``neighbours[e, 1]`` across ``v1→v2``, and
``neighbours[e, 2]`` across ``v2→v0``. Boundary → ``-1``.
"""
if self._neighbours is None:
self._neighbours = build_neighbours_mesh(self._elements.astype(np.int32))
return self._neighbours
# --------------------------
# 3D exit along a triangle (constant velocity on plane)
# --------------------------
[docs]
def exitTime(
self,
p: np.ndarray, # (3, S)
v: np.ndarray, # (3, S)
elem_id: np.ndarray, # (S,)
*,
samples: Optional[np.ndarray] = None, # None or (3, M, 1) or (3, M, S)
tol: float = 1e-12,
) -> Tuple[np.ndarray, np.ndarray]:
"""Earliest t>0 where x(t)=p+v t hits a **directed edge** of the current triangle.
Args:
p: Positions (3, S).
v: Velocities (3, S).
elem_id: Current triangle per sample (S,).
samples: Optional sampled nodes (3, M, 1) or (3, M, S).
tol: Numerical tolerance.
Returns:
Tuple[np.ndarray, np.ndarray]:
next_elem (S,), t_exit (S,) with ``-1``/``nan`` for no exit.
"""
p = np.asarray(p, dtype=float)
v = np.asarray(v, dtype=float)
if p.shape != v.shape or p.ndim != 2 or p.shape[0] != 3:
raise ValueError("`p` and `v` must be (3, S).")
S = p.shape[1]
if elem_id.shape != (S,):
raise ValueError("`elem_id` must be shape (S,).")
elems = self.elements.astype(np.int32)
tri = elems[elem_id] # (S,3)
i0, i1, i2 = tri[:, 0], tri[:, 1], tri[:, 2]
pts = self.getSamples(samples, S=S) # (3, M, S)
ar = np.arange(S, dtype=np.int32)
P0 = pts[:, i0, ar]
P1 = pts[:, i1, ar]
P2 = pts[:, i2, ar]
# Plane basis / normal
E0 = P1 - P0
E1 = P2 - P0
n = np.cross(E0.T, E1.T).T
n_norm = np.linalg.norm(n, axis=0)
good = n_norm > tol
n[:, good] /= n_norm[good]
# Project pos/vel to plane
dp = p - P0
p_plane = p - n * np.sum(dp * n, axis=0)
v_tan = v - n * np.sum(v * n, axis=0)
moving = np.linalg.norm(v_tan, axis=0) > tol
ok = good & moving
next_elem = np.full(S, -1, dtype=np.int32)
t_exit = np.full(S, np.nan, dtype=float)
if not np.any(ok):
return next_elem, t_exit
ids = np.flatnonzero(ok)
def _edge_points(A: ArrayF, B: ArrayF) -> np.ndarray:
# (3, 2, K) with columns [A, B]
return np.stack((A, B), axis=1)
t0 = timeRaySegment(p_plane[:, ids], v_tan[:, ids], _edge_points(P0[:, ids], P1[:, ids]), tol=tol)
t1 = timeRaySegment(p_plane[:, ids], v_tan[:, ids], _edge_points(P1[:, ids], P2[:, ids]), tol=tol)
t2 = timeRaySegment(p_plane[:, ids], v_tan[:, ids], _edge_points(P2[:, ids], P0[:, ids]), tol=tol)
T = np.vstack((t0, t1, t2)) # (3, K)
e_idx = np.argmin(T, axis=0)
t_best = T[e_idx, np.arange(T.shape[1])]
hit = np.isfinite(t_best)
if np.any(hit):
sel = ids[hit]
t_exit[sel] = t_best[hit]
next_elem[sel] = self.neighbours[elem_id[sel], e_idx[hit]]
return next_elem, t_exit
# --------------------------
# 3D parabola–triangle walk
# --------------------------
[docs]
def intersectParabola(
self,
p: np.ndarray, # (3, S)
v: np.ndarray, # (3, S)
a: np.ndarray, # (3, S)
current: np.ndarray, # (S,)
*,
samples: Optional[np.ndarray] = None, # None or (3, M, 1) or (3, M, S)
t_min: float = 0.0,
t_max: float = np.inf,
tol: float = 1e-12,
max_steps: int = 32,
) -> Tuple[np.ndarray, np.ndarray]:
"""First impact for x(t)=p + v t + 0.5 a t² using directed-edge neighbour walking.
Args:
p: Initial positions (3, S).
v: Initial velocities (3, S).
a: Constant accelerations (3, S).
current: Starting triangle per sample (S,) (use -1 for “unknown”).
samples: Optional sampled nodes (3, M, 1) or (3, M, S).
t_min: Minimum accepted time (inclusive).
t_max: Maximum accepted time (inclusive).
tol: Numerical tolerance.
max_steps: Maximum neighbour-walk iterations.
Returns:
Tuple[np.ndarray, np.ndarray]: (hit_elem (S,), t_hit (S,))
with ``-1``/``nan`` on no impact.
"""
p = np.asarray(p, dtype=float)
v = np.asarray(v, dtype=float)
a = np.asarray(a, dtype=float)
if p.shape != v.shape or p.shape != a.shape or p.ndim != 2 or p.shape[0] != 3:
raise ValueError("`p`, `v`, `a` must be (3, S).")
S = p.shape[1]
points = self.getSamples(samples, S=S) # (3, M, S)
triangles = np.asarray(self.elements, dtype=np.int32) # (E, 3)
neighbours = self.neighbours.astype(np.int32) # (E, 3)
m = triangles.shape[0]
if np.any((triangles < 0) | (triangles >= points.shape[1])):
raise ValueError("`elements` contain invalid vertex indices.")
if neighbours.shape != (m, 3) or np.any((neighbours < -1) | (neighbours >= m)):
raise ValueError("`neighbours` invalid or mismatched with elements.")
cur = np.asarray(current, dtype=np.int32).copy()
cur[cur < 0] = 0
hit_elem = np.full(S, -1, dtype=np.int32)
t_hit = np.full(S, np.nan, dtype=float)
cum_time = np.zeros(S, dtype=float)
p_cur = np.array(p)
v_cur = np.array(v)
alive = np.ones(S, dtype=bool)
for _ in range(max_steps):
if not np.any(alive):
break
ids = np.flatnonzero(alive)
tri = triangles[cur[ids]] # (K, 3)
tri_points = getTriPoints(points, tri, ids) # (3, 3, K)
# 1) time to current planes
time = timeParabolaPlane(
p_cur[:, ids], v_cur[:, ids], a[:, ids], tri_points,
tol=tol, t_min=t_min, t_max=t_max
) # (K,)
ok_time = np.isfinite(time)
if not np.any(ok_time):
alive[ids] = False
continue
good = ids[ok_time]
time_good = time[ok_time]
# 2) hit points
p_good = p_cur[:, good] + v_cur[:, good] * time_good + 0.5 * a[:, good] * (time_good * time_good)
tri_points_good = tri_points[:, :, ok_time] # (3, 3, |good|)
# 3) inside / step decision
edge_idx = isInsideTriangle(p_good, tri_points_good, tol=tol) # -1 or 0/1/2
inside = (edge_idx == -1)
if np.any(inside):
acc = good[inside]
cum_time[acc] += time_good[inside]
hit_elem[acc] = cur[acc]
t_hit[acc] = cum_time[acc]
alive[acc] = False
rem_mask = ~inside
if np.any(rem_mask):
rem = good[rem_mask]
eidx = edge_idx[rem_mask]
nxt = neighbours[cur[rem], eidx]
cur[rem] = nxt
# leave mesh → stop
dead = nxt < 0
if np.any(dead):
alive[rem[dead]] = False
# advance to edge midpoint (stable local step)
mid = 0.5 * (
tri_points[:, eidx, rem] + tri_points[:, (eidx + 1) % 3, rem]
)
dt = timeClosest(p_cur[:, rem], v_cur[:, rem], a[:, rem], mid)
ok_dt = np.isfinite(dt)
if np.any(ok_dt):
good2 = rem[ok_dt]
dt2 = dt[ok_dt]
p_cur[:, good2] += v_cur[:, good2] * dt2 + 0.5 * a[:, good2] * (dt2 * dt2)
v_cur[:, good2] += a[:, good2] * dt2
cum_time[good2] += dt2
return hit_elem, t_hit