diff --git a/docs/documentation-eng.odt b/docs/documentation-eng.odt new file mode 100644 index 0000000..01749e2 Binary files /dev/null and b/docs/documentation-eng.odt differ diff --git a/docs/quaternion-eng.md b/docs/quaternion-eng.md new file mode 100644 index 0000000..4d2db25 --- /dev/null +++ b/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. + diff --git a/docs/quaternion-rus.md b/docs/quaternion-rus.md index f99be83..539738a 100644 --- a/docs/quaternion-rus.md +++ b/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. \ No newline at end of file +кватернионов и версоров: поля версоров объявлены как константы, в то время как +поля кватерниона не являются константами. + +Это сделано намеренно, чтобы побудить разработчика использовать функции для +версоров, вместо того, чтобы задавать значения полей напрямую, потому что +функции версоров обеспечивают, чтобы модуль версора был равен единице. + +В то же время, разработчик может обращаться к полям версора, чтобы получить +значения этих полей для своих целей, например, чтобы сохранить значение +версора в файле или передать по сети. +