Kimelas/bgc-c
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Andrey Pokidov 2025-02-07 23:46:30 +07:00
parent a3ff67792d
commit 72b6690ad6
4 changed files with 92 additions and 165 deletions
Download patch file Download diff file Expand all files Collapse all files

94
docs/quaternion-eng.md
View file

@ -1,70 +1,36 @@
# Quaternions # Quaternions
If brief, quaternions are hypercomplex numbers with one real component and three Quaternions are hypercomplex numbers that extend the concept of complex numbers. They consist of one real component and three imaginary components:
complex components. Quaternions can be represented with formulas:
![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* where:
and *k* are imaginary units.
Quaternions can be represented with several ways. For example, a quaternion can - w, x, y, z ∈ R are real numbers
be represented as a tuple of four 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 ## Quaternion implementation in the library
have many similar features as four-dimensional vectors do. For example:
* summation and subtraction of quaternions are same as for four-dimensional The library provides two implementations of quaternions:
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 than the dot product 1. **General-purpose quaternions**
of two four-dimensional vectors. - 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 2. **Versors**:
a three-dimensional vector: - 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 ### Quaternion structures
to represent and combine rotations in three-dimensional Euclidean space.
Usually quaternions with unit modulus are used to represent rotations. Such #### General purpose quaternions
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:
```c
typedef struct { typedef struct {
float s0, x1, x2, x3; float s0, x1, x2, x3;
} BgcQuaternionFP32; } BgcQuaternionFP32;
@ -72,10 +38,11 @@ There two structural types for quaternions:
typedef struct { typedef struct {
double s0, x1, x2, x3; double s0, x1, x2, x3;
} BgcQuaternionFP64; } BgcQuaternionFP64;
```
#### Versors
And there are two strucutral types for versors: ```c
typedef struct { typedef struct {
const float s0, x1, x2, x3; const float s0, x1, x2, x3;
} BgcVersorFP32; } BgcVersorFP32;
@ -83,17 +50,12 @@ And there are two strucutral types for versors:
typedef struct { typedef struct {
const double s0, x1, x2, x3; const double s0, x1, x2, x3;
} BgcVersorFP64; } BgcVersorFP64;
```
As you can see there is a difference in the definision of quaternions and Fields:
versors: the fields of versors are const while the fields of quaternions - s0 is the real part of the versor.
are not const. - x1, x2, x3 - Imaginary components of the versor.
This was done intensionally to make a developer to use special functions for 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.
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 quaternion fields are free to be changed by the developer using the library.

93
docs/quaternion-rus.md
View file

@ -1,70 +1,35 @@
# Кватернионы # Кватернионы
Кватернионы - это гиперкомплексные числа, у которых имеется одна действительная Кватернионы — это гиперкомплексные числа, которые расширяют понятие комплексных чисел. Они состоят из одной действительной компоненты и трёх мнимых компонент:
компонента и три комплексных компоненты:
![Определение кватерниона](./media/quaternion_definition.png) q = w + ix + jy + kz
Где *q* - это кватернион, *w*, *x*, *y* и *z* - это действительные числа, а *i*, где:
*j* и *k* - это мнимые единицы.
Кватернион можно представлять по-разному, например, в виде кортежа - w, x, y, z &isin; R - действительные числа
(последовательности) из четырёх чисел: - i, j, k - мнимые единицы, удовлетворяющие следующим условиям:
- i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1
![Кватернион-кортеж](./media/quaternion_vector4_form.png) Кватернионы были открыты математиком Уильямом Гамильтоном и представлены публике в 1843 году. Они нашли широкое применение в компьютерной графике, робототехнике и физике для описания поворотов в трёхмерном пространстве.
В такой форме кватернион напоминает четырёхмерный вектор. И кватернионы
действительно имеют ряд сходств с четрырёхмерными векторами, например:
* сложение и вычитание кватернионов такие же, как и у четырёхмерных векторов;
* умножение и деление кватериона на действительное число такие же как и для
четырёхмерного вектора;
* взятие модуля кватерниона вычисляется также как и для четырёхмерного вектора.
Но произведение кватернионов совершенно иное, чем скалярное произведение двух
четырёхмерных векторов.
Ещё одним способом представления кватерниона является пара из действительного
числа и трёхмерного вектора:
![Кватернион как число и вектор](./media/quaternion_mixed_form.png)
Кватернионы обладают массой интересных свойств и применений. В геометрии
основным применением является описание поворотов в трёхмерном евклидовом
пространстве.
Обычно для представления поворотов используются кватернионы с модулем, равным
единице. Такие кватернионы называются [версорами](./versor-rus.md).
## Реализация кватернионов в библиотеке ## Реализация кватернионов в библиотеке
В библиотеке кватернионы реализованы в двух вариантах: Библиотека предоставляет две реализации кватернионов:
* в виде обычных кватернионов 1. **Кватернионы общего назначения**
* в виде веросоров - Поддерживают все основные операции (сложение, вычитание, умножение на скаляр и т.д.).
Главное отличие в реализации кватернионов и версоров том, что реализация 2. **Версоры**:
версоров ориентирована именно для представления поворотов в трёхмерном - Специализированные кватернионы, модуль которых всегда равен единице.
евклидовом пространстве пространстве, в то время как кватернионы имеют более - Подходят для описания поворотов в трёхмерном пространстве.
общую реализацию. - Не поддерживают операции сложения, вычитания и умножения на скаляр.
Версоры нельзя складывать, вычитать. Также версоры нельзя умножать и делить на Кватернионы общего назначения также можно использовать для представления поворотов в трёхмерном пространстве. Но разработчик, использующий кватернионы для описания поворотов, сам должен следить за тем, чтобы модули кватернионов не становились меньше величины погрешности и не принимали значение NaN (не число).
вещественные числа. Но кватернионы можно складывать, вычитать, а также умножать
и делить на вещественное число.
Версоры можно комбинировать. Операция комбинирования версоров является обычным ### Структуры для кватернионов
произведением кватернионов. Единственное отличие в том, что операция
комбинирования версоров обеспечивает, чтобы результат комбинации также имел
модуль, равный единицы.
Все функции версоров, которые менияют состояние версора, обеспечивают, чтобы #### Кватернионы общего назначения
модуль версора оставался близким к единице.
Да, модуль версора очень близок к единице, потому что числа с плавающей запятой
не совершенны и имеют небольшие погрешности. Поэтому модуль не всегда равен
единице, но очень близок к единице.
Для описаия кватернионов есть две структуры:
```c
typedef struct { typedef struct {
float s0, x1, x2, x3; float s0, x1, x2, x3;
} BgcQuaternionFP32; } BgcQuaternionFP32;
@ -72,10 +37,11 @@
typedef struct { typedef struct {
double s0, x1, x2, x3; double s0, x1, x2, x3;
} BgcQuaternionFP64; } BgcQuaternionFP64;
```
#### Версоры
Для описания версоров также имеется две структуры: ```c
typedef struct { typedef struct {
const float s0, x1, x2, x3; const float s0, x1, x2, x3;
} BgcVersorFP32; } BgcVersorFP32;
@ -83,17 +49,12 @@
typedef struct { typedef struct {
const double s0, x1, x2, x3; const double s0, x1, x2, x3;
} BgcVersorFP64; } BgcVersorFP64;
```
Уже в определении структур можно заметить разницу между в реализации Поля:
кватернионов и версоров: поля версоров объявлены как константы, в то время как - s0 - это вещественная часть версора.
поля кватерниона не являются константами. - x1, x2, x3 - Мнимые компоненты версора.
Это сделано намеренно, чтобы побудить разработчика использовать функции для Поля версоров объявлены как const, чтобы разработчик использовал функции библиотеки для работы с версорами, а не изменял их напрямую.
версоров, вместо того, чтобы задавать значения полей напрямую, потому что
функции версоров обеспечивают, чтобы модуль версора был равен единице.
В то же время, разработчик может обращаться к полям версора, чтобы получить
значения этих полей для своих целей, например, чтобы сделать какие-либо
вычисления или сохранить состояние версора в файле, или передать версор через
подключение по компьютерной сети.
Поля кватернионов разработчик, использующий библиотеку, может менять свободно.

18
docs/versor-eng.md
View file

@ -2,11 +2,13 @@
[Quaternions](./quaternion-eng.md) are hypercomplex numbers that have one real component and three imaginary components: [Quaternions](./quaternion-eng.md) are hypercomplex numbers that have one real component and three imaginary components:
q = w + ix + jy + kz, where w is the real component, x, y, z are the imaginary components, and i, j, k are the imaginary units q = w + ix + jy + kz
i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1 where:
w, x, y, z &isin; R - w, x, y, z &isin; 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
Quaternions were discovered by mathematician William Hamilton and introduced to the public in 1843. Hamilton later proposed a special class of quaternions, which he called versors. Quaternions were discovered by mathematician William Hamilton and introduced to the public in 1843. Hamilton later proposed a special class of quaternions, which he called versors.
@ -18,11 +20,10 @@ It is sufficient to add the equation of the modulus being equal to one to the fo
q = w + ix + jy + kz q = w + ix + jy + kz
i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = -1 - w, x, y, z &isin; R are real numbers
- i, j, k are imaginary units that satisfy the following conditions:
w, x, y, z &isin; R - i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1
- w<sup>2</sup> + x<sup>2</sup> + y<sup>2</sup> + z<sup>2</sup> = 1
w<sup>2</sup> + x<sup>2</sup> + y<sup>2</sup> + z<sup>2</sup> = 1
The name comes from the Latin verb "versare", meaning "to turn", "to rotate", to which the Latin ending -or is added, denoting the subject performing the action. Literally, the Latin word "versor" can be translated as "rotator" or "turner". The name comes from the Latin verb "versare", meaning "to turn", "to rotate", to which the Latin ending -or is added, denoting the subject performing the action. Literally, the Latin word "versor" can be translated as "rotator" or "turner".
@ -55,6 +56,7 @@ The BGC library provides a separate implementation for versors in the form of st
} BgcVersorFP64; } BgcVersorFP64;
``` ```
Fields:
- s0 is the real part of the versor. - s0 is the real part of the versor.
- x1, x2, x3 are the imaginary components of the versor. - x1, x2, x3 are the imaginary components of the versor.

