QR 코드 추적 개요

아티클
06/29/2024

QR 코드 샘플에 대한 GitHub 리포지토리에 액세스하려면 다음을 수행합니다.

Windows Mixed Reality 및 HoloLens 헤드셋을 사용하면 앱이 헤드셋 주변 환경에서 QR 코드를 감지하여 각 코드의 실제 위치에 좌표계를 설정할 수 있습니다. 여러 디바이스에서 동일한 위치에 홀로그램을 렌더링하여 공유 환경을 만들 수도 있습니다. 디바이스의 웹캠을 사용하도록 설정하면 최신 버전의 프로젝트에서 QR 코드를 인식하게 됩니다. 프로덕션 환경에 대한 최상의 결과를 위해 모범 사례 섹션을 검토하는 것이 좋습니다.

이 문서에서는 다음에 대해 알아봅니다.

QR 코드 추적에 지원되는 디바이스
지원되는 QR 코드 버전
QR 코드 검색에 대한 모범 사례
문제 해결 및 FAQ

장치 지원

Product	HoloLens 1세대	HoloLens 2	몰입형 헤드셋
OpenXR		✔️ (OpenXR 런타임 버전 113 및 OpenXR XR_MSFT_scene_marker 확장 사용)
Mixed Reality Unity 플러그 인		✔️ (OpenXR 런타임 버전 113 및 Mixed Reality Unity 플러그 인 `ARMarkerManager`사용)
레거시 QR SDK	✔️	✔️	✔️

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

레거시 QR 코드 SDK를 사용하여 데스크톱 PC에서 몰입형 Windows Mixed Reality 헤드셋을 사용한 QR 코드 추적은 Windows 10 버전 2004 이상에서 지원됩니다. API를 Microsoft.MixedReality.QRCodeWatcher.IsSupported() 사용하여 기능이 현재 디바이스에서 지원되는지 여부를 확인합니다.

지원되는 QR 코드 버전

다음 표에서는 지원되는 QR 코드 버전과 지원되지 않는 QR 코드 버전을 나열합니다.

	QR 코드 버전
지원됨:	QR 코드 버전 1 - 10 마이크로 QR 코드 M1-M4 모든 인코딩
지원 안 됨:	QR 코드 10 - 20(완전히 지원되지 않음) QR 코드 버전 21 이상 조정된 모듈(예: 원형 모듈, 리플렉션, 반전됨(검정/흰색)) 로고 구조적 추가

QR 코드 검색에 대한 모범 사례

QR 코드 주변의 조용한 영역

올바르게 읽으려면 QR 코드에 코드의 모든 면 주위에 여백이 필요합니다. 이 여백은 인쇄된 콘텐츠를 포함해서는 안 되며 네 개의 모듈(코드의 검은색 사각형 하나)이어야 합니다.

공식 QR 코드 설명서에는 조용한 영역에 대한 자세한 정보가 포함되어 있습니다.

조명 및 배경

QR 코드 감지 품질은 다양한 조명 및 배경에 취약합니다.

일반 조명 조건에서 성능 향상을 위해 흑백 모듈에 충분한 대비를 제공합니다.
밝은 조명 또는 어두운 배경이 있는 극단적인 조명 조건에서는 QR 코드 감지 속도를 향상시킬 수 있는 대비를 줄이고 조정할 수 있습니다. QR 코드 내의 흰색 배경은 255에서 아래쪽으로 줄일 수 있습니다.

QR 코드의 크기

Windows Mixed Reality 및 HoloLens 디바이스는 5cm보다 작은 면이 있는 QR 코드에서 작동하지 않습니다.

5cm에서 10cm 사이의 측면이 있는 QR 코드의 경우 디바이스가 코드를 감지하기 위해 상당히 가까워야 합니다. 코드를 검색하는 데 평균보다 오래 걸릴 수 있습니다.

코드를 검색하는 정확한 시간은 QR 코드의 크기뿐만 아니라 코드에서 얼마나 멀리 떨어져 있는지에 따라 달라집니다. 코드에 더 가깝게 이동하면 크기 문제를 상쇄하는 데 도움이 됩니다.

QR 코드에서의 거리 및 각도 위치

추적 카메라는 특정 수준의 세부 정보만 검색할 수 있습니다. 작은 코드(측면을 따라 10cm 미만)의 경우 상당히 가까이 있어야 합니다. 10cm에서 25cm 사이의 버전 1 QR 코드의 경우 최소 검색 거리는 0.15미터에서 0.5미터 사이입니다.

