Back

BaseCamera

sofa::component::visual::BaseCamera
BaseObject
Abstract (AI generated)

The `BaseCamera` component defines fundamental camera properties such as position, orientation, field of view, and clipping planes in the SOFA framework.

Metadata
module
Sofa.Component.Visual
namespace
sofa::component::visual
include
sofa/component/visual/BaseCamera.h
inherits
  • BaseObject
description

Mathematical and Physical Description of BaseCamera Component

Position and Orientation

The BaseCamera in the SOFA framework is fundamentally defined by its position (d_position) and orientation (d_orientation). The position is a vector $ extbf{p} = (x, y, z) $ that indicates where the camera is located in 3D space. Orientation is represented using a quaternion $ q = (w, x, y, z) $, which allows for efficient and numerically stable rotations without gimbal lock.

Quaternion Representation of Orientation

A quaternion $ q $ can be decomposed as:

$$ q = w + xi + yj + zk $$

where $ i^2 = j^2 = k^2 = ijk = -1 $. The rotation matrix $ R $ corresponding to this quaternion is given by:

$$ R(q) = \begin{bmatrix} 1-2(y^2+z^2) & 2(xy-wz) & 2(xz+wy) \\ 2(xy+wz) & 1-2(x^2+z^2) & 2(yz-wx) \\ 2(xz-wy) & 2(yz+wx) & 1-2(x^2+y^2) \end{bmatrix} $$

The rotation matrix $ R(q) $ can then be used to transform vectors from the camera's local coordinate system to the world coordinate system.

Look At Point and Distance

The BaseCamera also has a look-at point (d_lookAt) which defines where the camera is directed. The distance between the camera position and this point is stored in d_distance. Given the current position $ extbf{p} = (x, y, z) $ and look-at point $ extbf{l} = (l_x, l_y, l_z) $, the distance can be computed as:

$$ d_{distance} = || extbf{l} - extbf{p}|| = \sqrt{(l_x - x)^2 + (l_y - y)^2 + (l_z - z)^2} $$

Field of View and Projection Matrices

The camera has a field of view (d_fieldOfView) which defines the extent of the visible scene in degrees. The projection matrix depends on whether it is an orthographic or perspective projection.

Orthographic Projection Matrix

For an orthographic projection, the projection matrix $ P_{ortho} $ can be defined as:

$$ P_{ortho} = \begin{bmatrix} 1/(r-l) & 0 & 0 & -(r+l)/(2(r-l)) \\ 0 & 1/(t-b) & 0 & -(t+b)/(2(t-b)) \\ 0 & 0 & -2/(f-n) & -(f+n)/(2(f-n)) \\ 0 & 0 & 0 & 1 \end{bmatrix} $$

where $ l, r, t, b $ are the left, right, top, and bottom clipping planes respectively, and $ n, f $ are the near and far clipping planes.

Perspective Projection Matrix

For a perspective projection, the matrix is given by:

$$ P_{persp} = \begin{bmatrix} 1/ an(fovy/2) & 0 & 0 & 0 \\ 0 & 1/h & 0 & 0 \\ 0 & 0 & -(f+n)/(f-n) & -2fn/(f-n) \\ 0 & 0 & -1 & 0 \end{bmatrix} $$

where $ fovy $ is the vertical field of view in radians, and $ h $ is the aspect ratio (width/height).

Clipping Planes

Near (d_zNear) and far (d_zFar) clipping planes define the range of distances from the camera where objects are rendered. Anything closer than zNear or farther than zFar will not be visible.

Automatic Z-Clip Plane Computation

If d_computeZClip is true, the near and far clipping planes can be automatically computed based on the bounding box of the scene defined by its minimum (d_minBBox) and maximum (d_maxBBox) points. The center $ C $ and radius $ R $ of the scene are:

$$ C = (d_{minBBox} + d_{maxBBox})/2 $$ $$ R = ||d_{maxBBox} - d_{minBBox}|| / 2 $$

The near and far clipping planes can then be set to a reasonable distance around the scene:

$$ z_{Near} = C_z - R \times k_1 $$ $$ z_{Far} = C_z + R \times k_2 $$

where $ k_1, k_2 $ are scaling factors.

Viewport Dimensions and Aspect Ratio

