raystrack 1.0.1__py3-none-any.whl

raystrack/utils/geometry.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+from typing import Iterable, List, Tuple
+import numpy as np
+
+
+
+def flatten_receivers(meshes, idx_emit, skip: Iterable[int] = ()):  # type: ignore[assignment]
+    """Return flattened receiver triangle arrays.
+
+    Parameters
+    ----------
+    meshes : list
+        List of ``(name, V, F)`` mesh tuples.
+    idx_emit : int
+        Index of the emitting surface in ``meshes`` (kept for callers that
+        want to decide whether to exclude it or not).
+    skip : Iterable[int], optional
+        Surface indices to exclude from the receiver list. Note: the emitter
+        is NOT excluded automatically anymore; callers must pass it here when
+        they want to exclude the whole emitting mesh.
+    """
+    v0s, e1s, e2s, sids, norms = [], [], [], [], []
+    skip_set = set(skip)
+    for sid, (_, V, F) in enumerate(meshes):
+        if sid in skip_set:
+            continue
+        v0 = V[F[:, 0]].astype(np.float32)
+        v1 = V[F[:, 1]].astype(np.float32)
+        v2 = V[F[:, 2]].astype(np.float32)
+
+        v0s.append(v0)
+        e1s.append(v1 - v0)
+        e2s.append(v2 - v0)
+        sids.append(np.full(len(F), sid, np.int32))
+
+        n = np.cross(v1 - v0, v2 - v0)
+        n /= np.linalg.norm(n, axis=1)[:, None]
+        norms.append(n.astype(np.float32))
+
+    if not v0s:
+        return (
+            np.empty((0, 3), np.float32),
+            np.empty((0, 3), np.float32),
+            np.empty((0, 3), np.float32),
+            np.empty((0,), np.int32),
+            np.empty((0, 3), np.float32),
+        )
+
+    v0 = np.concatenate(v0s)
+    e1 = np.concatenate(e1s)
+    e2 = np.concatenate(e2s)
+    sid = np.concatenate(sids)
+    norm = np.concatenate(norms)
+    return v0, e1, e2, sid, norm
+
+
+def flip_meshes(meshes: List[Tuple[str, np.ndarray, np.ndarray]]
+               ) -> List[Tuple[str, np.ndarray, np.ndarray]]:
+    """Return a deep-copied list whose every triangle has reversed order."""
+    flipped = []
+    for name, V, F in meshes:
+        F_flipped = F[:, [0, 2, 1]].copy()
+        flipped.append((name, V.copy(), F_flipped))
+    return flipped
+
+__all__ = ["flatten_receivers", "flip_meshes"]

raystrack/utils/halton.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+import numba as nb
+
+
+@nb.njit(inline="always", cache=True)
+def _halton(i: int, base: int) -> float:
+    """Return the i-th value of a 1-D Halton sequence in the given base."""
+    f = 1.0
+    r = 0.0
+    while i:
+        f /= base
+        r += f * (i % base)
+        i //= base
+    return r
+
+
+@nb.njit(cache=True)
+def _build_halton_grid(samples: int):
+    g = samples
+    cells = g * g
+    u = np.empty(cells, np.float32)
+    v = np.empty(cells, np.float32)
+    for c in range(cells):
+        i, j = divmod(c, g)
+        u[c] = (_halton(c + 1, 2) + i) / g
+        v[c] = (_halton(c + 1, 3) + j) / g
+    return u, v
+
+
+@nb.njit(cache=True)
+def _build_halton_dim(length: int, base: int):
+    out = np.empty(length, np.float32)
+    for i in range(length):
+        out[i] = _halton(i + 1, base)
+    return out
+
+
+@lru_cache(maxsize=128)
+def cached_halton(samples: int):
+    """Return a cached 2-D Halton jitter grid of size ``samples * samples``."""
+    return _build_halton_grid(int(samples))
+
+
+@lru_cache(maxsize=128)
+def cached_halton_dims(length: int):
+    """Return cached low-discrepancy dimensions for ray generation."""
+    n = int(length)
+    return (
+        _build_halton_dim(n, 5),
+        _build_halton_dim(n, 2),
+        _build_halton_dim(n, 3),
+        _build_halton_dim(n, 7),
+        _build_halton_dim(n, 11),
+    )
+
+
+__all__ = ["cached_halton", "cached_halton_dims"]