크기에 대한 검색 거리는 선형적으로 증가하지만 지원되는 QR 버전 또는 모듈 크기에 따라 달라집니다. 버전이 높을수록 모듈이 작을수록 더 가까운 위치에서만 검색할 수 있습니다. 검색 거리가 더 길어지도록 하려면 마이크로 QR 코드를 사용해 볼 수도 있습니다. QR 검색은 각도 += 45 디그 범위에서 작동하여 코드를 검색하는 적절한 해상도를 보장합니다.

기타 검색 고려 사항:

곡선 표면의 QR 코드는 지원되지 않습니다.
평면 내 방향이 지원됩니다. 평면 외부는 더 나은 감지를 위해 +-45를 똑바로 바라봐야 합니다 <.
QR 코드의 물리적 크기에는 최소 2/3픽셀의 모듈이 있어야 합니다. 참고: 더 높은 버전의 QR 코드에는 더 작은 모듈이 있습니다.

최적의 검색을 위해 QR 코드의 거리와 크기 간의 절충 관계는 다음 그래프를 참조하세요.

Important

항상 충분한 대비와 적절한 테두리가 있는지 확인합니다.

QR 코드 데이터 관리

Windows Mixed Reality 및 HoloLens 디바이스는 드라이버의 시스템 수준에서 QR 코드를 검색합니다. 디바이스가 다시 부팅되거나 드라이버가 다시 시작되면 검색된 QR 코드 기록이 지워집니다. 다시 검색된 QR 코드는 새 개체로 처리됩니다.

앱 내에서 지정할 수 있는 특정 타임스탬프보다 오래된 QR 코드를 무시하도록 앱을 구성하는 것이 좋습니다. QR 코드 API는 마지막 검색이 발생한 시간을 지정합니다. 대부분의 앱 개발자는 앱이 시작될 때 시스템 시간을 사용하여 QR 코드가 검색되는 시간을 결정합니다.

QR 코드 데이터는 앱과 관련이 없습니다. 앱이 시작되면 사용 가능한 QR 코드 목록이 제공됩니다. 앱 개발자는 이 앱과 관련된 QR 코드를 결정합니다.

공간에 QR 코드 배치

QR 코드를 배치하는 위치 및 방법에 대한 권장 사항은 HoloLens에 대한 환경 고려 사항을 참조하세요.

문제 해결 및 FAQ

필요한 기능은 무엇인가요?

HoloLens 애플리케이션에서 QR 코드 추적을 사용하도록 설정하려면 애플리케이션의 매니페스트에 웹캠 기능을 추가합니다. Unity에서 개발하는 경우 플레이어 설정에서 구성할 수 있습니다.

또한 사용자에게 앱 웹캠 권한을 부여하라는 권한 대화 상자의 메시지가 표시될 수 있습니다. 이 작업은 앱의 수명 동안 한 번만 발생합니다. 웹캠 액세스를 명시적으로 요청하는 앱과 같은 경우 대화 상자가 다시 나타나지 않습니다.

WebCam 기능이 있는 Unity 앱의 경우 장면에서 사용하도록 설정 ARMarkerManager 하면 웹캠 권한 대화 상자가 표시되도록 트리거할 수 있습니다.

네이티브 OpenXR C++ 앱의 경우 포함하는 XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT xrComputeNewSceneMSFT XrNewSceneComputeInfoMSFT::requestedFeatures 에 대한 초기 호출은 권한 대화 상자를 트리거할 수 있습니다.

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

매니페스트에 추가된 웹캠 기능이 필요합니다(Unity 기능의 확인란). 표준 UWP 프로젝트로 빌드하는 경우 솔루션 프로젝트의 package.appxmanifest에도 있습니다.

레거시 QR 코드 SDK에서 다음 메서드를 호출하여 액세스를 요청합니다.

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

액세스 상태는 .이어야 (status == QRCodeWatcherAccessStatus::Allowed)합니다.

액세스가 거부되면 기능을 시작할 때 거부된 액세스 권한을 반환합니다 QRTracking.

개체를 생성하기 전에 이 API를 QRCodeWatcher 호출해야 합니다.

Unity에서 프로젝트를 실행하는 경우 UI 스레드에서 호출하는지 확인해야 합니다. 그렇지 않으면 API는 항상 거부된 상태로 반환됩니다. 자세한 내용은 Unity 설명서의 AppCallbacks 클래스를 참조하세요.

Unity용 프로젝트를 설정하는 방법에 대한 자세한 내용은 Windows Mixed Reality용 Unity 구성을 참조하세요.

HoloLens 2 디바이스에서 QR 코드 추적 기능을 사용할 어떻게 할까요? 있나요?

QR 추적은 HoloLens 2에서 자동으로 수행되며 앱에 추가된 "웹캠" 기능이 필요합니다.

API 플러그 인 파일은 어디에서 찾을 수 있나요?

