$LastChangedDate: 27-Juil-2011 $

# CL_rot_defRotVec

Rotation transforming 2 vectors into 2 vectors

## Calling Sequence

       [q, Inok] = CL_rot_defRotVec(u1, v1, u2, v2)

## Description

- Computes the rotation that transforms 2 vectors into 2 vectors.

  Except for possible scale factors and vector adjustments, the rotation R is such that:

  R(u1) = u2 and R(v1) = v2

  The rotation R is returned as a quaternion (q). In practice, the rotation is determined such that (assuming the vectors not aligned):

  R(u1/||u1||) = u2/||u2||

  R(u1^v1/||u1^v1||) = u2^v2/||u2^v2||

  so that the angular separations between u1 and v1, and u2 and v2 do not matter (provided they remain in ]0,pi[).

- Notes:

  If (u1 and v1) or (u2 and v2) are colinear, then the rotation is not uniquely defined or may not exist, and the corresponding indices are returned in Inok. In that case, the returned rotation is the rotation that transforms u1 into u2 about an axis perpendicular to the plane (u1,u2) which is the one with the smallest rotation angle. If additionnaly u1 and u2 are colinear, then the rotation is either the identity or a 180 degree rotation about an axis perpendicular to u1.

- Use note:

  The function can be used for frame determination when 2 vectors are known in 2 different frames:

  - u1,v1: coordinates relative to frame 1

  - u2,v2: coordinates relative to frame 2

  => q = CL_rot_defRotVec(u1,v1,u2,v2) gives the rotation that transforms the basis vectors of frame2 into the basis vectors of frame 1.

  The frame transformation matrix M from Frame 1 to Frame 2 is then: M = CL_rot_quat2matrix(q'), and is such that: u2 = M*u1 and v2 = M*v1

## Parameters

u1:

  First vector (3xN or 3x1)

v1:

  Second vector (3xN or 3x1)

u2:

  Desired image of u1 by the rotation (3xN or 3x1)

v2:

  Desired image of v1 by the rotation (3xN or 3x1)

q:

  Quaternion that defines the rotation (dim N)

Inok:

  Indices for which u1,v1,u2,v2 do not define a unique rotation.

## Authors

- CNES - DCT/SB

## See also

- CL_rot_defQuat

- CL_rot_defFrameVec

## Examples

    // Example1: (u1,v1) and (u2,v2) have the same angular separation:
    u1 = [ 1 ; 2 ; 3 ];
    v1 = [ 3 ; 1 ; 2 ];
    q = CL_rot_axAng2quat([0;0;1], 0.1)
    u2 = CL_rot_rotVect(q,u1);
    v2 = CL_rot_rotVect(q,v1);
    q2 = CL_rot_defRotVec(u1,v1,u2,v2) // q == q2

    // Example2: (u1,v1) and (u2,v2) have different angular separations:
    u1 = [ 1 ; 2 ; 3 ];
    v1 = [ 3 ; 1 ; 2 ];
    q = CL_rot_axAng2quat([0;0;1], 0.1)
    u2 = CL_rot_rotVect(q,u1);
    v2 = CL_rot_rotVect(q,v1) + 10 * u2;
    q2 = CL_rot_defRotVec(u1,v1,u2,v2) //q == q2

    // Example3: One pair of vectors
    u1 = [ 1 ; 2 ; 3 ];
    u2 = [ 1 ; 4 ; 5 ];
    [q,ind] = CL_rot_defRotVec(u1,u1,u2,u2); // ind == 1

    // Example4: frame determnation
    kep = [7000.e3; 0.01; %pi/3; 0; %pi/2; 0]; // orbital elements
    [p,v] = CL_oe_kep2car(kep); // inertial position and velocity
    M = CL_fr_qswMat(p,v); // inertial to "qsw" local frame
    u2 = [1;2;3];   // "2" => coord. relative to "qsw"
    v2 = [-1;1;0];
    u1 = M' * u2;   // "1" => coord relative to inertial frame
    v1 = M' * v2;
    q = CL_rot_defRotVec(u1,v1,u2,v2);
    CL_rot_quat2matrix(q') - M  // => 0
    q = CL_rot_defRotVec(u2,v2,u1,v1);
    CL_rot_quat2matrix(q) - M  // => 0

    M1 = CL_rot_defFrameVec(u1,v1,1,2); // inertial => vectors
    M2 = CL_rot_defFrameVec(u2,v2,1,2); // qsw => vectors
    M2'*M1 - M // => 0