Raycaster

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

Пример


    const raycaster = new v3d.Raycaster();
    let pointer = null;

    function onPointerMove(event) {
        pointer = pointer || new v3d.Vector2(-1, -1);
        // рассчитываем позицию курсора в нормализованных координатах устройства
        // (-1 to +1) для обоих компонентов
        pointer.x = (event.offsetX / app.getWidth()) * 2 - 1;
        pointer.y = -(event.offsetY / app.getHeight()) * 2 + 1;
    }

    function pick() {
        // не используем позицию без инициализации
        if (!pointer)
            return;

        // обновляем луч на основе камеры и позиции курсора
        raycaster.setFromCamera(pointer, app.camera);

        // определяем объекты, пересекающие луч
        const intersects = raycaster.intersectObjects(app.scene.children);
        for (let i = 0; i < intersects.length; i++) {
            intersects[i].object.visible = false;
        }
    }

    app.container.addEventListener('pointermove', onPointerMove);
    app.renderCallbacks.push(pick);

Конструктор

Raycaster(origin : Vector3, direction : Vector3, near : Float, far : Float) {

origin — вектор начала координат, из которого отбрасывается луч.
direction — вектор направления, задающий направление луча. Должен быть нормализован.
near — возвращаемые результаты будут находиться дальше, чем near. Near не может быть отрицательным. Значение по умолчанию 0.
far — возвращаемые результаты будут находиться ближе, чем far. Far не может быть меньше, чем near. Значение по умолчанию Infinity (бесконечность).

Создает новый Raycaster-объект.

Свойства

# .far : Float

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

# .near : Float

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

# .camera : Camera

Камера, которую следует использовать при создании лучей для объектов, зависящих от вида, таких как объекты с билбордами, например Sprites. Это поле может быть задано вручную или устанавливается при вызове .setFromCamera(). По умолчанию имеет значение null.

# .layers : Layers

Используется Raycaster для выборочного игнорирования 3Д-объектов при выполнении тестов пересечения. Следующий код гарантирует, что экземпляр Raycaster будет учитывать только 3Д-объекты на слое 1.


    raycaster.layers.set(1);
    object.layers.enable(1);

# .params : Object

Объект со следующими свойствами:


    {
        Mesh: { omitGeometry: false },
        Line: { threshold: 1 },
        LOD: {},
        Points: { threshold: 1 },
        Sprite: {},
        checkVisibility: true
    }

Где threshold — это точность рейкастинга при пересечении объектов в мировых единицах. Указание omitGeometry=true позволяет направлять лучи только на ограничители мешей (а не на саму геометрию), что обеспечивает высокую производительность. Параметр checkVisiblity позволяет включать/отключать наведение лучей на невидимые объекты.

# .ray : Ray

Луч используемый для рейкастинга.

Методы

# .set(origin : Vector3, direction : Vector3)

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

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

# .setFromCamera(coords : Vector2, camera : Camera)

coords — 2Д-координаты мыши в нормализованных координатах устройства (NDC) — компоненты X и Y должны быть в пределах от -1 до 1.
camera — камера, из которой должен исходить луч.

Обновляет луч с новым началом и направлением.

# .intersectObject(object : Object3D, recursive : Boolean, optionalTarget : Array) → Array

object — объект, который нужно проверить на пересечение с лучом.
recursive — если true, то проверяются также все потомки. В противном случае проверяется только пересечение с объектом. По умолчанию true.
optionalTarget — (необ.) цель для установки результата. В противном случае создается новый Array. Если задан, то перед каждым вызовом необходимо очищать этот массив (т.е. array.length = 0;).

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


    [{ distance, point, face, faceIndex, object }, ...]

distance – расстояние между началом луча и точкой пересечения.
point – точка пересечения, в мировых координатах.
face – пересекаемая поверхность.
faceIndex – индекс пересекаемой грани.
object – пересекаемый объект.
uv — U,V координаты в точке пересечения.
uv2 — второй набор координат U,V в точке пересечения.

Raycaster делегирует метод raycast переданного объекта, когда оценивает, пересекает ли луч объект или нет. Это позволяет meshes реагировать на отбрасывание лучей иначе, чем lines и pointclouds.

Обратите внимание, что для мешей грани должны быть направлены к ориджину ray, чтобы быть обнаруженными; пересечения луча, проходящего через заднюю часть грани, не будут обнаружены. Чтобы направить луч на обе грани объекта, нужно установить свойство material side в v3d.DoubleSide.

# .intersectObjects(objects : Array, recursive : Boolean, optionalTarget : Array) → Array

objects — объекты для проверки пересечения с лучом.
recursive — Если true, то также проверяются все потомки объектов. В противном случае проверяется только пересечение с объектами. По умолчанию true.
optionalTarget — (необ.) цель для установки результата. В противном случае создается новый Array. Если задан, то перед каждым вызовом необходимо очищать этот массив (т.е. array.length = 0;).

Проверяет все пересечения между лучом и объектами с потомками или без них. Пересечения возвращаются отсортированными по расстоянию, сначала возвращаются ближайшие. Пересечения имеют ту же форму, что и те, которые возвращает .intersectObject.

Пазлы

Пазл raycast может использоваться для осуществления рейкастинга без программирования.

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

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