Camera Module
=============

.. module:: mimic_data_api.camera

The camera module provides data structures for representing camera sensors,
including intrinsic parameters, distortion models, and captured image data.

Camera
------

.. autoclass:: Camera
   :members:
   :undoc-members:
   :show-inheritance:

.. note::

   ``Camera.trajectory.object2world`` contains camera-to-world poses. It is
   formed by composing the matching vehicle-to-world pose with
   ``Camera.extrinsics`` (camera-to-vehicle); it is not the raw ego trajectory.

CameraIntrinsics
----------------

.. autoclass:: CameraIntrinsics
   :members:
   :undoc-members:
   :show-inheritance:

   .. rubric:: Intrinsic Matrix

   The intrinsic matrix K is structured as:

   .. math::

       K = \begin{bmatrix}
           f_x & skew & c_x \\
           0 & f_y & c_y \\
           0 & 0 & 1
       \end{bmatrix}

DistortionParameters
--------------------

.. autoclass:: DistortionParameters
   :members:
   :undoc-members:
   :show-inheritance:

   .. rubric:: Distortion Model

   The standard OpenCV distortion model:

   .. math::

       x_{distorted} = x(1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + 2p_1 xy + p_2(r^2 + 2x^2)

   .. math::

       y_{distorted} = y(1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + p_1(r^2 + 2y^2) + 2p_2 xy

   where :math:`r^2 = x^2 + y^2`.

RollingShutterParameters
------------------------

.. autoclass:: RollingShutterParameters
   :members:
   :undoc-members:
   :show-inheritance:

ImageData
---------

.. autoclass:: ImageData
   :members:
   :undoc-members:
   :show-inheritance:

Camera Models
-------------

.. data:: CameraModels

   Supported camera projection models (aligned with COLMAP):

   - ``simple_pinhole``: Single focal length (fx = fy), no distortion
   - ``pinhole``: Separate fx, fy, no distortion
   - ``simple_radial``: Single focal length with k1 distortion
   - ``radial``: Single focal length with k1, k2 distortion
   - ``opencv``: Full OpenCV model (fx, fy, cx, cy, k1, k2, p1, p2)
   - ``opencv_fisheye``: OpenCV fisheye model
   - ``equirectangular``: 360° equirectangular projection
   - ``omnidirectionalstereo_l``: ODS left eye
   - ``omnidirectionalstereo_r``: ODS right eye
   - ``vr180_l``: VR180 left eye
   - ``vr180_r``: VR180 right eye
   - ``orthophoto``: Orthographic projection
   - ``fisheye624``: 6+2+4 parameter fisheye model

   See `COLMAP Camera Models <https://colmap.github.io/cameras.html>`_ for detailed documentation.