Table of Contents

Пользовательская реализация камеры в unity —— внешний источник данных кадров

Через внешний источник данных кадров (ExternalFrameSource), разработчики могут расширить пользовательскую реализацию камеры для EasyAR Sense, поддерживая тем самым определенные устройства шлемов виртуальной реальности или другие устройства ввода. Дальнейшее содержание описывает структуру типов и определения интерфейсов внешнего источника данных кадров.

Перед началом

Типы внешних источников данных кадров

---
  config:
    class:
      hideEmptyMembersBox: true
---
classDiagram
  class FrameSource {
    <<abstract>>
  }
  class ExternalFrameSource {
    <<abstract>>
  }
  class ExternalDeviceFrameSource  {
    <<abstract>>
  }
  class ExternalDeviceMotionFrameSource:::EasyAR {
    <<abstract>>
  }
  class ExternalDeviceRotationFrameSource:::EasyAR {
    <<abstract>>
  }
  class ExternalImageStreamFrameSource:::EasyAR {
    <<abstract>>
  }

  ExternalFrameSource --|> FrameSource
  ExternalDeviceFrameSource --|> ExternalFrameSource
  ExternalDeviceMotionFrameSource --|> ExternalDeviceFrameSource
  ExternalDeviceRotationFrameSource --|> ExternalDeviceFrameSource
  ExternalImageStreamFrameSource --|> ExternalFrameSource
  
  classDef EasyAR fill:#6e6ce6,stroke:#333,color:#fff

На схеме показана иерархия типов внешних источников данных кадров.

В зависимости от входных данных, внешние источники делятся на две категории:

  • Расширения для ввода изображений и данных о движении устройства
    • Реализуются через наследование ExternalDeviceMotionFrameSource: устройство и его SDK обеспечивают 6DoF-трекинг. Трансформация виртуальной камеры и управление выполняются SDK устройства.
    • Реализуются через наследование ExternalDeviceRotationFrameSource: устройство и его SDK обеспечивают 3DoF-трекинг вращения. Трансформация виртуальной камеры и управление выполняются SDK устройства.
  • Расширения для ввода изображений
    • Реализуются через наследование ExternalImageStreamFrameSource: обеспечивают только ввод изображений. Трансформация виртуальной камеры и управление выполняются EasyAR.

Доступные функции AR различаются для типов источников:

  • Расширение для изображений и данных о движении ExternalDeviceMotionFrameSource
    • Mega
    • Motion tracking (обеспечивается устройством)
    • Sparse spatial map
    • Dense spatial map
    • Image tracking (с поддержкой слияния данных о движении)
    • Cloud image recognition
    • Object tracking (с поддержкой слияния данных о движении)
  • Расширение для изображений и данных о вращении ExternalDeviceRotationFrameSource
    • Mega
    • Image tracking (без слияния данных о движении)
    • Cloud image recognition
    • Object tracking (без слияния данных о движении)
  • Расширение для ввода изображений ExternalImageStreamFrameSource
    • Image tracking (без слияния данных о движении)
    • Cloud image recognition
    • Object tracking (без слияния данных о движении)

Внешние источники данных кадров интерфейс определение

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

Определение устройства

  • FrameSource.IsHMD: Определяет, является ли устройство гарнитурой виртуальной реальности
    Устанавливается true только на гарнитурах виртуальной реальности.
    Если устройство является гарнитурой, диагностическая информация будет отображаться на 3D-планке перед камерой, а не на экране. Некоторые функции AR работают с небольшими отличиями на гарнитурах.

  • FrameSource.Display: Определяет систему отображения
    Предоставляет информацию о текущем отображении, такую как вращение.
    Для получения информации о дисплее по умолчанию можно использовать Display.DefaultSystemDisplay или Display.DefaultHMDDisplay.
    Обычно на гарнитурах можно использовать Display.DefaultHMDDisplay.

Дополнительных настроек нет.

Доступность

  • FrameSource.IsAvailable: Доступность (Availability)
    Используется для определения, доступен ли источник кадров (frame source) для использования.
    Если источник кадров недоступен на текущем устройстве или в текущей среде выполнения, это значение должно быть false.
    Если это значение равно Optional\<bool\>.Empty, будет вызвана корутина FrameSource.CheckAvailability(). Перед завершением работы этой корутины необходимо обновить значение FrameSource.IsAvailable.
    Интерфейс доступности используется во время сборки сессии (session); недоступные компоненты не будут выбраны, и их методы не будут вызываться во время работы сессии.
  • FrameSource.CheckAvailability() (опционально): Корутина для проверки доступности источника кадров
    Вызывается, когда FrameSource.IsAvailable равно Optional\<bool\>.Empty. Процесс сборки сессии будет заблокирован до завершения работы этой корутины.

session происхождения

  • ExternalDeviceFrameSource.OriginType：Тип происхождения

    • XROrigin：SDK устройства использует Unity.XR.CoreUtils.XROrigin как происхождение.
    • Custom：SDK устройства использует кастомное происхождение. Требуется указать ExternalDeviceFrameSource.Origin.
    • None：SDK устройства не определяет происхождение. В этом случае происхождение будет автоматически выбрано или создано из сцены, но не будет перемещаться.
      Сессия будет поддерживать только центральный режим SessionOrigin. Разработчикам приложений следует быть осторожными с размещением виртуальных объектов, так как все цели и их содержимое будут постоянно двигаться в системе координат Unity. Некоторые функции пользователя (например, физическая система) могут работать некорректно. Объекты, помещённые в мировую систему координат Unity, никогда не отобразятся правильно при любой конфигурации.

  • ExternalDeviceFrameSource.Origin：Объект происхождения
    Определите собственное происхождение только если ExternalDeviceFrameSource.OriginType имеет значение Custom. В остальных случаях не требуется переопределение.

