Unity의 QR 코드

HoloLens 2 헤드셋은 홀로그램 및 기타 AR 기능을 제공하는 데 사용할 수 있는 QR 코드를 추적하고 검색할 수 있습니다. 이 문서에서는 다음을 포함하여 Unity 앱에서 QR 코드 사용을 시작하기 위해 알아야 할 모든 사항을 안내합니다.

• Unity 앱에 QR 코드 검색 추가
• 사용해야 하는 중요한 개념 및 Unity 구성 요소를 이해합니다.
• 일반적인 QR 코드 사용을 다루는 자습서를 제공합니다.
• QR 코드 사용 장면 및 예제 스크립트를 보여 주는 AR 표식 샘플 시나리오를 소개합니다.

이 문서를 계속 진행하기 전에 QR 코드 개요를 진행하는 것이 좋습니다.

Unity 프로젝트 및 앱 구성

QR 코드 기능을 사용하도록 설정하려면 Unity 프로젝트 및 앱을 올바르게 설정하고 구성해야 합니다. 다음이 필요합니다.

• Windows Mixed Reality용 OpenXR 버전 113.2403.5001 이상

  참고 항목

  이는 OS와 함께 제공되며 Windows 스토어를 통해 업데이트할 수 있습니다. 사용자에게 이전 버전이 설치되어 있을 수 있으며, 해당 디바이스는 버전 113.2403.5001 이상으로 업데이트될 때까지 QR 코드와 같은 AR 마커를 사용할 수 없습니다.

• 지원되는 Unity 버전과 호환되는 프로젝트:
  • Unity 2022.3 LTS(권장)
  • Unity 2021.3 LTS
• Mixed Reality OpenXR 플러그 인입니다.
• Unity 프로젝트에 사용할 수 있는 웹캠 기능입니다.
• 앱에 부여된 카메라 권한입니다.

다음 섹션에서는 QR 코드 검색을 사용하도록 Unity 프로젝트 및 앱을 구성하는 방법을 안내합니다.

Mixed Reality OpenXR 플러그 인 가져오기

Mixed Reality OpenXR 플러그 인 패키지에는 QR 코드 기능에 액세스하는 데 사용할 수 있는 C# API가 포함되어 있습니다.

패키지를 가져오려면 다음을 수행합니다.

1. Mixed Reality 기능 도구를 다운로드 하고 실행합니다.
2. OpenXR 플러그 인을 설치 합니다.

또한 Mixed Reality 기능 도구는 패키지 관리를 간소화하며 앱에 필요한 Mixed Reality 기능을 찾고, 업데이트하고, 추가하는 데 사용할 수 있습니다. 이 도구를 사용하는 방법에 대한 자세한 지침은 Mixed Reality 기능 도구 시작 기능을 참조하세요.

WebCam 기능 사용

QR 코드를 검색하고 추적하려면 Unity 프로젝트에 WebCam 기능을 사용하도록 설정해야 합니다.

WebCam 기능을 사용하도록 설정하려면 다음을 수행합니다.

1. Unity 프로젝트를 엽니다.
2. Unity 편집기 앱 메뉴에서 편집을 클릭합니다.
3. 프로젝트 설정 플레이어로 이동하여 다음과 같이 UWP 탭을 선택합니다. >
4. 기능 목록에서 WebCam을 사용하도록 설정합니다.
5. 프로젝트 설정을 종료 합니다.

이제 Unity 앱에 WebCam 기능이 사용하도록 설정되었습니다. 그러나 디바이스 카메라에 액세스할 수 있는 권한이 앱에 계속 부여되어야 합니다.

앱 카메라 액세스 권한 부여

앱에 WebCam 기능이 사용하도록 설정된 경우 사용 권한 대화 상자는 사용자에게 디바이스 카메라에 대한 앱 액세스 권한을 부여하라는 메시지를 표시합니다.

이 대화 상자는 일반적으로 QR 코드 표식 지원을 사용하도록 설정된 장면을 입력할 ARMarkerManager 때 한 번만 표시됩니다. 카메라 액세스가 거부되면 사용자는 설정 앱으로 이동하여 앱의 고급 옵션을 통해 사용하도록 설정할 수 있습니다.>

장면에 QR 코드 검색 빌드

QR 코드 검색은 다음이 필요한 QR 코드를 사용하려는 모든 장면에 기본 제공되어야 합니다.

• ARMarkerManager 연결된 A GameObject 입니다. ARMarkerManager 는 검색된 QR 코드에 대해 모든 GameObject 코드를 만들고, 업데이트하고, 제거할 책임이 있습니다.
• 연결된 프리팹 ARMarker 입니다.
• ARMarkerManager QR 코드가 검색될 때 프리팹을 GameObject 사용하도록 구성됩니다.

