docs/concepts.rst

   1 ..
   2   SPDX-License-Identifier: BSD-3-Clause
   3   Copyright Contributors to the OpenEXR Project.
   4
   5 .. _Concepts:
   6
   7 Concepts
   8 ########
   9
  10 .. toctree::
  11    :caption: Concepts
  12    :maxdepth: 0
  13
  14 The Imath library emphasizes simplicity, ease of use, correctness and
  15 verifiability, performance, and breadth of adoption. Imath is not
  16 intended to be a comprehensive linear algebra or numerical analysis
  17 package.
  18
  19 Imath is not a substitute for `Eigen <https://eigen.tuxfamily.org>`_!
  20 It's not a full-featured linear algebra package, and it doesn't
  21 represent vectors and matrices of arbitrary dimension. Its greatest
  22 utility is as a geometric data representation, primarily for 2D images
  23 and 3D scenes and coordinate transformations, along with an
  24 accompanying set of utility methods and functions.
  25
  26 Example
  27 =======
  28
  29 A basic program:
  30
  31 .. literalinclude:: examples/intro.cpp
  32
  33 Matrices Are Row-Major
  34 ======================
  35
  36 Imath stores matrices in row-major layout, originally inspired by
  37 compatibility with OpenGL matrices.
  38
  39 A matrix described as:
  40
  41 .. math::
  42   \begin{bmatrix}
  43   m_{00} & m_{01} & m_{02} & m_{03} \\
  44   m_{10} & m_{11} & m_{12} & m_{13} \\
  45   m_{20} & m_{21} & m_{22} & m_{23} \\
  46   m_{30} & m_{31} & m_{32} & m_{33} \\
  47   \end{bmatrix}
  48
  49 is laid out in memory as:
  50
  51 .. list-table::
  52    :widths: 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10
  53    :header-rows: 1
  54
  55    * - 0
  56      - 1
  57      - 2
  58      - 3
  59      - 4
  60      - 5
  61      - 6
  62      - 7
  63      - 8
  64      - 9
  65      - 10
  66      - 11
  67      - 12
  68      - 13
  69      - 14
  70      - 15
  71    * - :math:`m_{00}`
  72      - :math:`m_{01}`
  73      - :math:`m_{02}`
  74      - :math:`m_{03}`
  75      - :math:`m_{10}`
  76      - :math:`m_{11}`
  77      - :math:`m_{12}`
  78      - :math:`m_{13}`
  79      - :math:`m_{20}`
  80      - :math:`m_{21}`
  81      - :math:`m_{22}`
  82      - :math:`m_{23}`
  83      - :math:`m_{30}`
  84      - :math:`m_{31}`
  85      - :math:`m_{32}`
  86      - :math:`m_{33}`
  87
  88 A matrix representing a homogeneous transform has a right-hand column
  89 of :math:`\begin{bmatrix} 0 & 0 & 0 & 1\end{bmatrix}` and the
  90 translation component across the bottom row.
  91
  92 As a result, it is best to think of Imath vectors as row-vectors, and
  93 vector-matrix multiplication with the vector on the left and matrix on
  94 the right:
  95
  96 .. math::
  97   \begin{bmatrix} v_{0}' & v_{1}' & v_{2}' & 1' \end{bmatrix}
  98   =
  99   \begin{bmatrix} v_{0} & v_{1} & v_{2} & 1 \end{bmatrix}
 100   \begin{bmatrix} m_{00} & m_{01} & m_{02} & 0 \\
 101   m_{10} & m_{11} & m_{12} & 0 \\
 102   m_{20} & m_{21} & m_{22} & 0 \\
 103   m_{30} & m_{31} & m_{32} & 1
 104   \end{bmatrix}
 105
 106 This further implies that you should interpret local transformations
 107 as pre-multiplication:
 108
 109 .. code-block::
 110
 111    M44f M;
 112    M.translate (tx, ty, tz);
 113    m.rotate (r, 0, 0);
 114    m.scale (s);
 115
 116 .. math::
 117   \begin{bmatrix}
 118   m_{00} & m_{01} & m_{02} & m_{03} \\
 119   m_{10} & m_{11} & m_{12} & m_{13} \\
 120   m_{20} & m_{21} & m_{22} & m_{23} \\
 121   m_{30} & m_{31} & m_{32} & m_{33} \\
 122   \end{bmatrix}
 123   =
 124   \begin{bmatrix}
 125   s & 0 & 0 & 0 \\
 126   0 & s & 0 & 0 \\
 127   0 & 0 & s & 0 \\
 128   0 & 0 & 0 & 1 \\
 129   \end{bmatrix}
 130   \begin{bmatrix}
 131   1 & 0 & 0 & 0 \\
 132   0 & \cos(r) & \sin(r) & 0 \\
 133   0 & -\sin(r) & \cos(r) & 0 \\
 134   0 & 0 & 0 & 1 \\
 135   \end{bmatrix}
 136   \begin{bmatrix}
 137   1 & 0 & 0 & 0 \\
 138   0 & 1 & 0 & 0 \\
 139   0 & 0 & 1 & 0 \\
 140   tx & ty & tz & 1 \\
 141   \end{bmatrix}
 142
 143