voxcity.simulator_gpu.visibility.geometry
=========================================

.. py:module:: voxcity.simulator_gpu.visibility.geometry

.. autoapi-nested-parse::

   Geometry utilities for view analysis.

   Provides ray direction generation using various sampling strategies:
   - Grid-based sampling (uniform azimuth x elevation grid)
   - Fibonacci spiral sampling (more uniform hemisphere coverage)



Classes
-------

.. toctree::
   :hidden:

   /autoapi/voxcity/simulator_gpu/visibility/geometry/RayDirectionField

.. autoapisummary::

   voxcity.simulator_gpu.visibility.geometry.RayDirectionField


Functions
---------

.. autoapisummary::

   voxcity.simulator_gpu.visibility.geometry.generate_ray_directions_grid
   voxcity.simulator_gpu.visibility.geometry.generate_ray_directions_fibonacci
   voxcity.simulator_gpu.visibility.geometry.generate_hemisphere_directions
   voxcity.simulator_gpu.visibility.geometry.rotate_vector_axis_angle
   voxcity.simulator_gpu.visibility.geometry.rotate_vector_axis_angle_ti
   voxcity.simulator_gpu.visibility.geometry.build_face_basis
   voxcity.simulator_gpu.visibility.geometry.build_face_basis_ti


Module Contents
---------------

.. py:function:: generate_ray_directions_grid(n_azimuth: int = 120, n_elevation: int = 20, elevation_min_degrees: float = -30.0, elevation_max_degrees: float = 30.0) -> numpy.ndarray

   Generate ray directions using a regular grid sampling.

   :param n_azimuth: Number of azimuthal divisions
   :param n_elevation: Number of elevation divisions
   :param elevation_min_degrees: Minimum elevation angle in degrees
   :param elevation_max_degrees: Maximum elevation angle in degrees

   :returns: Array of shape (n_azimuth * n_elevation, 3) with unit direction vectors


.. py:function:: generate_ray_directions_fibonacci(n_rays: int = 2400, elevation_min_degrees: float = -30.0, elevation_max_degrees: float = 30.0) -> numpy.ndarray

   Generate ray directions using Fibonacci spiral sampling.

   This provides more uniform coverage of the hemisphere compared to grid sampling.

   :param n_rays: Total number of rays
   :param elevation_min_degrees: Minimum elevation angle in degrees
   :param elevation_max_degrees: Maximum elevation angle in degrees

   :returns: Array of shape (n_rays, 3) with unit direction vectors


.. py:function:: generate_hemisphere_directions(n_azimuth: int = 80, n_elevation: int = 40) -> numpy.ndarray

   Generate ray directions covering the upper hemisphere.

   Elevation goes from 0 (horizon) to 90 (zenith).

   :param n_azimuth: Number of azimuthal divisions
   :param n_elevation: Number of elevation divisions

   :returns: Array of shape (n_azimuth * n_elevation, 3) with unit direction vectors


.. py:function:: rotate_vector_axis_angle(vec: numpy.ndarray, axis: numpy.ndarray, angle: float) -> numpy.ndarray

   Rotate a vector around an axis by a specified angle using Rodrigues' rotation formula.

   This is a CPU implementation matching voxcity.simulator.common.geometry.rotate_vector_axis_angle.

   :param vec: Vector to rotate (3,)
   :param axis: Rotation axis (3,) - will be normalized
   :param angle: Rotation angle in radians

   :returns: Rotated vector (3,)


.. py:function:: rotate_vector_axis_angle_ti(vec: ti.template(), axis: ti.template(), angle: taichi.f32) -> ti.template()

   Taichi GPU kernel function for rotating a vector around an axis.

   Uses Rodrigues' rotation formula.

   :param vec: Vector to rotate (Vector3)
   :param axis: Rotation axis (Vector3) - will be normalized
   :param angle: Rotation angle in radians

   :returns: Rotated Vector3


.. py:function:: build_face_basis(normal: numpy.ndarray) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Build orthonormal basis (u, v, n) for a surface normal.

   Matches voxcity.simulator.common.geometry._build_face_basis.

   :param normal: Surface normal vector (3,)

   :returns: Tuple of (u, v, n) orthonormal vectors


.. py:function:: build_face_basis_ti(normal: ti.template()) -> ti.template()

   Taichi GPU kernel function to build orthonormal basis for a surface normal.

   :param normal: Surface normal Vector3

   :returns: Tuple of (u, v, n) orthonormal Vector3s