Виртуальная камера

  • FrameSource.Camera: Виртуальная камера
    Камера не управляется сессией. Трансформация камеры, матрица проекции и рендеринг фонового изображения должны управляться внешним кодом.
    Используется только на гарнитурах для отображения диагностического текста перед глазами.
    Не требует определения, если ExternalDeviceFrameSource.OriginType имеет значение XROrigin. EasyAR автоматически использует камеру, определённую в Unity XR framework.

Физическая камера

  • FrameSource.DeviceCameras: Параметры физической камеры
    Физическая камера, предоставляющая данные кадров. Если данные кадров поступают от нескольких камер, список должен включать все физические камеры.
    Необходимо гарантировать, что параметры физической камеры доступны корректно при FrameSource.CameraFrameStarted равном true.
  • FrameSource.CameraFrameStarted: Начался ли ввод кадров с камеры
    Возвращает true после готовности физической камеры к передаче данных в EasyAR, и false после остановки камеры. При FrameSource.CameraFrameStarted равном false EasyAR не работает. При FrameSource.CameraFrameStarted равном true необходимо гарантировать доступность данных FrameSource.DeviceCameras и непрерывную передачу кадров в EasyAR. При длительном отсутствии ввода кадров EasyAR выдает предупреждение, помогая пользователю диагностировать проблемы.

Параметры физической камеры должны соответствовать реальной камере устройства.

  • FrameSourceCamera.CameraType: Тип физической камеры
    Обычно выбирается задняя камера для не фронтальных случаев, например в гарнитурах.
  • FrameSourceCamera.CameraOrientation: Угол поворота по часовой стрелке для отображения изображения с камеры в естественной ориентации устройства
    Диапазон [0, 360).
  • FrameSourceCamera.FrameSize: Размер изображения
  • FrameSourceCamera.FrameRateRange: Диапазон частоты кадров
    Определяет x как нижнюю границу диапазона, y как верхнюю границу диапазона частоты кадров.
  • DeviceFrameSourceCamera.AxisSystem: Система координат для pose головы/камеры и экстринсиков камеры
    Все матрицы должны использовать одну систему координат. Если используемые данные не соответствуют известной системе, необходимо преобразовать оси перед передачей в EasyAR.
  • DeviceFrameSourceCamera.Extrinsics: Экстринсики физической камеры
    Обычно калибровочная матрица. Ее оси должны соответствовать определению DeviceFrameSourceCamera.AxisSystem. Если оси экстринсиков отличаются от определения осей фактического pose или не соответствуют определению DeviceFrameSourceCamera.AxisSystem, необходимо преобразовать оси перед установкой этого значения.

Запуск и остановка сеанса

  • FrameSource.OnSessionStart(ARSession)：Обрабатывает событие запуска сеанса
    Действительно, когда этот источник кадров выбран при сборке сеанса.
    Может использоваться для отложенной инициализации, для выполнения инициализации, специфичной для AR, в этом методе.
  • FrameSource.OnSessionStop()：Обрабатывает событие остановки сеанса
    Действительно, когда этот источник кадров выбран при сборке сеанса.
    В этом методе можно уничтожить ресурсы, созданные в FrameSource.OnSessionStart(ARSession) и во время работы сеанса, и восстановить внутреннее состояние. Гарантируется, что этот метод будет вызван до уничтожения сеанса. Если источник кадров уничтожается до сеанса, этот метод не будет вызван, и сеанс перейдет в состояние Broken.

Входные кадры

  • ExternalDeviceMotionFrameSource.HandleCameraFrameData(DeviceFrameSourceCamera, double, Image, CameraParameters, Pose, MotionTrackingStatus): Ввод данных кадра камеры

  • ExternalDeviceRotationFrameSource.HandleCameraFrameData(DeviceFrameSourceCamera, double, Image, CameraParameters, Quaternion): Ввод данных кадра камеры
    Можно вызывать из любого потока, при условии, что API SDK устройства являются потокобезопасными.
    Эти данные должны соответствовать моменту экспозиции сенсора физической камеры. Рекомендуется вводить данные с частотой 30 или 60 кадров в секунду. Минимально приемлемая частота кадров — 2, но это может повлиять на время отклика некоторых алгоритмов. По возможности рекомендуется вводить цветные данные, это улучшает работу Mega.
    Для максимальной эффективности можно спроектировать весь поток данных так, чтобы необработанные данные YUV передавались напрямую через общую память, передавались в EasyAR с использованием указателя на данные и учитывалось владение данными.

  • ExternalDeviceMotionFrameSource.HandleRenderFrameData(double, Pose, MotionTrackingStatus): Ввод данных рендер-кадра

  • ExternalDeviceRotationFrameSource.HandleRenderFrameData(double, Quaternion): Ввод данных рендер-кадра
    Необходимо вызывать каждый рендер-кадр после готовности данных устройства, без пропуска кадров. Эти данные должны соответствовать данным, управляющим виртуальной камерой Unity в том же кадре.

  • ExternalFrameSource.TryAcquireBuffer(int): Попытаться получить блок памяти из пула памяти
    Этот блок памяти обычно используется для хранения данных изображения кадра камеры и передачи их в EasyAR.
  • ExternalFrameSource.ReceivedFrameCount: Счетчик кадров камеры, полученных EasyAR
    EasyAR использует его для проверки работоспособности ввода кадров камеры с устройства. Может использоваться при отладке; если это число перестает расти, это обычно означает, что устройство перестало передавать данные в EasyAR.

Сообщения Unity

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

Следующие шаги

Связанные темы