The viewport dimensions (d_widthViewport, d_heightViewport) define the size of the render target. The aspect ratio ($ A = width/height $) is used in perspective projection matrices to maintain correct proportions when changing window sizes.

Scene Bounding Box Fit

Methods like fitSphere() and fitBoundingBox() adjust camera parameters so that the entire scene or specified sphere/boundingBox is visible within the defined field of view. These methods typically update position, orientation, and distance based on the bounding box dimensions to ensure all relevant objects are included in the rendered image.

Ray Casting

The method toRay() converts a screen point (usually mouse cursor position) into a ray in world coordinates for picking or other interactive purposes. Given a normalized viewport coordinate $ (u, v) $, the corresponding ray in camera space can be computed and transformed to world space using the inverse of the model-view matrix.

Conclusion

The BaseCamera component provides foundational functionality for defining and manipulating cameras within 3D environments, utilizing mathematical concepts such as vectors, quaternions, matrices, and projection transformations. Its design supports both orthographic and perspective projections with configurable parameters to control field of view, clipping planes, and viewport dimensions.

Data Fields
NameTypeDefaultHelp
d_position type::Vec3 Camera's position
d_orientation Quat Camera's orientation
d_lookAt type::Vec3 Camera's look at
d_distance double Distance between camera and look at
d_fieldOfView double Camera's FOV
d_zNear double Camera's zNear
d_zFar double Camera's zFar
d_computeZClip bool Compute Z clip planes (Near and Far) according to the bounding box
d_minBBox type::Vec3 minBBox
d_maxBBox type::Vec3 maxBBox
d_widthViewport unsigned int widthViewport
d_heightViewport unsigned int heightViewport
d_type sofa::helper::OptionsGroup Camera Type (0 = Perspective, 1 = Orthographic)
d_activated bool Camera activated ?
d_fixedLookAtPoint bool keep the lookAt point always fixed
Methods
void init () virtual
void reinit () virtual
void bwdInit () virtual
void activate ()
void desactivate ()
bool isActivated ()
bool exportParametersInFile (const int & viewFilename)
bool importParametersFromFile (const int & viewFilename)
void translate (const type::Vec3 & t)
void translateLookAt (const type::Vec3 & t)
void rotate (const Quat & r)
void moveCamera (const type::Vec3 & p, const Quat & q)
void rotateCameraAroundPoint (Quat & rotation, const type::Vec3 & point)
void rotateWorldAroundPoint (Quat & rotation, const type::Vec3 & point, Quat orientationCam) virtual
void rotateWorldAroundPoint (Quat & rotation, const type::Vec3 & point, Quat orientationCam, type::Vec3 positionCam) virtual
type::Vec3 screenToViewportPoint (const type::Vec3 & p)
type::Vec3 screenToWorldPoint (const type::Vec3 & p)
type::Vec3 viewportToScreenPoint (const type::Vec3 & p)
type::Vec3 viewportToWorldPoint (const type::Vec3 & p)
type::Vec3 worldToScreenPoint (const type::Vec3 & p)
type::Vec3 worldToViewportPoint (const type::Vec3 & p)
type::Ray viewportPointToRay (const type::Vec3 & p)
type::Ray screenPointToRay (const type::Vec3 & p)
type::Ray toRay ()
type::Vec3 cameraToWorldCoordinates (const type::Vec3 & p)
type::Vec3 worldToCameraCoordinates (const type::Vec3 & p)
type::Vec3 cameraToWorldTransform (const type::Vec3 & v)
type::Vec3 worldToCameraTransform (const type::Vec3 & v)
type::Vec3 screenToWorldCoordinates (int x, int y)
type::Vec2 worldToScreenCoordinates (const type::Vec3 & p)
void fitSphere (const type::Vec3 & center, SReal radius)
void fitBoundingBox (const type::Vec3 & min, const type::Vec3 & max)
type::Vec3 getPosition ()
Quat getOrientation ()
type::Vec3 getLookAt ()
double getDistance ()
double getFieldOfView ()
double getHorizontalFieldOfView ()
unsigned int getCameraType ()
void setCameraType (unsigned int type)
void setBoundingBox (const type::Vec3 & min, const type::Vec3 & max)
void setViewport (unsigned int w, unsigned int h)
double getZNear ()
double getZFar ()
void setView (const type::Vec3 & position, const Quat & orientation)
void setDefaultView (const type::Vec3 & gravity)
void getModelViewMatrix (double[16] mat) virtual
void getProjectionMatrix (double[16] mat) virtual
void getOpenGLModelViewMatrix (double[16] mat)
void getOpenGLProjectionMatrix (double[16] mat)
Quat getOrientationFromLookAt (const type::Vec3 & pos, const type::Vec3 & lookat)
type::Vec3 getLookAtFromOrientation (const type::Vec3 & pos, const double & distance, const Quat & orientation)
type::Vec3 getPositionFromOrientation (const type::Vec3 & lookAt, const double & distance, const Quat & orientation)
void manageEvent (core::objectmodel::Event * event) virtual
void internalUpdate () virtual
void handleEvent (sofa::core::objectmodel::Event * event) virtual
void computeZ ()
bool isStereo () virtual
void setCurrentSide (Side ) virtual
Side getCurrentSide () virtual
void setStereoEnabled (bool ) virtual
bool getStereoEnabled () virtual
void setStereoMode (StereoMode ) virtual
StereoMode getStereoMode () virtual
void setStereoStrategy (StereoStrategy ) virtual
StereoStrategy getStereoStrategy () virtual
void setStereoShift (double ) virtual
double getStereoShift () virtual
void draw (const core::visual::VisualParams * ) virtual
void computeClippingPlane (const core::visual::VisualParams * vp, double & zNear, double & zFar)
void drawCamera (const core::visual::VisualParams * ) virtual
void updateOutputData () 
{
  "name": "BaseCamera",
  "namespace": "sofa::component::visual",
  "module": "Sofa.Component.Visual",
  "include": "sofa/component/visual/BaseCamera.h",
  "doc": "",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_position",
      "type": "type::Vec3",
      "xmlname": "position",
      "help": "Camera's position"
    },
    {
      "name": "d_orientation",
      "type": "Quat",
      "xmlname": "orientation",
      "help": "Camera's orientation"
    },
    {
      "name": "d_lookAt",
      "type": "type::Vec3",
      "xmlname": "lookAt",
      "help": "Camera's look at"
    },
    {
      "name": "d_distance",
      "type": "double",
      "xmlname": "distance",
      "help": "Distance between camera and look at"
    },
    {
      "name": "d_fieldOfView",
      "type": "double",
      "xmlname": "fieldOfView",
      "help": "Camera's FOV"
    },
    {
      "name": "d_zNear",
      "type": "double",
      "xmlname": "zNear",
      "help": "Camera's zNear"
    },
    {
      "name": "d_zFar",
      "type": "double",
      "xmlname": "zFar",
      "help": "Camera's zFar"
    },
    {
      "name": "d_computeZClip",
      "type": "bool",
      "xmlname": "computeZClip",
      "help": "Compute Z clip planes (Near and Far) according to the bounding box"
    },
    {
      "name": "d_minBBox",
      "type": "type::Vec3",
      "xmlname": "minBBox",
      "help": "minBBox"
    },
    {
      "name": "d_maxBBox",
      "type": "type::Vec3",
      "xmlname": "maxBBox",
      "help": "maxBBox"
    },
    {
      "name": "d_widthViewport",
      "type": "unsigned int",
      "xmlname": "widthViewport",
      "help": "widthViewport"
    },
    {
      "name": "d_heightViewport",
      "type": "unsigned int",
      "xmlname": "heightViewport",
      "help": "heightViewport"
    },
    {
      "name": "d_type",
      "type": "sofa::helper::OptionsGroup",
      "xmlname": "projectionType",
      "help": "Camera Type (0 = Perspective, 1 = Orthographic)"
    },
    {
      "name": "d_activated",
      "type": "bool",
      "xmlname": "activated",
      "help": "Camera activated ?"
    },
    {
      "name": "d_fixedLookAtPoint",
      "type": "bool",
      "xmlname": "fixedLookAt",
      "help": "keep the lookAt point always fixed"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdInit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "activate",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "desactivate",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isActivated",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "exportParametersInFile",
      "return_type": "bool",
      "params": [
        {
          "name": "viewFilename",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "importParametersFromFile",
      "return_type": "bool",
      "params": [
        {
          "name": "viewFilename",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "translate",
      "return_type": "void",
      "params": [
        {
          "name": "t",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "translateLookAt",
      "return_type": "void",
      "params": [
        {
          "name": "t",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "rotate",
      "return_type": "void",
      "params": [
        {
          "name": "r",
          "type": "const Quat &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "moveCamera",
      "return_type": "void",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        },
        {
          "name": "q",
          "type": "const Quat &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "rotateCameraAroundPoint",
      "return_type": "void",
      "params": [
        {
          "name": "rotation",
          "type": "Quat &"
        },
        {
          "name": "point",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "rotateWorldAroundPoint",
      "return_type": "void",
      "params": [
        {
          "name": "rotation",
          "type": "Quat &"
        },
        {
          "name": "point",
          "type": "const type::Vec3 &"
        },
        {
          "name": "orientationCam",
          "type": "Quat"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "rotateWorldAroundPoint",
      "return_type": "void",
      "params": [
        {
          "name": "rotation",
          "type": "Quat &"
        },
        {
          "name": "point",
          "type": "const type::Vec3 &"
        },
        {
          "name": "orientationCam",
          "type": "Quat"
        },
        {
          "name": "positionCam",
          "type": "type::Vec3"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "screenToViewportPoint",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "screenToWorldPoint",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "viewportToScreenPoint",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "viewportToWorldPoint",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "worldToScreenPoint",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "worldToViewportPoint",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "viewportPointToRay",
      "return_type": "type::Ray",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "screenPointToRay",
      "return_type": "type::Ray",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "toRay",
      "return_type": "type::Ray",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "cameraToWorldCoordinates",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "worldToCameraCoordinates",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "cameraToWorldTransform",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "v",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "worldToCameraTransform",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "v",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "screenToWorldCoordinates",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "x",
          "type": "int"
        },
        {
          "name": "y",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "worldToScreenCoordinates",
      "return_type": "type::Vec2",
      "params": [
        {
          "name": "p",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fitSphere",
      "return_type": "void",
      "params": [
        {
          "name": "center",
          "type": "const type::Vec3 &"
        },
        {
          "name": "radius",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fitBoundingBox",
      "return_type": "void",
      "params": [
        {
          "name": "min",
          "type": "const type::Vec3 &"
        },
        {
          "name": "max",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPosition",
      "return_type": "type::Vec3",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getOrientation",
      "return_type": "Quat",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getLookAt",
      "return_type": "type::Vec3",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDistance",
      "return_type": "double",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFieldOfView",
      "return_type": "double",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getHorizontalFieldOfView",
      "return_type": "double",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCameraType",
      "return_type": "unsigned int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setCameraType",
      "return_type": "void",
      "params": [
        {
          "name": "type",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setBoundingBox",
      "return_type": "void",
      "params": [
        {
          "name": "min",
          "type": "const type::Vec3 &"
        },
        {
          "name": "max",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setViewport",
      "return_type": "void",
      "params": [
        {
          "name": "w",
          "type": "unsigned int"
        },
        {
          "name": "h",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getZNear",
      "return_type": "double",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getZFar",
      "return_type": "double",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setView",
      "return_type": "void",
      "params": [
        {
          "name": "position",
          "type": "const type::Vec3 &"
        },
        {
          "name": "orientation",
          "type": "const Quat &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDefaultView",
      "return_type": "void",
      "params": [
        {
          "name": "gravity",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getModelViewMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mat",
          "type": "double[16]"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getProjectionMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mat",
          "type": "double[16]"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getOpenGLModelViewMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mat",
          "type": "double[16]"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getOpenGLProjectionMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mat",
          "type": "double[16]"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getOrientationFromLookAt",
      "return_type": "Quat",
      "params": [
        {
          "name": "pos",
          "type": "const type::Vec3 &"
        },
        {
          "name": "lookat",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getLookAtFromOrientation",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "pos",
          "type": "const type::Vec3 &"
        },
        {
          "name": "distance",
          "type": "const double &"
        },
        {
          "name": "orientation",
          "type": "const Quat &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPositionFromOrientation",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "lookAt",
          "type": "const type::Vec3 &"
        },
        {
          "name": "distance",
          "type": "const double &"
        },
        {
          "name": "orientation",
          "type": "const Quat &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "manageEvent",
      "return_type": "void",
      "params": [
        {
          "name": "event",
          "type": "core::objectmodel::Event *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "internalUpdate",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleEvent",
      "return_type": "void",
      "params": [
        {
          "name": "event",
          "type": "sofa::core::objectmodel::Event *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeZ",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isStereo",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setCurrentSide",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "Side"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCurrentSide",
      "return_type": "Side",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setStereoEnabled",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStereoEnabled",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setStereoMode",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "StereoMode"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStereoMode",
      "return_type": "StereoMode",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setStereoStrategy",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "StereoStrategy"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStereoStrategy",
      "return_type": "StereoStrategy",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setStereoShift",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "double"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStereoShift",
      "return_type": "double",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeClippingPlane",
      "return_type": "void",
      "params": [
        {
          "name": "vp",
          "type": "const core::visual::VisualParams *"
        },
        {
          "name": "zNear",
          "type": "double &"
        },
        {
          "name": "zFar",
          "type": "double &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "drawCamera",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateOutputData",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "title": "BaseCamera Component Documentation",
  "description": "**Overview**\n\nThe BaseCamera component serves as an abstract base class for defining various types of cameras in the SOFA (Simulation Open Framework Architecture) framework. It provides fundamental functionalities and properties common to all camera objects, such as position, orientation, field of view, near/far clipping planes, and viewport dimensions.\n\n**Properties & Data Members**\n\n- **Position**: `Data<type::Vec3> d_position` - Stores the 3D position of the camera in world coordinates.\n- **Orientation**: `Data<Quat> d_orientation` - Represents the orientation (rotation) of the camera using a quaternion.\n- **Look At Point**: `Data<type::Vec3> d_lookAt` - Indicates where the camera is looking at, specified by a 3D point in world coordinates.\n- **Distance to Look At**: `Data<double> d_distance` - Distance between the camera's position and its look-at point.\n- **Field of View (FOV)**: `Data<double> d_fieldOfView` - Defines the vertical field of view angle for the camera, typically used in perspective projection cameras.\n- **Near Clipping Plane**: `Data<double> d_zNear` - Distance to the near clipping plane from the viewer's position; anything closer will not be rendered.\n- **Far Clipping Plane**: `Data<double> d_zFar` - Distance to the far clipping plane from the viewer's position; objects beyond this distance are not visible.\n- **Compute Z Clip Planes**: `Data<bool> d_computeZClip` - Boolean flag that, when true, automatically computes near and far clipping planes based on the scene’s bounding box.\n- **Bounding Box Min/Max Points**: `Data<type::Vec3> d_minBBox`, `d_maxBBox` - Minimum and maximum points of the scene's bounding box used for automatic camera positioning or zooming.\n- **Viewport Dimensions**: `Data<unsigned int> d_widthViewport, d_heightViewport` - Width and height of the viewport (render target).\n- **Camera Type**: `Data<sofa::helper::OptionsGroup> d_type` - Enumerates different types of cameras such as Perspective or Orthographic.\n- **Activation Flag**: `Data<bool> d_activated` - Controls whether the camera is active and participates in rendering.\n\n**Initialization & Activation Methods**\n\n- `init()`: Called during initialization to set up default properties and configurations.\n- `reinit()`: Allows reinitialization after changes to scene or settings have been made.\n- `activate()`, `desactivate()` - Methods for turning the camera on/off, which also sets/unsets the d_activated Data member accordingly.\n\n**Camera Transformations & Conversions**\n\nThe BaseCamera provides several methods for converting between screen coordinates (pixels), viewport coordinates (normalized [0.0, 1.0]), and world coordinates (3D space). It supports common operations such as translation (`translate()`, `translateLookAt()`), rotation (`rotate()`, `rotateWorldAroundPoint()`), setting camera position/orientation with `setView()`, and fitting the view to a specified sphere or bounding box using `fitSphere()`, `fitBoundingBox()`. The `toRay()` method converts screen points into 3D rays in world space, useful for mouse picking or similar interactions.\n\n**Matrix Extraction & OpenGL Compatibility**\n\nThe component can output its model-view matrix and projection matrix as 16-element arrays of doubles, suitable for use with OpenGL. Methods like `getModelViewMatrix()`, `getProjectionMatrix()` retrieve these matrices in a format ready to be passed directly to shaders or rendering pipelines.\n\n**Customization & Stereoscopic Support**\n\nDerived classes can override the `manageEvent()` method to handle custom events and implement specific behavior based on input devices, application logic, etc. The BaseCamera also supports stereoscopic rendering through properties like stereo mode (`get/setStereoMode`), strategy (`get/setStereoStrategy`), and shift value (`get/setStereoShift`).\n\n**Drawing & Debugging**\n\nThe component provides a `draw()` method for visualizing the camera's view frustum or other elements in the scene, useful for debugging purposes. A virtual `drawCamera()` method is intended to be overridden by derived classes to provide class-specific visualization.\n",
  "tags": [
    "Base Camera",
    "SOFA Component",
    "3D Rendering",
    "OpenGL Integration",
    "Stereo Vision"
  ],
  "examples": [],
  "see_also": [],
  "source_code_links": [
    {
      "url": "./src/engine/BaseCamera.h"
    }
  ],
  "maths": "# Mathematical and Physical Description of BaseCamera Component\n\n## Position and Orientation\n\nThe `BaseCamera` in the SOFA framework is fundamentally defined by its position (`d_position`) and orientation (`d_orientation`). The position is a vector \\( \textbf{p} = (x, y, z) \\) that indicates where the camera is located in 3D space. Orientation is represented using a quaternion \\( q = (w, x, y, z) \\), which allows for efficient and numerically stable rotations without gimbal lock.\n\n### Quaternion Representation of Orientation\nA quaternion \\( q \\) can be decomposed as:\n\\[ q = w + xi + yj + zk \\]\nwhere \\( i^2 = j^2 = k^2 = ijk = -1 \\). The rotation matrix \\( R \\) corresponding to this quaternion is given by:\n\\[\nR(q) = \n\\begin{bmatrix}\n    1-2(y^2+z^2) & 2(xy-wz)     & 2(xz+wy)      \\\\\n    2(xy+wz)       & 1-2(x^2+z^2) & 2(yz-wx)      \\\\\n    2(xz-wy)       & 2(yz+wx)     & 1-2(x^2+y^2)\n\\end{bmatrix}\n\\]\nThe rotation matrix \\( R(q) \\) can then be used to transform vectors from the camera's local coordinate system to the world coordinate system.\n\n## Look At Point and Distance\nThe `BaseCamera` also has a look-at point (`d_lookAt`) which defines where the camera is directed. The distance between the camera position and this point is stored in `d_distance`. Given the current position \\( \textbf{p} = (x, y, z) \\) and look-at point \\( \textbf{l} = (l_x, l_y, l_z) \\), the distance can be computed as:\n\\[\nd_{distance} = ||\textbf{l} - \textbf{p}|| = \n\\sqrt{(l_x - x)^2 + (l_y - y)^2 + (l_z - z)^2}\n\\]\n\n## Field of View and Projection Matrices\nThe camera has a field of view (`d_fieldOfView`) which defines the extent of the visible scene in degrees. The projection matrix depends on whether it is an orthographic or perspective projection.\n\n### Orthographic Projection Matrix\nFor an orthographic projection, the projection matrix \\( P_{ortho} \\) can be defined as:\n\\[\nP_{ortho} = \n\\begin{bmatrix}\n    1/(r-l) & 0          & 0        & -(r+l)/(2(r-l)) \\\\\n    0       & 1/(t-b)   & 0        & -(t+b)/(2(t-b)) \\\\\n    0       & 0          & -2/(f-n) & -(f+n)/(2(f-n)) \\\\\n    0       & 0          & 0        & 1\n\\end{bmatrix}\n\\]\nwhere \\( l, r, t, b \\) are the left, right, top, and bottom clipping planes respectively, and \\( n, f \\) are the near and far clipping planes.\n\n### Perspective Projection Matrix\nFor a perspective projection, the matrix is given by:\n\\[\nP_{persp} = \n\\begin{bmatrix}\n    1/\tan(fovy/2) & 0      & 0             & 0 \\\\\n    0              & 1/h   & 0             & 0 \\\\\n    0              & 0      & -(f+n)/(f-n)  & -2fn/(f-n) \\\\\n    0              & 0      & -1            & 0\n\\end{bmatrix}\n\\]\nwhere \\( fovy \\) is the vertical field of view in radians, and \\( h \\) is the aspect ratio (width/height).\n\n## Clipping Planes\nNear (`d_zNear`) and far (`d_zFar`) clipping planes define the range of distances from the camera where objects are rendered. Anything closer than `zNear` or farther than `zFar` will not be visible.\n\n### Automatic Z-Clip Plane Computation\nIf `d_computeZClip` is true, the near and far clipping planes can be automatically computed based on the bounding box of the scene defined by its minimum (`d_minBBox`) and maximum (`d_maxBBox`) points. The center \\( C \\) and radius \\( R \\) of the scene are:\n\\[\nC = (d_{minBBox} + d_{maxBBox})/2\n\\]\n\\[\nR = ||d_{maxBBox} - d_{minBBox}|| / 2\n\\]\nThe near and far clipping planes can then be set to a reasonable distance around the scene:\n\\[ z_{Near} = C_z - R \\times k_1 \\]\n\\[ z_{Far} = C_z + R \\times k_2 \\]\nwhere \\( k_1, k_2 \\) are scaling factors.\n\n## Viewport Dimensions and Aspect Ratio\nThe viewport dimensions (`d_widthViewport`, `d_heightViewport`) define the size of the render target. The aspect ratio (\\( A = width/height \\)) is used in perspective projection matrices to maintain correct proportions when changing window sizes.\n\n### Scene Bounding Box Fit\nMethods like `fitSphere()` and `fitBoundingBox()` adjust camera parameters so that the entire scene or specified sphere/boundingBox is visible within the defined field of view. These methods typically update position, orientation, and distance based on the bounding box dimensions to ensure all relevant objects are included in the rendered image.\n\n## Ray Casting\nThe method `toRay()` converts a screen point (usually mouse cursor position) into a ray in world coordinates for picking or other interactive purposes. Given a normalized viewport coordinate \\( (u, v) \\), the corresponding ray in camera space can be computed and transformed to world space using the inverse of the model-view matrix.\n\n## Conclusion\nThe `BaseCamera` component provides foundational functionality for defining and manipulating cameras within 3D environments, utilizing mathematical concepts such as vectors, quaternions, matrices, and projection transformations. Its design supports both orthographic and perspective projections with configurable parameters to control field of view, clipping planes, and viewport dimensions.",
  "abstract": "The `BaseCamera` component defines fundamental camera properties such as position, orientation, field of view, and clipping planes in the SOFA framework.",
  "sheet": "# BaseCamera\n\n## Overview\n\nThe `BaseCamera` is an abstract base class for defining various types of cameras within the SOFA framework. It provides essential functionalities including position (`d_position`), orientation (`d_orientation`), field of view (`d_fieldOfView`), near and far clipping planes (`d_zNear`, `d_zFar`), and viewport dimensions (`d_widthViewport`, `d_heightViewport`). The component supports both perspective and orthographic projections.\n\n## Parameters and Data\n\nThe significant data fields exposed by the `BaseCamera` include:\n\n- **Position**: `Data<type::Vec3> d_position` - Stores the 3D position of the camera in world coordinates.\n- **Orientation**: `Data<Quat> d_orientation` - Represents the orientation (rotation) of the camera using a quaternion.\n- **Look At Point**: `Data<type::Vec3> d_lookAt` - Indicates where the camera is looking at, specified by a 3D point in world coordinates.\n- **Distance to Look At**: `Data<double> d_distance` - Distance between the camera's position and its look-at point.\n- **Field of View (FOV)**: `Data<double> d_fieldOfView` - Defines the vertical field of view angle for the camera, typically used in perspective projection cameras.\n- **Near Clipping Plane**: `Data<double> d_zNear` - Distance to the near clipping plane from the viewer's position; anything closer will not be rendered.\n- **Far Clipping Plane**: `Data<double> d_zFar` - Distance to the far clipping plane from the viewer's position; objects beyond this distance are not visible.\n- **Compute Z Clip Planes**: `Data<bool> d_computeZClip` - Boolean flag that, when true, automatically computes near and far clipping planes based on the scene’s bounding box.\n- **Bounding Box Min/Max Points**: `Data<type::Vec3> d_minBBox`, `d_maxBBox` - Minimum and maximum points of the scene's bounding box used for automatic camera positioning or zooming.\n- **Viewport Dimensions**: `Data<unsigned int> d_widthViewport, d_heightViewport` - Width and height of the viewport (render target).\n- **Camera Type**: `Data<sofa::helper::OptionsGroup> d_type` - Enumerates different types of cameras such as Perspective or Orthographic.\n- **Activation Flag**: `Data<bool> d_activated` - Controls whether the camera is active and participates in rendering.\n\n## Mathematical Model\n\n### Position and Orientation\n\nThe position of the camera is defined by a vector \\(\\mathbf{p} = (x, y, z)\\). The orientation is represented using a quaternion \\(q = w + xi + yj + zk\\), which can be decomposed into a rotation matrix \\(R(q)\\):\n\n\begin{equation*}\n    R(q) = \n    \\begin{bmatrix}\n        1-2(y^2+z^2) & 2(xy-wz)     & 2(xz+wy)      \\\\\n        2(xy+wz)       & 1-2(x^2+z^2) & 2(yz-wx)      \\\\\n        2(xz-wy)       & 2(yz+wx)     & 1-2(x^2+y^2)\n    \\end{bmatrix}\n\\end{equation*}\n\n### Look At Point and Distance\n\nThe distance between the camera position \\(\\mathbf{p} = (x, y, z)\\) and the look-at point \\(\\mathbf{l} = (l_x, l_y, l_z)\\) is given by:\n\n\begin{equation*}\n    d_{distance} = ||\\mathbf{l} - \\mathbf{p}|| = \n    \\sqrt{(l_x - x)^2 + (l_y - y)^2 + (l_z - z)^2}\n\\end{equation*}\n\n### Field of View and Projection Matrices\n\nThe projection matrix depends on whether it is an orthographic or perspective projection.\n\n#### Orthographic Projection Matrix\n\nFor an orthographic projection, the projection matrix \\(P_{ortho}\\) can be defined as:\n\n\begin{equation*}\n    P_{ortho} = \n    \\begin{bmatrix}\n        1/(r-l) & 0          & 0        & -(r+l)/(2(r-l)) \\\\\n        0       & 1/(t-b)   & 0        & -(t+b)/(2(t-b)) \\\\\n        0       & 0          & -2/(f-n) & -(f+n)/(2(f-n)) \\\\\n        0       & 0          & 0        & 1\n    \\end{bmatrix}\n\\end{equation*}\n\nwhere \\(l, r, t, b\\) are the left, right, top, and bottom clipping planes respectively, and \\(n, f\\) are the near and far clipping planes.\n\n#### Perspective Projection Matrix\n\nFor a perspective projection, the matrix is given by:\n\n\begin{equation*}\n    P_{persp} = \n    \\begin{bmatrix}\n        1/\\tan(fovy/2) & 0      & 0             & 0 \\\\\n        0              & 1/h   & 0             & 0 \\\\\n        0              & 0      & -(f+n)/(f-n)  & -2fn/(f-n) \\\\\n        0              & 0      & -1            & 0\n    \\end{bmatrix}\n\\end{equation*}\n\nwhere \\(fovy\\) is the vertical field of view in radians, and \\(h\\) is the aspect ratio (width/height).\n\n### Clipping Planes\n\nNear (`d_zNear`) and far (`d_zFar`) clipping planes define the range of distances from the camera where objects are rendered. Anything closer than `zNear` or farther than `zFar` will not be visible.\n\n#### Automatic Z-Clip Plane Computation\n\nIf `d_computeZClip` is true, the near and far clipping planes can be automatically computed based on the bounding box of the scene defined by its minimum (`d_minBBox`) and maximum (`d_maxBBox`) points. The center \\(C\\) and radius \\(R\\) of the scene are:\n\n\begin{equation*}\n    C = (d_{minBBox} + d_{maxBBox})/2\n\\end{equation*}\n\n\begin{equation*}\n    R = ||d_{maxBBox} - d_{minBBox}|| / 2\n\\end{equation*}\n\nThe near and far clipping planes can then be set to a reasonable distance around the scene:\n\n\begin{align*}\n    z_{Near} &= C_z - R \\times k_1 \\\\\n    z_{Far} &= C_z + R \\times k_2\n\\end{align*}\n\nwhere \\(k_1, k_2\\) are scaling factors.\n\n## Practical Notes\n\nThe `BaseCamera` component is intended to be subclassed for specific camera types and behaviors. It provides methods for setting up the camera view (`setView()`, `setDefaultView()`), fitting the view to a bounding box or sphere (`fitBoundingBox()`, `fitSphere()`), and handling stereoscopic rendering through properties like stereo mode, strategy, and shift value."
}