raystrack 1.0.1__py3-none-any.whl

raystrack/utils/prepared.py

@@ -0,0 +1,442 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from .bvh import build_bvh
+from .halton import cached_halton, cached_halton_dims
+from .helpers import grid_from_density
+
+
+@dataclass(frozen=True)
+class PreparedScene:
+    v0: np.ndarray
+    e1: np.ndarray
+    e2: np.ndarray
+    normals: np.ndarray
+    sid: np.ndarray
+    bb_min: Optional[np.ndarray]
+    bb_max: Optional[np.ndarray]
+    left: Optional[np.ndarray]
+    right: Optional[np.ndarray]
+    start: Optional[np.ndarray]
+    count: Optional[np.ndarray]
+    use_bvh: bool
+
+
+@dataclass(frozen=True)
+class PreparedEmitter:
+    tri_a: np.ndarray
+    tri_e1: np.ndarray
+    tri_e2: np.ndarray
+    tri_u: np.ndarray
+    tri_v: np.ndarray
+    tri_n: np.ndarray
+    tri_origin_eps: np.ndarray
+    plane_origin: np.ndarray
+    plane_normal: np.ndarray
+    plane_tol: float
+    plane_is_planar: bool
+    cdf: np.ndarray
+    total_area: float
+    g: int
+    u_grid: np.ndarray
+    v_grid: np.ndarray
+    halton_tri: np.ndarray
+    halton_u: np.ndarray
+    halton_v: np.ndarray
+    halton_r1: np.ndarray
+    halton_r2: np.ndarray
+
+    @property
+    def n_cells(self) -> int:
+        return int(self.u_grid.shape[0])
+
+
+@dataclass(frozen=True)
+class PreparedDeviceScene:
+    v0: Any
+    e1: Any
+    e2: Any
+    normals: Any
+    sid: Any
+    bb_min: Optional[Any]
+    bb_max: Optional[Any]
+    left: Optional[Any]
+    right: Optional[Any]
+    start: Optional[Any]
+    count: Optional[Any]
+    use_bvh: bool
+
+
+@dataclass(frozen=True)
+class PreparedDeviceEmitter:
+    u_grid: Any
+    v_grid: Any
+    halton_tri: Any
+    halton_u: Any
+    halton_v: Any
+    halton_r1: Any
+    halton_r2: Any
+    cdf: Any
+    tri_a: Any
+    tri_e1: Any
+    tri_e2: Any
+    tri_u: Any
+    tri_v: Any
+    tri_n: Any
+    tri_origin_eps: Any
+
+
+def _safe_normalize(v: np.ndarray) -> np.ndarray:
+    n = np.linalg.norm(v, axis=1, keepdims=True)
+    n = np.maximum(n, 1e-12)
+    return v / n
+
+
+def _triangle_frames(tri_n: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    tri_u = np.empty_like(tri_n, dtype=np.float32)
+    tri_v = np.empty_like(tri_n, dtype=np.float32)
+
+    axis_x = np.asarray([1.0, 0.0, 0.0], dtype=np.float32)
+    axis_y = np.asarray([0.0, 1.0, 0.0], dtype=np.float32)
+
+    for i in range(tri_n.shape[0]):
+        n = tri_n[i]
+        ref = axis_x if abs(float(n[0])) < 0.9 else axis_y
+        u = np.cross(ref, n).astype(np.float32)
+        u_len = float(np.linalg.norm(u))
+        if u_len <= 1e-12:
+            ref = axis_y if ref is axis_x else axis_x
+            u = np.cross(ref, n).astype(np.float32)
+            u_len = float(np.linalg.norm(u))
+        if u_len <= 1e-12:
+            tri_u[i] = axis_x
+            tri_v[i] = axis_y
+            continue
+        u /= u_len
+        tri_u[i] = u
+        tri_v[i] = np.cross(n, u).astype(np.float32)
+    return tri_u, tri_v
+
+
+def _triangle_origin_eps(tri_e1: np.ndarray, tri_e2: np.ndarray) -> np.ndarray:
+    edge_a = np.linalg.norm(tri_e1, axis=1)
+    edge_b = np.linalg.norm(tri_e2, axis=1)
+    edge_c = np.linalg.norm(tri_e2 - tri_e1, axis=1)
+    scale = np.maximum(edge_a, np.maximum(edge_b, edge_c))
+    return np.maximum(scale * 1.0e-6, 1.0e-8).astype(np.float32, copy=False)
+
+
+def _emitter_plane(
+    tri_a: np.ndarray,
+    tri_e1: np.ndarray,
+    tri_e2: np.ndarray,
+    tri_n: np.ndarray,
+    tri_origin_eps: np.ndarray,
+) -> Tuple[np.ndarray, np.ndarray, float, bool]:
+    plane_origin = np.zeros(3, dtype=np.float32)
+    plane_normal = np.zeros(3, dtype=np.float32)
+    plane_tol = float(max(1.0e-7, np.max(tri_origin_eps) if tri_origin_eps.size else 0.0))
+
+    if tri_a.shape[0] == 0:
+        return plane_origin, plane_normal, plane_tol, False
+
+    plane_origin = np.asarray(tri_a[0], dtype=np.float32)
+    plane_normal = np.asarray(tri_n[0], dtype=np.float32)
+    normal_len = float(np.linalg.norm(plane_normal))
+    if normal_len <= 1.0e-12:
+        return plane_origin, plane_normal, plane_tol, False
+
+    plane_normal = (plane_normal / normal_len).astype(np.float32, copy=False)
+    normal_align = tri_n @ plane_normal
+    if np.any(normal_align < (1.0 - 1.0e-4)):
+        return plane_origin, plane_normal, plane_tol, False
+
+    offsets = (
+        np.abs((tri_a - plane_origin) @ plane_normal),
+        np.abs((tri_a + tri_e1 - plane_origin) @ plane_normal),
+        np.abs((tri_a + tri_e2 - plane_origin) @ plane_normal),
+    )
+    max_dev = max(float(np.max(arr)) if arr.size else 0.0 for arr in offsets)
+    if max_dev > plane_tol:
+        return plane_origin, plane_normal, plane_tol, False
+
+    return plane_origin, plane_normal, plane_tol, True
+
+
+def prepare_scene(
+    meshes: List[Tuple[str, np.ndarray, np.ndarray]],
+    *,
+    use_bvh: bool,
+) -> PreparedScene:
+    v0s = []
+    e1s = []
+    e2s = []
+    normals = []
+    sids = []
+
+    for sid, (_, V, F) in enumerate(meshes):
+        tri_a = np.asarray(V[F[:, 0]], dtype=np.float32)
+        tri_b = np.asarray(V[F[:, 1]], dtype=np.float32)
+        tri_c = np.asarray(V[F[:, 2]], dtype=np.float32)
+
+        tri_e1 = (tri_b - tri_a).astype(np.float32, copy=False)
+        tri_e2 = (tri_c - tri_a).astype(np.float32, copy=False)
+        tri_n = np.cross(tri_e1, tri_e2).astype(np.float32, copy=False)
+        tri_n = _safe_normalize(tri_n).astype(np.float32, copy=False)
+
+        v0s.append(tri_a)
+        e1s.append(tri_e1)
+        e2s.append(tri_e2)
+        normals.append(tri_n)
+        sids.append(np.full(F.shape[0], sid, dtype=np.int32))
+
+    if not v0s:
+        empty3 = np.empty((0, 3), dtype=np.float32)
+        empty1 = np.empty((0,), dtype=np.int32)
+        return PreparedScene(
+            empty3,
+            empty3,
+            empty3,
+            empty3,
+            empty1,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            False,
+        )
+
+    v0 = np.concatenate(v0s, axis=0)
+    e1 = np.concatenate(e1s, axis=0)
+    e2 = np.concatenate(e2s, axis=0)
+    tri_n = np.concatenate(normals, axis=0)
+    sid = np.concatenate(sids, axis=0)
+
+    bb_min = bb_max = left = right = start = count = None
+    if use_bvh and v0.shape[0] > 0:
+        bb_min, bb_max, left, right, start, count, perm = build_bvh(v0, e1, e2)
+        v0 = v0[perm]
+        e1 = e1[perm]
+        e2 = e2[perm]
+        tri_n = tri_n[perm]
+        sid = sid[perm]
+
+    return PreparedScene(
+        v0=v0,
+        e1=e1,
+        e2=e2,
+        normals=tri_n,
+        sid=sid,
+        bb_min=bb_min,
+        bb_max=bb_max,
+        left=left,
+        right=right,
+        start=start,
+        count=count,
+        use_bvh=bool(use_bvh and v0.shape[0] > 0),
+    )
+
+
+def prepare_emitters(
+    meshes: List[Tuple[str, np.ndarray, np.ndarray]],
+    *,
+    samples: int,
+    rays: int,
+    flip_faces: bool,
+) -> List[PreparedEmitter]:
+    emitters: List[PreparedEmitter] = []
+    for _, V, F in meshes:
+        F_emit = F[:, [0, 2, 1]] if flip_faces else F
+        tri_a = np.asarray(V[F_emit[:, 0]], dtype=np.float32)
+        tri_b = np.asarray(V[F_emit[:, 1]], dtype=np.float32)
+        tri_c = np.asarray(V[F_emit[:, 2]], dtype=np.float32)
+
+        tri_e1 = (tri_b - tri_a).astype(np.float32, copy=False)
+        tri_e2 = (tri_c - tri_a).astype(np.float32, copy=False)
+
+        tri_n_raw = np.cross(tri_e1, tri_e2).astype(np.float32, copy=False)
+        twice_area = np.linalg.norm(tri_n_raw, axis=1)
+        tri_n = _safe_normalize(tri_n_raw).astype(np.float32, copy=False)
+        tri_u, tri_v = _triangle_frames(tri_n)
+        tri_origin_eps = _triangle_origin_eps(tri_e1, tri_e2)
+        plane_origin, plane_normal, plane_tol, plane_is_planar = _emitter_plane(
+            tri_a,
+            tri_e1,
+            tri_e2,
+            tri_n,
+            tri_origin_eps,
+        )
+
+        areas = 0.5 * twice_area
+        total_area = float(areas.sum())
+        if total_area <= 0.0:
+            cdf = np.ones(F_emit.shape[0], dtype=np.float32)
+            g = 4
+            u_grid = np.zeros(g * g, dtype=np.float32)
+            v_grid = np.zeros_like(u_grid)
+            halton_tri = np.zeros(g * g * rays, dtype=np.float32)
+            halton_u = np.zeros_like(halton_tri)
+            halton_v = np.zeros_like(halton_tri)
+            halton_r1 = np.zeros_like(halton_tri)
+            halton_r2 = np.zeros_like(halton_tri)
+        else:
+            cdf = np.cumsum(areas, dtype=np.float64)
+            cdf = (cdf / cdf[-1]).astype(np.float32)
+            g = grid_from_density(total_area, samples)
+            u_grid, v_grid = cached_halton(g)
+            n_rays_once = g * g * rays
+            halton_tri, halton_u, halton_v, halton_r1, halton_r2 = cached_halton_dims(n_rays_once)
+
+        emitters.append(
+            PreparedEmitter(
+                tri_a=tri_a,
+                tri_e1=tri_e1,
+                tri_e2=tri_e2,
+                tri_u=tri_u.astype(np.float32, copy=False),
+                tri_v=tri_v.astype(np.float32, copy=False),
+                tri_n=tri_n,
+                tri_origin_eps=tri_origin_eps,
+                plane_origin=plane_origin,
+                plane_normal=plane_normal,
+                plane_tol=plane_tol,
+                plane_is_planar=plane_is_planar,
+                cdf=cdf,
+                total_area=total_area,
+                g=g,
+                u_grid=u_grid,
+                v_grid=v_grid,
+                halton_tri=halton_tri,
+                halton_u=halton_u,
+                halton_v=halton_v,
+                halton_r1=halton_r1,
+                halton_r2=halton_r2,
+            )
+        )
+    return emitters
+
+
+class PreparedSolver:
+    """Cache prepared geometry, ray-generation tables and CUDA uploads.
+
+    Reusing a single instance across repeated solves on the same mesh set
+    avoids rebuilding triangle buffers, BVHs, Halton tables and device copies.
+    """
+
+    def __init__(self, meshes: List[Tuple[str, np.ndarray, np.ndarray]]):
+        self.meshes = list(meshes)
+        self.total_faces = int(sum(F.shape[0] for _, _, F in self.meshes))
+        self._scene_cache: Dict[bool, PreparedScene] = {}
+        self._emitter_cache: Dict[Tuple[int, int, bool], List[PreparedEmitter]] = {}
+        self._device_scene_cache: Dict[Tuple[int, bool], PreparedDeviceScene] = {}
+        self._device_emitter_cache: Dict[Tuple[int, int, int, int, bool], PreparedDeviceEmitter] = {}
+        self._mesh_bounds_cache: Optional[Tuple[np.ndarray, np.ndarray]] = None
+
+    def get_scene(self, *, use_bvh: bool) -> PreparedScene:
+        key = bool(use_bvh)
+        scene = self._scene_cache.get(key)
+        if scene is None:
+            scene = prepare_scene(self.meshes, use_bvh=key)
+            self._scene_cache[key] = scene
+        return scene
+
+    def get_emitters(self, *, samples: int, rays: int, flip_faces: bool) -> List[PreparedEmitter]:
+        key = (int(samples), int(rays), bool(flip_faces))
+        emitters = self._emitter_cache.get(key)
+        if emitters is None:
+            emitters = prepare_emitters(self.meshes, samples=samples, rays=rays, flip_faces=flip_faces)
+            self._emitter_cache[key] = emitters
+        return emitters
+
+    def get_emitter(self, index: int, *, samples: int, rays: int, flip_faces: bool) -> PreparedEmitter:
+        return self.get_emitters(samples=samples, rays=rays, flip_faces=flip_faces)[int(index)]
+
+    def get_mesh_bounds(self) -> Tuple[np.ndarray, np.ndarray]:
+        bounds = self._mesh_bounds_cache
+        if bounds is None:
+            n_mesh = len(self.meshes)
+            centers = np.zeros((n_mesh, 3), dtype=np.float32)
+            extents = np.zeros((n_mesh, 3), dtype=np.float32)
+            for idx, (_, V, _) in enumerate(self.meshes):
+                if V.size == 0:
+                    continue
+                v = np.asarray(V, dtype=np.float32)
+                vmin = np.min(v, axis=0)
+                vmax = np.max(v, axis=0)
+                centers[idx] = 0.5 * (vmin + vmax)
+                extents[idx] = 0.5 * (vmax - vmin)
+            bounds = (centers, extents)
+            self._mesh_bounds_cache = bounds
+        return bounds
+
+    def clear_device_cache(self) -> None:
+        self._device_scene_cache.clear()
+        self._device_emitter_cache.clear()
+
+    def get_device_scene(self, *, use_bvh: bool) -> PreparedDeviceScene:
+        from numba import cuda
+
+        key = (int(cuda.get_current_device().id), bool(use_bvh))
+        scene = self._device_scene_cache.get(key)
+        if scene is None:
+            host_scene = self.get_scene(use_bvh=use_bvh)
+            scene = PreparedDeviceScene(
+                v0=cuda.to_device(host_scene.v0),
+                e1=cuda.to_device(host_scene.e1),
+                e2=cuda.to_device(host_scene.e2),
+                normals=cuda.to_device(host_scene.normals),
+                sid=cuda.to_device(host_scene.sid),
+                bb_min=None if host_scene.bb_min is None else cuda.to_device(host_scene.bb_min),
+                bb_max=None if host_scene.bb_max is None else cuda.to_device(host_scene.bb_max),
+                left=None if host_scene.left is None else cuda.to_device(host_scene.left),
+                right=None if host_scene.right is None else cuda.to_device(host_scene.right),
+                start=None if host_scene.start is None else cuda.to_device(host_scene.start),
+                count=None if host_scene.count is None else cuda.to_device(host_scene.count),
+                use_bvh=host_scene.use_bvh,
+            )
+            self._device_scene_cache[key] = scene
+        return scene
+
+    def get_device_emitter(self, index: int, *, samples: int, rays: int, flip_faces: bool) -> PreparedDeviceEmitter:
+        from numba import cuda
+
+        idx = int(index)
+        key = (int(cuda.get_current_device().id), idx, int(samples), int(rays), bool(flip_faces))
+        emitter = self._device_emitter_cache.get(key)
+        if emitter is None:
+            host_emitter = self.get_emitter(idx, samples=samples, rays=rays, flip_faces=flip_faces)
+            emitter = PreparedDeviceEmitter(
+                u_grid=cuda.to_device(host_emitter.u_grid),
+                v_grid=cuda.to_device(host_emitter.v_grid),
+                halton_tri=cuda.to_device(host_emitter.halton_tri),
+                halton_u=cuda.to_device(host_emitter.halton_u),
+                halton_v=cuda.to_device(host_emitter.halton_v),
+                halton_r1=cuda.to_device(host_emitter.halton_r1),
+                halton_r2=cuda.to_device(host_emitter.halton_r2),
+                cdf=cuda.to_device(host_emitter.cdf),
+                tri_a=cuda.to_device(host_emitter.tri_a),
+                tri_e1=cuda.to_device(host_emitter.tri_e1),
+                tri_e2=cuda.to_device(host_emitter.tri_e2),
+                tri_u=cuda.to_device(host_emitter.tri_u),
+                tri_v=cuda.to_device(host_emitter.tri_v),
+                tri_n=cuda.to_device(host_emitter.tri_n),
+                tri_origin_eps=cuda.to_device(host_emitter.tri_origin_eps),
+            )
+            self._device_emitter_cache[key] = emitter
+        return emitter
+
+
+__all__ = [
+    "PreparedScene",
+    "PreparedEmitter",
+    "PreparedDeviceScene",
+    "PreparedDeviceEmitter",
+    "PreparedSolver",
+    "prepare_scene",
+    "prepare_emitters",
+]

raystrack/utils/ray_builder.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import math
+
+import numba as nb
+
+
+@nb.njit(inline="always", cache=True)
+def _binary_search_cdf(cdf, x):
+    lo = 0
+    hi = cdf.shape[0] - 1
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        if cdf[mid] < x:
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    if lo < 0:
+        return 0
+    if lo >= cdf.shape[0]:
+        return cdf.shape[0] - 1
+    return lo
+
+
+@nb.njit(parallel=True, cache=True, fastmath=True)
+def build_rays(
+    u_grid,
+    v_grid,
+    halton_tri,
+    halton_u,
+    halton_v,
+    halton_r1,
+    halton_r2,
+    cdf,
+    tri_a,
+    tri_e1,
+    tri_e2,
+    tri_u,
+    tri_v,
+    tri_n,
+    tri_origin_eps,
+    rays_per_cell,
+    orig,
+    dire,
+    cp_grid,
+    cp_dims,
+):
+    """Create ray origins and directions from precomputed emitter data."""
+    n_rays = orig.shape[0]
+    two_pi = 6.283185307179586
+
+    for idx in nb.prange(n_rays):
+        cell = idx // rays_per_cell
+        ug = (u_grid[cell] + cp_grid[0]) % 1.0
+        vg = (v_grid[cell] + cp_grid[1]) % 1.0
+
+        q_tri = (halton_tri[idx] + cp_dims[0]) % 1.0
+        tri = _binary_search_cdf(cdf, q_tri)
+
+        ur = (halton_u[idx] + cp_dims[1] + ug) % 1.0
+        vr = (halton_v[idx] + cp_dims[2] + vg) % 1.0
+
+        s = math.sqrt(ur)
+        mix_b = s * vr
+        mix_c = s * (1.0 - vr)
+
+        ax = tri_a[tri, 0]
+        ay = tri_a[tri, 1]
+        az = tri_a[tri, 2]
+
+        px = ax + mix_b * tri_e1[tri, 0] + mix_c * tri_e2[tri, 0]
+        py = ay + mix_b * tri_e1[tri, 1] + mix_c * tri_e2[tri, 1]
+        pz = az + mix_b * tri_e1[tri, 2] + mix_c * tri_e2[tri, 2]
+
+        r1 = (halton_r1[idx] + cp_dims[3]) % 1.0
+        r2 = (halton_r2[idx] + cp_dims[4]) % 1.0
+
+        sin_t = math.sqrt(1.0 - r1)
+        phi = two_pi * r2
+        x = sin_t * math.cos(phi)
+        y = sin_t * math.sin(phi)
+        z = math.sqrt(r1)
+
+        dx = x * tri_u[tri, 0] + y * tri_v[tri, 0] + z * tri_n[tri, 0]
+        dy = x * tri_u[tri, 1] + y * tri_v[tri, 1] + z * tri_n[tri, 1]
+        dz = x * tri_u[tri, 2] + y * tri_v[tri, 2] + z * tri_n[tri, 2]
+        eps = tri_origin_eps[tri]
+
+        orig[idx, 0] = px + eps * tri_n[tri, 0]
+        orig[idx, 1] = py + eps * tri_n[tri, 1]
+        orig[idx, 2] = pz + eps * tri_n[tri, 2]
+        dire[idx, 0] = dx
+        dire[idx, 1] = dy
+        dire[idx, 2] = dz
+
+
+__all__ = ["build_rays"]

raystrack-1.0.1.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: raystrack
+Version: 1.0.1
+Summary: Lightweight Monte-Carlo view-factor solver with CPU, CUDA and BVH paths
+Author-email: Philip Balizki <philip@metis.earth>
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/philip-ba/raystrack
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0,>=1.24
+Requires-Dist: numba<0.60,>=0.59
+Dynamic: license-file
+
+# Raystrack
+
+<p align="left">
+  <img src="raystrack_icon.svg" alt="Raystrack icon" width="160">
+</p>
+
+Lightweight Monte-Carlo view-factor solver for polygonal meshes.
+
+Raystrack computes radiative view factors F(i->j) between triangulated surfaces
+using quasi-Monte-Carlo ray tracing. It runs on CPU, can leverage Numba/CUDA on
+NVIDIA GPUs when available, and optionally accelerates ray intersection with a
+BVH. The repository also ships a pure-Python API you can use outside Rhino.
+
+## Features
+- Efficient Monte-Carlo view factors: front/back hits, optional reciprocity
+- CPU and optional CUDA GPU backends (Numba)
+- Optional BVH acceleration structures
+- Python API plus Grasshopper components (Rhino installer coming soon)
+
+## Installation
+
+### Python package
+Use Raystrack as a normal Python package outside Rhino or Grasshopper.
+
+From a local clone of this repository:
+```
+pip install .
+```
+
+Or from an absolute path:
+```
+pip install /path/to/raystrack
+```
+
+Requirements: Python 3.9+, `numpy`, `numba`. CUDA acceleration is enabled
+automatically when `numba.cuda` detects a compatible GPU.
+
+### Rhino / Grasshopper status
+The Rhino 8 Grasshopper installers are not yet published. Follow this README or the issue tracker for updates when a
+tested Rhino workflow becomes available.
+
+## Examples
+
+All examples live in `examples/`. Start by running `ex00_street_canyon_geometry`
+to generate `street_canyon.json`; subsequent scripts expect that file. Each
+Python example now documents its own inputs and parameters inline, so open the
+scripts directly for usage guidance and tunable options.
+
+## Quick start (Python)
+```python
+import numpy as np
+from raystrack import view_factor_matrix, MatrixParams
+
+# Each mesh is a tuple: (name: str, V: (N,3) float32, F: (M,3) int32)
+V_a = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]], dtype=np.float32)
+F_a = np.array([[0, 1, 2], [0, 2, 3]], dtype=np.int32)  # two triangles
+
+V_b = np.array([[0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]], dtype=np.float32)
+F_b = F_a.copy()
+
+meshes = [
+    ("A", V_a, F_a),
+    ("B", V_b, F_b),
+]
+
+params = MatrixParams(
+    samples=256,   # sampling density per unit area (QMC grid)
+    rays=256,      # rays per cell
+    bvh="builtin", # optional BVH acceleration (auto|off|builtin)
+    reciprocity=True,
+)
+
+res = view_factor_matrix(meshes, params=params)
+
+print(res["A"])  # e.g. {"B_front": 0.5, "B_back": 0.0, ...}
+```
+
+To persist a matrix without directional suffixes in the saved JSON:
+```python
+from raystrack import save_vf_matrix_json
+
+save_vf_matrix_json(res, "vf_matrix.json", strip_dir=True)
+```
+This collapses receiver keys like `"B_front"` and `"B_back"` into `"B"` and
+sums both values per sender row.
+
+## Parameter presets
+Raystrack uses two parameter containers to keep configuration consistent:
+- `MatrixParams`: controls the scene-to-scene view-factor solve (sampling, BVH,
+  device selection, convergence tolerances, and reciprocity enforcement).
+- `SkyParams`: controls the sky view-factor solve (sampling, device selection,
+  and convergence tolerances, plus `discrete=True` for 145 sky patches or
+  `False` for a single merged `"Sky"` output).
+
+Typical usage:
+```python
+from raystrack import MatrixParams, SkyParams, view_factor_matrix, view_factor_to_tregenza_sky
+
+matrix_params = MatrixParams(samples=32, rays=256, reciprocity=True, flip_faces=False)
+sky_params = SkyParams(samples=32, rays=256)
+
+vf_scene = view_factor_matrix(meshes, params=matrix_params)
+vf_sky = view_factor_to_tregenza_sky(meshes, params=sky_params)
+```
+
+## License
+GPL-3.0-only - see `LICENSE`.

raystrack-1.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+raystrack/__init__.py,sha256=QVC1j713ZEl4BcWD-CDvQmHmXKbj2_fUAGsIhW_kt1M,677
+raystrack/api.py,sha256=yvtM7LoKZhihAZrziwMWgSB5NHdLUXiZ-Kx099gyKPY,7742
+raystrack/io.py,sha256=CsU6pSplFqYUBwPHOXuU48IKrTgfFoyc0j-N5BMUic8,8154
+raystrack/main.py,sha256=U3LgHHiwz5dHsZfssE50vGQLDQPu_ZArpt0nsQ9KwUA,91750
+raystrack/params.py,sha256=bIwRfzb0sdTDEwvldDIRg8xz529zA2l2cKDvJdS1-6Y,4313
+raystrack/utils/__init__.py,sha256=hJ0nNPOGhBbYQOxdiOLca3kjc6XK-897cPqmnGpjHiM,702
+raystrack/utils/bvh.py,sha256=H-nGkBMjvFxuhWHoksz0cmiRS5mxnEU36szMTPmLcTQ,2283
+raystrack/utils/cpu_trace.py,sha256=-Jztd6moL0-3QseJ1XBNbwPZrrbU7nxiYnwakr4LJfE,22785
+raystrack/utils/cuda_trace.py,sha256=lIgPG9h-HocPWZlJ0UFyAOCEbXznRNqvDTFPEo4SLoo,34636
+raystrack/utils/geometry.py,sha256=D3ABPcrYDJZXxAGiw3MuLPTPaKRPKr-w52ygxcu1YzQ,2151
+raystrack/utils/halton.py,sha256=2_ShczxX-WTpZpOLLiJPAdlNuu3rNKSo7Zw7tRDieCQ,1467
+raystrack/utils/helpers.py,sha256=Hu4f-2QRU_8lWa74DUXA2u9HPgCbr3m2cK58KSER_N8,8995
+raystrack/utils/prepared.py,sha256=FvOSwN_3zCktBEJdKl223qe7cZ_0nCb7Gpu3mpzVDiE,15219
+raystrack/utils/ray_builder.py,sha256=IV-81KdGxuYfqZcRHhwtoMYDLvH9zFxYBcgAT4Y76Bw,2372
+raystrack-1.0.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+raystrack-1.0.1.dist-info/METADATA,sha256=vpyrXC_CJWWzIsUVLE5TzjNGuhKmujNjmEupHpRkNgw,4226
+raystrack-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+raystrack-1.0.1.dist-info/top_level.txt,sha256=tLhnPDw74DVcYVMnJeqw8bPMFLURvyR756B05cQrJKE,10
+raystrack-1.0.1.dist-info/RECORD,,

raystrack-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+