Matrix4 - Руководство по Вердж3Д - Софт Эйт Софт
Description: Узнайте как использовать Matrix4 в интерактивных 3Д-веб-приложениях сделанных на Вердж3Д

# Matrix4

Класс представляющий матрицу 4x4.

Наиболее распространенное использование матрицы 4x4 в трехмерной компьютерной графике - в качестве матрицы трансформации.

Это позволяет вектору, представляющему точку в трехмерном пространстве, подвергаться преобразованиям, таким как перенос, поворот, сдвиг, масштаб, отражение, получение ортогональной или перспективной проекции и так далее, путем умножения на матрицу. Это известно как применение матрицы к вектору.

Каждый Object3D имеет три связанные с ним матрицы 4x4:

- Object3D.matrix: Здесь хранится локальное преобразование объекта. Это преобразование объекта относительно его родителя.
- Object3D.matrixWorld: Глобальное или мировое преобразование объекта. Если у объекта нет родителя, то оно идентично локальному преобразованию, хранящемуся в matrix.
- Object3D.modelViewMatrix: Это представляет собой преобразование объекта относительно системы координат камеры. Матрица ModelViewMatrix объекта - это matrixWorld объекта, предварительно умноженная на matrixWorldInverse камеры.

Объекты камер имеют три дополнительные матрицы 4x4:

- Camera.matrixWorldInverse: Матрица вида - обратная матрице камеры matrixWorld.
- Camera.projectionMatrix: Представляет информацию о том, как спроецировать сцену.
- Camera.projectionMatrixInverse: Инверсия от projectionMatrix.

Примечание: Object3D.normalMatrix это матрица 3x3 (Matrix3), а не 4x4.

## Замечание о порядке следования строк и столбцов

Метод set() принимает аргументы в порядке row-major а внутри массива elements они хранятся в главном порядке столбцов.

Это означает, что вызов

`const m = new v3d.Matrix4(); m.set(11, 12, 13, 14, 21, 22, 23, 24, 31, 32, 33, 34, 41, 42, 43, 44);`

приведет к тому, что массив elements будет содержать:

`m.elements = [11, 21, 31, 41, 12, 22, 32, 42, 13, 23, 33, 43, 14, 24, 34, 44];`

и внутри все вычисления выполняются с использованием упорядочивания по столбцам. Однако, поскольку фактический порядок не имеет математического значения, а большинство людей привыкли думать о матрицах в порядке возрастания строк, в документации «Вердж3Д» матрицы показаны в порядке возрастания строк. Просто имейте в виду, что если вы читаете исходный код, вам придется сделать транспонирование любых матриц, описанных здесь, чтобы понять смысл вычислений.

## Извлечение положения, поворота и масштаба

Существует несколько вариантов извлечения позиции, поворота и масштабирования из Matrix4.

- Vector3.setFromMatrixPosition: можно использовать для извлечения компонента положения.
- Vector3.setFromMatrixScale: можно использовать для извлечения компонента масштаба.
- Quaternion.setFromRotationMatrix, Euler.setFromRotationMatrix или extractRotation можно использовать для извлечения компонента поворота из чистой (немасштабированной) матрицы.
- decompose можно использовать для одновременного извлечения положения, поворота и масштаба.

## Конструктор

### Matrix4()

Создает и инициализирует Matrix4 в 4x4 единичную матрицу.

## Свойства

### # .elements : Array

column-major список значений матрицы.

## Методы

### # .clone() → Matrix4

Создает новую Matrix4 с элементами elements, идентичными данной.

### # .compose(position : Vector3, quaternion : Quaternion, scale : Vector3) → this

Устанавливает преобразование матрицы, состоящее из position, quaternion и scale.

### # .composeE(position : Vector3, euler : Euler, scale : Vector3) → this

Устанавливает преобразование матрицы, состоящее из position, euler и scale.

### # .copy(m : Matrix4) → this

Копирует элементы матрицы m в данную матрицу.

### # .copyPosition(m : Matrix4) → this

Копирует компонент перемещения предоставленной матрицы m в компонент перемещения текущей матрицы.

### # .decompose(position : Vector3, quaternion : Quaternion, scale : Vector3) → this

