# A Riemannian quotient representation for the essential manifold
Contributed by Roberto Tron.

The essential matrix is a 3x3 matrix that encodes the epipolar
constraint between the homogeneous coordinates of the projection of a
common 3-D point in two cameras. Not all the 3x3 matrices are essential matrices, as
these need to encode the relative pose of the two cameras (up to a
global scaling). The space of valid essential matrices can be endowed
with a Riemannian structure by following the derivations presented in:

  R. Tron, K. Daniilidis,
  "The Space of Essential Matrices as a Riemannian Quotient Manifold -
  Geometric Interpretation and Optimization Algorithms" 
  International Journal of Computer Vision, (submitted).

This work shows that the essential manifold can be seen as a quotient
manifold of $SO(3) \times SO(3)$, where $SO(3)$ is the manifold of 3-D
rotations. In Matlab, we represents k points on the essential
manifold as array of dimension $[3 \times 6 \times k]$, where each $[3 \times 3]$
sub matrix is a 3-D rotation.

The implementation provides both the "signed" and "unsigned" version
of the manifold presented in the paper. The only difference between
the two is in how the logarithm, and hence the distance, are
computed. In the signed version, the points related by the twisted pair
ambiguity are considered as distinct; in practice, this is the case when the
cheirality constraint is used to remove the ambiguity. In the unsigned
version, points related by the twisted pair ambiguity belong to the
same class; in practice, it means that they all produce equivalent
epipolar constraints. See the paper for details.

Factory call:
M=essentialfactory(k,signature).
By default, k equals 1. The string signature should be set to "signed"
(resp. "unsigned") to use the signed (resp. unsigned) version of the
manifold. By default, signature equals "signed".

See the paper for the definition of the set and tangent spaces.

Note: following the representation of tangent vectors for SO(3) in
MANOPT, tangent vectors for the essential manifold are represented as
$[3 \times 6 \times k]$ matrices, where each $[3 \times 3]$
sub matrix is skew-symmetric. The real tangent vector in the ambient
space is obtained by multiplying on the left each $[3 \times 3]$
skew-symmetric matrix with the corresponding rotation from the base
point.

## Toolset
The following list contains some of the nontrivial available functions
in the structure M.

- Dimension
M.dim()
$\dim M=5k$

- Metric
M.inner(X,S,T)
$\langle U, V \rangle = \sum_{i=1}^k trace(S_i^TT_i)$, where S and T
are representation of two tangent vectors at X.

- Norm
M.norm(X,S)
$\norm{U}=\sqrt{\langle U, U \rangle}$

