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

# Object3D

Это базовый класс для большинства объектов в «Вердж3Д», предоставляющий набор свойств и методов для манипулирования объектами в трехмерном пространстве.

Обратите внимание, что его можно использовать для группировки объектов с помощью метода .add(object), который добавляет объект в качестве дочернего, однако для этого лучше использовать Group.

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

### Object3D()

Конструктор не принимает никаких аргументов.

## Свойства

### # .animations : AnimationClip

Массив с анимационными клипами объекта.

### # .castShadow : Boolean

Будет ли объект рендериться в карту теней. По умолчанию `false`.

### # .children : Object3D

Массив с дочерними объектами объекта. Информацию о группировании объектов см. в Group.

### # .constraints : Array

Массив ограничителей, применяемых к объекту.

### # .customDepthMaterial : Material

Пользовательский материал глубины, который будет использоваться при рендеринге на карту глубины. Может использоваться только в контексте меша. При создании теней с помощью DirectionalLight или SpotLight, если вы изменяете положение вершин в вершинном шейдере, вы должны указать пользовательский материал глубины (customDepthMaterial) для правильного рендеринга теней. По умолчанию — `undefined`.

### # .customDistanceMaterial : Material

То же, что и customDepthMaterial, но используется с PointLight. По умолчанию — `undefined`.

### # .disableChildRendering : Boolean

Если `true`, дочерние объекты не будут рендериться. По умолчанию — `false`.

### # .frustumCulled : Boolean

Если этот параметр установлен, каждый кадр перед отрисовкой объекта будет проверяться, находится ли он в пирамиде видимости камеры. В противном случае объект будет отображаться каждый кадр, даже если он не виден. По умолчанию `true`.

### # .groupNames : Array

Массив, указывающий группы, к которым принадлежит данный объект. Используется для группировки/ссылки на коллекции объектов.

### # .hidpiCompositing : Boolean

Будет ли объект ренедириться в специальном пассе с увеличенной плотностью пикселей (HiDPI compositing). По умолчанию — `false`.

### # .id : Integer

Только для чтения. Уникальный номер данного экземпляра объекта.

### # .isObject3D : Boolean

Флаг только для чтения, указывающий что данный объект является экземпляром класса Object3D.

### # .layers : Layers

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

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

### # .matrix : Matrix4

Матрица локального преобразования.

### # .matrixAutoUpdate : Boolean

Если этот параметр установлен, рендер вычисляет матрицу положения (вращения или кватерниона) и масштаба каждый кадр, а также пересчитывает свойство matrixWorld. По умолчанию Object3D.DefaultMatrixAutoUpdate (`true`).

### # .matrixWorld : Matrix4

Глобальное преобразование объекта. Если у объекта Object3D нет родителя, то оно идентично локальному преобразованию .matrix.

### # .matrixWorldAutoUpdate : Boolean

По умолчанию — `true`. Если установлен, рендер будет проверять каждый кадр, нуждается ли объект и его потомки в обновлении матриц. Если не установлен, вам нужно будет обновлять матрицы самостоятельно.

### # .matrixWorldNeedsUpdate : Boolean

Если это значение установлено, matrixWorld вычисляется в текущем кадре, затем этот флаг сбрасывается `false`. По умолчанию `false`.

### # .modelViewMatrix : Matrix4

Этот параметр передается в шейдер и используется для расчета положения объекта.

### # .name : String

Необязательное и не обязательно уникальное имя объекта. По умолчанию это пустая строка.

### # .normalMatrix : Matrix3

Эта матрица передается в шейдер и используется для расчета освещения объекта. Матрица получается транспонированием обратной верхней левой подматрицы 3x3 матрицы modelViewMatrix объекта.

Причина создания этой специальной матрицы заключается в том, что простое использование матрицы modelViewMatrix может привести к неединичной длине нормалей (при масштабировании) или неперпендикулярному направлению (при неравномерном масштабировании).

С другой стороны, часть с перемещением матрицы modelViewMatrix не имеет значения для расчета нормалей. Поэтому достаточно матрицы Matrix3.

### # .objectAlpha : Float

Альфа-канал объекта. Используется для подачи на выход шейдерной ноды «Блендера» object info.