52
docs/versor-rus.md
View file

@ -4,11 +4,12 @@
q = w + ix + jy + kz, где w - действительная компонена, x, y, z - мнимые компоненты, а i, j, k - мнимые единицы q = w + ix + jy + kz, где w - действительная компонена, x, y, z - мнимые компоненты, а i, j, k - мнимые единицы
i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1 где
- w, x, y, z &isin; R - действительные числа
- i, j, k - мнимые единицы, удовлетворяющие следующим условиям:
- i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1
w, x, y, z &isin; R Кватернионы были открыты математиком Уильямом Гамильтоном и представлены публике в 1843 году. Позже Гамильтон предложил особый класс кватернионов, которые назвал версорами.
Кватернионы были открыты математиком Уильямом Гамильтоном и представлены публике в 1843 году. Позже Гамильтон предложил особый класс кватернионов, которые назвал версорами.
## Что такое версор? ## Что такое версор?
@ -18,11 +19,11 @@ w, x, y, z &isin; R
q = w + ix + jy + kz q = w + ix + jy + kz
i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = -1 где
- w, x, y, z &isin; R - действительные числа
w, x, y, z &isin; R - i, j, k - мнимые единицы, удовлетворяющие следующим условиям:
- i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = ijk = -1
w<sup>2</sup> + x<sup>2</sup> + y<sup>2</sup> + z<sup>2</sup> = 1 - w<sup>2</sup> + x<sup>2</sup> + y<sup>2</sup> + z<sup>2</sup> = 1
Название происходит от латинского глагола "versare", означающего "поворачивать", "вращать", к которому добавлено латинское окончание -or, обозначающее субъект, выполняющий действие. Дословно латинское слово "versor" можно перевести как "вращатель" или "поворачиватель". Название происходит от латинского глагола "versare", означающего "поворачивать", "вращать", к которому добавлено латинское окончание -or, обозначающее субъект, выполняющий действие. Дословно латинское слово "versor" можно перевести как "вращатель" или "поворачиватель".
@ -57,24 +58,25 @@ w<sup>2</sup> + x<sup>2</sup> + y<sup>2</sup> + z<sup>2</sup> = 1
} BgcVersorFP64; } BgcVersorFP64;
``` ```
Поля:
- s0 - это вещественная часть версора. - s0 - это вещественная часть версора.
- x1, x2, x3 - Мнимые компоненты версора. - x1, x2, x3 - Мнимые компоненты версора.
## Операции с версорами ## Операции с версорами
- [Сброс состояния (reset)](./versor-reset-rus.md) - [Сброс состояния](./versor-reset-rus.md)
- [Указание значений компонент (set values)](./versor-set-values-rus.md) - [Указание значений компонент](./versor-set-values-rus.md)
- Копирование значений компонент (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) - Сравнение