raystrack 1.0.1__py3-none-any.whl

raystrack/__init__.py

@@ -0,0 +1,30 @@
+from .main import (
+    view_factor_matrix,
+    view_factor,
+    view_factor_to_tregenza_sky,
+)
+from .api import view_factor_outside_workflow
+from .params import MatrixParams, SkyParams
+from .utils.prepared import PreparedSolver
+from .io import (
+    save_vf_matrix_json,
+    load_vf_matrix_json,
+    save_meshes_json,
+    load_meshes_json,
+    merge_vf_matrix
+)
+
+__all__ = [
+    "view_factor_matrix",
+    "view_factor",
+    "view_factor_to_tregenza_sky",
+    "view_factor_outside_workflow",
+    "MatrixParams",
+    "SkyParams",
+    "PreparedSolver",
+    "save_vf_matrix_json",
+    "load_vf_matrix_json",
+    "save_meshes_json",
+    "load_meshes_json",
+    "merge_vf_matrix"
+]

raystrack/api.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+from .main import (
+    outside_workflow_shareable,
+    view_factor_matrix,
+    view_factor_matrix_and_sky,
+    view_factor_to_tregenza_sky,
+)
+from .params import MatrixParams, SkyParams
+from .utils.helpers import (
+    enforce_reciprocity_and_rowsum as _enforce_reciprocity_and_rowsum,
+    enforce_reciprocity_only as _enforce_reciprocity_only,
+)
+from .utils.prepared import PreparedSolver
+
+
+def _row_sum(row: Dict[str, float]) -> float:
+    return float(sum(float(v) for v in row.values()))
+
+
+def view_factor_outside_workflow(
+    meshes: List[Tuple[str, np.ndarray, np.ndarray]],
+    *,
+    matrix_params: MatrixParams,
+    sky_params: SkyParams,
+    prepared: PreparedSolver | None = None,
+) -> Tuple[
+    Dict[str, Dict[str, float]],
+    Dict[str, Dict[str, float]],
+    Dict[str, Dict[str, float]],
+]:
+    """Compute scene VF matrix, sky VF and the residual fraction.
+
+    Steps
+    - Compute regular view-factor matrix (scene-to-scene).
+    - Compute Radiance-style sky view factor(s): merged (Sky) or 145 patches.
+    - For each emitter, compute the residual fraction required so that the
+      total view factor sums to one: ``1 - sum(scene VFs) - sky_total``.
+
+    Shared-ray optimization
+    -----------------------
+    When ``matrix_params`` and ``sky_params`` use the same sampling and device
+    configuration, this workflow traces one set of rays per emitter and derives
+    both outputs from that shared sample set. In that mode:
+
+    - scene hits are accumulated into the view-factor matrix
+    - rays that miss all geometry are classified directly into the sky result
+
+    This avoids tracing the same rays twice. When the two parameter sets are
+    not compatible, the workflow falls back to the legacy behaviour of calling
+    :func:`view_factor_matrix` and :func:`view_factor_to_tregenza_sky`
+    separately.
+
+    Prepared-state reuse
+    --------------------
+    Pass a shared :class:`~raystrack.utils.prepared.PreparedSolver` via
+    ``prepared`` when solving the same mesh set repeatedly. The workflow will
+    then reuse prepared triangle buffers, BVHs, ray tables and CUDA uploads
+    across runs.
+
+    Parameters
+    ----------
+    meshes : list of (name, V, F)
+        Scene meshes (float32/float64 vertices, int faces).
+    matrix_params, sky_params : MatrixParams
+        Passed through to the matrix and sky solvers. To enable the shared-ray
+        path, the two parameter sets must agree on the ray-generation settings
+        (`samples`, `rays`, `seed`) and execution settings (`bvh`, `device`,
+        `cuda_async`, `gpu_raygen`). The matrix solve must also use
+        ``flip_faces=False``.
+
+    Returns
+    -------
+    vf_scene : dict
+        Scene view-factor matrix. For compatible parameter sets this comes from
+        the shared-ray solve; otherwise it is returned by
+        :func:`view_factor_matrix`.
+    sky_vf : dict
+        Sky view factor(s): either {'Sky': vf} or {'Sky_Patch_i': vf} per
+        emitter. For compatible parameter sets this is derived from the same
+        rays that produced ``vf_scene``.
+    rest_vf : dict
+        Residual view factor per emitter (``{"Rest": value}``) so that
+        ``scene + sky + rest = 1``.
+    """
+    if not isinstance(matrix_params, MatrixParams):
+        raise TypeError("matrix_params must be a MatrixParams instance")
+    if not isinstance(sky_params, SkyParams):
+        raise TypeError("sky_params must be a SkyParams instance")
+    threshold = 1e-6
+    enforce_scene = bool(matrix_params.enforce_reciprocity_rowsum)
+    reciprocity_flag = bool(matrix_params.reciprocity)
+
+    # Ensure we don't auto-enforce rows at matrix stage
+    matrix_defaults = MatrixParams(**matrix_params.as_dict())
+    matrix_defaults.enforce_reciprocity_rowsum = False
+
+    if outside_workflow_shareable(matrix_defaults, sky_params):
+        vf_scene, sky_vf = view_factor_matrix_and_sky(
+            meshes,
+            matrix_params=matrix_defaults,
+            sky_params=sky_params,
+            prepared=prepared,
+        )
+    else:
+        vf_scene = view_factor_matrix(meshes, params=matrix_defaults, prepared=prepared)
+        sky_vf = view_factor_to_tregenza_sky(meshes, params=sky_params, prepared=prepared)
+
+    # Determine convergence tolerances
+    tol_matrix = float(matrix_params.tol)
+    tol_sky = float(sky_params.tol)
+    threshold = abs(float(threshold)) if threshold is not None else max(tol_matrix, tol_sky)
+
+    mesh_names = [name for name, _, _ in meshes]
+    scene_totals = {name: max(0.0, _row_sum(vf_scene.get(name, {}))) for name in mesh_names}
+
+    if enforce_scene:
+        row_targets = [scene_totals.get(name, 0.0) for name in mesh_names]
+        _enforce_reciprocity_and_rowsum(vf_scene, meshes, None, row_targets=row_targets)
+
+    rest_vf: Dict[str, Dict[str, float]] = {}
+
+    mesh_names = [name for name, _, _ in meshes]
+    sky_totals = {name: 0.0 for name in mesh_names}
+
+    for emitter in mesh_names:
+        row = vf_scene.get(emitter, {})
+        scene_sum = _row_sum(row)
+        sky_row = dict(sky_vf.get(emitter, {}))
+        if sky_params.discrete:
+            sky_total = float(sum(float(v) for v in sky_row.values()))
+        else:
+            sky_total = float(sky_row.get("Sky", 0.0))
+
+        if scene_sum + sky_total > 1.0 + threshold:
+            if sky_total > 0.0:
+                allowed_sky = max(0.0, 1.0 - scene_sum)
+                scale = min(1.0, allowed_sky / sky_total) if sky_total else 0.0
+                if sky_params.discrete:
+                    for key, value in list(sky_row.items()):
+                        sky_row[key] = float(value) * scale
+                    sky_total = float(sum(float(v) for v in sky_row.values()))
+                else:
+                    sky_row["Sky"] = float(sky_row.get("Sky", 0.0)) * scale
+                    sky_total = float(sky_row.get("Sky", 0.0))
+                sky_vf[emitter] = sky_row
+            else:
+                sky_total = 0.0
+
+        sky_totals[emitter] = max(0.0, sky_total)
+
+    if enforce_scene:
+        row_targets = [max(0.0, 1.0 - sky_totals.get(name, 0.0)) for name in mesh_names]
+        _enforce_reciprocity_and_rowsum(vf_scene, meshes, None, row_targets=row_targets)
+    elif reciprocity_flag:
+        _enforce_reciprocity_only(vf_scene, meshes)
+
+    for emitter in mesh_names:
+        row = vf_scene.get(emitter, {})
+        scene_sum = _row_sum(row)
+        sky_row = dict(sky_vf.get(emitter, {}))
+        if sky_params.discrete:
+            sky_total = float(sum(float(v) for v in sky_row.values()))
+        else:
+            sky_total = float(sky_row.get("Sky", 0.0))
+
+        combined = scene_sum + sky_total
+        if combined > 1.0 + threshold and sky_total > 0.0:
+            allowed_sky = max(0.0, 1.0 - scene_sum)
+            if allowed_sky <= 0.0:
+                sky_row = {key: 0.0 for key in sky_row}
+                sky_total = 0.0
+            else:
+                scale = min(1.0, allowed_sky / sky_total)
+                if sky_params.discrete:
+                    for key, value in list(sky_row.items()):
+                        sky_row[key] = float(value) * scale
+                    sky_total = float(sum(float(v) for v in sky_row.values()))
+                else:
+                    sky_row["Sky"] = float(sky_row.get("Sky", 0.0)) * scale
+                    sky_total = float(sky_row.get("Sky", 0.0))
+            sky_vf[emitter] = sky_row
+            combined = scene_sum + sky_total
+
+        residual = 1.0 - combined
+        if abs(residual) <= threshold:
+            residual = 0.0
+
+        rest_vf[emitter] = {"Rest": residual}
+
+    return vf_scene, sky_vf, rest_vf
+
+
+__all__ = ["view_factor_outside_workflow"]
+

