Документация: кватернионы и версоры / Documentation: quaternions and versors

docs/quaternion-eng.md

@@ -0,0 +1,94 @@
+# Quaternions
+
+If brief, quaternions are hypercompex numbers with one real component and three
+complex components. Quaternions can be represented with formulas:
+
+![Definition of quaternions](./media/quaternion_definition.png)
+
+Where *q* is a quaternion, *w*, *x*, *y* and *z* are real numbers and *i*, *j*
+and *k* are imaginary units.
+
+Quaternions can be represented with several ways. For example, a quaternion can
+be represented as a tuple of four real numbers:
+
+![Quaternion as a tuple](./media/quaternion_vector4_form.png)
+
+In that case a quaternion reminds a four-dimensional vector. And quaternions do
+have many similar features as four-dimensional vectors do. For example:
+
+* 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.
+
+But the product of two quaternions is comletely different result than the dot
+product of two four-dimensional vectors.
+
+Another way to represent a quaternion is a pair of a real number and
+a three-dimensional vector:
+
+![Quaternion as a pair of a number and a vector](./media/quaternion_mixed_form.png)
+
+Quaternions have many interesting features. In geometry, quaternions are used
+to represent and combine rotations in three-dimensional Euclidean space.
+
+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.
+
+But 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.
+
+There two structural types for quaternions:
+
+    typedef struct {
+        float s0, x1, x2, x3;
+    } BgFP32Quaternion;
+
+    typedef struct {
+        double s0, x1, x2, x3;
+    } BgFP64Quaternion;
+
+
+And there are two strucutral types for versors:
+
+    typedef struct {
+        const float s0, x1, x2, x3;
+    } BgFP32Versor;
+
+    typedef struct {
+        const double s0, x1, x2, x3;
+    } BgFP64Versor;
+
+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.
+
+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 his|her own
+needs, for example, for saving a versor in a file or pass it via a network.
+

docs/quaternion-rus.md

@@ -5,60 +5,36 @@
 
 ![Определение кватерниона](./media/quaternion_definition.png)
 
+Где *q* - это кватернион, *w*, *x*, *y* и *z* - это действительные числа, а *i*,
+*j* и *k* - это мнимые единицы.
+
 Кватернион можно представлять по-разному, например, в виде кортежа
-(последовательности) из четырёх чисел также как четырёхмерный вектор:
+(последовательности) из четырёх чисел:
 
 ![Кватернион-кортеж](./media/quaternion_vector4_form.png)
 
-Можно представлять как пару из числа и трёхмерного вектора:
+В такой форме кватернион напоминает четырёхмерный вектор. И кватернионы
+действительно имеют ряд сходств с четрырёхмерными векторами, например:
+
+* сложение и вычитание кватернионов такие же, как и у четырёхмерных векторов;
+* умножение и деление кватериона на действительное число такие же как и для
+четырёхмерного вектора;
+* взятие модуля кватерниона вычисляется также как и для четырёхмерного вектора.
+
+Но произведение кватернионов совершенно иное, чем скалярное произведение двух
+четырёхмерных векторов.
+
+Ещё одним способом представления кватерниона является пара из действительного
+числа и трёхмерного вектора:
 
 ![Кватернион как число и вектор](./media/quaternion_mixed_form.png)
 
-Кватернионы можно легко вывести из обычных комплексных чисел. Обычные
-комлексные числа в качестве в качестве компонент имеют вещественные
-числа *a* и *b*:
-
-![Определение комплексного числа](./media/compex_number_000.png)
-
-Но, что если представить, что компоненты *a* и *b* тоже комплексные
-числа, но с другой мнимой единицей *j* вместо *i*, при этом
-мнимая единица *j* имеет такие же свойства, что и *i*:
-
-![Комплексная единица j](./media/imaginary_j.png)
-
-Тогда компоненты *a* и *b* можно представить следующим образом:
-
-![Комплексные компоненты](./media/compex_number_001.png)
-
-Если подставить их в формулу комплексного числа, то получается:
-
-![Гиперкомплексное число](./media/compex_number_002.png)
-
-В этом выражении наиболее интересно произведение мнимых единиц *ij*. Если
-представить, что произведение антикоммутативно, то у произведения
-получаются интересные свойства.
-
-![Антикоммутативность](./media/imaginary_anticommutative.png)
-
-Например, если взять квадрат произведения, то получается, что оно ведёт себя
-как мнимая единица:
-
-![Квадрат произведения](./media/imaginary_anticommutative2.png)
-
-Таким образом, произведение мнимых единиц *ij* можно обозначить новой мнимой
-единицей:
-
-![Новая мнимая единица](./media/imaginary_k.png)
-
-И тогда получается полноценный кватернион:
-
-![Кватернион](./media/quaternion_result.png)
-
 Кватернионы обладают массой интересных свойств и применений. В геометрии
-основным применением является описание поворотов в трёхмерном пространстве.
+основным применением является описание поворотов в трёхмерном евклидовом
+пространстве.
 
-Кватернионы, которые описывают поворот в трёхмерном пространстве называются
-[версорами](./versor-rus.md).
+Обычно для представления поворотов используются кватернионы с модулем, равным
+единице. Такие кватернионы называются [версорами](./versor-rus.md).
 
 ## Реализация кватернионов в библиотеке
 
@@ -98,7 +74,14 @@
     } BgFP64Versor;
 
 Уже в определении структур можно заметить разницу между в реализации
-кватернионов и версоров: поля версоров объявлены как константы.
-Это сделано намеренно, чтобы разработчик, использующий библиотеку мог считывать
-данные из полей, но для изменения состояния версора прибегал к использованию
-специальных функций, которые обеспечивают, чтобы модуль версора был равен 1.
+кватернионов и версоров: поля версоров объявлены как константы, в то время как
+поля кватерниона не являются константами.
+
+Это сделано намеренно, чтобы побудить разработчика использовать функции для
+версоров, вместо того, чтобы задавать значения полей напрямую, потому что
+функции версоров обеспечивают, чтобы модуль версора был равен единице.
+
+В то же время, разработчик может обращаться к полям версора, чтобы получить
+значения этих полей для своих целей, например, чтобы сохранить значение
+версора в файле или передать по сети.
+