### # .objectColor : Color

Цвет объекта. Используется для подачи на выход шейдерной ноды «Блендера» object info.

### # .objectIndex : Integer

Индекс объекта. Используется для подачи на выход шейдерной ноды «Блендера» object info.

### # .onAfterRender : Function

Необязательная функция обратного вызова, которая вызывается сразу после рендеринга объекта. Эта функция вызывается со следующими параметрами: renderer (рендерер), scene (сцена), camera(камера), geometry (геометрия), material (материал), group (группа).

Учтите, что данная функция вызывается только для объектов, которые можно «отрендерить», то есть для объектов, имеющих материал и геометрию: Mesh, Line, Points или Sprite. Экземпляры классов Object3D, Group и Bone не могут быть отрендерены, соответственно данная функция для них не вызывается.

### # .onBeforeRender : Function

Необязательная функция обратного вызова, которая вызывается непосредственно перед рендерингом объекта. Эта функция вызывается со следующими параметрами: renderer (рендерер), scene (сцена), camera(камера), geometry (геометрия), material (материал), group (группа).

Учтите, что данная функция вызывается только для объектов, которые можно «отрендерить», то есть для объектов, имеющих материал и геометрию: Mesh, Line, Points или Sprite. Экземпляры классов Object3D, Group и Bone не могут быть отрендерены, соответственно данная функция для них не вызывается.

### # .parent : Object3D

Родитель объекта в графе сцены. У объекта может быть не более одного родителя.

### # .position : Vector3

Vector3, представляющий локальную позицию объекта. По умолчанию `(0, 0, 0)`.

### # .quaternion : Quaternion

Локальное вращение объекта в виде кватерниона.

### # .receiveShadow : Boolean

Принимает ли материал тени. По умолчанию `false`.

### # .renderOrder : Float

Это значение позволяет переопределить порядок рендеринга объектов графа сцены по умолчанию, хотя непрозрачные и прозрачные объекты остаются отсортированными независимо. Когда это свойство установлено для экземпляра Group, все объекты-потомки будут отсортированы и отрисованы вместе. Сортировка производится от низшего к высшему порядку рендеринга. Значение по умолчанию — `0`.

### # .rotation : Euler

Локальное вращение объекта (см. углы Эйлера), в радианах.

### # .scale : Vector3

Локальный масштаб объекта. По умолчанию `(1, 1, 1)`.

### # .up : Vector3

Используется методом lookAt, например, для определения ориентации результата. По умолчанию это Object3D.DefaultUp — то есть `(0, 1, 0)`.

### # .userData : Object

Объект, который можно использовать для хранения пользовательских данных. Он не должен содержать ссылки на функции, так как они не будут клонироваться.

### # .uuid : String

UUID данного экземпляра объекта. Он присваивается автоматически, поэтому его не следует редактировать.

### # .visible : Boolean

Объект отображается, если `true`. По умолчанию `true`.

Это свойство не влияет на рендеринг дочерних объектов (за исключением мешей, входящих в мульти-материальный объект). Чтобы запретить их рендеринг, используйте свойство .disableChildRendering.

## Статические свойства

Статические свойства и методы определяются для каждого класса, а не для каждого экземпляра этого класса. Это означает, что изменение Object3D.DefaultUp или Object3D.DefaultMatrixAutoUpdate изменит значения up и matrixAutoUpdate для каждого экземпляра Object3D (или производных классов), созданный после внесения изменения (уже созданные Object3D не будут затронуты).

### # .DefaultUp : Vector3

Направление по умолчанию up для объектов, также используется как положение по умолчанию для DirectionalLight и Spotlight (которые создают свет, светящий сверху вниз). По умолчанию имеет значение `(0, 1, 0)`.

### # .DefaultMatrixAutoUpdate : Boolean

Настройка по умолчанию для matrixAutoUpdate для вновь созданных Object3D.

## Методы

Для данного класса также доступны методы родительского класса EventDispatcher.

### # .add(object : Object3D, ...) → this

Добавляет `object` в качестве дочернего объекта данного объекта. Может быть добавлено произвольное количество объектов. Любой текущий родитель объекта, переданного здесь, будет удален, так как объект может иметь не более одного родителя.

