Улучшение документации по кватернионам и версорам

docs/quaternion-eng.md

@@ -1,70 +1,36 @@
 # Quaternions
 
-If brief, quaternions are hypercomplex numbers with one real component and three
-complex components. Quaternions can be represented with formulas:
+Quaternions are hypercomplex numbers that extend the concept of complex numbers. They consist of one real component and three imaginary components:
 
-![Definition of quaternions](./media/quaternion_definition.png)
+q = w + ix + jy + kz
 
-Where *q* is a quaternion, *w*, *x*, *y* and *z* are real numbers and *i*, *j*
-and *k* are imaginary units.
+where:
 
-Quaternions can be represented with several ways. For example, a quaternion can
-be represented as a tuple of four real numbers:
+- w, x, y, z ∈ R are real numbers
+- i, j, k are imaginary units that satisfy the following conditions:
+   - i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1
 
-![Quaternion as a tuple](./media/quaternion_vector4_form.png)
+Quaternions were discovered by mathematician William Hamilton and introduced to the public in 1843. They have found wide application in computer graphics, robotics, and physics to describe rotations in three-dimensional space.
 
-In that case a quaternion reminds a four-dimensional vector. And quaternions do
-have many similar features as four-dimensional vectors do. For example:
+## Quaternion implementation in the library
 
-* summation and subtraction of quaternions are same as for four-dimensional
-vectors;
-* multiplication and division of a quaternion at a real number are same
-as for a four-dimensional vector;
-* modulus of a quaternion is calculated the same way as for four-dimensional
-vector.
+The library provides two implementations of quaternions:
 
-But the product of two quaternions is comletely different than the dot product
-of two four-dimensional vectors.
+1. **General-purpose quaternions**
+   - Support all basic operations (addition, subtraction, multiplication by a scalar, etc.).
 
-Another way to represent a quaternion is a pair of a real number and
-a three-dimensional vector:
+2. **Versors**:
+   - Specialized quaternions whose absolute value is always equal to one.
+   - Suitable for describing rotations in three-dimensional space.
+   - Do not support addition, subtraction, and multiplication by a scalar.
 
-![Quaternion as a pair of a number and a vector](./media/quaternion_mixed_form.png)
+General-purpose quaternions can also be used to represent rotations in three-dimensional space. But the developer using quaternions to describe rotations must ensure that the absolute values of the quaternions do not become less than the error value and do not take the NaN (not a number) value.
 
-Quaternions have many interesting features. In geometry, quaternions are used
-to represent and combine rotations in three-dimensional Euclidean space.
+### Quaternion structures
 
-Usually quaternions with unit modulus are used to represent rotations. Such
-quaterions are named as [versors](./versor-eng.md).
-
-## Implementation of quaternions in the library
-
-There are two varians of implementation of quaternions in the library:
-* quaternions
-* versors
-
-The main difference implementation of quaternions and versors is that
-the versors are designed for representation of rotations in
-the three-dimensional Euclidean space while quaternions are implemented in
-a more general sense.
-
-Versors are not possible to add and subtract. Versors cannot be mutiplied
-or divided with a real number. But quaternions can be added and subtracted,
-multiplied and divided with a number.
-
-Versors can be combined. It is the same operation as multiplication of
-two quaternions but the function of combination of two versors watches that
-the resulting versor has modulus equal to 1.
-
-All the functions which change the state of a versor keep the modulus of
-a versor close to 1.
-
-Yes, the modulus of a versor is very close to 1 because floating point numbers
-are not perfect and have little aberrations. Thus the modulus is not always
-equal to 1 but very close to 1.
-
-There two structural types for quaternions:
+#### General purpose quaternions
 
+```c
     typedef struct {
         float s0, x1, x2, x3;
     } BgcQuaternionFP32;
@@ -72,10 +38,11 @@ There two structural types for quaternions:
     typedef struct {
         double s0, x1, x2, x3;
     } BgcQuaternionFP64;
+```
 
+#### Versors
 
-And there are two strucutral types for versors:
-
+```c
     typedef struct {
         const float s0, x1, x2, x3;
     } BgcVersorFP32;
@@ -83,17 +50,12 @@ And there are two strucutral types for versors:
     typedef struct {
         const double s0, x1, x2, x3;
     } BgcVersorFP64;
+```
 
-As you can see there is a difference in the definision of quaternions and
-versors: the fields of versors are const while the fields of quaternions
-are not const.
+Fields:
+- s0 is the real part of the versor.
+- x1, x2, x3 - Imaginary components of the versor.
 
-This was done intensionally to make a developer to use special functions for
-versors to set the state of a versor instead of direct setting of
-the field values because versor functions keep the modulus of a versor equal
-to 1.
-
-At the same time a developer can read the fields of a versor for their own
-needs, for example, for some computations or for saving a versor in a file
-or for passing it via a computer network.
+The versor fields are declared as const so that the developer uses the library functions to work with versors, and does not change them directly.
 
+The quaternion fields are free to be changed by the developer using the library.