Table of Contents

Unity에서의 사용자 정의 카메라 구현 —— 외부 프레임 데이터 소스

외부 프레임 데이터 소스(ExternalFrameSource)를 통해 개발자는 EasyAR Sense에 사용자 정의 카메라 구현을 확장하여 특정 헤드-마운트 디스플레이(head-mounted display) 장치나 기타 입력 장치를 지원할 수 있습니다. 다음 내용은 외부 프레임 데이터 소스의 타입 구조와 인터페이스 정의를 소개합니다.

시작하기 전에

외부 프레임 데이터 소스 유형

---
  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가 처리.
  • 이미지 입력 확장

이들 외부 프레임 데이터 소스 연결 시 사용 가능한 AR 기능은 다음과 같이 다릅니다:

  • 이미지 및 디바이스 모션 데이터 입력 확장 ExternalDeviceMotionFrameSource
    • Mega
    • 모션 트래킹 (디바이스 자체 제공)
    • 희소 공간 맵
    • 밀집 공간 맵
    • 이미지 트래킹 (모션 퓨전 지원)
    • 이미지 클라우드 인식
    • 오브젝트 트래킹 (모션 퓨전 지원)
  • 이미지 및 디바이스 모션 데이터 입력 확장 ExternalDeviceRotationFrameSource
    • Mega
    • 이미지 트래킹 (모션 퓨전 미지원)
    • 이미지 클라우드 인식
    • 오브젝트 트래킹 (모션 퓨전 미지원)
  • 이미지 입력 확장 ExternalImageStreamFrameSource
    • 이미지 트래킹 (모션 퓨전 미지원)
    • 이미지 클라우드 인식
    • 오브젝트 트래킹 (모션 퓨전 미지원)

외부 프레임 데이터 소스 인터페이스 정의

외부 프레임 데이터 소스를 생성할 때는 관련 인터페이스를 구현해야 합니다. 아래에서는 이러한 인터페이스의 정의 및 사용 방법을 소개합니다.

장치 정의

  • FrameSource.IsHMD: HMD 여부 정의
    HMD 장치에서만 true로 설정됩니다.
    장치가 HMD인 경우, 진단 정보는 화면 대신 카메라 전방의 3D 보드에 표시됩니다. 일부 AR 기능은 HMD 장치에서 약간 다르게 동작합니다.

  • FrameSource.Display: 디스플레이 시스템 정의
    현재 디스플레이의 회전 정보 등을 제공합니다.
    기본 디스플레이 정보는 Display.DefaultSystemDisplay 또는 Display.DefaultHMDDisplay로 획득 가능합니다.
    일반적으로 HMD에서는 Display.DefaultHMDDisplay를 사용할 수 있습니다.

추가 설정 없음.

가용성

  • FrameSource.IsAvailable: 가용성 (Availability)
    frame source 사용 가능 여부를 판단합니다.
    frame source 가 현재 실행 중인 장치 또는 환경에서 사용 불가능한 경우, 이 값은 false 여야 합니다.
    이 값이 Optional<bool>.Empty 와 같으면, FrameSource.CheckAvailability() 코루틴이 호출되며, 코루틴이 끝나기 전에 FrameSource.IsAvailable 을 업데이트해야 합니다.
    가용성 인터페이스는 세션 조립 시 사용되며, 사용 불가능한 컴포넌트는 선택되지 않으며 해당 메소드는 세션 실행 중 호출되지 않습니다.
  • FrameSource.CheckAvailability() (선택 사항): Frame source 가용성 확인 코루틴
    FrameSource.IsAvailable 이 Optional<bool>.Empty 와 같을 때 호출됩니다. 이 코루틴이 끝나기 전까지 세션의 조립 과정은 차단됩니다.