애플리케이션은 QR 코드를 검색하기 위해 HoloLen의 OpenXR 런타임을 사용해야 합니다. Windows Mixed Reality용 OpenXR(113.2403.5001 이상)은 HoloLens 디바이스에서 QR 코드 지원을 제공합니다.

Unity 앱의 경우 QR 코드 지원은 Mixed Reality OpenXR 플러그 인과 함께 제공되는 구성 요소를 통해 ARMarkerManager 제공됩니다.

비 Unity 앱에서 QR 코드 지원의 경우 OpenXR XR_MSFT_scene_marker 확장을 사용합니다.

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

필요한 모든 파일 및 설명서는 NuGet에서 찾을 수 있습니다.

Microsoft.MixedReality.QR

ARMarkerManager를 사용하여 QR 코드를 검색하도록 Unity 앱을 준비할 어떻게 할까요? 있나요?

Unity 앱 ARMarkerManager 에서 구성 요소는 실제 환경 내에서 QR 코드 검색이 장면에서 표시되는 방식을 처리하는 데 사용됩니다. ARMarkerManager 제공:

검색된 QR 코드가 관리자에 추가, 업데이트 또는 제거된 경우 구독자에게 알리는 이벤트입니다.
검색 중인 QR 코드에 대한 추적 가능한 컬렉션 ARMarker 입니다.
추적 가능한 ID로 지정된 대로 QR 코드에 대한 데이터를 반환하는 메서드입니다.

앱에서 사용 ARMarkerManager 하려면 Mixed Reality OpenXR 플러그 인 패키지를 가져와야 합니다.

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

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

이 도구를 사용하는 방법에 대한 자세한 지침은 Mixed Reality 기능 도구 시작 기능을 참조하세요.

일반적인 절차는 다음과 같습니다.

Unity 프로젝트에서 WebCam 기능을 사용하도록 설정합니다.
다음과 같이 프리팹을 ARMarker 만들고 구성 요소를 연결합니다.
실행할 때 QR 코드를 검색할 장면을 엽니다.
장면에서 GameObject에 연결 ARMarkerManager 하고 마커 프리팹을 만든 프리팹으로 설정합니다.

자세한 지침 및 정보는 Unity의 QR 코드로 이동하세요.

Unity 앱에서 QR 코드를 사용하는 방법에 대한 예제는 GitHub의 QR 코드 샘플 시나리오 를 참조하세요.

OpenXR을 사용하여 QR 코드를 검색하는 비 Unity 앱을 준비할 어떻게 할까요? 있나요?

OpenXR의 QR 코드 검색은 XR_MSFT_scene_marker 확장을 통해 제공됩니다. 이 확장을 사용하면 여러 QR 코드를 추적할 수 있으며, 검색된 QR 코드에 대한 크기, 위치, 마지막 검색 타임스탬프, UUID 및 버퍼링된 QR 코드 데이터를 제공할 수 있습니다.

QR 코드 지원을 사용하도록 설정하려면 XR_MSFT_scene_marker 확장과 XR_MSFT_scene_understanding 확장을 모두 사용하도록 설정해야 합니다.

자세한 단계별 내용은 OpenXR 1.0 사양의 XR_MSFT_scene_marker 확장 개요를 참조하세요.

QR 코드를 사용하는 방법에 대한 예제는 GitHub의 SceneUnderstandingUwp 샘플에서 Scene_QRCode.cpp 참조하세요.

Microsoft.MixedReality.QR.QRCodeWatcher를 사용하도록 UWP를 준비할 어떻게 할까요? 있나요?

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

NuGet 팩을 사용하여 필요한 파일의 압축을 풀 수 있습니다.
프로젝트에서 참조를 Microsoft.MixedReality.QR.winmd 추가하고 API 사용을 시작합니다.
플러그 인의 올바른 아키텍처 버전을 추가하고 빌드에 적절하게 사용합니다.

Microsoft.MixedReality.QR.QRCodeWatcher를 사용하여 Unity를 준비할 어떻게 할까요? 있나요?

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

Unity용 NuGet을 사용하고 위의 NuGet 팩을 가리킵니다.

QR 코드를 만들려면 어떻게 해야 하나요?

QR 코드 생성기를 확인합니다.

QR 코드 추적이 일반적으로 작동하지 않는 경우 어떻게 해야 하나요?

QR Code 버전이 지원되는 버전인가요? 버전 40과 같은 고밀도 버전은 지원하지 않습니다. 버전 10 이상은 보장되지 않습니다. 20 이상 버전은 지원되지 않습니다.
QR 코드에 충분히 근접한가요? QR 코드에서 거리 및 각도 위치를 확인합니다.
조명은 어떻게 합니까? QR 코드가 어두운 환경 배경에 있을 때 감지가 어려워지는 알려진 문제가 있습니다. 고대비로 인해 QR 코드가 카메라로 씻겨 나갔습니다. 자세한 내용은 조명 및 배경을 참조 하세요.