QR 코드에 대한 프리팹 만들기

장면에서 QR 코드를 사용하려면 QR 코드에 대한 프리팹을 만들어야 합니다. ARMarkerManager 는 QR 코드가 GameObject 검색될 때마다 이 프리팹을 사용하여 만듭니다.

QR 코드에 대한 프리팹을 만들려면 다음을 수행합니다.

1. 프로젝트에 대한 새 프리팹 을 만듭니다.
2. ARMarkerMicrosoft.MixedReality.OpenXR > ARMarker 스크립트 > 아래에 있는 프리팹에 구성 요소를 추가합니다.
   

이제 작업할 기본 프리팹이 있습니다. 앱이 환경에서 검색된 QR 코드를 시각적으로 나타내려고 할 수 있습니다. 다음 섹션에서는 QR 코드에 대한 시각적 표현을 추가하는 방법을 안내합니다.

시각적 개체 추가

이전 섹션에서 프리팹에 추가 ARMarker하면 구성 요소도 자동으로 추가 ARMarkerScale 되었습니다. 이 구성 요소는 QR 코드의 시각적 표현 크기를 실제와 일치시킬 때 사용됩니다.

이를 수행하려면:

1. 이전 섹션에서 만든 프리팹에 빈 GameObject 항목을 추가합니다. 모든 시각적 표식 콘텐츠를 나타냅니다.
2. 표식 콘텐츠에 자식 3D GameObject(예: a Quad)를 추가합니다 GameObject.
3. 프리팹의 ARMarkerScale 구성 요소에서 표식 크기 조정 변환을 표식 콘텐츠GameObject로 설정합니다. 이 필드를 설정하면 선택한 3D GameObject 의 크기가 실제 QR 코드와 일치하도록 올바르게 조정됩니다.

장면에 추가 ARMarkerManager

ARMarkerManager 는 검색된 QR 코드에 대해 모든 GameObject 코드를 만들고, 업데이트하고, 제거할 책임이 있습니다.

장면에 추가 ARMarkerManager 하려면 다음을 수행합니다.

1. 장면에 GameObject 배치합니다.
2. ARMarkerManager Microsoft.MixedReality.OpenXR > ARMarkerManager 스크립트 > 아래에 있는 구성 요소에 구성 요소를 GameObject추가합니다.
   
3. ARMarkerManager 표식 프리팹 필드를 이전 섹션에서 만든 프리팹으로 설정합니다.
4. 사용 가능한 표식 형식을 확장한 다음 요소를 선택하고 QR 코드로 설정합니다.

QR 코드 변경 내용 추적

ARMarkerManager 에는 markersChanged 구독자에게 제공하는 ARMarkersChangedEventArgs 이벤트가 포함됩니다. 이러한 이벤트 인수를 사용하여 검색 또는 업데이트된 포즈 데이터에서 추가 또는 제거되는 QR 코드를 추적합니다.

다음 코드는 이벤트 구독을 ARMarkerManager.markersChanged 보여 줍니다., 개체 ARMarkerManager 를 반복 ARMarker 하는 이벤트 인수를 사용 하 여 처리 하 고 추가 되는지 여부를 디버그에 쓰기, 제거 또는 업데이트 합니다.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

private void Awake()
{
    m_arMarkerManager = GetComponent<ARMarkerManager>();
    m_arMarkerManager.markersChanged += OnQRCodesChanged;
}

void OnQRCodesChanged(ARMarkersChangedEventArgs args)
{
    foreach (ARMarker qrCode in args.added)
        Debug.Log($"QR code with the ID {qrCode.trackableId} added.");

    foreach (ARMarker qrCode in args.removed)
        Debug.Log($"QR code with the ID {qrCode.trackableId} removed.");

    foreach (ARMarker qrCode in args.updated)
    {
        Debug.Log($"QR code with the ID {qrCode.trackableId} updated.");
        Debug.Log($"Pos:{qrCode.transform.position} Rot:{qrCode.transform.rotation} Size:{qrCode.size}");
    }
}

QR 코드가 마지막으로 검색된 시간 가져오기

ARMarker.lastSeenTime 이 속성을 사용하여 디바이스가 마지막으로 검색된 QR 코드를 추적한 시기와 추적이 손실된 경우의 시간을 확인합니다. 시간은 Unity가 애플리케이션을 시작한 이후의 시간(초)으로 측정되며, 이는 .와 유사합니다 UnityEngine.Time.realtimeSinceStartup.

