lsurf 1.0.0__py3-none-any.whl

lsurf/geometry/detector_arrays.py

@@ -0,0 +1,1785 @@
+# 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.
+
+"""
+Detector Array Utilities
+
+Factory functions for creating arrays of detectors with various placement patterns.
+Supports Fibonacci lattice distribution on spheres and cones for uniform coverage.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..surfaces import AnnularPlaneSurface, BoundedPlaneSurface, SurfaceRole
+
+
+def fibonacci_sphere_points(n_points: int) -> NDArray[np.float64]:
+    """
+    Generate uniformly distributed points on unit sphere using Fibonacci lattice.
+
+    The Fibonacci lattice provides nearly uniform point distribution on a sphere
+    without clustering at poles (unlike latitude/longitude grids).
+
+    Parameters
+    ----------
+    n_points : int
+        Number of points to generate.
+
+    Returns
+    -------
+    ndarray, shape (n_points, 3)
+        Unit vectors on the sphere surface.
+
+    Examples
+    --------
+    >>> points = fibonacci_sphere_points(100)
+    >>> points.shape
+    (100, 3)
+    >>> np.allclose(np.linalg.norm(points, axis=1), 1.0)
+    True
+    """
+    golden_ratio = (1 + np.sqrt(5)) / 2
+
+    indices = np.arange(n_points)
+
+    # Polar angle: arccos(1 - 2*(i + 0.5)/n)
+    phi = np.arccos(1 - 2 * (indices + 0.5) / n_points)
+
+    # Azimuthal angle: 2*pi*i/golden_ratio
+    theta = 2 * np.pi * indices / golden_ratio
+
+    # Convert to Cartesian coordinates
+    x = np.sin(phi) * np.cos(theta)
+    y = np.sin(phi) * np.sin(theta)
+    z = np.cos(phi)
+
+    return np.column_stack([x, y, z])
+
+
+def fibonacci_cone_points(
+    n_points: int,
+    cone_half_angle_deg: float,
+    cone_axis: tuple[float, float, float] = (0, 0, 1),
+) -> NDArray[np.float64]:
+    """
+    Generate uniformly distributed points within a cone around a specified axis.
+
+    Uses Fibonacci lattice on the full sphere, then filters to points within
+    the specified cone angle from the axis.
+
+    Parameters
+    ----------
+    n_points : int
+        Target number of points to return (may return fewer if over-generating).
+    cone_half_angle_deg : float
+        Half-angle of the cone in degrees (0-90).
+    cone_axis : tuple of float, optional
+        Unit vector for cone axis direction. Default is (0, 0, 1) = +z.
+
+    Returns
+    -------
+    ndarray, shape (M, 3)
+        Unit vectors within the cone, where M >= n_points (or all available).
+
+    Examples
+    --------
+    >>> # Points within 30° cone around +z axis
+    >>> points = fibonacci_cone_points(100, 30.0)
+    >>> points.shape[0] >= 100 or points.shape[0] > 0
+    True
+    >>> # All points should have z >= cos(30°)
+    >>> np.all(points[:, 2] >= np.cos(np.radians(30.0)) - 1e-6)
+    True
+    """
+    if cone_half_angle_deg <= 0 or cone_half_angle_deg > 90:
+        raise ValueError("Cone half-angle must be in (0, 90] degrees")
+
+    # Normalize cone axis
+    axis = np.array(cone_axis, dtype=np.float64)
+    axis = axis / np.linalg.norm(axis)
+
+    # Cosine threshold for cone membership
+    cos_limit = np.cos(np.radians(cone_half_angle_deg))
+
+    # Estimate how many points to generate on full sphere
+    # Cone solid angle fraction = (1 - cos(theta)) / 2
+    cone_fraction = (1 - cos_limit) / 2
+    n_generate = int(n_points / cone_fraction * 1.5) + 10
+
+    # Generate on full sphere (around +z axis initially)
+    all_points = fibonacci_sphere_points(n_generate)
+
+    # Filter to cone around +z axis
+    z_values = all_points[:, 2]
+    mask = z_values >= cos_limit
+    cone_points = all_points[mask]
+
+    # If cone axis is not +z, rotate points
+    if not np.allclose(axis, [0, 0, 1]):
+        cone_points = _rotate_points_to_axis(cone_points, axis)
+
+    # Return requested number of points
+    if len(cone_points) >= n_points:
+        return cone_points[:n_points]
+    return cone_points
+
+
+def _rotate_points_to_axis(
+    points: NDArray[np.float64],
+    target_axis: NDArray[np.float64],
+) -> NDArray[np.float64]:
+    """
+    Rotate points from +z axis alignment to target axis alignment.
+
+    Uses Rodrigues' rotation formula.
+
+    Parameters
+    ----------
+    points : ndarray, shape (N, 3)
+        Points aligned with +z axis.
+    target_axis : ndarray, shape (3,)
+        Target axis unit vector.
+
+    Returns
+    -------
+    ndarray, shape (N, 3)
+        Rotated points aligned with target axis.
+    """
+    z_axis = np.array([0.0, 0.0, 1.0])
+
+    # Rotation axis = z × target (cross product)
+    k = np.cross(z_axis, target_axis)
+    k_norm = np.linalg.norm(k)
+
+    # If axes are parallel or anti-parallel
+    if k_norm < 1e-10:
+        if np.dot(z_axis, target_axis) > 0:
+            return points.copy()  # Same direction
+        else:
+            return -points.copy()  # Opposite direction (flip z)
+
+    k = k / k_norm
+
+    # Rotation angle
+    cos_angle = np.dot(z_axis, target_axis)
+    sin_angle = k_norm
+
+    # Rodrigues' rotation: v' = v*cos(θ) + (k×v)*sin(θ) + k*(k·v)*(1-cos(θ))
+    # For each point
+    rotated = np.zeros_like(points)
+    for i, p in enumerate(points):
+        cross_kp = np.cross(k, p)
+        dot_kp = np.dot(k, p)
+        rotated[i] = p * cos_angle + cross_kp * sin_angle + k * dot_kp * (1 - cos_angle)
+
+    return rotated
+
+
+def create_planar_detector_array(
+    n_detectors: int,
+    altitude: float,
+    edge_length: float,
+    earth_center: tuple[float, float, float] = (0, 0, -6.371e6),
+    earth_radius: float = 6.371e6,
+    target_point: tuple[float, float, float] = (0, 0, 0),
+    cone_half_angle_deg: float | None = None,
+    cone_axis: tuple[float, float, float] | None = None,
+    name_prefix: str = "detector",
+) -> list[BoundedPlaneSurface]:
+    """
+    Create array of bounded planar detectors at specified altitude.
+
+    Detectors are arranged in a Fibonacci lattice pattern on a sphere at the
+    specified altitude above Earth's surface. Optionally limited to a cone
+    around a specified direction.
+
+    All detector normals point toward the target point (typically the origin
+    where ray reflections occur).
+
+    Parameters
+    ----------
+    n_detectors : int
+        Number of detectors to create.
+    altitude : float
+        Altitude above Earth surface (meters).
+    edge_length : float
+        Edge length of square detectors (meters).
+    earth_center : tuple of float, optional
+        Earth center position in simulation coordinates.
+        Default is (0, 0, -6.371e6).
+    earth_radius : float, optional
+        Earth radius (meters). Default is 6.371e6.
+    target_point : tuple of float, optional
+        Point that all detector normals should point toward.
+        Default is (0, 0, 0).
+    cone_half_angle_deg : float or None, optional
+        If provided, limit detectors to a cone of this half-angle.
+        Cone is centered on cone_axis direction.
+    cone_axis : tuple of float or None, optional
+        Direction for cone axis. If None, automatically computed as
+        (target_point - earth_center) normalized. This is typically
+        the "up" direction at the target point.
+    name_prefix : str, optional
+        Prefix for detector names. Default is "detector".
+
+    Returns
+    -------
+    list of BoundedPlaneSurface
+        Configured detector surfaces ready for GeometryBuilder.
+
+    Examples
+    --------
+    >>> # Create 100 detectors in 30° cone at 33km altitude
+    >>> detectors = create_planar_detector_array(
+    ...     n_detectors=100,
+    ...     altitude=33000.0,
+    ...     edge_length=100.0,
+    ...     cone_half_angle_deg=30.0,
+    ... )
+    >>> len(detectors)
+    100
+    >>> detectors[0].role == SurfaceRole.DETECTOR
+    True
+    """
+    earth_center = np.array(earth_center, dtype=np.float64)
+    target = np.array(target_point, dtype=np.float64)
+
+    # Sphere radius for detector placement
+    detection_radius = earth_radius + altitude
+
+    # Determine cone axis if not specified
+    if cone_axis is None:
+        # Default: "up" direction at target point (radially outward from Earth center)
+        radial = target - earth_center
+        radial_norm = np.linalg.norm(radial)
+        if radial_norm < 1e-6:
+            cone_axis_vec = np.array([0.0, 0.0, 1.0])
+        else:
+            cone_axis_vec = radial / radial_norm
+    else:
+        cone_axis_vec = np.array(cone_axis, dtype=np.float64)
+        cone_axis_vec = cone_axis_vec / np.linalg.norm(cone_axis_vec)
+
+    # Generate unit vectors for detector positions
+    if cone_half_angle_deg is not None:
+        unit_vectors = fibonacci_cone_points(
+            n_detectors, cone_half_angle_deg, tuple(cone_axis_vec)
+        )
+    else:
+        unit_vectors = fibonacci_sphere_points(n_detectors)
+
+    # Create detectors
+    detectors = []
+    for i, unit_vec in enumerate(unit_vectors):
+        # Detector center position on the sphere
+        detector_center = earth_center + detection_radius * unit_vec
+
+        # Normal pointing toward target point
+        to_target = target - detector_center
+        to_target_norm = np.linalg.norm(to_target)
+        if to_target_norm < 1e-6:
+            # Detector at target point - use radial direction
+            normal = -unit_vec
+        else:
+            normal = to_target / to_target_norm
+
+        # Create bounded plane detector
+        detector = BoundedPlaneSurface(
+            point=tuple(detector_center.tolist()),
+            normal=tuple(normal.tolist()),
+            width=edge_length,
+            height=edge_length,
+            role=SurfaceRole.DETECTOR,
+            name=f"{name_prefix}_{i:04d}",
+        )
+        detectors.append(detector)
+
+    return detectors
+
+
+def create_optimized_detector_grid(
+    ray_positions: NDArray[np.float64],
+    detector_edge: float,
+    n_detectors_x: int = 10,
+    n_detectors_y: int = 10,
+    altitude: float = 33000.0,
+    earth_center: tuple[float, float, float] = (0, 0, -6.371e6),
+    earth_radius: float = 6.371e6,
+    ray_intensities: NDArray[np.float64] | None = None,
+    target_point: tuple[float, float, float] = (0, 0, 0),
+    name_prefix: str = "grid",
+) -> list[BoundedPlaneSurface]:
+    """
+    Create a dense detector grid centered on the peak intensity location.
+
+    Finds the maximum intensity ray position and creates a fixed-size grid
+    of non-overlapping planar detectors around it at the specified altitude.
+
+    Parameters
+    ----------
+    ray_positions : ndarray, shape (N, 3)
+        Detected ray positions from Phase 1 simulation.
+    detector_edge : float
+        Edge length of each square detector (meters).
+    n_detectors_x : int, optional
+        Number of detectors in x (East) direction. Default 10.
+    n_detectors_y : int, optional
+        Number of detectors in y (North) direction. Default 10.
+    altitude : float, optional
+        Altitude above Earth surface for all detectors (meters). Default 33000.
+    earth_center : tuple of float, optional
+        Earth center position. Default (0, 0, -6.371e6).
+    earth_radius : float, optional
+        Earth radius (meters). Default 6.371e6.
+    ray_intensities : ndarray, shape (N,), optional
+        Ray intensities for finding peak location. If None, uses centroid.
+    target_point : tuple of float, optional
+        Point that all detector normals should point toward. Default (0, 0, 0).
+    name_prefix : str, optional
+        Prefix for detector names. Default is "grid".
+
+    Returns
+    -------
+    list of BoundedPlaneSurface
+        Grid of n_detectors_x * n_detectors_y detector surfaces.
+
+    Examples
+    --------
+    >>> detector_grid = create_optimized_detector_grid(
+    ...     ray_positions=discovery_rays.positions,
+    ...     ray_intensities=discovery_rays.intensities,
+    ...     detector_edge=100.0,
+    ...     n_detectors_x=10,
+    ...     n_detectors_y=10,
+    ... )
+    >>> print(f"Created {len(detector_grid)} detectors")  # 100 detectors
+    """
+    if len(ray_positions) == 0:
+        return []
+
+    ray_positions = np.asarray(ray_positions, dtype=np.float64)
+    earth_center_arr = np.array(earth_center, dtype=np.float64)
+    target = np.array(target_point, dtype=np.float64)
+
+    # Find peak intensity location (or centroid if no intensities)
+    if ray_intensities is not None and len(ray_intensities) > 0:
+        peak_idx = np.argmax(ray_intensities)
+        peak_position = ray_positions[peak_idx]
+    else:
+        peak_position = np.mean(ray_positions, axis=0)
+
+    # Project peak position to correct altitude sphere
+    radial = peak_position - earth_center_arr
+    radial_norm = np.linalg.norm(radial)
+    radial_unit = radial / radial_norm
+
+    # Center point at correct altitude
+    center_3d = earth_center_arr + (earth_radius + altitude) * radial_unit
+
+    # Establish local tangent plane frame (East-North-Up)
+    global_z = np.array([0.0, 0.0, 1.0])
+
+    if np.abs(np.dot(radial_unit, global_z)) > 0.999:
+        # Near pole - use global X as reference
+        east = np.cross(radial_unit, np.array([1.0, 0.0, 0.0]))
+    else:
+        east = np.cross(global_z, radial_unit)
+
+    east = east / np.linalg.norm(east)
+    north = np.cross(radial_unit, east)
+
+    # Generate detector grid centered on peak
+    detectors = []
+    for i in range(n_detectors_x):
+        for j in range(n_detectors_y):
+            # Offset from center (grid centered on peak)
+            east_offset = (i - (n_detectors_x - 1) / 2) * detector_edge
+            north_offset = (j - (n_detectors_y - 1) / 2) * detector_edge
+
+            # 3D position in tangent plane at altitude
+            offset_3d = east_offset * east + north_offset * north
+            det_center = center_3d + offset_3d
+
+            # Normal pointing toward target
+            to_target = target - det_center
+            normal = to_target / np.linalg.norm(to_target)
+
+            det = BoundedPlaneSurface(
+                point=tuple(det_center.tolist()),
+                normal=tuple(normal.tolist()),
+                width=detector_edge,
+                height=detector_edge,
+                role=SurfaceRole.DETECTOR,
+                name=f"{name_prefix}_{i:02d}_{j:02d}",
+            )
+            detectors.append(det)
+
+    return detectors
+
+
+def compute_footprint_statistics(
+    ray_positions: NDArray[np.float64],
+    ray_intensities: NDArray[np.float64] | None = None,
+    earth_center: tuple[float, float, float] = (0, 0, -6.371e6),
+) -> dict:
+    """
+    Compute statistics about the spatial footprint of detected rays.
+
+    Useful for Phase 1 analysis before creating optimized detector grid.
+
+    Parameters
+    ----------
+    ray_positions : ndarray, shape (N, 3)
+        Detected ray positions.
+    ray_intensities : ndarray, shape (N,), optional
+        Ray intensities for weighted centroid calculation.
+    earth_center : tuple of float, optional
+        Earth center position.
+
+    Returns
+    -------
+    dict
+        Dictionary containing:
+        - 'centroid': Mean position (3,)
+        - 'intensity_weighted_centroid': Intensity-weighted mean position (3,)
+        - 'east_extent': Footprint extent in East direction (meters)
+        - 'north_extent': Footprint extent in North direction (meters)
+        - 'bounding_box_area': Area of bounding box (m²)
+        - 'aspect_ratio': Ratio of larger to smaller extent
+        - 'extent_95th': 95th percentile extents (east, north)
+        - 'local_frame': Dict with 'east', 'north', 'up' unit vectors
+    """
+    if len(ray_positions) == 0:
+        return {
+            "centroid": np.zeros(3),
+            "intensity_weighted_centroid": np.zeros(3),
+            "east_extent": 0.0,
+            "north_extent": 0.0,
+            "bounding_box_area": 0.0,
+            "aspect_ratio": 1.0,
+            "extent_95th": (0.0, 0.0),
+            "local_frame": {
+                "east": np.zeros(3),
+                "north": np.zeros(3),
+                "up": np.zeros(3),
+            },
+        }
+
+    ray_positions = np.asarray(ray_positions, dtype=np.float64)
+    earth_center_arr = np.array(earth_center, dtype=np.float64)
+
+    # Centroid
+    centroid = np.mean(ray_positions, axis=0)
+
+    # Intensity-weighted centroid
+    if ray_intensities is not None and len(ray_intensities) > 0:
+        weights = np.asarray(ray_intensities, dtype=np.float64)
+        total_weight = np.sum(weights)
+        if total_weight > 0:
+            intensity_centroid = np.average(ray_positions, axis=0, weights=weights)
+        else:
+            intensity_centroid = centroid.copy()
+    else:
+        intensity_centroid = centroid.copy()
+
+    # Local frame at centroid
+    radial = centroid - earth_center_arr
+    radial = radial / np.linalg.norm(radial)
+
+    global_z = np.array([0.0, 0.0, 1.0])
+    if np.abs(np.dot(radial, global_z)) > 0.999:
+        global_ref = np.array([1.0, 0.0, 0.0])
+        east = np.cross(radial, global_ref)
+    else:
+        east = np.cross(global_z, radial)
+    east = east / np.linalg.norm(east)
+    north = np.cross(radial, east)
+
+    # Project onto tangent plane
+    rel_pos = ray_positions - centroid
+    east_coords = np.dot(rel_pos, east)
+    north_coords = np.dot(rel_pos, north)
+
+    # Extents
+    east_extent = east_coords.max() - east_coords.min()
+    north_extent = north_coords.max() - north_coords.min()
+
+    # 95th percentile extents (robust to outliers)
+    if len(east_coords) > 10:
+        east_95 = np.percentile(np.abs(east_coords), 95) * 2
+        north_95 = np.percentile(np.abs(north_coords), 95) * 2
+    else:
+        east_95 = east_extent
+        north_95 = north_extent
+
+    # Aspect ratio
+    if min(east_extent, north_extent) > 0:
+        aspect_ratio = max(east_extent, north_extent) / min(east_extent, north_extent)
+    else:
+        aspect_ratio = 1.0
+
+    return {
+        "centroid": centroid,
+        "intensity_weighted_centroid": intensity_centroid,
+        "east_extent": east_extent,
+        "north_extent": north_extent,
+        "bounding_box_area": east_extent * north_extent,
+        "aspect_ratio": aspect_ratio,
+        "extent_95th": (east_95, north_95),
+        "local_frame": {"east": east, "north": north, "up": radial},
+    }
+
+
+def create_grid_detector_array(
+    n_rows: int,
+    n_cols: int,
+    center: tuple[float, float, float],
+    normal: tuple[float, float, float],
+    spacing: float,
+    edge_length: float,
+    name_prefix: str = "detector",
+) -> list[BoundedPlaneSurface]:
+    """
+    Create a rectangular grid of planar detectors.
+
+    Detectors are arranged in a flat grid pattern, useful for near-field
+    detection or planar detector arrays.
+
+    Parameters
+    ----------
+    n_rows : int
+        Number of rows in the grid.
+    n_cols : int
+        Number of columns in the grid.
+    center : tuple of float
+        Center position of the entire grid.
+    normal : tuple of float
+        Normal direction for all detectors (perpendicular to grid).
+    spacing : float
+        Spacing between detector centers (meters).
+    edge_length : float
+        Edge length of each square detector (meters).
+    name_prefix : str, optional
+        Prefix for detector names. Default is "detector".
+
+    Returns
+    -------
+    list of BoundedPlaneSurface
+        Grid of detector surfaces.
+
+    Examples
+    --------
+    >>> # Create 10x10 grid of detectors
+    >>> detectors = create_grid_detector_array(
+    ...     n_rows=10,
+    ...     n_cols=10,
+    ...     center=(0, 0, 1000),
+    ...     normal=(0, 0, -1),
+    ...     spacing=100.0,
+    ...     edge_length=50.0,
+    ... )
+    >>> len(detectors)
+    100
+    """
+    center = np.array(center, dtype=np.float64)
+    normal = np.array(normal, dtype=np.float64)
+    normal = normal / np.linalg.norm(normal)
+
+    # Compute local axes for the grid
+    # U axis: perpendicular to normal, in a "horizontal" direction
+    if abs(normal[2]) < 0.9:
+        ref = np.array([0.0, 0.0, 1.0])
+    else:
+        ref = np.array([1.0, 0.0, 0.0])
+
+    u_axis = ref - np.dot(ref, normal) * normal
+    u_axis = u_axis / np.linalg.norm(u_axis)
+    v_axis = np.cross(normal, u_axis)
+
+    # Grid offsets centered at (0, 0)
+    row_offsets = (np.arange(n_rows) - (n_rows - 1) / 2) * spacing
+    col_offsets = (np.arange(n_cols) - (n_cols - 1) / 2) * spacing
+
+    detectors = []
+    idx = 0
+    for row_off in row_offsets:
+        for col_off in col_offsets:
+            # Detector position
+            pos = center + col_off * u_axis + row_off * v_axis
+
+            detector = BoundedPlaneSurface(
+                point=tuple(pos.tolist()),
+                normal=tuple(normal.tolist()),
+                width=edge_length,
+                height=edge_length,
+                role=SurfaceRole.DETECTOR,
+                name=f"{name_prefix}_{idx:04d}",
+            )
+            detectors.append(detector)
+            idx += 1
+
+    return detectors
+
+
+# =============================================================================
+# Ring Detector Arrays
+# =============================================================================
+
+
+def create_ring_detector_array(
+    n_rings: int,
+    max_radius: float,
+    center: tuple[float, float, float] | None = None,
+    altitude: float = 33000.0,
+    target_point: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    name_prefix: str = "ring",
+) -> list[AnnularPlaneSurface]:
+    """
+    Create concentric ring detectors in a flat plane.
+
+    All rings share the same center and normal (toward target_point).
+    This is useful for analyzing radial distribution of detected rays around
+    a specular reflection point.
+
+    Parameters
+    ----------
+    n_rings : int
+        Number of concentric rings to create.
+    max_radius : float
+        Linear distance from center to outer edge of outermost ring (meters).
+    center : tuple of float, optional
+        Center point of the ring array (x, y, z). If None, uses (0, 0, altitude).
+    altitude : float, optional
+        Only used if center is None. Default 33000 m.
+    target_point : tuple of float, optional
+        Point that all ring normals should point toward. Default (0, 0, 0).
+    name_prefix : str, optional
+        Prefix for ring names. Default "ring".
+
+    Returns
+    -------
+    list of AnnularPlaneSurface
+        N annular ring detectors, from innermost to outermost.
+
+    Examples
+    --------
+    >>> # Rings centered at footprint location
+    >>> rings = create_ring_detector_array(
+    ...     n_rings=20,
+    ...     max_radius=50000.0,
+    ...     center=(191857.0, 320.6, 29441.9),  # footprint centroid
+    ...     target_point=(0, 0, 0),
+    ... )
+    >>> len(rings)
+    20
+
+    Notes
+    -----
+    Ring widths are uniform: ring_width = max_radius / n_rings.
+    Ring i has inner_radius = i * ring_width and outer_radius = (i+1) * ring_width.
+    """
+    if n_rings <= 0:
+        raise ValueError("n_rings must be positive")
+    if max_radius <= 0:
+        raise ValueError("max_radius must be positive")
+
+    # Ring center: use provided center or default to (0, 0, altitude)
+    if center is not None:
+        ring_center = np.array(center, dtype=np.float64)
+    else:
+        ring_center = np.array([0.0, 0.0, altitude], dtype=np.float64)
+    target = np.array(target_point, dtype=np.float64)
+
+    # Compute normal pointing toward target
+    to_target = target - ring_center
+    to_target_norm = np.linalg.norm(to_target)
+    if to_target_norm < 1e-6:
+        # Center at target - use default downward normal
+        normal = np.array([0.0, 0.0, -1.0])
+    else:
+        normal = to_target / to_target_norm
+
+    # Ring width is uniform
+    ring_width = max_radius / n_rings
+
+    rings = []
+    for i in range(n_rings):
+        inner_radius = i * ring_width
+        outer_radius = (i + 1) * ring_width
+
+        ring = AnnularPlaneSurface(
+            center=tuple(ring_center.tolist()),
+            normal=tuple(normal.tolist()),
+            inner_radius=inner_radius,
+            outer_radius=outer_radius,
+            role=SurfaceRole.DETECTOR,
+            name=f"{name_prefix}_{i:03d}",
+        )
+        rings.append(ring)
+
+    return rings
+
+
+def create_sphere_patch_detectors(
+    n_patches: int,
+    sphere_radius: float = 33000.0,
+    patch_size: float = 10000.0,
+    target_point: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    zenith_limit_deg: float = 90.0,
+    name_prefix: str = "patch",
+) -> list[BoundedPlaneSurface]:
+    """
+    Create detector patches on a sphere centered at origin.
+
+    Each patch is a bounded planar detector tangent to the sphere surface,
+    with its normal pointing toward the origin. This provides constant
+    path length from origin to all detectors.
+
+    Parameters
+    ----------
+    n_patches : int
+        Number of patches to create.
+    sphere_radius : float, optional
+        Distance from origin to patch centers (meters). Default 33000 m.
+    patch_size : float, optional
+        Edge length of each square patch (meters). Default 10000 m.
+    target_point : tuple of float, optional
+        Sphere center (patches face toward this point). Default (0, 0, 0).
+    zenith_limit_deg : float, optional
+        Only create patches within this angle from +z axis (degrees).
+        Use 90 for upper hemisphere only, 180 for full sphere. Default 90.
+    name_prefix : str, optional
+        Prefix for patch names. Default "patch".
+
+    Returns
+    -------
+    list of BoundedPlaneSurface
+        N bounded plane detectors tangent to the origin-centered sphere.
+
+    Examples
+    --------
+    >>> patches = create_sphere_patch_detectors(
+    ...     n_patches=100,
+    ...     sphere_radius=33000.0,
+    ...     patch_size=5000.0,
+    ...     zenith_limit_deg=60.0,  # Within 60 deg of +z
+    ... )
+    >>> len(patches)
+    100
+
+    Notes
+    -----
+    Patches are distributed using Fibonacci spiral for uniform coverage.
+    All patch normals point toward the target_point (origin by default).
+    """
+    if n_patches <= 0:
+        raise ValueError("n_patches must be positive")
+    if sphere_radius <= 0:
+        raise ValueError("sphere_radius must be positive")
+    if patch_size <= 0:
+        raise ValueError("patch_size must be positive")
+    if zenith_limit_deg <= 0 or zenith_limit_deg > 180:
+        raise ValueError("zenith_limit_deg must be in (0, 180]")
+
+    target = np.array(target_point, dtype=np.float64)
+
+    # Generate unit vectors using Fibonacci spiral, filtered by zenith angle
+    if zenith_limit_deg < 180.0:
+        # Use cone points around +z axis
+        unit_vectors = fibonacci_cone_points(
+            n_patches, zenith_limit_deg, cone_axis=(0.0, 0.0, 1.0)
+        )
+    else:
+        # Full sphere
+        unit_vectors = fibonacci_sphere_points(n_patches)
+
+    patches = []
+    for i, unit_vec in enumerate(unit_vectors):
+        # Patch center on the sphere
+        patch_center = target + sphere_radius * unit_vec
+
+        # Normal points toward target (origin)
+        # Normal = -unit_vec (since unit_vec points from target to patch)
+        normal = -unit_vec
+
+        patch = BoundedPlaneSurface(
+            point=tuple(patch_center.tolist()),
+            normal=tuple(normal.tolist()),
+            width=patch_size,
+            height=patch_size,
+            role=SurfaceRole.DETECTOR,
+            name=f"{name_prefix}_{i:04d}",
+        )
+        patches.append(patch)
+
+    return patches
+
+
+# =============================================================================
+# Ray Binning Functions
+# =============================================================================
+
+
+@dataclass
+class RingSegmentStats:
+    """Statistics for a single ring-azimuth segment."""
+
+    ring_index: int
+    azimuth_bin: int
+    azimuth_center_deg: float
+    inner_radius: float
+    outer_radius: float
+    segment_area: float
+    ray_count: int
+    total_intensity: float
+    irradiance: float
+    mean_time: float
+    time_std: float
+    positions: NDArray[np.float64] | None = None
+    times: NDArray[np.float64] | None = None
+    intensities: NDArray[np.float64] | None = None
+
+
+def bin_rays_by_ring_and_azimuth(
+    ray_positions: NDArray[np.float64],
+    ray_times: NDArray[np.float64],
+    ray_intensities: NDArray[np.float64],
+    ring_detectors: list[AnnularPlaneSurface],
+    n_azimuth_bins: int = 36,
+    store_raw_data: bool = False,
+) -> list[RingSegmentStats]:
+    """
+    Bin detected rays into (ring, azimuth) segments.
+
+    After simulation with ring detectors, use this function to subdivide
+    each ring into azimuthal segments and compute per-segment statistics.
+
+    Parameters
+    ----------
+    ray_positions : ndarray, shape (N, 3)
+        Detected ray positions.
+    ray_times : ndarray, shape (N,)
+        Ray arrival times (seconds).
+    ray_intensities : ndarray, shape (N,)
+        Ray intensities.
+    ring_detectors : list of AnnularPlaneSurface
+        The ring detectors used in the simulation.
+    n_azimuth_bins : int, optional
+        Number of azimuthal bins (e.g., 36 for 10 degree bins). Default 36.
+    store_raw_data : bool, optional
+        If True, store positions/times/intensities arrays in each segment.
+        Default False (saves memory).
+
+    Returns
+    -------
+    list of RingSegmentStats
+        Statistics for each segment with ray_count > 0.
+
+    Examples
+    --------
+    >>> segment_stats = bin_rays_by_ring_and_azimuth(
+    ...     ray_positions=result.detected.positions,
+    ...     ray_times=result.detected.times,
+    ...     ray_intensities=result.detected.intensities,
+    ...     ring_detectors=rings,
+    ...     n_azimuth_bins=36,  # 10 deg bins
+    ... )
+    >>> for seg in segment_stats[:5]:
+    ...     print(f"Ring {seg.ring_index}, Az {seg.azimuth_center_deg:.0f}deg: "
+    ...           f"{seg.ray_count} rays, irradiance={seg.irradiance:.2e} W/m2")
+    """
+    if len(ray_positions) == 0:
+        return []
+
+    ray_positions = np.asarray(ray_positions, dtype=np.float64)
+    ray_times = np.asarray(ray_times, dtype=np.float64)
+    ray_intensities = np.asarray(ray_intensities, dtype=np.float64)
+
+    # Get ring center and axes from first detector (all share same center/normal)
+    if not ring_detectors:
+        return []
+
+    ref_ring = ring_detectors[0]
+    center = np.array(ref_ring.center, dtype=np.float64)
+    u_axis = np.array(ref_ring._u_axis, dtype=np.float64)
+    v_axis = np.array(ref_ring._v_axis, dtype=np.float64)
+
+    # Compute local coordinates for all rays
+    rel = ray_positions - center
+    u_coords = np.dot(rel, u_axis)
+    v_coords = np.dot(rel, v_axis)
+    radii = np.sqrt(u_coords**2 + v_coords**2)
+    azimuths = np.arctan2(v_coords, u_coords)  # -pi to pi
+
+    # Azimuth bin edges
+    azimuth_bin_width = 2 * np.pi / n_azimuth_bins
+    # Shift azimuths to [0, 2*pi) for binning
+    azimuths_shifted = azimuths + np.pi  # Now [0, 2*pi)
+    azimuth_bin_indices = np.floor(azimuths_shifted / azimuth_bin_width).astype(int)
+    azimuth_bin_indices = np.clip(azimuth_bin_indices, 0, n_azimuth_bins - 1)
+
+    segments = []
+
+    for ring_idx, ring in enumerate(ring_detectors):
+        inner_r = ring.inner_radius
+        outer_r = ring.outer_radius
+
+        # Find rays in this ring
+        in_ring = (radii >= inner_r) & (radii < outer_r)
+
+        for az_bin in range(n_azimuth_bins):
+            # Find rays in this azimuth bin
+            in_az = azimuth_bin_indices == az_bin
+            mask = in_ring & in_az
+
+            if not np.any(mask):
+                continue
+
+            # Compute segment area
+            # Segment = annular wedge = (R_out^2 - R_in^2) * delta_theta / 2
+            segment_area = (outer_r**2 - inner_r**2) * np.pi / n_azimuth_bins
+
+            # Extract data for this segment
+            seg_times = ray_times[mask]
+            seg_intensities = ray_intensities[mask]
+            seg_positions = ray_positions[mask] if store_raw_data else None
+
+            # Compute statistics
+            ray_count = int(np.sum(mask))
+            total_intensity = float(np.sum(seg_intensities))
+            irradiance = total_intensity / segment_area if segment_area > 0 else 0.0
+
+            if total_intensity > 0:
+                mean_time = float(np.average(seg_times, weights=seg_intensities))
+                time_variance = float(
+                    np.average((seg_times - mean_time) ** 2, weights=seg_intensities)
+                )
+                time_std = float(np.sqrt(time_variance))
+            else:
+                mean_time = float(np.mean(seg_times))
+                time_std = float(np.std(seg_times))
+
+            # Azimuth center in degrees
+            az_center_rad = (az_bin + 0.5) * azimuth_bin_width - np.pi
+            az_center_deg = float(np.degrees(az_center_rad))
+
+            seg_stats = RingSegmentStats(
+                ring_index=ring_idx,
+                azimuth_bin=az_bin,
+                azimuth_center_deg=az_center_deg,
+                inner_radius=inner_r,
+                outer_radius=outer_r,
+                segment_area=segment_area,
+                ray_count=ray_count,
+                total_intensity=total_intensity,
+                irradiance=irradiance,
+                mean_time=mean_time,
+                time_std=time_std,
+                positions=seg_positions,
+                times=seg_times if store_raw_data else None,
+                intensities=seg_intensities if store_raw_data else None,
+            )
+            segments.append(seg_stats)
+
+    return segments
+
+
+@dataclass
+class PatchStats:
+    """Statistics for a single detector patch."""
+
+    patch_index: int
+    patch_name: str
+    center: tuple[float, float, float]
+    normal: tuple[float, float, float]
+    area: float
+    ray_count: int
+    total_intensity: float
+    irradiance: float
+    mean_time: float
+    time_std: float
+    positions: NDArray[np.float64] | None = None
+    times: NDArray[np.float64] | None = None
+    intensities: NDArray[np.float64] | None = None
+
+
+def bin_rays_by_patch(
+    ray_positions: NDArray[np.float64],
+    ray_times: NDArray[np.float64],
+    ray_intensities: NDArray[np.float64],
+    patch_detectors: list[BoundedPlaneSurface],
+    store_raw_data: bool = False,
+) -> list[PatchStats]:
+    """
+    Bin detected rays by which patch detector they hit.
+
+    After simulation with sphere patch detectors, use this function to
+    compute per-patch statistics.
+
+    Parameters
+    ----------
+    ray_positions : ndarray, shape (N, 3)
+        Detected ray positions.
+    ray_times : ndarray, shape (N,)
+        Ray arrival times (seconds).
+    ray_intensities : ndarray, shape (N,)
+        Ray intensities.
+    patch_detectors : list of BoundedPlaneSurface
+        The patch detectors used in the simulation.
+    store_raw_data : bool, optional
+        If True, store positions/times/intensities arrays in each patch.
+        Default False (saves memory).
+
+    Returns
+    -------
+    list of PatchStats
+        Statistics for each patch with ray_count > 0.
+
+    Examples
+    --------
+    >>> patch_stats = bin_rays_by_patch(
+    ...     ray_positions=result.detected.positions,
+    ...     ray_times=result.detected.times,
+    ...     ray_intensities=result.detected.intensities,
+    ...     patch_detectors=patches,
+    ... )
+    >>> for p in sorted(patch_stats, key=lambda x: -x.irradiance)[:5]:
+    ...     print(f"{p.patch_name}: {p.ray_count} rays, "
+    ...           f"irradiance={p.irradiance:.2e} W/m2")
+    """
+    if len(ray_positions) == 0:
+        return []
+
+    ray_positions = np.asarray(ray_positions, dtype=np.float64)
+    ray_times = np.asarray(ray_times, dtype=np.float64)
+    ray_intensities = np.asarray(ray_intensities, dtype=np.float64)
+
+    patch_stats_list = []
+
+    for patch_idx, patch in enumerate(patch_detectors):
+        patch_center = np.array(patch.point, dtype=np.float64)
+        patch_normal = np.array(patch._normal, dtype=np.float64)
+        patch_u = np.array(patch._u_axis, dtype=np.float64)
+        patch_v = np.array(patch._v_axis, dtype=np.float64)
+
+        # Vector from patch center to each ray position
+        rel_pos = ray_positions - patch_center
+
+        # Check if ray is on this patch plane (within tolerance)
+        dist_to_plane = np.abs(np.dot(rel_pos, patch_normal))
+        on_plane = dist_to_plane < 1.0  # 1m tolerance
+
+        # Check if within bounds
+        u_coord = np.dot(rel_pos, patch_u)
+        v_coord = np.dot(rel_pos, patch_v)
+        in_bounds = (np.abs(u_coord) <= patch.half_width + 0.1) & (
+            np.abs(v_coord) <= patch.half_height + 0.1
+        )
+
+        mask = on_plane & in_bounds
+
+        if not np.any(mask):
+            continue
+
+        # Extract data for this patch
+        seg_times = ray_times[mask]
+        seg_intensities = ray_intensities[mask]
+        seg_positions = ray_positions[mask] if store_raw_data else None
+
+        # Compute statistics
+        ray_count = int(np.sum(mask))
+        total_intensity = float(np.sum(seg_intensities))
+        area = patch.width * patch.height
+        irradiance = total_intensity / area if area > 0 else 0.0
+
+        if total_intensity > 0:
+            mean_time = float(np.average(seg_times, weights=seg_intensities))
+            time_variance = float(
+                np.average((seg_times - mean_time) ** 2, weights=seg_intensities)
+            )
+            time_std = float(np.sqrt(time_variance))
+        else:
+            mean_time = float(np.mean(seg_times))
+            time_std = float(np.std(seg_times))
+
+        stats = PatchStats(
+            patch_index=patch_idx,
+            patch_name=patch.name,
+            center=patch.point,
+            normal=patch._normal,
+            area=area,
+            ray_count=ray_count,
+            total_intensity=total_intensity,
+            irradiance=irradiance,
+            mean_time=mean_time,
+            time_std=time_std,
+            positions=seg_positions,
+            times=seg_times if store_raw_data else None,
+            intensities=seg_intensities if store_raw_data else None,
+        )
+        patch_stats_list.append(stats)
+
+    return patch_stats_list
+
+
+@dataclass
+class SphericalRingSegmentStats:
+    """Statistics for a single spherical arc ring segment."""
+
+    ring_index: int
+    azimuth_bin: int
+    azimuth_center_deg: float
+    inner_arc_distance: float  # Arc distance from zenith to inner edge (meters)
+    outer_arc_distance: float  # Arc distance from zenith to outer edge (meters)
+    inner_zenith_angle_deg: float  # Zenith angle at inner edge (degrees)
+    outer_zenith_angle_deg: float  # Zenith angle at outer edge (degrees)
+    segment_area: float  # Area on sphere surface (m^2)
+    ray_count: int
+    total_intensity: float
+    irradiance: float  # W/m^2
+    mean_time: float
+    time_std: float
+    mean_height: float  # Mean height of rays in this segment (meters)
+    positions: NDArray[np.float64] | None = None
+    times: NDArray[np.float64] | None = None
+    intensities: NDArray[np.float64] | None = None
+
+
+def bin_rays_by_spherical_arc_rings(
+    ray_positions: NDArray[np.float64],
+    ray_times: NDArray[np.float64],
+    ray_intensities: NDArray[np.float64],
+    sphere_radius: float,
+    ring_arc_width: float = 10000.0,
+    n_rings: int | None = None,
+    n_azimuth_bins: int = 36,
+    zenith_direction: tuple[float, float, float] = (0.0, 0.0, 1.0),
+    sphere_center: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    store_raw_data: bool = False,
+    earth_radius: float | None = None,
+) -> list[SphericalRingSegmentStats]:
+    """
+    Bin rays on a sphere into rings by arc distance from zenith.
+
+    Rays detected on a sphere are binned into concentric rings defined
+    by arc distance from the zenith point. Each ring is further subdivided
+    into azimuthal segments.
+
+    This is the correct geometry for spherical detectors where rings follow
+    the sphere surface rather than being flat planes.
+
+    Parameters
+    ----------
+    ray_positions : ndarray, shape (N, 3)
+        Detected ray positions on the sphere.
+    ray_times : ndarray, shape (N,)
+        Ray arrival times (seconds).
+    ray_intensities : ndarray, shape (N,)
+        Ray intensities.
+    sphere_radius : float
+        Radius of the detection sphere (meters).
+    ring_arc_width : float, optional
+        Arc length width of each ring (meters). Default 10000 m (10 km).
+    n_rings : int, optional
+        Number of rings. If None, computed from sphere_radius / ring_arc_width.
+    n_azimuth_bins : int, optional
+        Number of azimuthal bins (e.g., 36 for 10 degree bins). Default 36.
+    zenith_direction : tuple of float, optional
+        Unit vector defining the zenith direction (pole of the rings).
+        Default (0, 0, 1) = +z.
+    sphere_center : tuple of float, optional
+        Center of the sphere. Default (0, 0, 0).
+    store_raw_data : bool, optional
+        If True, store positions/times/intensities arrays in each segment.
+        Default False (saves memory).
+    earth_radius : float, optional
+        If provided, compute mean_height as altitude above Earth's surface
+        (radial distance from sphere_center minus earth_radius).
+        If None, mean_height is the z-projection onto the zenith axis.
+
+    Returns
+    -------
+    list of SphericalRingSegmentStats
+        Statistics for each segment with ray_count > 0.
+
+    Examples
+    --------
+    >>> # Bin rays into 10km arc-width rings on 33km sphere
+    >>> segment_stats = bin_rays_by_spherical_arc_rings(
+    ...     ray_positions=result.detected.positions,
+    ...     ray_times=result.detected.times,
+    ...     ray_intensities=result.detected.intensities,
+    ...     sphere_radius=33000.0,
+    ...     ring_arc_width=10000.0,  # 10 km rings
+    ...     n_azimuth_bins=36,  # 10 deg bins
+    ... )
+    >>> for seg in segment_stats[:5]:
+    ...     print(f"Ring {seg.ring_index} (arc {seg.inner_arc_distance/1000:.1f}-"
+    ...           f"{seg.outer_arc_distance/1000:.1f} km), "
+    ...           f"Az {seg.azimuth_center_deg:.0f}deg: {seg.ray_count} rays")
+
+    Notes
+    -----
+    Ring geometry:
+    - Ring 0: arc distance 0 to ring_arc_width from zenith
+    - Ring i: arc distance i*ring_arc_width to (i+1)*ring_arc_width
+    - The zenith point is at (0, 0, sphere_radius) if sphere_center=(0,0,0)
+      and zenith_direction=(0,0,1)
+
+    Arc distance s and zenith angle θ are related by: s = R * θ
+    where R is the sphere radius and θ is in radians.
+
+    The area of a spherical ring segment (annular wedge on sphere) is:
+    Area = R² * (cos(θ_inner) - cos(θ_outer)) * Δφ
+    where Δφ = 2π / n_azimuth_bins is the azimuthal width.
+    """
+    if len(ray_positions) == 0:
+        return []
+
+    ray_positions = np.asarray(ray_positions, dtype=np.float64)
+    ray_times = np.asarray(ray_times, dtype=np.float64)
+    ray_intensities = np.asarray(ray_intensities, dtype=np.float64)
+
+    center = np.array(sphere_center, dtype=np.float64)
+    zenith = np.array(zenith_direction, dtype=np.float64)
+    zenith = zenith / np.linalg.norm(zenith)
+
+    # Compute number of rings if not specified
+    if n_rings is None:
+        # Cover up to 90 degrees from zenith (half sphere)
+        max_arc = sphere_radius * np.pi / 2  # Quarter circumference
+        n_rings = int(np.ceil(max_arc / ring_arc_width))
+
+    # Compute local coordinate system
+    # x-axis: perpendicular to zenith, in a "horizontal" direction
+    if abs(zenith[2]) < 0.9:
+        ref = np.array([0.0, 0.0, 1.0])
+    else:
+        ref = np.array([1.0, 0.0, 0.0])
+
+    x_axis = ref - np.dot(ref, zenith) * zenith
+    x_axis = x_axis / np.linalg.norm(x_axis)
+    y_axis = np.cross(zenith, x_axis)
+
+    # For each ray, compute:
+    # 1. Vector from sphere center to ray position
+    rel_pos = ray_positions - center
+
+    # 2. Radial distance (should be close to sphere_radius)
+    radii = np.linalg.norm(rel_pos, axis=1)
+
+    # 3. Zenith angle (angle from zenith direction)
+    cos_zenith = np.dot(rel_pos, zenith) / radii
+    cos_zenith = np.clip(cos_zenith, -1.0, 1.0)
+    zenith_angles = np.arccos(cos_zenith)  # 0 at zenith, pi at nadir
+
+    # 4. Arc distance from zenith
+    arc_distances = sphere_radius * zenith_angles
+
+    # 5. Azimuth angle (around zenith axis)
+    # Project onto plane perpendicular to zenith
+    x_coords = np.dot(rel_pos, x_axis)
+    y_coords = np.dot(rel_pos, y_axis)
+    azimuths = np.arctan2(y_coords, x_coords)  # -pi to pi
+
+    # 6. Height computation
+    if earth_radius is not None:
+        # Compute altitude above Earth's surface
+        # (distance from sphere center = radii, altitude = radii - earth_radius)
+        heights = radii - earth_radius
+    else:
+        # Compute z-component relative to sphere center (projection onto zenith)
+        heights = np.dot(rel_pos, zenith)
+
+    # Ring bin edges (by arc distance)
+    ring_bin_indices = np.floor(arc_distances / ring_arc_width).astype(int)
+    ring_bin_indices = np.clip(ring_bin_indices, 0, n_rings - 1)
+
+    # Azimuth bin edges
+    azimuth_bin_width = 2 * np.pi / n_azimuth_bins
+    azimuths_shifted = azimuths + np.pi  # [0, 2*pi)
+    azimuth_bin_indices = np.floor(azimuths_shifted / azimuth_bin_width).astype(int)
+    azimuth_bin_indices = np.clip(azimuth_bin_indices, 0, n_azimuth_bins - 1)
+
+    segments = []
+
+    for ring_idx in range(n_rings):
+        inner_arc = ring_idx * ring_arc_width
+        outer_arc = (ring_idx + 1) * ring_arc_width
+
+        # Convert arc distances to zenith angles
+        inner_theta = inner_arc / sphere_radius
+        outer_theta = outer_arc / sphere_radius
+
+        # Find rays in this ring
+        in_ring = ring_bin_indices == ring_idx
+
+        for az_bin in range(n_azimuth_bins):
+            in_az = azimuth_bin_indices == az_bin
+            mask = in_ring & in_az
+
+            if not np.any(mask):
+                continue
+
+            # Compute segment area on sphere
+            # Area = R² * (cos(θ_inner) - cos(θ_outer)) * Δφ
+            delta_phi = 2 * np.pi / n_azimuth_bins
+            segment_area = (
+                sphere_radius**2
+                * (np.cos(inner_theta) - np.cos(outer_theta))
+                * delta_phi
+            )
+
+            # Extract data for this segment
+            seg_times = ray_times[mask]
+            seg_intensities = ray_intensities[mask]
+            seg_positions = ray_positions[mask] if store_raw_data else None
+            seg_heights = heights[mask]
+
+            # Compute statistics
+            ray_count = int(np.sum(mask))
+            total_intensity = float(np.sum(seg_intensities))
+            irradiance = total_intensity / segment_area if segment_area > 0 else 0.0
+
+            if total_intensity > 0:
+                mean_time = float(np.average(seg_times, weights=seg_intensities))
+                time_variance = float(
+                    np.average((seg_times - mean_time) ** 2, weights=seg_intensities)
+                )
+                time_std = float(np.sqrt(time_variance))
+                mean_height = float(np.average(seg_heights, weights=seg_intensities))
+            else:
+                mean_time = float(np.mean(seg_times))
+                time_std = float(np.std(seg_times))
+                mean_height = float(np.mean(seg_heights))
+
+            # Azimuth center in degrees
+            az_center_rad = (az_bin + 0.5) * azimuth_bin_width - np.pi
+            az_center_deg = float(np.degrees(az_center_rad))
+
+            seg_stats = SphericalRingSegmentStats(
+                ring_index=ring_idx,
+                azimuth_bin=az_bin,
+                azimuth_center_deg=az_center_deg,
+                inner_arc_distance=inner_arc,
+                outer_arc_distance=outer_arc,
+                inner_zenith_angle_deg=float(np.degrees(inner_theta)),
+                outer_zenith_angle_deg=float(np.degrees(outer_theta)),
+                segment_area=segment_area,
+                ray_count=ray_count,
+                total_intensity=total_intensity,
+                irradiance=irradiance,
+                mean_time=mean_time,
+                time_std=time_std,
+                mean_height=mean_height,
+                positions=seg_positions,
+                times=seg_times if store_raw_data else None,
+                intensities=seg_intensities if store_raw_data else None,
+            )
+            segments.append(seg_stats)
+
+    return segments
+
+
+def compute_spherical_ring_summary(
+    segment_stats: list[SphericalRingSegmentStats],
+) -> dict[str, Any]:
+    """
+    Compute summary statistics across all spherical ring segments.
+
+    Parameters
+    ----------
+    segment_stats : list of SphericalRingSegmentStats
+        Output from bin_rays_by_spherical_arc_rings.
+
+    Returns
+    -------
+    dict
+        Summary containing:
+        - 'total_rays': Total ray count
+        - 'total_intensity': Total detected intensity
+        - 'n_segments': Number of segments with hits
+        - 'peak_irradiance': Maximum segment irradiance
+        - 'peak_segment': SphericalRingSegmentStats for peak irradiance segment
+        - 'per_ring': List of per-ring summaries
+    """
+    if not segment_stats:
+        return {
+            "total_rays": 0,
+            "total_intensity": 0.0,
+            "n_segments": 0,
+            "peak_irradiance": 0.0,
+            "peak_segment": None,
+            "per_ring": [],
+        }
+
+    total_rays = sum(s.ray_count for s in segment_stats)
+    total_intensity = sum(s.total_intensity for s in segment_stats)
+    peak_segment = max(segment_stats, key=lambda s: s.irradiance)
+
+    # Per-ring summaries
+    ring_indices = sorted(set(s.ring_index for s in segment_stats))
+    per_ring = []
+    for ring_idx in ring_indices:
+        ring_segs = [s for s in segment_stats if s.ring_index == ring_idx]
+        if ring_segs:
+            inner_arc = ring_segs[0].inner_arc_distance
+            outer_arc = ring_segs[0].outer_arc_distance
+            mid_arc = (inner_arc + outer_arc) / 2
+            inner_zenith = ring_segs[0].inner_zenith_angle_deg
+            outer_zenith = ring_segs[0].outer_zenith_angle_deg
+        else:
+            inner_arc = outer_arc = mid_arc = inner_zenith = outer_zenith = 0.0
+
+        per_ring.append(
+            {
+                "ring_index": ring_idx,
+                "inner_arc_km": inner_arc / 1000,
+                "outer_arc_km": outer_arc / 1000,
+                "mid_arc_km": mid_arc / 1000,
+                "inner_zenith_deg": inner_zenith,
+                "outer_zenith_deg": outer_zenith,
+                "n_segments": len(ring_segs),
+                "total_rays": sum(s.ray_count for s in ring_segs),
+                "total_intensity": sum(s.total_intensity for s in ring_segs),
+                "mean_irradiance": (
+                    np.mean([s.irradiance for s in ring_segs]) if ring_segs else 0.0
+                ),
+                "mean_height_km": (
+                    np.mean([s.mean_height for s in ring_segs]) / 1000
+                    if ring_segs
+                    else 0.0
+                ),
+            }
+        )
+
+    return {
+        "total_rays": total_rays,
+        "total_intensity": total_intensity,
+        "n_segments": len(segment_stats),
+        "peak_irradiance": peak_segment.irradiance,
+        "peak_segment": peak_segment,
+        "per_ring": per_ring,
+    }
+
+
+def bin_rays_by_elevation_rings(
+    ray_positions: NDArray[np.float64],
+    ray_times: NDArray[np.float64],
+    ray_intensities: NDArray[np.float64],
+    sphere_radius: float,
+    earth_radius: float,
+    elevation_bin_width_deg: float | None = 0.1,
+    max_elevation_deg: float = 90.0,
+    min_elevation_deg: float = -2.0,
+    n_azimuth_bins: int = 36,
+    origin: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    store_raw_data: bool = False,
+    ring_boundaries_deg: NDArray[np.float64] | None = None,
+) -> list[SphericalRingSegmentStats]:
+    """
+    Bin rays into rings defined by elevation angle from origin (no shadowing).
+
+    Unlike bin_rays_by_spherical_arc_rings which uses arc distance on the sphere,
+    this function defines rings by elevation angle as seen from the origin.
+    This ensures no ring shadows another when viewed from the origin.
+
+    Can use either fixed elevation bin width OR custom ring boundaries for
+    variable-width rings (e.g., constant physical size detectors).
+
+    Parameters
+    ----------
+    ray_positions : ndarray, shape (N, 3)
+        Detected ray positions.
+    ray_times : ndarray, shape (N,)
+        Ray arrival times (seconds).
+    ray_intensities : ndarray, shape (N,)
+        Ray intensities.
+    sphere_radius : float
+        Radius of detection sphere from Earth center (meters).
+    earth_radius : float
+        Radius of Earth (meters). Used to compute altitude.
+    elevation_bin_width_deg : float or None, optional
+        Width of each elevation bin in degrees. Default 0.1 deg.
+        Ignored if ring_boundaries_deg is provided.
+    max_elevation_deg : float, optional
+        Maximum elevation angle (at zenith). Default 90 deg.
+        Ignored if ring_boundaries_deg is provided.
+    min_elevation_deg : float, optional
+        Minimum elevation angle (below horizontal). Default -2 deg.
+        Ignored if ring_boundaries_deg is provided.
+    n_azimuth_bins : int, optional
+        Number of azimuthal bins. Default 36 (10 deg each).
+    origin : tuple of float, optional
+        Origin point for elevation angle computation. Default (0, 0, 0).
+    store_raw_data : bool, optional
+        If True, store raw data arrays in each segment. Default False.
+    ring_boundaries_deg : ndarray, optional
+        Custom ring boundary elevation angles in degrees, sorted descending
+        (from zenith to horizon). If provided, overrides elevation_bin_width_deg.
+        Example: [90, 81.4, 73.2, ...] for variable-width rings.
+
+    Returns
+    -------
+    list of SphericalRingSegmentStats
+        Statistics for each segment with ray_count > 0.
+
+    Notes
+    -----
+    Ring boundaries are defined by elevation angle from origin, not arc distance.
+    This ensures rays from origin see non-overlapping rings (no shadowing).
+    The arc distances in the returned stats are computed from the elevation angles.
+    """
+    if len(ray_positions) == 0:
+        return []
+
+    ray_positions = np.asarray(ray_positions, dtype=np.float64)
+    ray_times = np.asarray(ray_times, dtype=np.float64)
+    ray_intensities = np.asarray(ray_intensities, dtype=np.float64)
+    origin_arr = np.array(origin, dtype=np.float64)
+
+    # Compute position relative to origin
+    rel_pos = ray_positions - origin_arr
+
+    # Compute elevation angle from origin (angle above horizontal)
+    # horizontal distance and vertical distance
+    horizontal_dist = np.sqrt(rel_pos[:, 0] ** 2 + rel_pos[:, 1] ** 2)
+    vertical_dist = rel_pos[:, 2]
+    elevation_rad = np.arctan2(vertical_dist, horizontal_dist)
+    elevation_deg = np.degrees(elevation_rad)
+
+    # Compute azimuth from origin
+    azimuths = np.arctan2(rel_pos[:, 1], rel_pos[:, 0])  # -pi to pi
+
+    # Compute altitude above Earth surface
+    dist_from_earth_center = np.sqrt(
+        rel_pos[:, 0] ** 2 + rel_pos[:, 1] ** 2 + (rel_pos[:, 2] + earth_radius) ** 2
+    )
+    heights = dist_from_earth_center - earth_radius
+
+    # Elevation bin edges - use custom boundaries if provided
+    if ring_boundaries_deg is not None:
+        elevation_bins = np.asarray(ring_boundaries_deg, dtype=np.float64)
+        n_rings = len(elevation_bins) - 1
+        # For custom boundaries, use searchsorted to find bin indices
+        # Boundaries are sorted descending, so we need to handle this
+        # Bin i contains elevations in [elevation_bins[i+1], elevation_bins[i])
+        ring_bin_indices = (
+            np.searchsorted(-elevation_bins[:-1], -elevation_deg, side="right") - 1
+        )
+        ring_bin_indices = np.clip(ring_bin_indices, 0, n_rings - 1)
+    else:
+        n_rings = int(
+            np.ceil((max_elevation_deg - min_elevation_deg) / elevation_bin_width_deg)
+        )
+        elevation_bins = np.linspace(max_elevation_deg, min_elevation_deg, n_rings + 1)
+        # Bin by elevation (ring 0 is at zenith = highest elevation)
+        ring_bin_indices = np.floor(
+            (max_elevation_deg - elevation_deg) / elevation_bin_width_deg
+        ).astype(int)
+        ring_bin_indices = np.clip(ring_bin_indices, 0, n_rings - 1)
+
+    # Azimuth bin edges
+    azimuth_bin_width = 2 * np.pi / n_azimuth_bins
+    azimuths_shifted = azimuths + np.pi  # [0, 2*pi)
+    azimuth_bin_indices = np.floor(azimuths_shifted / azimuth_bin_width).astype(int)
+    azimuth_bin_indices = np.clip(azimuth_bin_indices, 0, n_azimuth_bins - 1)
+
+    segments = []
+
+    # Helper function to compute distance from origin to detector sphere at elevation angle
+    def _distance_at_elevation(elev_deg: float) -> float:
+        """Distance from origin to detector sphere at given elevation angle."""
+        elev_rad = np.radians(elev_deg)
+        cos_e, sin_e = np.cos(elev_rad), np.sin(elev_rad)
+        discriminant = sphere_radius**2 - earth_radius**2 * cos_e**2
+        if discriminant < 0:
+            return 0.0
+        return -sin_e * earth_radius + np.sqrt(discriminant)
+
+    for ring_idx in range(n_rings):
+        # Elevation bounds for this ring
+        inner_elev_deg = elevation_bins[ring_idx]
+        outer_elev_deg = elevation_bins[ring_idx + 1]
+        inner_elev_rad = np.radians(inner_elev_deg)
+        outer_elev_rad = np.radians(outer_elev_deg)
+
+        # Compute horizontal distances from origin to inner/outer ring boundaries
+        # These are more meaningful than arc distances for elevation-based rings
+        inner_dist = _distance_at_elevation(inner_elev_deg)
+        outer_dist = _distance_at_elevation(outer_elev_deg)
+        inner_horiz = inner_dist * np.cos(inner_elev_rad)
+        outer_horiz = outer_dist * np.cos(outer_elev_rad)
+
+        # Find rays in this ring
+        in_ring = ring_bin_indices == ring_idx
+
+        for az_bin in range(n_azimuth_bins):
+            in_az = azimuth_bin_indices == az_bin
+            mask = in_ring & in_az
+
+            if not np.any(mask):
+                continue
+
+            # Compute segment area (approximate as flat annular sector)
+            # For elevation rings, use spherical cap area approximation
+            delta_phi = 2 * np.pi / n_azimuth_bins
+            # Area on sphere between two elevation angles
+            # A = R² * (sin(e1) - sin(e2)) * delta_phi (for elevation angles)
+            segment_area = (
+                sphere_radius**2
+                * abs(np.sin(inner_elev_rad) - np.sin(outer_elev_rad))
+                * delta_phi
+            )
+
+            # Extract data
+            seg_times = ray_times[mask]
+            seg_intensities = ray_intensities[mask]
+            seg_positions = ray_positions[mask] if store_raw_data else None
+            seg_heights = heights[mask]
+
+            # Compute statistics
+            ray_count = int(np.sum(mask))
+            total_intensity = float(np.sum(seg_intensities))
+            irradiance = total_intensity / segment_area if segment_area > 0 else 0.0
+
+            if total_intensity > 0:
+                mean_time = float(np.average(seg_times, weights=seg_intensities))
+                time_variance = float(
+                    np.average((seg_times - mean_time) ** 2, weights=seg_intensities)
+                )
+                time_std = float(np.sqrt(time_variance))
+                mean_height = float(np.average(seg_heights, weights=seg_intensities))
+            else:
+                mean_time = float(np.mean(seg_times))
+                time_std = float(np.std(seg_times))
+                mean_height = float(np.mean(seg_heights))
+
+            # Azimuth center in degrees
+            az_center_rad = (az_bin + 0.5) * azimuth_bin_width - np.pi
+            az_center_deg = float(np.degrees(az_center_rad))
+
+            seg_stats = SphericalRingSegmentStats(
+                ring_index=ring_idx,
+                azimuth_bin=az_bin,
+                azimuth_center_deg=az_center_deg,
+                inner_arc_distance=float(
+                    inner_horiz
+                ),  # Horizontal distance to inner edge
+                outer_arc_distance=float(
+                    outer_horiz
+                ),  # Horizontal distance to outer edge
+                inner_zenith_angle_deg=90.0
+                - inner_elev_deg,  # Convert elevation to zenith angle
+                outer_zenith_angle_deg=90.0 - outer_elev_deg,
+                segment_area=segment_area,
+                ray_count=ray_count,
+                total_intensity=total_intensity,
+                irradiance=irradiance,
+                mean_time=mean_time,
+                time_std=time_std,
+                mean_height=mean_height,
+                positions=seg_positions,
+                times=seg_times if store_raw_data else None,
+                intensities=seg_intensities if store_raw_data else None,
+            )
+            segments.append(seg_stats)
+
+    return segments
+
+
+def compute_ring_summary(
+    segment_stats: list[RingSegmentStats],
+) -> dict[str, Any]:
+    """
+    Compute summary statistics across all ring segments.
+
+    Parameters
+    ----------
+    segment_stats : list of RingSegmentStats
+        Output from bin_rays_by_ring_and_azimuth.
+
+    Returns
+    -------
+    dict
+        Summary containing:
+        - 'total_rays': Total ray count
+        - 'total_intensity': Total detected intensity
+        - 'n_segments': Number of segments with hits
+        - 'peak_irradiance': Maximum segment irradiance
+        - 'peak_segment': RingSegmentStats for peak irradiance segment
+        - 'per_ring': List of per-ring summaries (ring_index, n_segments, total_intensity)
+    """
+    if not segment_stats:
+        return {
+            "total_rays": 0,
+            "total_intensity": 0.0,
+            "n_segments": 0,
+            "peak_irradiance": 0.0,
+            "peak_segment": None,
+            "per_ring": [],
+        }
+
+    total_rays = sum(s.ray_count for s in segment_stats)
+    total_intensity = sum(s.total_intensity for s in segment_stats)
+    peak_segment = max(segment_stats, key=lambda s: s.irradiance)
+
+    # Per-ring summaries
+    ring_indices = sorted(set(s.ring_index for s in segment_stats))
+    per_ring = []
+    for ring_idx in ring_indices:
+        ring_segs = [s for s in segment_stats if s.ring_index == ring_idx]
+        per_ring.append(
+            {
+                "ring_index": ring_idx,
+                "n_segments": len(ring_segs),
+                "total_rays": sum(s.ray_count for s in ring_segs),
+                "total_intensity": sum(s.total_intensity for s in ring_segs),
+                "mean_irradiance": np.mean([s.irradiance for s in ring_segs]),
+            }
+        )
+
+    return {
+        "total_rays": total_rays,
+        "total_intensity": total_intensity,
+        "n_segments": len(segment_stats),
+        "peak_irradiance": peak_segment.irradiance,
+        "peak_segment": peak_segment,
+        "per_ring": per_ring,
+    }