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

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)

docs/versor-rus.md

@@ -1,7 +1,7 @@
 # Версоры
 
-[Кватернионы](./quaternion-rus.md) - это гиперкомплексные числа, у которых имеется одна действительная
+[Кватернионы](./quaternion-rus.md) - это гиперкомплексные числа, у которых
-компонента и три комплексных компоненты:
+имеется одна действительная компонента и три комплексных компоненты:
 
 ![Определение кватерниона](./media/quaternion_definition.png)
 
@@ -23,6 +23,45 @@
 
 ![Определение версора](./media/versor_definition.png)
 
+Несмотря на то, что версоны как класс кватернионов были предложены ещё Уильямом
+Гамильтоном для описаний поворотв, в русскоязычной литературе термин "версор",
+можно сказать, что не употребляется.
+
+## Преимущества версоров над кватернионами
+
+Основным преимуществом версоров заключается в том, что они не деградируют.
+
+Если умножить два кватерниона, модули которых равны единице, то результатом
+будет также кватернион с модулем, равным единице. В то время как произведение
+двух кватернионов, у которых модули отличаются от единицы, даст кватернион,
+модуль которого, скорее всего, также будет отличаться от единицы. А произведение
+ряда кватернионов может дать кватернион, у которого модуль будет близок к нулю.
+
+Таком образом, модуль версора всегда равен единице в отличие от обычного
+кватерниона.
+
+На практике модуль веросна не всегда равен единице, но близок к единице из-за
+наличия погрешности типов **float** и **double** (**binary32** и **binary64**).
+
+Вторым преимуществом версоров в том, что функции библиотеки берут на себя
+задачу поддержания модуля версора, чтобы оно не сильно отклонялось от единицы.
+
+Таким образом, разработчику не нужно производить нормализацию, как это пришлось
+бы делать с обычными кватернионами.
+
+Третьим преимуществом версоров является то, что функции библиотеки не всегда
+производят нормализацию версоров, а только тогда, когда это необходимо.
+
+Функции библиотеки проверяют разницу между модулем версора и единицей, и только
+больше предопределенного порога (эпсилон), функция нормализует полученный
+версор.
+
+В большинстве случаев, когда входные параметры являются версорами
+(нормализованными кватернионами), нет необходимости нормализовать результат
+функции. Таким образом, можно избежать трудоемких операций, таких как вычисление
+квадратных корней и деление. Такой подход позволяет повысить производительность
+и поддерживать версоры нормализованными.
+
 ## Версоры в библиотеке
 
 Библиотека имеет отдельную реализацию для версоров в виде специальных структур и
@@ -47,3 +86,21 @@
 устанавливать новые значения в поля структур **BgcVersorFP32** и
 **BgcVersorFP64**.
 
+## Операции с версорами
+
+- Сброс состояния (reset)
+- Указание значений компонент (set values)
+- Копирование значений компонент (copy)
+- Обмен значений компонент (swap)
+- Построение на основе поворота (set turn)
+- Проверка на отсутствие поворота (is idle)
+- Преобразование типа (convert)
+- Сокращение поворота (shorten)
+- Инверсия (invert)
+- Комбинирование (combine)
+- Получение описание поворота (get rotation)
+- Получение матрицы поворота (get rotation matrix)
+- Получение матрицы обратного поворота (get reverse matrix)
+- Поворот вектора (turn vector)
+- Обратный поворот вектора (turn vector back)
+- Сравнение (are close)