QR 코드의 추적 가능한 ID 사용

QR 코드는 AR 디바이스가 물리적 환경에서 감지하고 추적할 수 있는 모든 항목인 추적 가능한 코드입니다. 추적 가능 항목은 ID, 추적 상태, 포즈 및 기타 데이터를 제공하는 형식 ARTrackable<TSessionRelativeData, TTrackable> 에서 파생됩니다.

QR 코드의 추적 가능한 ID를 메서드로 ARMarkerManager 전달하여 QR 코드의 속성, 원시 바이트 데이터 및 문자열 표현을 가져오고 QR 코드에 대한 변환 모드를 설정할 수 있습니다. 이러한 메서드를 사용하면 개체 참조를 유지하지 않고도 QR 코드에 대한 데이터를 검색할 수 ARMarker 있습니다.

QR 코드의 ID를 다음 ARMarkerManager 메서드에 전달할 수 있습니다.

• GetDecodedString(UnityEngine.XR.ARSubsystems.TrackableId trackableId)
• GetMarker(UnityEngine.XR.ARSubsystems.TrackableId trackableId)
• GetQRCodeProperties(UnityEngine.XR.ARSubsystems.TrackableId)
• GetRawData(UnityEngine.XR.ARSubsystems.TrackableId, Unity.Collections.Allocator)
• SetTransformMode(UnityEngine.XR.ARSubsystems.TrackableId, Microsoft.MixedReality.OpenXR.TransformMode)

참고 항목

메서드 매개 변수allocator의 GetRawData 경우 대부분의 시나리오에서 전달 Unity.Collections.Allocator.Temp 만으로도 충분합니다.

QR 코드의 추적 상태에 따라

ARMarker 추적 가능하므로 속성을 상속 trackingState 하고 다음 세 UnityEngine.XR.ARSubsystems.TrackingState가지 중 하나로 설정됩니다.

• Limited: QR 코드가 추적 중이지만 제한된 정보를 사용할 수 있거나 품질이 좋지 않은 것을 나타냅니다.
• Tracking: QR 코드가 완전히 추적되도록 지정합니다.
• None: QR 코드가 추적되지 않음을 나타냅니다.

QR 코드에 대한 추적 상태를 모니터링하려면 이벤트 처리기에 전달된 이벤트 인수에 제공된 표식 컬렉션을 구독 ARMarkerManager.markersChanged 하고 반복 ARMarker 합니다.

다음 코드에서는 이벤트를 사용하여 ARMarkerManager.markersChanged 새로 검색된 QR 코드에 대한 개체를 반복 ARMarker 하고 추적 가능한 ID를 디버그 창에 쓰는 방법을 보여 줍니다.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

private void Awake()
{
    m_arMarkerManager = GetComponent<ARMarkerManager>();
    m_arMarkerManager.markersChanged += OnQRCodesChanged;
}

void OnQRCodesChanged(ARMarkersChangedEventArgs args)
{
    foreach (ARMarker qrCode in args.added)
    {
       if (qrCode.trackingState == UnityEngine.XR.ARSubsystems.TrackingState.Tracking)
           Debug.Log($"Fully tracked QR code with the ID {qrCode.trackableId} was added.");
    }
}

QR 코드의 버전 및 QR 코드 형식 가져오기

검색된 QR 코드의 버전 및 형식을 얻으려면 다음을 수행합니다.

1. 인스턴스를 반환하는 호출 ARMarker.GetQRCodeProperties()입니다 QRCodeProperties .
2. 반환 값의 필드에 QRCodeProperties 액세스하여 QR 코드의 형식을 가져옵니다. 값은 QRCodeType.QRCode 또는 QRCodeType.MicroQRCode입니다.
3. 반환 값의 QRCodeProperties.version 필드에 액세스하여 QR 코드의 버전을 가져옵니다. 값의 범위는 형식이 1에서 40이고 형식이 QRCodeType.QRCode면 1에서 4까지입니다 QRCodeType.MicroQRCode.

또는 개체의 추적 가능한 ID를 전달 ARMarker 하여 ARMarkerManager.GetQRCodeProperties(TrackableId) QR 코드의 형식 및 버전을 가져옵니다.

Warning

QR 코드는 현재 지원되는 유일한 표식 형식이지만 향후 릴리스에서 다른 표식 형식에 대한 지원이 추가될 수 있습니다. 그렇지 않으면 markerType ARMarkerType.QRCode호출 GetQRCodeProperties(TrackableId) 이 throw됩니다.System.InvalidOperationException 나중에 앱에서 문제가 발생할 수 있는 경우 try-catch 블록에서 호출 GetQRCodeProperties(TrackableId) 을 래핑하는 것이 좋습니다.

