lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/intersection/bounded_plane.py

@@ -0,0 +1,205 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+GPU-Accelerated Bounded Plane Intersection
+
+Analytical ray-plane intersection with rectangular bounds checking.
+
+This module contains ONLY pure CUDA kernels - no GPU memory management.
+The propagator layer is responsible for cuda.to_device() and copy_to_host().
+"""
+
+import math
+
+from ..registry import IntersectionKernelID, register_kernel
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = True
+except ImportError:
+
+    class _FakeCuda:
+        """Fake cuda module for when numba is not installed."""
+
+        @staticmethod
+        def jit(*args, **kwargs):
+            """Return a no-op decorator."""
+
+            def decorator(func):
+                return func
+
+            if args and callable(args[0]):
+                return args[0]
+            return decorator
+
+        @staticmethod
+        def is_available():
+            return False
+
+        @staticmethod
+        def grid(n):
+            return 0
+
+        @staticmethod
+        def synchronize():
+            pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+
+# =============================================================================
+# CUDA Kernels
+# =============================================================================
+
+
+@register_kernel(IntersectionKernelID.BOUNDED_PLANE_ANALYTICAL)
+@cuda.jit
+def kernel_bounded_plane_intersect(
+    origins,  # (N, 3) ray origins
+    directions,  # (N, 3) ray directions
+    distances_out,  # (N,) output distances
+    hit_mask_out,  # (N,) output hit mask
+    normals_out,  # (N, 3) output normals at intersection
+    # Plane parameters
+    plane_normal_x,  # Plane normal X component
+    plane_normal_y,  # Plane normal Y component
+    plane_normal_z,  # Plane normal Z component
+    # Rectangle center
+    center_x,
+    center_y,
+    center_z,
+    # Local U axis for bounds checking
+    u_axis_x,
+    u_axis_y,
+    u_axis_z,
+    # Local V axis for bounds checking
+    v_axis_x,
+    v_axis_y,
+    v_axis_z,
+    # Half-dimensions
+    half_width,
+    half_height,
+):
+    """
+    CUDA kernel for ray-bounded-plane intersection.
+
+    Uses analytical solution for ray-plane intersection, then checks
+    if the intersection point lies within the rectangular bounds.
+
+    The plane is defined by its center point and normal.
+    The rectangle bounds are checked by projecting onto local U/V axes.
+    """
+    idx = cuda.grid(1)
+    if idx >= origins.shape[0]:
+        return
+
+    # Load ray data
+    ox = origins[idx, 0]
+    oy = origins[idx, 1]
+    oz = origins[idx, 2]
+    dx = directions[idx, 0]
+    dy = directions[idx, 1]
+    dz = directions[idx, 2]
+
+    # Normalize direction
+    d_len = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if d_len < 1e-10:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+    dx /= d_len
+    dy /= d_len
+    dz /= d_len
+
+    # Compute denominator: n · d
+    denom = plane_normal_x * dx + plane_normal_y * dy + plane_normal_z * dz
+
+    # Check if ray is parallel to plane
+    if abs(denom) < 1e-10:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Compute numerator: (center - origin) · n
+    numer = (
+        plane_normal_x * (center_x - ox)
+        + plane_normal_y * (center_y - oy)
+        + plane_normal_z * (center_z - oz)
+    )
+
+    # Compute intersection distance
+    t = numer / denom
+
+    # Only forward intersections
+    if t < 0:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Compute intersection point
+    px = ox + t * dx
+    py = oy + t * dy
+    pz = oz + t * dz
+
+    # Vector from center to intersection
+    rx = px - center_x
+    ry = py - center_y
+    rz = pz - center_z
+
+    # Project onto local axes
+    u_coord = rx * u_axis_x + ry * u_axis_y + rz * u_axis_z
+    v_coord = rx * v_axis_x + ry * v_axis_y + rz * v_axis_z
+
+    # Check bounds
+    if abs(u_coord) > half_width or abs(v_coord) > half_height:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Valid bounded intersection
+    hit_mask_out[idx] = True
+    distances_out[idx] = t
+
+    # Normal points toward ray origin (flip if ray hits from behind)
+    if denom > 0:
+        normals_out[idx, 0] = -plane_normal_x
+        normals_out[idx, 1] = -plane_normal_y
+        normals_out[idx, 2] = -plane_normal_z
+    else:
+        normals_out[idx, 0] = plane_normal_x
+        normals_out[idx, 1] = plane_normal_y
+        normals_out[idx, 2] = plane_normal_z

lsurf/propagation/kernels/intersection/plane.py

@@ -0,0 +1,166 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+GPU-Accelerated Plane Intersection
+
+Analytical ray-plane intersection using signed distance.
+
+This module contains ONLY pure CUDA kernels - no GPU memory management.
+The propagator layer is responsible for cuda.to_device() and copy_to_host().
+"""
+
+import math
+
+from ..registry import IntersectionKernelID, register_kernel
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = True
+except ImportError:
+
+    class _FakeCuda:
+        """Fake cuda module for when numba is not installed."""
+
+        @staticmethod
+        def jit(*args, **kwargs):
+            """Return a no-op decorator."""
+
+            def decorator(func):
+                return func
+
+            if args and callable(args[0]):
+                return args[0]
+            return decorator
+
+        @staticmethod
+        def is_available():
+            return False
+
+        @staticmethod
+        def grid(n):
+            return 0
+
+        @staticmethod
+        def synchronize():
+            pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+
+# =============================================================================
+# CUDA Kernels
+# =============================================================================
+
+
+@register_kernel(IntersectionKernelID.PLANE_ANALYTICAL)
+@cuda.jit
+def kernel_plane_intersect(
+    origins,  # (N, 3) ray origins
+    directions,  # (N, 3) ray directions
+    distances_out,  # (N,) output distances
+    hit_mask_out,  # (N,) output hit mask
+    normals_out,  # (N, 3) output normals at intersection
+    plane_normal_x,  # Plane normal X component
+    plane_normal_y,  # Plane normal Y component
+    plane_normal_z,  # Plane normal Z component
+    plane_d,  # Plane distance from origin (ax + by + cz + d = 0)
+):
+    """
+    CUDA kernel for ray-plane intersection.
+
+    Uses analytical solution: t = -(n·o + d) / (n·d)
+    where n is plane normal, o is ray origin, d is ray direction.
+
+    The plane is defined as: n·p + d = 0
+    where n is the normal and d is the signed distance from origin.
+    """
+    idx = cuda.grid(1)
+    if idx >= origins.shape[0]:
+        return
+
+    # Load ray data
+    ox = origins[idx, 0]
+    oy = origins[idx, 1]
+    oz = origins[idx, 2]
+    dx = directions[idx, 0]
+    dy = directions[idx, 1]
+    dz = directions[idx, 2]
+
+    # Normalize direction
+    d_len = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if d_len < 1e-10:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+    dx /= d_len
+    dy /= d_len
+    dz /= d_len
+
+    # Compute denominator: n · d
+    denom = plane_normal_x * dx + plane_normal_y * dy + plane_normal_z * dz
+
+    # Check if ray is parallel to plane
+    if abs(denom) < 1e-10:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Compute numerator: -(n · o + d)
+    numer = -(plane_normal_x * ox + plane_normal_y * oy + plane_normal_z * oz + plane_d)
+
+    # Compute intersection distance
+    t = numer / denom
+
+    # Only forward intersections
+    if t < 0:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Store results
+    hit_mask_out[idx] = True
+    distances_out[idx] = t
+
+    # Normal points toward ray origin (flip if ray hits from behind)
+    if denom > 0:
+        normals_out[idx, 0] = -plane_normal_x
+        normals_out[idx, 1] = -plane_normal_y
+        normals_out[idx, 2] = -plane_normal_z
+    else:
+        normals_out[idx, 0] = plane_normal_x
+        normals_out[idx, 1] = plane_normal_y
+        normals_out[idx, 2] = plane_normal_z

