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. transform виртуальной камеры и прочее управление выполняются SDK устройства.
    • Реализуется наследованием от ExternalDeviceRotationFrameSource: устройство и SDK устройства предоставляют отслеживание вращения 3DoF. transform виртуальной камеры и прочее управление выполняются SDK устройства.
  • Расширение ввода изображений
    • Реализуется наследованием от ExternalImageStreamFrameSource: предоставляет только ввод изображений. transform виртуальной камеры и прочее управление выполняются EasyAR.

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

  • Расширение ввода изображений и данных о движении устройства ExternalDeviceMotionFrameSource
    • Mega
    • Отслеживание движения (предоставляется самим устройством)
    • Разреженная пространственная карта
    • Плотная пространственная карта
    • Отслеживание изображений (с поддержкой слияния с движением)
    • Облачное распознавание изображений
    • Отслеживание объектов (с поддержкой слияния с движением)
  • Расширение ввода изображений и данных о движении устройства ExternalDeviceRotationFrameSource
    • Mega
    • Отслеживание изображений (без поддержки слияния с движением)
    • Облачное распознавание изображений
    • Отслеживание объектов (без поддержки слияния с движением)
  • Расширение ввода изображений ExternalImageStreamFrameSource
    • Отслеживание изображений (без поддержки слияния с движением)
    • Облачное распознавание изображений
    • Отслеживание объектов (без поддержки слияния с движением)

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

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

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

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

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

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

Доступность

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

Источник координат session

  • ExternalDeviceFrameSource.OriginType：Тип источника координат

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

  • ExternalDeviceFrameSource.Origin：Объект источника координат
    Собственный источник координат определяется тогда и только тогда, когда ExternalDeviceFrameSource.OriginType равен Custom; в остальных случаях переопределение не требуется.

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

  • FrameSource.Camera：Виртуальная камера
    Камера не управляется session; transform камеры, матрица проекции и рендеринг фонового изображения должны управляться внешним кодом.
    Эта камера используется только на головных дисплеях, чтобы показывать диагностический текст перед глазами.
    Когда 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, перед установкой этого значения нужно выполнить преобразование координатных осей.

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

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

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

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

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

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

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

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

Сообщения Unity

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

Дальнейшие шаги

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