Раскладывает текущую матрицу на компоненты position, quaternion и scale.

Замечание: не все матрицы могут быть разложены такоим образом. В частности, метод не может быть использован для разложения мировой матрицы объекта, если его родитель имеет неоднородный масштаб.

### # .decomposeE(position : Vector3, euler : Euler, scale : Vector3) → this

order — порядок углов Эйлера, используемый для разложения параметра `euler`. По умолчанию `euler._order`.

Раскладывает текущую матрицу на компоненты position, euler и scale.

### # .determinant() → Float

Вычисляет и возвращает определитель (детерминант) матрицы.

### # .equals(m : Matrix4) → Boolean

Возвращает `true`, если текущая матрица и m равны.

### # .extractBasis(xAxis : Vector3, yAxis : Vector3, zAxis : Vector3) → this

Извлекает базис текущей матрицы в три предоставленных вектора осей. Если эта матрица вида:

`a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p`

то для xAxis, yAxis, zAxis будут установлены значения:

`xAxis = (a, e, i) yAxis = (b, f, j) zAxis = (c, g, k)`

### # .extractRotation(m : Matrix4) → this

Извлекает компонент вращения предоставленной матрицы m в компонент вращения текущей матрицы.

### # .fromArray(array : Array, offset : Integer) → this

- array — массив для чтения элементов из него.
- offset — (необязательное) смещение в массиве. По умолчанию равно `0`.

Устанавливает элементы текущей матрицы на основе массива в формате column-major.

### # .invert() → this

Инвертирует текущую матрицу, используя аналититический метод.

Вы не можете инвертировать с детерминантом, равным нулю. Если вы попытаетесь это сделать, метод выдаст нулевую матрицу.

### # .getMaxScaleOnAxis() → Float

Получает максимальное значение масштаба по 3 осям.

### # .identity() → this

Сбрасывает данную матрицу в единичную матрицу.

### # .lookAt(eye : Vector3, center : Vector3, up : Vector3,) → this

Строит матрицу вращения, направленную от eye к center, ориентированную вектором up.

### # .makeRotationAxis(axis : Vector3, theta : Float) → this

- axis — Ось вращения, должна быть нормализована.
- theta — Угол поворота в радианах.

Устанавливает текущую матрицу как преобразование вращения вокруг axis на theta радиан.

Это несколько спорная, но математически обоснованная альтернатива вращению через кватернионы.

### # .makeBasis(xAxis : Vector3, yAxis : Vector3, zAxis : Vector3) → this

Установить текущую матрицу в базисную матрицу, состоящую из трех предоставленных базисных векторов:

`xAxis.x, yAxis.x, zAxis.x, 0, xAxis.y, yAxis.y, zAxis.y, 0, xAxis.z, yAxis.z, zAxis.z, 0, 0, 0, 0, 1`

### # .makePerspective(left : Float, right : Float, top : Float, bottom : Float, near : Float, far : Float) → this

Создает матрицу перспективной проекции. Используется внутри метода PerspectiveCamera.updateProjectionMatrix()

### # .makeOrthographic(left : Float, right : Float, top : Float, bottom : Float, near : Float, far : Float) → this

Создает матрицу ортогональной проекции. Используется внутри метода OrthographicCamera.updateProjectionMatrix().

### # .makeRotationFromEuler(euler : Euler) → this

Устанавливает компонент вращения (левая верхняя матрица 3x3) текущей матрицы на поворот, заданный углами Эйлера. Остальная часть матрицы устанавливается в единичную матрицу. В зависимости от пордяка углов Эйлера возможны шесть исходов. Полный список смотрите здесь.

### # .makeRotationFromQuaternion(q : Quaternion) → this

Устанавливает компонент вращения текущей матрицы на вращение, заданное q, как описано здесь. Остальная часть матрицы устанавливается в единичную матрицу. Таким образом, при задании q = w + xi + yj + zk результирующая матрица будет иметь вид:

`1-2y²-2z² 2xy-2zw 2xz+2yw 0 2xy+2zw 1-2x²-2z² 2yz-2xw 0 2xz-2yw 2yz+2xw 1-2x²-2y² 0 0 0 0 1`

### # .makeRotationX(theta : Float) → this