lsurf/propagation/kernels/intersection/protocol.py

@@ -0,0 +1,95 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Intersection Kernel Protocol
+
+Defines the interface for surface intersection kernels that find
+ray-surface intersections.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from numba.cuda.devicearray import DeviceNDArray
+
+
+@runtime_checkable
+class IntersectionKernelProtocol(Protocol):
+    """
+    Protocol for surface intersection kernels.
+
+    Intersection kernels find where rays intersect with geometric surfaces.
+    They support different geometry types (planes, spheres, waves) and
+    intersection methods (analytical, ray-marching).
+
+    Common Parameters
+    -----------------
+    origins : DeviceNDArray, shape (N, 3)
+        Ray origin positions in meters
+    directions : DeviceNDArray, shape (N, 3)
+        Ray direction unit vectors
+    distances_out : DeviceNDArray, shape (N,)
+        Output: distance to intersection (inf if no hit)
+    hit_mask_out : DeviceNDArray, shape (N,)
+        Output: boolean mask of rays that hit
+    normals_out : DeviceNDArray, shape (N, 3)
+        Output: surface normals at intersection points
+
+    Geometry-Specific Parameters
+    ----------------------------
+    Additional parameters depend on the geometry type:
+    - Plane: normal vector, point on plane
+    - Sphere: center, radius
+    - Wave: amplitude, wavenumber, frequency, time
+
+    Notes
+    -----
+    Kernels are registered with the central registry using @register_kernel
+    decorator and IntersectionKernelID enum values.
+    """
+
+    def __call__(
+        self,
+        origins: DeviceNDArray,
+        directions: DeviceNDArray,
+        distances_out: DeviceNDArray,
+        hit_mask_out: DeviceNDArray,
+        normals_out: DeviceNDArray,
+        *args,
+        **kwargs,
+    ) -> None:
+        """Execute the intersection kernel."""
+        ...