Информацию о ручном группировании объектов см. в Group.

### # .applyMatrix4(matrix : Matrix4)

Применяет матричное преобразование к объекту и обновляет положение, поворот и масштаб объекта.

### # .applyQuaternion(quaternion : Quaternion) → this

Применяет к объекту вращение, представленное кватернионом.

### # .attach(object : Object3D) → this

Добавляет `object` в качестве дочернего объекта, сохраняя положение объекта в мировой системе координат.

Метод не поддерживает графы сцен, включающие объект с неоднородными масштабированиями (по осям).

### # .clone(recursive : Boolean) → Object3D

recursive — если `true`, потомки объекта также клонируются. По умолчанию — `true`.

Возвращает клон этого объекта и, по желанию, всех потомков.

### # .copy(object : Object3D, recursive : Boolean) → this

recursive — если `true`, потомки объекта также копируются. По умолчанию — `true`.

Копирует заданный объект в этот объект. Примечание: обработчики событий и обратные вызовы (.onAfterRender и .onBeforeRender) не копируются.

### # .getObjectById(id : Integer) → Object3D

id — уникальный номер экземпляра объекта

Выполняет поиск объекта и его дочерних элементов, начиная с самого объекта, и возвращает первый с совпадающим `id`. Обратите внимание, что идентификаторы присваиваются в хронологическом порядке: 1, 2, 3, ..., увеличиваясь на единицу для каждого нового объекта.

### # .getObjectByName(name : String) → Object3D

name — строка для сопоставления с дочерним свойством Object3D.name.

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

### # .getObjectByProperty(name : String, value : Float) → Object3D

- name — имя свойства для поиска.
- value — значение данного свойства.

Выполняет поиск по объекту и его дочерним объектам, начиная с самого объекта, и возвращает первый объект, свойство которого соответствует заданному значению.

### # .getObjectsByProperty(name : String, value : Any) → Object3D

- name — the property name to search for.
- value — value of the given property.

Searches through an object and its children, starting with the object itself, and returns all the objects with a property that matches the value given.

### # .getWorldDirection(target : Vector3) → Vector3

target — результат будет скопирован в этот Vector3.

Возвращает вектор, представляющий направление положительной оси z объекта в мировом пространстве.

### # .getWorldEuler(target : Euler, order : String) → Euler

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

Возвращает эйлеровский угол поворота объекта в мировой системе координат.

### # .getWorldPosition(target : Vector3) → Vector3

target — результат будет скопирован в этот Vector3.

Возвращает вектор положения объекта в мировой системе координат.

### # .getWorldQuaternion(target : Quaternion) → Quaternion

target — результат будет скопирован в этот кватернион.

Возвращает кватернион вращения объекта в мировой системе координат.

### # .getWorldScale(target : Vector3) → Vector3

target — результат будет скопирован в этот Vector3.

Возвращает вектор масштабирования, применяемого к объекту для каждой оси в мировом пространстве.

### # .localToWorld(vector : Vector3) → Vector3

vector — вектор, представляющий позицию в локальном пространстве этого объекта.

Преобразует вектор из локального пространства этого объекта в мировое пространство.

### # .lookAt(vector : Vector3)
# .lookAt(x : Float, y : Float, z : Float)

- vector — вектор, представляющий позицию в мировом пространстве.
- необ. компоненты x, y и z положения в мировом пространстве.

Поворачивает объект лицом к точке в мировом пространстве.

Этот метод не поддерживает объекты с неоднородно масштабированными родителями.

### # .raycast(raycaster : Raycaster, intersects : Array) → Array

Абстрактный (пустой) метод для получения пересечений между брошенным лучом и данным объектом. Подклассы, такие как Mesh, Line и Points, реализуют этот метод, чтобы реализовать функцию трассировки лучей.

### # .remove(object : Object3D, ...) → this

Удаляет `object` как дочерний объект данного объекта. Может быть удалено произвольное количество объектов.

### # .removeFromParent() → this

Удаляет объект из своего родителя.

### # .clear() → this

Удаляет все дочерние объекты.

### # .rotateOnAxis(axis : Vector3, angle : Float) → this

- axis — нормированный вектор в пространстве объекта.
- angle — угол в радианах.