- Distance
M.dist(X,Y)
$\dist(X,Y)=\sqrt(\sum_{i=1}^k \norm{\log(X_i,Y_i)}$, see M.log(X,Y)
below

- Typical distance
M.typicaldist()
\pi\sqrt{k}

- Vertical tangent space projector
M.vertproj(X,H)
Projects a point in the ambient space onto the vertical space at
X. See the paper for details. Note that this operation returns an
array containing skew-symmetric matrices.

- Tangent space projector
M.proj(X,H)
Projects a point in the ambient space onto the horizontal space at
X. See the paper for details. Note that this operation returns an
array containing skew-symmetric matrices.

- Tangent space to ambient space
M.tangent2ambient(X,S)
Computes a matrix H where H(1:3,:,i)=X(1:3,:,i)*S(1:3,:,i) and
H(4:6,:,i)=X(4:6,:,i)*S(4:6,:,i). This function is necessary because
the proj operator takes as input an ambient vector and returns a
tangent vector. To apply the proj again to the result (which should
change nothing), it is necessary to first represent the tangent vector
obtained as an ambient vector. This function is here because of formal
peculiarities and is likely to disappear at some point. 

- Essential matrix
M.E(X)
Returns the 3\times 3 essential matrix corresponding to the point on
the manifold X.

- Tangent of the essential matrix
M.dE(X,S)
Returns the matrix $\dot{E}$ obtained from a point X moving on a curve
with tangent S. Mathematically, this is the push-forward of S through
the mapping M.E(X)

- Double tangent of the essential matrix
M.ddE(X,S)
Returns the matrix $\ddot{E}$ obtained from a point X moving on a
*geodesic* curve (i.e., with zero acceleration) with tangent S. 
Mathematically, this is the push-forward of S through the mapping M.dE(X,S)

- Euclidean to Riemannian function
M.ef2rf(X,ef)
Returns the value of ef evaluated at M.E(X). ef must be a function handle

- Euclidean gradient of a function of E to Euclidean gradient of a function of X
M.egradE2egrad(X,egradE)
Returns the Euclidean gradient (matrix of partial derivatives) in the
entries of X (taken as a $3 \times 6$ matrix) given the Euclidean gradient
of a function of E (which is a $3 \times 3$ matrix). egrad must be
a function handle for which egrad(E) returns the $3 \times 3$
Euclidean gradient of a function evaluated at the essential matrix E=M.E(X)
Note: this function uses a different convention than egrad2rgrad for
other manifolds. In this case egradE is a function handle, while in the
other cases egrad is a matrix.

- Euclidean to Riemannian gradient
M.egrad2rgrad(X,egrad)
Returns the Riemannian gradient (a tangent vector at X) corresponding
to the Euclidean gradient of a function of X taken as a matrix. egrad must be
a function handle for which egrad(X) returns the $3 \times 6$
Euclidean gradient of a function evaluated at the point X.
Note: this function uses a different convention than egrad2rgrad for
other manifolds. In this case egrad is a function handle, while in the
other cases egrad is a matrix.

- Euclidean gradient of a function of E to Riemannian gradient
M.egradE2rgrad(X,egradE)
This function is the combination of M.egradE2egrad and
M.egrad2rgrad. See the respective comments for more information.

- Euclidean Hessian of a function of E to to Euclidean Hessian of a function of X 
M.ehessE2ehess(X,egradE, ehessE, V)
Returns the Euclidean Hessian (operator given by second order partial
derivatives) in the entries of X (taken as a $3 \times 6$ matrix)
evaluated in the direction V (which represents a direction in the
ambient space) given the Euclidean Hessian operator of a function of E
(which is a $3 \times 3$ matrix). ehessE must be a function handle for which
egrad(E,dE) returns the $3 \times 3$ Euclidean Hessian of a function
evaluated at the essential matrix E for the tangent vector dE. See
also M.egradE2egrad.

- Euclidean to Riemannian Hessian 
M.ehessE2rhess(X,egrad, ehess, V)
This function is the combination of M.ehessE2ehess and
M.ehess2rhess. See the respective comments for more information.

- Exponential map
M.exp(X,S,t)
Returns the point obtained by following the normal geodesic starting from X
with tangent S for a length t. This function does not check that S is
horizontal: it simply applies the exponential map on each copy of
SO(3)

- Logarithm map
M.log(X,Y)
The inverse of the exponential map. It is guaranteed to correspond to
the horizontal vector pointing in the direction of the shortest
geodesic from X to Y.

- Transport
M.transp(X1,X2,S1)
Transport a vector from the tangent space of X1 to the tangent space
of X2, using left translations in SO(3)^2. This transport preserves
the length of the vectors.

- Distance
M.dist(X,Y)
$\dist(X,Y)=\|\log(X,Y)\|$
Compute the shortest geodesic distance between X and Y. 

- Pair mean
M.pairmean(X,Y)
Mid-point of the shortest geodesic between X and Y.


## Example

The file essential_svd.m contains an example of the use of the
essential manifold in MANOPT. It first builds random essential
matrices A_i, i=1,..,k. It then tries to find matrices E_i, i=1,...,k
which minimize

\sum_{i=1}^k \frac{1}{2}\|E_i-A_i\|^2.

The i-th component of the Euclidean gradient is simply E_i-A_i and the
Hessian operator is the identity.

This problem is trivial, as the cost function is separable in each i
and the solution is simply E_i=A_i. However, this example shows
how to define the gradient and hessian of the cost function with k>1
and shows that indeed the optimization procedure converges
to the expected minimizer.

## Files
With respect to a vanilla installation of MANOPT, the implementation
of the essential manifold adds the following files and directories

manopt/manifolds/essential
examples/essential_svd.m