raystrack/io.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Tuple, Union
+import numpy as np
+
+
+VFDict = Dict[str, Dict[str, float]]
+VFInput = Union[VFDict, List[VFDict]]
+MeshTuple = Tuple[str, np.ndarray, np.ndarray]
+Meshes = List[MeshTuple]
+
+
+def _strip_direction_suffix(name: str) -> str:
+    if name.endswith("_front"):
+        return name[:-6]
+    if name.endswith("_back"):
+        return name[:-5]
+    return name
+
+
+def merge_vf_matrix(vf_matrix: VFInput) -> VFDict:
+    """
+    Normalize and deep-merge input to a single dict of the form:
+        { sender: { receiver: value } }
+
+    Accepts either:
+      - a single dict
+      - a list of dicts
+
+    When a list is provided, all dicts are merged. 
+    If the same `sender` key appears in multiple dicts, 
+    their nested `receiver` mappings are merged instead of replaced.
+    Later entries overwrite earlier ones only for overlapping receiver keys.
+
+    Parameters
+    ----------
+    vf_matrix : dict or list of dict
+        Input dictionary/dictionaries to normalize and merge.
+
+    Returns
+    -------
+    VFDict
+        A single merged dictionary with combined receiver entries.
+
+    Raises
+    ------
+    TypeError
+        If vf_matrix is neither a dict nor a list of dicts.
+    """
+    if isinstance(vf_matrix, list):
+        flat: VFDict = {}
+        for d in vf_matrix:
+            if not isinstance(d, dict):
+                raise TypeError("All elements of vf_matrix list must be dicts")
+            for sender, receivers in d.items():
+                if sender not in flat:
+                    flat[sender] = {}
+                flat[sender].update(receivers)
+        return flat
+
+    if isinstance(vf_matrix, dict):
+        return vf_matrix
+
+    raise TypeError("vf_matrix must be a dict or list of dicts")
+
+
+def save_vf_matrix_json(vf_matrix: VFInput, save_path: str, *, strip_dir: bool = False) -> str:
+    """Save a view-factor matrix to a JSON file.
+
+    Receivers with value exactly 0.0 are omitted from the saved JSON to reduce
+    file size and noise.
+
+    When ``strip_dir=True``, receiver keys ending in ``_front`` or ``_back``
+    are written without that suffix and values for the same base receiver are
+    summed per sender row before serialization.
+    """
+    flat = merge_vf_matrix(vf_matrix)
+
+    # Basic validation of structure and numeric values
+    for sender, row in flat.items():
+        if not isinstance(sender, str):
+            raise TypeError("Sender keys must be strings")
+        if not isinstance(row, dict):
+            raise TypeError(f"Row for '{sender}' must be a dict mapping receiver->value")
+        for recv, val in row.items():
+            if not isinstance(recv, str):
+                raise TypeError("Receiver keys must be strings")
+            try:
+                float(val)
+            except Exception:
+                raise TypeError(f"Value for '{sender}'->'{recv}' must be numeric")
+
+    path = Path(save_path)
+    if path.suffix.lower() == "":
+        path = path.with_suffix(".json")
+    if path.parent and not path.parent.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Drop zero-valued receivers
+    cleaned: VFDict = {}
+    for sender, row in flat.items():
+        pruned: Dict[str, float] = {}
+        for key, value in row.items():
+            value_f = float(value)
+            if value_f == 0.0:
+                continue
+            out_key = _strip_direction_suffix(key) if strip_dir else key
+            pruned[out_key] = pruned.get(out_key, 0.0) + value_f
+        cleaned[sender] = pruned
+
+    with path.open("w", encoding="utf-8") as fh:
+        json.dump(cleaned, fh, ensure_ascii=False, indent=2, sort_keys=True)
+
+    return str(path.resolve())
+
+
+def load_vf_matrix_json(load_path: str) -> VFDict:
+    """Load a view-factor matrix JSON file and return a dictionary."""
+    path = Path(load_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {load_path}")
+
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+
+    if not isinstance(data, dict):
+        raise TypeError("Loaded JSON must be a dict of dicts")
+
+    # Validate and coerce values to float
+    out: VFDict = {}
+    for sender, row in data.items():
+        if not isinstance(sender, str) or not isinstance(row, dict):
+            raise TypeError("Invalid structure: expected {str: {str: number}}")
+        new_row: Dict[str, float] = {}
+        for recv, val in row.items():
+            if not isinstance(recv, str):
+                raise TypeError("Receiver keys must be strings")
+            try:
+                new_row[recv] = float(val)
+            except Exception:
+                raise TypeError(f"Value for '{sender}'->'{recv}' must be numeric")
+        out[sender] = new_row
+
+    return out
+
+
+# ---------------------------------------------------------------
+# Mesh geometry JSON IO
+# ---------------------------------------------------------------
+
+def save_meshes_json(meshes: Meshes, save_path: str) -> str:
+    """Save meshes to a JSON file.
+
+    The expected input format is a list of tuples:
+        [(name: str, V: float32[N,3], F: int32[M,3]), ...]
+
+    The JSON structure is:
+        { "meshes": [
+            {"name": str,
+             "vertices": [[x,y,z], ...],
+             "faces": [[i,j,k], ...]
+            }, ...
+        ]}
+    """
+    if not isinstance(meshes, list):
+        raise TypeError("meshes must be a list of (name, V, F) tuples")
+
+    payload = {"meshes": []}
+    for item in meshes:
+        if not (isinstance(item, tuple) and len(item) == 3):
+            raise TypeError("Each mesh must be a (name, V, F) tuple")
+        name, V, F = item
+        if not isinstance(name, str) or name.strip() == "":
+            raise TypeError("Mesh name must be a non-empty string")
+        V = np.asarray(V, dtype=np.float32)
+        F = np.asarray(F, dtype=np.int32)
+        if V.ndim != 2 or V.shape[1] != 3:
+            raise ValueError(f"Vertices for '{name}' must have shape (N,3)")
+        if F.ndim != 2 or F.shape[1] != 3:
+            raise ValueError(f"Faces for '{name}' must have shape (M,3) of triangles")
+        payload["meshes"].append(
+            {
+                "name": name,
+                "vertices": V.tolist(),
+                "faces": F.tolist(),
+            }
+        )
+
+    path = Path(save_path)
+    if path.suffix.lower() == "":
+        path = path.with_suffix(".json")
+    if path.parent and not path.parent.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    with path.open("w", encoding="utf-8") as fh:
+        json.dump(payload, fh, ensure_ascii=False, indent=2)
+
+    return str(path.resolve())
+
+
+def load_meshes_json(load_path: str) -> Meshes:
+    """Load meshes from a JSON file saved by save_meshes_json.
+
+    Returns a list of (name, V, F), where V is float32[N,3], F is int32[M,3].
+    """
+    path = Path(load_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {load_path}")
+
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+
+    if not isinstance(data, dict) or "meshes" not in data:
+        raise TypeError("Invalid mesh JSON: expected an object with 'meshes' list")
+    meshes_raw = data["meshes"]
+    if not isinstance(meshes_raw, list):
+        raise TypeError("'meshes' must be a list")
+
+    out: Meshes = []
+    for i, entry in enumerate(meshes_raw):
+        if not isinstance(entry, dict):
+            raise TypeError("Each entry in 'meshes' must be an object")
+        name = entry.get("name")
+        V = entry.get("vertices")
+        F = entry.get("faces")
+        if not isinstance(name, str) or name.strip() == "":
+            raise TypeError(f"Entry {i}: 'name' must be a non-empty string")
+        V = np.asarray(V, dtype=np.float32)
+        F = np.asarray(F, dtype=np.int32)
+        if V.ndim != 2 or V.shape[1] != 3:
+            raise ValueError(f"Entry {i} ('{name}'): vertices must have shape (N,3)")
+        if F.ndim != 2 or F.shape[1] != 3:
+            raise ValueError(f"Entry {i} ('{name}'): faces must have shape (M,3)")
+        out.append((name, V, F))
+
+    return out