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
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.

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)
В такой форме кватернион напоминает четырёхмерный вектор. И кватернионы
действительно имеют ряд сходств с четрырёхмерными векторами, например:
* сложение и вычитание кватернионов такие же, как и у четырёхмерных векторов;
* умножение и деление кватериона на действительное число такие же как и для
четырёхмерного вектора;
* взятие модуля кватерниона вычисляется также как и для четырёхмерного вектора.
Но произведение кватернионов совершенно иное, чем скалярное произведение двух
четырёхмерных векторов.
Ещё одним способом представления кватерниона является пара из действительного
числа и трёхмерного вектора:
![Кватернион как число и вектор](./media/quaternion_mixed_form.png)
Кватернионы обладают массой интересных свойств и применений. В геометрии
основным применением является описание поворотов в трёхмерном евклидовом
пространстве.
Обычно для представления поворотов используются кватернионы с модулем, равным
единице. Такие кватернионы называются [версорами](./versor-rus.md).
Кватернионы были открыты математиком Уильямом Гамильтоном и представлены публике в 1843 году. Они нашли широкое применение в компьютерной графике, робототехнике и физике для описания поворотов в трёхмерном пространстве.
## Реализация кватернионов в библиотеке
В библиотеке кватернионы реализованы в двух вариантах:
* в виде обычных кватернионов
* в виде веросоров
Библиотека предоставляет две реализации кватернионов:
1. **Кватернионы общего назначения**
- Поддерживают все основные операции (сложение, вычитание, умножение на скаляр и т.д.).
Главное отличие в реализации кватернионов и версоров том, что реализация
версоров ориентирована именно для представления поворотов в трёхмерном
евклидовом пространстве пространстве, в то время как кватернионы имеют более
общую реализацию.
2. **Версоры**:
- Специализированные кватернионы, модуль которых всегда равен единице.
- Подходят для описания поворотов в трёхмерном пространстве.
- Не поддерживают операции сложения, вычитания и умножения на скаляр.
Версоры нельзя складывать, вычитать. Также версоры нельзя умножать и делить на
вещественные числа. Но кватернионы можно складывать, вычитать, а также умножать
и делить на вещественное число.
Кватернионы общего назначения также можно использовать для представления поворотов в трёхмерном пространстве. Но разработчик, использующий кватернионы для описания поворотов, сам должен следить за тем, чтобы модули кватернионов не становились меньше величины погрешности и не принимали значение NaN (не число).
Версоры можно комбинировать. Операция комбинирования версоров является обычным
произведением кватернионов. Единственное отличие в том, что операция
комбинирования версоров обеспечивает, чтобы результат комбинации также имел
модуль, равный единицы.
### Структуры для кватернионов
Все функции версоров, которые менияют состояние версора, обеспечивают, чтобы
модуль версора оставался близким к единице.
Да, модуль версора очень близок к единице, потому что числа с плавающей запятой
не совершенны и имеют небольшие погрешности. Поэтому модуль не всегда равен
единице, но очень близок к единице.
Для описаия кватернионов есть две структуры:
#### Кватернионы общего назначения
```c
typedef struct {
float s0, x1, x2, x3;
} BgcQuaternionFP32;
@ -72,10 +37,11 @@
typedef struct {
double s0, x1, x2, x3;
} BgcQuaternionFP64;
```
#### Версоры
Для описания версоров также имеется две структуры:
```c
typedef struct {
const float s0, x1, x2, x3;
} BgcVersorFP32;
@ -83,17 +49,12 @@
typedef struct {
const double s0, x1, x2, x3;
} 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:
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.
@ -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
i<sup>2</sup> = j<sup>2</sup> = k<sup>2</sup> = -1
w, x, y, z &isin; R
w<sup>2</sup> + x<sup>2</sup> + y<sup>2</sup> + z<sup>2</sup> = 1
- 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
- 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".
@ -55,6 +56,7 @@ The BGC library provides a separate implementation for versors in the form of st
} BgcVersorFP64;
```
Fields:
- s0 is the real part of the versor.
- x1, x2, x3 are the imaginary components of the versor.

50
docs/versor-rus.md
View file

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