raystrack/utils/helpers.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+from typing import Dict, Iterable, List, Tuple
+import os
+import sys
+import numpy as np
+
+
+def grid_from_density(area: float, density: float) -> int:
+    """Return Halton grid size for a given surface area and sample density."""
+    g = int(np.ceil(np.sqrt(max(area, 0.0) * density)))
+    return max(g, 4)
+
+
+def enforce_reciprocity_and_rowsum(
+    result: Dict[str, Dict[str, float]],
+    meshes: List[Tuple[str, np.ndarray, np.ndarray]],
+    areas: List[float] | None,
+    row_targets: Iterable[float] | None = None,
+    tol: float = 1e-10,
+    max_iter: int = 500,
+) -> None:
+    """In-place adjust result so that rows sum to targets and reciprocity holds.
+
+    Operates on totals per pair (front+back) using symmetric diagonal scaling
+    of G = diag(A) F after symmetrization, then maps back to front/back totals
+    proportionally to the original split.
+
+    Parameters
+    ----------
+    row_targets : iterable of float, optional
+        Desired total view factor per emitter (same order as ``meshes``). When
+        omitted, rows are normalised to sum to one. When provided, the helper
+        enforces the specified totals while still honouring reciprocity.
+    """
+    n = len(meshes)
+    names = [m[0] for m in meshes]
+    name_to_idx = {name: i for i, name in enumerate(names)}
+
+    if areas is None:
+        areas = []
+        for _, V_a, F_a in meshes:
+            A_a = 0.5 * np.linalg.norm(
+                np.cross(
+                    V_a[F_a[:, 1]] - V_a[F_a[:, 0]],
+                    V_a[F_a[:, 2]] - V_a[F_a[:, 0]],
+                ),
+                axis=1,
+            )
+            areas.append(float(A_a.sum()))
+    A = np.asarray(areas, dtype=np.float64)
+    if row_targets is None:
+        target = A
+    else:
+        target = np.asarray(list(row_targets), dtype=np.float64)
+        if target.shape != A.shape:
+            raise ValueError("row_targets must match number of meshes")
+        target = np.clip(target, 0.0, None)
+        target = A * target
+
+    F = np.zeros((n, n), dtype=np.float64)
+
+    def base_of(key: str) -> str:
+        if key.endswith("_front"):
+            return key[:-6]
+        if key.endswith("_back"):
+            return key[:-5]
+        return key
+
+    for si, sname in enumerate(names):
+        row = result.get(sname, {})
+        if not isinstance(row, dict):
+            continue
+        accum: Dict[str, float] = {}
+        for rkey, val in row.items():
+            b = base_of(rkey)
+            accum[b] = accum.get(b, 0.0) + float(val)
+        for bname, v in accum.items():
+            j = name_to_idx.get(bname, None)
+            if j is None:
+                continue
+            F[si, j] = v
+
+    G = (A[:, None] * F)
+    G = 0.5 * (G + G.T)
+
+    d = np.ones(n, dtype=np.float64)
+    for _ in range(max_iter):
+        row = d * (G @ d)
+        row = np.maximum(row, 1e-30)
+        upd = target / row if row_targets is not None else A / row
+        upd = np.maximum(upd, 0.0)
+        d_new = d * np.sqrt(upd)
+        if np.max(np.abs(d_new - d)) < tol:
+            d = d_new
+            break
+        d = d_new
+
+    Gp = (d[:, None] * G) * d[None, :]
+    with np.errstate(divide="ignore", invalid="ignore"):
+        Fp = np.divide(Gp, A[:, None], out=np.zeros_like(Gp), where=A[:, None] > 0.0)
+
+    for si, sname in enumerate(names):
+        row = result.get(sname, {})
+        fb: Dict[str, Tuple[float, float]] = {}
+        for rkey, val in row.items():
+            if rkey.endswith("_front"):
+                base = rkey[:-6]
+                cur_f, cur_b = fb.get(base, (0.0, 0.0))
+                fb[base] = (cur_f + float(val), cur_b)
+            elif rkey.endswith("_back"):
+                base = rkey[:-5]
+                cur_f, cur_b = fb.get(base, (0.0, 0.0))
+                fb[base] = (cur_f, cur_b + float(val))
+            else:
+                base = rkey
+                cur_f, cur_b = fb.get(base, (0.0, 0.0))
+                fb[base] = (cur_f, cur_b + float(val))
+
+        for bj, rname in enumerate(names):
+            t_new = float(max(Fp[si, bj], 0.0))
+            cur_f, cur_b = fb.get(rname, (0.0, 0.0))
+            t_old = cur_f + cur_b
+            if t_old > 0.0:
+                s = t_new / t_old
+                new_f = cur_f * s
+                new_b = cur_b * s
+            else:
+                new_f = 0.0
+                new_b = t_new
+
+            if new_f > 0.0:
+                row[f"{rname}_front"] = new_f
+            elif f"{rname}_front" in row:
+                del row[f"{rname}_front"]
+            if new_b > 0.0:
+                row[f"{rname}_back"] = new_b
+            elif f"{rname}_back" in row:
+                del row[f"{rname}_back"]
+
+        result[sname] = row
+
+
+def enforce_reciprocity_only(
+    result: Dict[str, Dict[str, float]],
+    meshes: List[Tuple[str, np.ndarray, np.ndarray]],
+    tol: float = 1e-12,
+) -> None:
+    """In-place adjust result so that reciprocity holds without row scaling."""
+    if tol <= 0.0:
+        tol = 1e-12
+
+    n = len(meshes)
+    names = [m[0] for m in meshes]
+    name_to_idx = {name: i for i, name in enumerate(names)}
+
+    areas: List[float] = []
+    for _, V_a, F_a in meshes:
+        A_a = 0.5 * np.linalg.norm(
+            np.cross(
+                V_a[F_a[:, 1]] - V_a[F_a[:, 0]],
+                V_a[F_a[:, 2]] - V_a[F_a[:, 0]],
+            ),
+            axis=1,
+        )
+        areas.append(float(A_a.sum()))
+    A = np.asarray(areas, dtype=np.float64)
+
+    def base_of(key: str) -> str:
+        if key.endswith("_front"):
+            return key[:-6]
+        if key.endswith("_back"):
+            return key[:-5]
+        return key
+
+    F = np.zeros((n, n), dtype=np.float64)
+    for si, sname in enumerate(names):
+        row = result.get(sname, {})
+        if not isinstance(row, dict):
+            continue
+        accum: Dict[str, float] = {}
+        for rkey, val in row.items():
+            b = base_of(rkey)
+            accum[b] = accum.get(b, 0.0) + float(val)
+        for bname, v in accum.items():
+            j = name_to_idx.get(bname, None)
+            if j is None:
+                continue
+            F[si, j] = v
+
+    F_new = F.copy()
+    for i in range(n):
+        Ai = A[i]
+        for j in range(i + 1, n):
+            Aj = A[j]
+            fij = F[i, j]
+            fji = F[j, i]
+            if fij <= tol and fji <= tol:
+                F_new[i, j] = 0.0
+                F_new[j, i] = 0.0
+                continue
+            gij = 0.5 * (Ai * fij + Aj * fji)
+            if Ai > 0.0:
+                F_new[i, j] = max(gij / Ai, 0.0)
+            else:
+                F_new[i, j] = 0.0
+            if Aj > 0.0:
+                F_new[j, i] = max(gij / Aj, 0.0)
+            else:
+                F_new[j, i] = 0.0
+
+    for si, sname in enumerate(names):
+        row = result.get(sname, {})
+        if not isinstance(row, dict):
+            row = {}
+        fb: Dict[str, Tuple[float, float]] = {}
+        for rkey, val in row.items():
+            if rkey.endswith("_front"):
+                base = rkey[:-6]
+                cur_f, cur_b = fb.get(base, (0.0, 0.0))
+                fb[base] = (cur_f + float(val), cur_b)
+            elif rkey.endswith("_back"):
+                base = rkey[:-5]
+                cur_f, cur_b = fb.get(base, (0.0, 0.0))
+                fb[base] = (cur_f, cur_b + float(val))
+            else:
+                base = rkey
+                cur_f, cur_b = fb.get(base, (0.0, 0.0))
+                fb[base] = (cur_f, cur_b + float(val))
+
+        for bj, rname in enumerate(names):
+            if si == bj:
+                continue
+            t_new = float(max(F_new[si, bj], 0.0))
+            cur_f, cur_b = fb.get(rname, (0.0, 0.0))
+            t_old = cur_f + cur_b
+            if t_old > 0.0:
+                s = t_new / t_old
+                new_f = cur_f * s
+                new_b = cur_b * s
+            else:
+                new_f = 0.0
+                new_b = t_new
+
+            front_key = f"{rname}_front"
+            back_key = f"{rname}_back"
+
+            if new_f > tol:
+                row[front_key] = new_f
+            elif front_key in row:
+                del row[front_key]
+
+            if new_b > tol:
+                row[back_key] = new_b
+            elif back_key in row:
+                del row[back_key]
+
+        result[sname] = row
+
+
+def hold_console_open(prompt: str = "Press Enter to close...") -> None:
+    """Keep the console window open when running scripts directly.
+
+    Controlled by the environment variable ``RAYSTRACK_HOLD_CONSOLE``.
+    Set it to ``0`` or ``false`` to disable the prompt.
+    """
+    flag = os.environ.get("RAYSTRACK_HOLD_CONSOLE", "1").lower()
+    if flag in {"0", "false", "no"}:
+        return
+    stdin = getattr(sys, "stdin", None)
+    if stdin is None or not stdin.isatty():
+        return
+    try:
+        input(prompt)
+    except EOFError:
+        pass
+
+
+__all__ = [
+    "grid_from_density",
+    "enforce_reciprocity_and_rowsum",
+    "enforce_reciprocity_only",
+    "hold_console_open",
+]
+