세션 오리진

  • ExternalDeviceFrameSource.OriginType: 오리진 유형

    • XROrigin: 디바이스 SDK는 Unity.XR.CoreUtils.XROrigin을 오리진으로 사용합니다.
    • Custom: 디바이스 SDK는 커스텀 오리진을 사용합니다. ExternalDeviceFrameSource.Origin을 지정해야 합니다.
    • None: 디바이스 SDK가 오리진을 정의하지 않습니다. 이 경우 오리진은 장면에서 자동으로 선택 또는 생성되지만 이동하지 않습니다.
      세션은 SessionOrigin 센터 모드만 지원합니다. 모든 타겟 및 타겟 하위 콘텐츠는 유니티 좌표계에서 항상 이동하므로 가상 오브젝트 배치 시 주의해야 합니다. 일부 사용자 콘텐츠(예: 물리 시스템)는 제대로 작동하지 않습니다. 유니티 월드 좌표계에 배치된 오브젝트는 어떤 구성에서도 올바른 위치에 표시될 수 없습니다.

  • ExternalDeviceFrameSource.Origin: 오리진 오브젝트
    ExternalDeviceFrameSource.OriginType이 Custom일 때만 커스텀 오리진을 정의하며, 다른 경우에는 재정의할 필요가 없습니다.

가상 카메라

  • FrameSource.Camera: 가상 카메라
    카메라는 세션에 의해 제어되지 않으며, 카메라의 transform 및 투영 행렬, 이미지 배경 렌더링은 외부 코드에 의해 제어되어야 합니다.
    헤드셋에서만 이 카메라가 사용되며, 진단 텍스트를 눈앞에 표시하는 데 활용됩니다.
    ExternalDeviceFrameSource.OriginType이 XROrigin일 경우 정의할 필요가 없으며, EasyAR이 Unity XR 프레임워크에서 정의된 카메라를 자동으로 사용합니다.

물리적 카메라

  • FrameSource.DeviceCameras: 물리적 카메라 파라미터
    카메라 프레임 데이터를 제공하는 물리적 카메라. 카메라 프레임 데이터가 여러 카메라에서 제공되는 경우, 목록에 모든 물리적 카메라가 포함되어야 합니다.
    FrameSource.CameraFrameStarted가 true일 때 정확한 물리적 카메라 파라미터를 얻을 수 있어야 합니다.
  • FrameSource.CameraFrameStarted: 카메라 프레임 입력 시작 여부
    물리적 카메라가 준비되어 EasyAR에 데이터를 입력할 수 있게 되면 true를 반환하고, 물리적 카메라가 작동을 중단하면 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): 세션 시작 이벤트 처리
    세션 조립 시 이 프레임 소스가 선택되었을 때 유효합니다.
    지연 초기화에 사용할 수 있으며, 이 메서드에서 AR 고유의 초기화 작업을 수행할 수 있습니다.
  • FrameSource.OnSessionStop(): 세션 중지 이벤트 처리
    세션 조립 시 이 프레임 소스가 선택되었을 때 유효합니다.
    이 메서드에서 FrameSource.OnSessionStart(ARSession) 및 세션 실행 중 생성된 리소스를 파괴하고 내부 상태를 복원할 수 있습니다. 세션 파괴 전에 이 메서드가 호출되는 것이 보장됩니다. 프레임 소스가 세션보다 먼저 파괴되면 이 메서드는 호출되지 않으며, 세션은 Broken 상태로 진입합니다.

입력 프레임

  • ExternalFrameSource.TryAcquireBuffer(int): 메모리 풀에서 메모리 청크 획득 시도
    이 메모리 청크는 일반적으로 카메라 프레임의 이미지 데이터를 저장하고 EasyAR에 입력하는 데 사용됩니다.
  • ExternalFrameSource.ReceivedFrameCount: EasyAR가 수신한 카메라 프레임 수
    EasyAR는 이를 사용하여 장치 카메라 프레임 입력의 상태를 확인합니다. 디버깅에 사용할 수 있으며, 이 값이 증가하지 않으면 일반적으로 장치가 EasyAR에 데이터 입력을 중지했음을 의미합니다.

Unity 메시지

스크립트에서 다음 메시지를 사용할 때는 기본 클래스 구현이 호출되도록 주의해야 합니다:

다음 단계

관련 주제