QR 데이터 읽기

ARMarker 구성 요소는 만드는 모든 GameObject 구성 ARMarkerManager 요소에 연결됩니다. ARMarker 에서는 QR 코드 데이터를 반환하는 두 가지 메서드를 제공합니다.

• GetDecodedString(): 이 메서드는 URL과 같은 QR 코드의 문자열 표현을 가져옵니다.

• GetRawData(Unity.Collections.Allocator allocator): 이 메서드는 QR 코드 콘텐츠를 바이트 배열로 반환하여 배열이 할당되는 방식을 세밀하게 튜닝할 수 있도록 합니다. 성능이 중요한 핫 경로 및 기타 상황에서 이 메서드를 사용합니다.

다음 코드는 기본 사용 및 GetRawData(Unity.Collections.Allocator allocator)다음을 GetDecodedString() 보여 줍니다.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

void OnQRCodesChanged(ARMarkersChangedEventArgs args)
{
    foreach (ARMarker qrCode in args.added)
    {
        var text = qrCode.GetDecodedString();
        Debug.Log($"QR code text: {text}");

        var bytes = qrCode.GetRawData(Unity.Collections.Allocator.Temp);
        Debug.Log($"QR code bytes: {bytes.Length}");
        bytes.Dispose();
    }
}

QR 코드 크기, 위치, 회전 및 가운데 가져오기

개체는 ARMarker 나타내는 QR 코드의 크기, 위치, 회전 및 중심을 제공합니다.

QR 코드의 크기를 미터 단위로 가져오려면 속성을 ARMarker.size사용합니다.

이 ARMarker.transform 속성을 사용하여 QR 코드 변환의 회전 및 세계 공간 위치를 가져오고 ARMarker.center QR 코드의 변환을 기준으로 QR 코드의 2D 좌표를 가져옵니다. 변환 자체는 (변환 모드)가 (가장 안정적인, QR 코드의 왼쪽 위) 또는 TransformMode.Center (가운데, QR 코드의 기하학적 중심)으로 설정 TransformMode.MostStable 되었는지 여부에 ARMarker.transformMode 따라 가운데에 맞춰집니다.

필드를 ARMarkerManager.defaultTransformMode 사용하여 변환 모드 ARMarkerManager 에서 새 ARMarker 개체를 만듭니다. 필드가 다음과 같이 Unity 검사기에서 설정되면 필드가 초기화 Default Transform Mode 됩니다.

사용 ARMarker.transformMode대신 개체의 추적 가능한 ID를 전달 ARMarker 하여 ARMarkerManager.SetTransformMode(TrackableId, TransformMode) 변환 모드를 설정합니다.

다음 코드에서는 새 QR 코드의 크기와 중심, 해당 변환의 위치 및 회전 및 변환 모드를 변경한 후 업데이트된 변환 위치를 가져오는 방법을 보여 줍니다.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

void OnMarkersChanged(ARMarkersChangedEventArgs args)
{
    Debug.Log($"Default transform mode is {ARMarkerManager.Instance.defaultTransformMode}./n");

    if (e.added.Count > 0)
    {
        ARMarker qrCode = args.added[0];

        Debug.Log($"Position: {qrCode.transform.position}");
        Debug.Log($"Rotation: {qrCode.transform.rotation}");
        Debug.Log($"Center: {qrCode.center}");

        if (qrCode.transformMode == TransformMode.Center)
            qrCode.transformMode = TransformMode.MostStable;
        else
            qrCode.transformMode = TransformMode.Center;

        Debug.Log($"QR code's transform mode is now set to {qrCode.transformMode}. /n");
        Debug.Log($"New position: {qrCode.transform.position}");
    }
}

AR 표식 샘플 시나리오

OpenXR 플러그 인 패키지와 함께 제공되는 샘플에는 사용 방법 및 ARMarker 사용 방법 ARMarkerManager 의 예를 제공하는 QR 코드 사용 장면이 포함되어 있습니다.

장면은 다음과 같이 Assets > ARMarker에 있습니다.

GitHub의 OpenXR Unity Mixed Reality 샘플 리포지토리에서 장면에서 사용되는 C# 스크립트를 찾을 수 있습니다. /OpenXR-Unity-MixedReality-Samples/tree/main/SampleScenarios/Scenarios/MarkerSample/Scripts

참고 항목

• Mixed Reality OpenXR 플러그 인 API 참조
• QR 코드 개요