Развитие документации по версорам

docs/versor-eng.md

@@ -32,6 +32,41 @@ There is a special name for a quaternion of unit length: versor.
 
 Versors are quaternions of unit length.
 
+## Advantages of versors over quaternions
+
+The main advantage of versors is that they do not degrade.
+
+If you multiply two quaternions whose moduli are equal to one, the result will
+also be a quaternion with a modulus equal to one. While the product of two
+quaternions whose moduli differ from one will yield a quaternion whose modulus
+will most likely also differ from one. And the product of several quaternions
+can yield a quaternion whose modulus will be close to zero.
+
+Thus, the modulus of a versor is always equal to one, unlike a regular
+quaternion.
+
+In practice, the modulus of a versor is not always equal to one, but is close
+to one due to the presence of an error in the **float** and **double**
+(**binary32** and **binary64**) types.
+
+The second advantage of versors is that the library functions take on the task
+of maintaining the versor modulus so that it does not deviate too much from one.
+
+Thus, the developer does not need to perform normalization, as he would have
+to do with regular quaternions.
+
+The third advantage of versors is that the library functions do not always
+perform versor normalization, but only when it is necessary.
+
+The library functions check the difference between the versor modulus and 1, and
+if the error is greater than a predefined threshold (epsilon), the function
+normalizes the resulting versor.
+
+In most cases, when the input parameters are versors (normalized quaternions),
+there is no need to normalize the function result. This way, time-consuming
+operations such as square root calculations and division can be avoided. This
+approach allows to improve performance and keep versions normalized.
+
 ## Implementation of versors in the library
 
 The library has a separate implementation for versors in the form of special
@@ -48,8 +83,62 @@ There are two structures for versors: **BgcVersorFP32** and **BgcVersorFP64**:
     } BgcVersorFP64;
 
 The fields are deliberately declared const so that a developer using these
-structures is not tempted to change the values ​​of the fields directly.
+structures is not tempted to change the values of the fields directly.
 
 With these structures, it is better to use special functions that allow you
-to save new values ​​in the structure fields of **BgcVersorFP32** and
+to save new values in the structure fields of **BgcVersorFP32** and
 **BgcVersorFP64**.
+
+## Operation with versors
+
+- Resetting the state to idle (reset)
+- Setting the values of components (set values)
+- Copying the state (copy)
+- Swapping the states (swap)
+- Making a versor with turn (set turn)
+- Checking the state is idle (is idle)
+- Convertation of type (convert)
+- Shortening of the turn (shorten)
+- Inversion (invert)
+- Combination (combine)
+- Getting description of the turn (get rotation)
+- Getting the rotation matrix (get rotation matrix)
+- Getting the reverse rotation matrix (get reverse matrix)
+- Turning a vector (turn vector)
+- Turning a vector backward (turn vector back)
+- Comparsion (are close)
+
+### Resetting the state to idle
+
+A versor which describes an idle turn has these values of the components:
+
+    s0 = 1, x1 = 0, x2 = 0, x3 = 0
+
+There is a function which resets the state of a versor to that state.
+
+For **BgcVersorFP32**:
+
+    inline void bgc_versor_reset_fp32(BgcVersorFP32* versor);
+
+For **BgcVersorFP64**:
+
+    inline void bgc_versor_reset_fp64(BgcVersorFP64* versor);
+
+Example of usage:
+
+    #include <stdio.h>
+    #include <basic-geometry.h>
+
+    int main() {
+        BgFP32Versor versor;
+
+        bgc_versor_reset_fp32(&versor);
+
+        printf("Versor: (%f, %f, %f, %f)\n", versor.s0, versor.x1, versor.x2, versor.x3);
+
+        return 0;
+    }
+
+Result:
+
+    Versor: (1.000000, 0.000000, 0.000000, 0.000000)