QR コード追跡の概要

QR コードのサンプルの GitHub リポジトリにアクセスするには、次のリンクをクリックします。

Unity での QR コードの追跡

Windows Mixed Reality と HoloLens ヘッドセットを使用すると、アプリはヘッドセット周辺の環境内の QR コードを検出し、各コードの実際の場所に座標系を確立できます。 複数のデバイスで同じ場所にホログラムをレンダリングして、共有エクスペリエンスを作成することもできます。 デバイスの Web カメラを有効にすると、最新バージョンのプロジェクトで QR コードが認識されるようになります。 運用環境が最適な結果となるようにするには、ベスト プラクティスに関するセクションを確認することをお勧めします。

この記事では、次の内容について説明します。

• QR コードの追跡でサポートされているデバイス
• サポートされている QR コードのバージョン
• QR コードの検出のベスト プラクティス
  • QR コードの周りの非表示ゾーン
  • 照明と背景
  • QR コードのサイズ
  • QR コードからの距離と角度
  • QR コード データの管理
  • 特定のスペースにおける QR コードの配置
• トラブルシューティングと FAQ
  • どのような機能が必要ですか?
  • holoLens 2 デバイスで QR コード追跡機能を機能させる操作方法
  • API プラグインのファイルはどこで入手できますか?
  • ARMarkerManager を使用して QR コードを検出するように Unity アプリを準備操作方法?
  • OpenXR を使用して QR コードを検出するように Unity 以外のアプリを準備操作方法?
  • Microsoft.MixedReality.QR.QRCodeWatcher を使用するには、UWP をどのように準備すればよいですか?
  • Microsoft.MixedReality.QR.QRCodeWatcher を使用するように Unity を準備するには、どのようにすればよいですか?
  • QR コードを作成するにはどうすればよいですか?
  • QR コードの追跡が全般的に機能しない場合は、どうすればよいですか?
  • 精度とは何ですか?
  • QR コードを検出するには、どのくらい近づく必要がありますか?
  • ロゴ付きの QR コードを読み取れないのはなぜですか?
  • QR コードが検出されるため、データが取得されないのはなぜですか?
  • QR コードは "スペース" レベルまたはアプリ レベルで保存されますか?
  • これは、基盤となるプラットフォームでどのように機能しますか? それらはどこに保持されますか?
  • "Microsoft.MixedReality.QR.pdb が見つかりません" というエラー メッセージが表示された場合は、Visual Studio でどのようにアプリをデバッグすればよいですか?

デバイス サポート

Product	HoloLens 第 1 世代	HoloLens 2	イマーシブ ヘッドセット
OpenXR		✔️ (OpenXR ランタイム バージョン 113 および OpenXR XR_MSFT_scene_marker 拡張機能を使用)
Mixed Reality Unity プラグイン		✔️ (OpenXR Runtime バージョン 113 と Mixed Reality Unity プラグイン ARMarkerManager)
レガシ QR SDK	✔️	✔️	✔️

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

従来の QR コード SDK を使用すると、Windows 10 バージョン 2004 以降では、デスクトップ PC 上のイマーシブ Windows Mixed Reality ヘッドセットを使用した QR コード追跡がサポートされています。 現在のデバイスでこの機能がサポートされているかどうかを判断するには、Microsoft.MixedReality.QRCodeWatcher.IsSupported() API を使用します。

サポートされている QR コードのバージョン

次の表は、サポートされる QR コード バージョンとサポートされない QR コード バージョンを示しています。

	QR コードのバージョン
サポート対象:	QR コード バージョン 1 ~ 10 マイクロQRコードM1-M4 すべてのエンコード
サポートされない:	QR コード 10 ~ 20 (完全にはサポートされていません) QR コード バージョン 21 以降 変形されたモジュール (円形のモジュール、反射、反転 (黒/白) など)。 ロゴス 構造化された追加

QR コードの検出のベスト プラクティス

QR コードの周りの非表示ゾーン