theta — угол поворота в радианах.

Устанавливает текущую матрицу как вращательное преобразование вокруг оси X на theta (θ) радиан. Результирующая матрица будет иметь вид:

`1 0 0 0 0 cos(θ) -sin(θ) 0 0 sin(θ) cos(θ) 0 0 0 0 1`

### # .makeRotationY(theta : Float) → this

theta — угол поворота в радианах.

Устанавливает текущую матрицу как вращательное преобразование вокруг оси Y на theta (θ) радиан. Результирующая матрица будет иметь вид:

`cos(θ) 0 sin(θ) 0 0 1 0 0 -sin(θ) 0 cos(θ) 0 0 0 0 1`

### # .makeRotationZ(theta : Float) → this

theta — угол поворота в радианах.

Устанавливает текущую матрицу как вращательное преобразование вокруг оси Z на theta (θ) радиан. Результирующая матрица будет иметь вид:

`cos(θ) -sin(θ) 0 0 sin(θ) cos(θ) 0 0 0 0 1 0 0 0 0 1`

### # .makeScale(x : Float, y : Float, z : Float) → this

- x — величина масштабирования по оси X.
- y — величина масштабирования по оси Y.
- z — величина масштабирования по оси Z.

Устанавливает преобразование маштабирования в текущую матрицу:

`x, 0, 0, 0, 0, y, 0, 0, 0, 0, z, 0, 0, 0, 0, 1`

### # .makeShear(xy : Float, xz : Float, yx : Float, yz : Float, zx : Float, zy : Float) → this

- xy — величина сдвига X относительно Y.
- xz — величина сдвига X относительно Z.
- yx — величина сдвига Y относительно X.
- yz — величина сдвига Y относительно Z.
- zx — величина сдвига Z относительно X.
- zy — величина сдвига Z относительно Y.

Устанавливает преобразование сдвига в текущую матрицу:

`1, yx, zx, 0, xy, 1, zy, 0, xz, yz, 1, 0, 0, 0, 0, 1`

### # .makeTranslation(x : Float, y : Float, z : Float) → this

- x — значение перемещения по оси X.
- y — значение перемещения по оси Y.
- z — значение перемещения по оси Z.

Устанавливает преобразование перемещения в текущую матрицу:

`1, 0, 0, x, 0, 1, 0, y, 0, 0, 1, z, 0, 0, 0, 1`

### # .multiply(m : Matrix4) → this

Умножает текущую матрицы на m справа

### # .multiplyMatrices(a : Matrix4, b : Matrix4) → this

Устанавливает текущую матрицу в a x b.

### # .multiplyScalar(s : Float) → this

Умножает каждый компонент матрицы на скалярное значение s.

### # .premultiply(m : Matrix4) → this

Умножает текущую матрицу на m слева.

### # .scale(v : Vector3) → this

Умножает столбцы текущей матрицы на вектор v.

### # .set(n11 : Float, n12 : Float, n13 : Float, n14 : Float, n21 : Float, n22 : Float, n23 : Float, n24 : Float, n31 : Float, n32 : Float, n33 : Float, n34 : Float, n41 : Float, n42 : Float, n43 : Float, n44 : Float) → this

Устанавливает elements текущей матрицы в заданные значения row-major n11, n12, ... n44.

### # .setFromMatrix3(m : Matrix3) → this

Устанавливает левые верхние элементы 3x3 текущей матрицы из матрицы m.

### # .setPosition(v : Vector3) → this

### # .setPosition(x : Float, y : Float, z : Float) → this // другой вариант вызова

Устанавливает компонент позиции для текущей матрицы из вектора v, не затрагивая остальную часть матрицы - т.е. если матрица находится в текущем состоянии:

`a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p`

Она становится:

`a, b, c, v.x, e, f, g, v.y, i, j, k, v.z, m, n, o, p`

### # .toArray(array : Array, offset : Integer) → Array

- array — (необ.) массив для хранения результирующего вектора.
- offset — (необязательное) смещение в результирующем массиве.

Записывает элементы текущей матрицы в массив в column-major формате.

### # .transpose() → this

Транспонирует текущую матрицу.

## Исходный файл

О том как получить исходный код этого модуля читайте тут.