voxcity.simulator_gpu.core
==========================

.. py:module:: voxcity.simulator_gpu.core

.. autoapi-nested-parse::

   Shared core utilities for simulator_gpu.

   Vector and ray utilities using Taichi for GPU acceleration.
   Based on ray-tracing-one-weekend-taichi patterns.

   GPU Optimization Notes:
   - All functions use @ti.func for GPU inlining
   - Branchless operations preferred where possible
   - Memory coalescing friendly access patterns
   - done-flag pattern for early termination (reduces warp divergence)



Attributes
----------

.. autoapisummary::

   voxcity.simulator_gpu.core.Vector3
   voxcity.simulator_gpu.core.Point3
   voxcity.simulator_gpu.core.Color3
   voxcity.simulator_gpu.core.PI
   voxcity.simulator_gpu.core.TWO_PI
   voxcity.simulator_gpu.core.HALF_PI
   voxcity.simulator_gpu.core.DEG_TO_RAD
   voxcity.simulator_gpu.core.RAD_TO_DEG
   voxcity.simulator_gpu.core.SOLAR_CONSTANT
   voxcity.simulator_gpu.core.EXT_COEF
   voxcity.simulator_gpu.core.MIN_STABLE_COSZEN
   voxcity.simulator_gpu.core.GPU_BLOCK_SIZE


Classes
-------

.. toctree::
   :hidden:

   /autoapi/voxcity/simulator_gpu/core/Rays
   /autoapi/voxcity/simulator_gpu/core/HitRecord

.. autoapisummary::

   voxcity.simulator_gpu.core.Rays
   voxcity.simulator_gpu.core.HitRecord


Functions
---------

.. autoapisummary::

   voxcity.simulator_gpu.core.normalize
   voxcity.simulator_gpu.core.normalize_safe
   voxcity.simulator_gpu.core.dot
   voxcity.simulator_gpu.core.cross
   voxcity.simulator_gpu.core.reflect
   voxcity.simulator_gpu.core.ray_at
   voxcity.simulator_gpu.core.length_squared
   voxcity.simulator_gpu.core.distance_squared
   voxcity.simulator_gpu.core.min3
   voxcity.simulator_gpu.core.max3
   voxcity.simulator_gpu.core.clamp
   voxcity.simulator_gpu.core.random_in_unit_sphere
   voxcity.simulator_gpu.core.random_in_hemisphere
   voxcity.simulator_gpu.core.random_cosine_hemisphere
   voxcity.simulator_gpu.core.spherical_to_cartesian
   voxcity.simulator_gpu.core.cartesian_to_spherical
   voxcity.simulator_gpu.core.rotate_vector_axis_angle
   voxcity.simulator_gpu.core.build_face_basis


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

.. py:data:: Vector3

.. py:data:: Point3

.. py:data:: Color3

.. py:data:: PI
   :value: 3.141592653589793


.. py:data:: TWO_PI
   :value: 6.283185307179586


.. py:data:: HALF_PI
   :value: 1.5707963267948966


.. py:data:: DEG_TO_RAD
   :value: 0.017453292519943295


.. py:data:: RAD_TO_DEG
   :value: 57.29577951308232


.. py:data:: SOLAR_CONSTANT
   :value: 1361.0


.. py:data:: EXT_COEF
   :value: 0.6


.. py:data:: MIN_STABLE_COSZEN
   :value: 0.0262


.. py:data:: GPU_BLOCK_SIZE
   :value: 256


.. py:function:: normalize(v: Vector3) -> Vector3

   Normalize a vector.


.. py:function:: normalize_safe(v: Vector3) -> Vector3

   Normalize a vector with safety check for zero-length.


.. py:function:: dot(v1: Vector3, v2: Vector3) -> taichi.f32

   Dot product of two vectors.


.. py:function:: cross(v1: Vector3, v2: Vector3) -> Vector3

   Cross product of two vectors.


.. py:function:: reflect(v: Vector3, n: Vector3) -> Vector3

   Reflect vector v around normal n.


.. py:function:: ray_at(origin: Point3, direction: Vector3, t: taichi.f32) -> Point3

   Get point along ray at parameter t.


.. py:function:: length_squared(v: Vector3) -> taichi.f32

   Compute squared length of vector (avoids sqrt).


.. py:function:: distance_squared(p1: Point3, p2: Point3) -> taichi.f32

   Compute squared distance between two points (avoids sqrt).


.. py:function:: min3(a: taichi.f32, b: taichi.f32, c: taichi.f32) -> taichi.f32

   Branchless minimum of three values.


.. py:function:: max3(a: taichi.f32, b: taichi.f32, c: taichi.f32) -> taichi.f32

   Branchless maximum of three values.


.. py:function:: clamp(x: taichi.f32, lo: taichi.f32, hi: taichi.f32) -> taichi.f32

   Clamp value to range [lo, hi].


.. py:function:: random_in_unit_sphere() -> Vector3

   Generate random point in unit sphere.


.. py:function:: random_in_hemisphere(normal: Vector3) -> Vector3

   Generate random vector in hemisphere around normal.


.. py:function:: random_cosine_hemisphere(normal: Vector3) -> Vector3

   Generate random vector with cosine-weighted distribution in hemisphere.
   Used for diffuse radiation sampling.


.. py:function:: spherical_to_cartesian(azimuth: taichi.f32, elevation: taichi.f32) -> Vector3

   Convert spherical coordinates to Cartesian unit vector.

   :param azimuth: Angle from north (y-axis), clockwise, in radians
   :param elevation: Angle from horizontal, in radians (0 = horizontal, pi/2 = zenith)

   :returns: Unit vector (x, y, z) where z is vertical (up)


.. py:function:: cartesian_to_spherical(v: Vector3) -> taichi.math.vec2

   Convert Cartesian unit vector to spherical coordinates.

   :returns: vec2(azimuth, elevation) in radians


.. py:function:: rotate_vector_axis_angle(vec: Vector3, axis: Vector3, angle: taichi.f32) -> Vector3

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

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

   :returns: Rotated vector


.. py:function:: build_face_basis(normal: Vector3)

   Build orthonormal basis for a face with given normal.

   :returns: Tuple of (tangent, bitangent, normal) vectors