QR コードを正しく読み取るには、コードのすべての周りに余白が必要です。 この余白には、印刷されたコンテンツを含めることはできません。また、4 つのモジュール (コード内の 1 つの黒い四角形) の幅にする必要があります。

公式 QR コードのドキュメントには、静かなゾーンに関する詳細情報が含まれています。

照明と背景

QR コード検出の品質は、さまざまな照明や背景によって影響を受けます。

• 通常の照明条件下では、パフォーマンスを向上させるために、黒/白モジュールが十分なコントラストを持つようにします。

• 明るい照明や暗い背景がある極端な照明条件では、コントラストを下げて調整すると、QR コードの検出率を向上させることができます。 QR コード内の白い背景は、255 から減らすことができます。

QR コードのサイズ

Windows Mixed Reality および HoloLens デバイスは、側面が 5 cm 未満の QR コードでは動作しません。

5 cm から 10 cm までの辺の QR コードの場合、コードを検出するためにはデバイスをかなり近づける必要があります。 コードを検出するには、平均よりも長い時間がかかる場合があります。

コードを正確に検出する時間は、QR コードのサイズだけでなく、コードからどれだけ離れているかによって異なります。 サイズの問題を解決するには、コードにより近づける必要があります。

QR コードからの距離と角度

追跡カメラでは、特定の詳細度しか検出できません。 小さなコード (側面に沿って 10 cm 未満) の場合は、かなり近い必要があります。 バージョン 1 の QR コードのサイズが 10 cm から 25 cm の場合、最小検出距離は 0.15 メートルから 0.5 メートルです。

サイズに対して検出距離は比例して増加しますが、サポートされる QR のバージョンとモジュールのサイズによっても異なります。 バージョンが高くなるほど、モジュールは小さくなり、より近い位置からしか検出できなくなります。 検出距離をより長くする必要がある場合は、マイクロ QR コードを試すこともできます。 QR 検出は、コードの検出に適切な解像度を確保するために、+= 45° の範囲で動作します。

その他の検出に関する考慮事項:

• 曲面上の QR コードはサポートされません。
• 面配向がサポートされます。 より良い検出のためには、面外が正面から見て <= +-45 である必要があります。
• QR コードの物理サイズには、2/3 ピクセル以上のモジュールがある必要があります。 注: 上位バージョンの QR コードには、より小さなモジュールがあります。

最適な検出のための QR コードの距離とサイズのトレードオフの関係については、次のグラフを参照してください。

重要

十分なコントラストと適切な境界線が確保されていることを必ず確認してください。

QR コード データの管理

Windows Mixed Reality および HoloLens デバイスは、ドライバーのシステム レベルで QR コードを検出します。 デバイスが再起動されるか、ドライバーが再起動されると、検出された QR コードの履歴がクリアされます。 再検出された QR コードは、新しいオブジェクトとして扱われます。

特定のタイムスタンプよりも古い QR コードを無視するようにアプリを構成することをお勧めします。これはアプリ内で指定できます。 QR コード API は、最後に検出された時刻を指定します。 ほとんどのアプリ開発者は、アプリが起動されたときのシステム時刻を使用して、QR コードが検出された時刻を判断します。

QR コードのデータは、アプリ固有ではありません。 アプリの起動時には、提供されている使用可能な QR コードのリストがあります。 アプリ開発者は、このアプリに関連する QR コードを判別します。

特定のスペースにおける QR コードの配置

QR コードを配置する場所と方法に関する推奨事項については、「HoloLens の環境に関する考慮事項」を参照してください。

トラブルシューティングとよくあるご質問

どのような機能が必要ですか?

HoloLens アプリケーションで QR コード追跡を有効にするには、Web カメラ機能をアプリケーションのマニフェストに追加します。 Unity で開発している場合は、プレーヤーの設定からこれを構成できます。

さらに、アプリ Web カメラのアクセス許可を付与するアクセス許可ダイアログが表示される場合があります。 これは、アプリの有効期間中に 1 回だけ発生します。 Web カメラへのアクセスを明示的に要求するアプリなどの場合、ダイアログは再表示されません。