정확도는 무엇인가요?

단일 프레임에서 검색된 크기는 실제 크기에서 최대 1% 오류가 발생할 것으로 예상됩니다. 예를 들어 10cm 코드는 측정된 크기에서 최대 +/- 1mm 떨어져 있을 수 있습니다. 연속 검색에서 코드의 위치는 최대 +/- 2.5mm까지 표류할 수 있습니다. 검색 범위를 벗어나면 이전 검색의 위치는 지도 오류의 자비에 달려 있습니다.

이를 감지하려면 QR 코드에 얼마나 가까이 있어야 하나요?

거리는 분명히 QR 코드의 크기 및 버전에 따라 달라집니다. 자세한 내용은 QR 코드에서 거리 및 각도 위치를 참조하세요.

HoloLens 2의 경우 버전 1 QR 코드의 경우 5cm 면에서 25cm 면까지 다양하며 최소 검색 거리는 0.25미터에서 0.5미터 사이입니다. 가장 먼 코드는 약 0.5m에서 가장 작은 코드의 경우 약 0.5m에서 더 큰 코드의 경우 2미터로 이동합니다.
Windows Mixed Reality에서는 크기에 대한 이러한 거리가 절반으로 줄어듭니다.
더 크고 추정되는 코드의 경우 크기에 대한 검색 거리가 선형적으로 증가합니다. 더 작은 코드의 경우 검색이 발생하지 않습니다. 4-5 cm는 검색할 수 있는 가장 작은 값입니다.

로고가 있는 QR 코드를 읽을 수 없는 이유는 무엇인가요?

로고가 있는 QR 코드는 지원되지 않습니다.

QR 코드가 검색되므로 데이터가 없는 이유는 무엇인가요?

플랫폼에서 QR 코드를 디코딩할 수 없는 경우 데이터가 없습니다. 스트림을 사용하고 오픈 소스 코드를 사용하여 데이터를 해석할 수 있습니다.
구조 추가와 같은 일부 기능은 지원되지 않습니다.

자세한 내용은 지원되는 QR 코드 버전을 참조 하세요.

QR 코드는 '공간' 수준 또는 앱 수준에서 저장되는가요?

QR 코드는 드라이버 세션의 시스템 수준 또는 HoloLens의 부팅 세션에 저장됩니다. 자세한 내용은 QR 코드 데이터 관리를 참조 하세요.

기본 플랫폼에서는 어떻게 작동하나요? 그들은 어디에 유지합니까?

검색된 QR 코드는 드라이버가 메모리에 유지합니다.

"`Microsoft.MixedReality.QR.pdb`찾을 수 없음" 오류 메시지가 표시되면 Visual Studio에서 앱을 디버그할 어떻게 할까요? 있나요?

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

포함된 모듈 목록에 지정되지 않았기 때문에 기호 로드 Microsoft.MixedReality.QR.dll 를 건너뛰었다.

재현하려면

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

단계를 따라 이 동작을 재현합니다.

Microsoft.MixedReality.QR(NuGet) 및 MRTK 설치
디버그 시도

Microsoft.MixedReality.QR.dll 사용하여 앱을 디버그할 수 있지만 DLL을 찾을 수 없습니다.

Microsoft.MixedReality.QR.pdb에서 오류 메시지를 찾을 수 없음

권장된 솔루션

참고 항목

다음은 레거시 QR 코드 API와 관련이 있습니다. 대신 QR 코드에 OpenXR 구현을 사용하는 것이 좋습니다.

다음 릴리스에 기호를 추가하는 작업을 진행 중입니다. 그 동안 Visual Studio 옵션에서 DLL을 제외하여 앱을 디버그할 수 있어야 합니다.

자세한 내용은 Visual Studio의 설정 구성을 참조 하세요.

세션에서 스캔할 수 있는 QR 코드 수에 제한이 있나요?

10분 이내에 드라이버의 시스템 수준에서 100개의 QR 코드가 저장됩니다.

QR 코드 다듬기 프로세스가 변경되었나요?

QR 코드 스무딩 프로세스가 20H2 이후 포즈 스무딩에서 크기 스무딩으로 변경되었습니다. 동작을 이전 스무딩 프로세스로 되돌리기 위해 새 QR 코드 포즈 데이터가 이전에 검색된 프레임의 5초 또는 10cm 이내에 감지되면 부드러운 알고리즘이 적용됩니다. 변환 데이터는 이전 프레임의 10%와 현재 프레임의 90%의 가중 비율을 통해 혼합됩니다.

다음을 통해 공유

QR 코드 추적 개요

장치 지원

지원되는 QR 코드 버전