Осуществляет поворот объекта вдоль оси в пространстве объекта. Предполагается, что ось нормализована.

### # .rotateOnWorldAxis(axis : Vector3, angle : Float) → this

- axis — нормированный вектор в мировом пространстве.
- angle — угол в радианах.

Осуществляет поворот объекта вдоль оси в мировом пространстве. Предполагается, что ось нормализована. Метод предполагает отсутствие поворота родителя.

### # .rotateX(rad : Float) → this

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

Поворачивает объект вокруг оси X в локальном пространстве.

### # .rotateY(rad : Float) → this

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

Поворачивает объект вокруг оси Y в локальном пространстве.

### # .rotateZ(rad : Float) → this

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

Поворачивает объект вокруг оси Z в локальном пространстве.

### # .setRotationFromAxisAngle(axis : Vector3, angle : Float)

- axis — нормированный вектор в пространстве объекта.
- angle — угол в радианах.

Вызывает setFromAxisAngle(axis, angle) на .quaternion.

### # .setRotationFromEuler(euler : Euler)

euler — угол Эйлера, определяющий величину поворота.

Вызывает setRotationFromEuler(euler) на .quaternion.

### # .setRotationFromMatrix(m : Matrix4)

m — повернуть кватернион по компоненту вращения матрицы.

Вызывает setFromRotationMatrix(m) на .quaternion. Обратите внимание, что это предполагает, что верхние 3x3 из `m` являются чистой матрицей вращения (т.е. немасштабированной).

### # .setRotationFromQuaternion(q : Quaternion)

q — нормализованный кватернион.

Копирует поворот объекта из заданного кватерниона в .quaternion.

### # .translateOnAxis(axis : Vector3, distance : Float) → this

- axis — нормализованный вектор в пространстве объекта.
- distance — расстояние для перевода.

Переносит объект на расстояние вдоль оси в пространстве объекта. Предполагается, что ось нормализована.

### # .translateX(distance : Float) → this

Перемещает объект вдоль оси X в пространстве объекта на `distance` единиц.

### # .translateY(distance : Float) → this

Переводит объект вдоль оси Y в пространстве объекта на `distance` единиц.

### # .translateZ(distance : Float) → this

Перемещает объект вдоль оси Z в пространстве объекта на `distance` единиц.

### # .traverse(callback : Function)

callback — функция обратного вызова, первым аргументом которой является объект Object3D.

Выполняет функцию для этого объекта и всех потомков. Примечание: не рекомендуется изменять граф сцены внутри обратного вызова.

### # .traverseVisible(callback : Function)

callback — функция, первым аргументом которой является объект Object3D.

Аналогично traverse, но функция будет выполняться только для видимых объектов. Потомки невидимых объектов не обходятся. Примечание: Не рекомендуется изменять граф сцены внутри обратного вызова.

### # .traverseAncestors(callback : Function)

callback — функция обратного вызова, первым аргументом которой является объект Object3D.

Выполняет функцию для всех родителей объекта. Примечание: не рекомендуется изменять граф сцены внутри обратного вызова.

### # .updateMatrix()

Обновляет матрицу локального положения объекта.

### # .updateMatrixWorld(force : Boolean)

force — логическое значение, используемое чтобы пропустить требование флага .matrixWorldAutoUpdate и принудительно обновить матрицу. Полезно указывать, если вы не хотите ждать одного кадра для обновления матрицы (предполагая что .matrixWorldAutoUpdate установлен в `true`).

Обновляет матрицу мирового положения объекта и его потомков если .matrixWorldNeedsUpdate установлен в `true` или если флаг `force` также установлен в `true`.

### # .updateWorldMatrix(updateParents : Boolean, updateChildren : Boolean)

- updateParents — рекурсивно обновляет мировое положение родителей.
- updateChildren — рекурсивно обновляет мировое положение потомков.

Обновляет матрицу мирового положения объекта.

### # .worldToLocal(vector : Vector3) → Vector3

vector — вектор, представляющий положение в мировом пространстве.

Преобразует вектор из мирового пространства в локальное пространство этого объекта.

## Пазлы

«Вердж3Д» поддерживает множество пазлов, упрощающих работу с 3Д-объектами.

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

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