WebCam 機能を備えた Unity アプリの場合、シーンで ARMarkerManager を有効にすると、Web カメラのアクセス許可ダイアログが表示されます。

ネイティブの OpenXR C++ アプリの場合、XR_SCENE_COMPUTE_FEATURE_MARKER_MSFTを含むXrNewSceneComputeInfoMSFT::requestedFeaturesxrComputeNewSceneMSFTへの初期呼び出しによって、アクセス許可ダイアログをトリガーできます。

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

Web カメラ機能がマニフェストに追加されている必要があります (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 で自動的に行われるため、アプリに "Web カメラ" 機能を追加する必要があります。

API プラグインのファイルはどこで入手できますか?

アプリケーションでは、QR コードを検出するために HoloLen の OpenXR ランタイムを使用する必要があります。 OpenXR for Windows Mixed Reality (113.2403.5001 以降) は、HoloLens デバイスで QR コードをサポートします。

Unity アプリの場合、QR コードのサポートは、Mixed Reality OpenXR プラグインで提供されるARMarkerManager コンポーネントを通じて提供されます。

Unity 以外のアプリで QR コードをサポートする場合は、OpenXR XR_MSFT_scene_marker 拡張機能を使用します。

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

必要なすべてのファイルとドキュメントは、NuGet のこちらにあります。

Microsoft.MixedReality.QR

ARMarkerManager を使用して QR コードを検出するように Unity アプリを準備操作方法?

Unity アプリでは、 ARMarkerManager コンポーネントを使用して、物理環境内の QR コード検出がシーンでどのように表されるかを処理します。 ARMarkerManager は次の機能を提供します。

• 検出された QR コードがマネージャーに追加、更新、または削除されたときにサブスクライバーに通知するためのイベント。

• 検出中の QR コードの追跡可能な ARMarker のコレクション。

• 追跡可能な ID で指定された QR コードのデータを返すメソッド。

アプリで ARMarkerManager を使用するには、 Mixed Reality OpenXR プラグイン パッケージをインポートする必要があります。

パッケージをインポートするには、次のようにします。

1. Mixed Reality Feature Tool をダウンロード 実行します。
2. OpenXR プラグインをインストール します。

ツールの使用方法の詳細については、「 Mixed Reality Feature Tool に関する記事を参照してください。

次の一般的な手順は次のとおりです。

1. Unity プロジェクトで、 WebCam 機能を有効にします。
2. プレハブを作成し、次のように ARMarker コンポーネントをアタッチします。
   
3. 実行中に QR コードを検出するシーンを開きます。
4. シーン内の GameObject に ARMarkerManager をアタッチし、 Marker Prefab を作成したプレハブに設定します。
   

詳細な手順と情報については、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 をどのように準備すればよいですか?

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

• NuGet パックを使用して、必要なファイルをアンパックします。

• プロジェクトに Microsoft.MixedReality.QR.winmd への参照を追加し、API の使用を開始します。

• 正しいアーキテクチャ バージョンのプラグインを追加して、ビルドでそれらを使用します。

Microsoft.MixedReality.QR.QRCodeWatcher を使用するように Unity を準備するには、どのようにすればよいですか?

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

Unity に NuGet を使用して、上記の NuGet パックを指すようにします。

QR コードを作成するにはどうすればよいですか?

QR コード ジェネレーターを確認します。

QR コードの追跡が全般的に機能しない場合は、どうすればよいですか?

• QR コードのバージョンはサポートされているバージョンですか。 バージョン 40 などの高密度バージョンはサポートされません。 バージョン 10 を超えるものは保証されず、バージョン 20 を超えるものはサポートされません。

• QR コードに十分に近づいていますか。 「QR コードからの距離と角度」を参照してください。

• 照明はどのような状態ですか。 QR コードが暗い環境の背景にあると検出が困難になるという既知の問題があります。高コントラストのため、QR コードがカメラに洗い流されて表示されます。 詳細については、「照明と背景」を参照してください。

精度はどれくらいですか?

1 つのフレームで検出された場合は、実際のサイズとの誤差が最大で 1% あることが予想されます。 たとえば、10 cm のコードは、測定されたサイズで最大 +/- 1 mm の場合があります。 継続的な検出では、コードの位置が最大で +/- 2.5 mm ずれる場合があります。 検出範囲外に移動すると、以前に検出された位置はマップ誤差に左右されることになります。

QR コードを検出するには、どのくらい近づく必要がありますか?

距離は、言うまでもなく QR コードのサイズとそのバージョンによって異なります。 詳細については、「QR コードからの距離と角度」を参照してください。

• HoloLens 2 では、バージョン 1 の QR コードが 5 cm 辺から 25 cm 辺に変化する場合、最小検出距離は 0.25 メートルから 0.5 メートルの範囲です。 これらから検出できる最も遠いものは、最小コードの場合は約 0.5 m から、大きい場合は 2 メートルです。

• Windows Mixed Reality では、これらのサイズでの距離は半分になります。

• コードが大きい場合は、外挿 -- サイズの検出距離が直線的に増加します。 コードが小さい場合、検出は発生しません--4-5 cm は検出できる最小です。

ロゴ付きの QR コードを読み取れないのはなぜですか?

ロゴ付きの QR コードはサポートされていません。

QR コードが検出されるため、データが取得されないのはなぜですか?

• プラットフォームで QR コードをデコードできない場合、データは取得されません。 ストリームを使用し、オープンソースのコードを使用してデータを解釈できます。

• 構造体の追加など、一部の機能はサポートされていません。

詳細については、「サポートされる QR コードのバージョン」を参照してください。

QR コードは "スペース" レベルまたはアプリ レベルのどちらで保存されますか?

QR コードは、ドライバー セッションまたは HoloLens のブート セッションのシステム レベルで保存されます。 詳細については、「QR コード データの管理」を参照してください。

これは、基盤となるプラットフォームでどのように機能しますか? それらはどこに保持されますか?

検出された QR コードは、ドライバーによってメモリに保持されます。

"Microsoft.MixedReality.QR.pdb が見つかりません" というエラー メッセージが表示された場合は、Visual Studio でどのようにアプリをデバッグすればよいですか?

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

Microsoft.MixedReality.QR.dll のシンボルの読み込みがスキップされたのは、含まれるモジュールのリストに指定されていないためです。

再現方法

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

この動作を再現するには、次の手順に従います。

1. Microsoft.MixedReality.QR (NuGet) と MRTK をインストールします
2. デバッグを試みます

Microsoft.MixedReality.QR.dll を使用してアプリをデバッグできるはずですが、DLL が見つかりません。

推奨される解決策

Note

以下は、レガシ QR コード API に固有のものです。 代わりに、QR コードに OpenXR 実装を使用することをお勧めします。

シンボルが追加されるように、次のリリースに対して作業を行っています。 それまでの間は、Visual Studio オプションで DLL を除外することで、アプリをデバッグできます。

詳細については、「Visual Studio の設定の構成」を参照してください。

セッションでスキャンできる QR コードの数に制限はありますか?

ドライバーのシステム レベルで保存される QR コードは、10 分以内に 100 個に制限されています。

QR コードのスムージング プロセスは変更されましたか?

QRコード平滑化処理は、姿勢平滑化からサイズ平滑化まで、20H2後に変更された。 動作を前のスムージング プロセスに戻すには、新しい QR コードポーズ データが以前に検出されたフレームから 5 秒以内または 10 cm 以内に検出された場合に、スムージング アルゴリズムを適用します。 変換データは、現在のフレームの 90% と前のフレームの 10% の重み付け比率でブレンドされます。

関連項目

• ネイティブ C++ および C# サンプルを使用した QR コード追跡
• 座標系
• Azure Spatial Anchors
• HoloLens 2 の場所を特定できるカメラの概要