クラウド認識
Wikitude Cloud RecognitionサービスはWikitudeによって提供されているクラウドベースのサービスであり、Wikitude SDKを使用してAndroidおよびiOSから送信された画像を認識します。認識された画像はカメラビューからの入力でトラッキングされ、AR体験に使用できます。
このドキュメントは、Manager APIと呼ばれるRESTful APIに焦点を合わせています。このAPIはCloud Recognitionサービスとのバックエンドレベルでのやり取りに使用されます。
用語の定義
-
ターゲット: 認識対象の画像と認識に必要とされる抽出データ。
-
ターゲットコレクション: ターゲットの集合体。認識対象の画像すべてを含むディレクトリと見なすことができます。Wikitude SDKでは2種類の異なるターゲットコレクションを扱うことができます。
- オンデバイスターゲットコレクション: 認識対象の画像と認識に必要とされる抽出データを含む静的な
wtc
ファイル。格納できる画像の数は最大1,000です。 - クラウドターゲットコレクション: Wikitudeサーバーに保存されたターゲットコレクション。下記の「クラウドアーカイブ」を参照してください。
- オンデバイスターゲットコレクション: 認識対象の画像と認識に必要とされる抽出データを含む静的な
-
クラウドアーカイブ: サーバーに保存されている、クラウド認識用に最適化されたアーカイブ。ターゲットコレクションから生成され、Wikitude SDK
AR.CloudRecognitionService
と組み合わせて使用されます。 -
ImageTracker:
AR.ImageTracker
と、AR.TargetCollectionResource
の組み合わせのようにカメラビューからの入力をデバイスで直接分析および計算するのではなく、AR.ImageTracker
とAR.CloudRecognitionService
を組み合わせることで、カメラで撮影した画像をWikitude Cloud Recognitionサーバーに送信します。サーバーは送られてきた画像を指定されたクラウドアーカイブ内のターゲットと一致させるための作業を行います。AR.CloudRecognitionService
には、AR.TargetCollectionResource
に比べて大規模な画像データベースを検索できる利点があり、さらにはほとんどのケースで全体的なパフォーマンスも向上します。特にターゲット数の多いターゲットコレクションや性能がそれほど高くないデバイスを使用するときに効果的です。 -
Manager API: ターゲット、ターゲットコレクション、およびクラウドアーカイブを管理するために開発者がCloud Recognitionサーバーとのやり取りに使用するRESTfulなWeb API。このAPIは開発者のみが使用します。アプリケーションのユーザーがこのAPIで通信することはありません。
-
Client API: Client APIは、Wikitude SDKとCloud Recognitionサービスとのインタフェースです。API自体はWikitude SDKの
AR.CloudTracker
クラスにカプセル化されており、直接アクセスすることはできません。Client APIの呼び出しのことを「スキャン」と呼びます。 -
Region: Wikitudeは、ネットワーク遅延を削減する目的として、クラウド認識サービスのために様々なホスティング場所を提供しています。開発者は、クラウド認識サービスの操作対象となる
Region
を選択する必要があります。
Cloud Recognitionサービスを使い始める前に
WIKITUDE CLOUD RECOGNITIONサービス用の利用可能な地域
Wikitude Cloud Recognitionサービスを使用する開発者は、プロジェクトで利用するサーバーの場所を選択する必要があります。Wikitudeは、世界中にWikitude Cloud Recognitionサービスを操作できるサーバーを提供しています。
地域サーバーが分離されているので、一つの領域のサーバーに格納された内容は、その特定のサーバー上のみで利用可能です。内容は地域全体に同期されません。選択可能なRegion
は以下の通りです。
Americas
Europe
各地域のサーバーは、専用のドメイン名および異なる構成があります。
Region | Target Manager | Manager API | SDK Setting |
---|---|---|---|
Americas | targetmanager‑us.wikitude.com | https://api-us.wikitude.com | Americas |
Europe | targetmanager.wikitude.com | https://api.wikitude.com または https://api-eu.wikitude.com | Europe |
準備
- Wikitudeアカウントを作成します。
- Cloud Recognitionサービスを使用するために必要なManager APIおよびClient API用のAPIトークンを取得します。認証の詳細については、このセクションを参照してください。
- サンプルを使用してAPIの認証を確認します。
- 確認が完了したら、製品版トークンを購入します。
最初のステップと基本的な使い方
- APIリファレンスを参照してManager APIの使い方を理解します。
ターゲットコレクション作成用
のエンドポイントを使用して最初のターゲットコレクションを作成し、ターゲットコレクションのIDを書き留めます。ターゲット作成用
のエンドポイントを使用して、そのターゲットコレクション用のターゲットを追加します。- 重要: ターゲットコレクション用の
クラウドアーカイブを生成
します。 - Wikitude SDKでAndroidまたはiOSプロジェクトを作成します。
- Client APIトークンを使用してAndroidまたはiOSプロジェクトを認証します。
- ターゲットコレクションIDを使用して画像を認識します。
使用可能なエンドポイント、およびManager APIの操作方法の詳細については、このセクションを参照してください。
ターゲットコレクション
の作成の代わりにREST APIを呼び出すことで、一つ以上のターゲット
の追加、クラウドアーカイブ
の生成を行います。Wikitude Targetmanagerはブラウザの代わりに手順1~4を実行することができます。
この場合、APIの呼び出しを確認するために、Postmanツールの使用を推奨します。このツールはリクエストの構成や応答の分析を手助けします。
認証
Cloud Recognitionサービスを使用するには、以下の2種類の認証トークンが必要です。
-
Manager APIトークン: このトークンは、開発者をRESTful Manager APIに対して認証するために必要です。Manager APIは、ターゲットおよびターゲットコレクションの作成、追加、削除に使用します。このトークンはWikitudeアカウントに関連付けられています。Manager APIの呼び出しは割り当て制限にカウントされません。
-
Client APIトークン: このトークンは、Wikitude SDKからCloud Recognitionサービスへの呼び出しを認証するために必要です。さらに、呼び出しを正当なものとして認証します。このトークンはWikitudeアカウントに関連付けられています。誤ったトークンまたはトークンなしでWikitude SDKからClient APIを呼び出した場合、Cloud Recognitionサービスにアクセスできません。
Manager APIの認証
Manager APIの各呼び出しにManager APIトークンを追加する必要があります。このトークンは、APIを使用していWikitudeアカウントを認証します。
Client APIの認証
Wikitude SDKを使用したアプリケーションにClient APIトークンを追加する必要があります。AR.CloudRecognitionService
クラスを操作するときに、SDKライセンスキーとこのトークンが必要となります。
制限事項
一般的なアップロード制限
Wikitude Cloud Recognitionサービスでは、1024kB(1MB)を超える画像はターゲットとして使用できません。このファイルサイズより大きい画像をアップロードしようとすると、HTTPステータスコード400
とエラーメッセージFILE_SIZE_LIMIT_EXCEED
が返されます。
Wikitude Cloud Recognitionサービスの制限
Wikitude Cloud Recognitionサービスには、知っておかなければならない大きな制限が2つあります。
-
ターゲット: あるWikitudeアカウントの下でクラウドサービスにアップロードおよび保存できるターゲットの数は、トークンによって一定数に制限されています。この制限は常に、単一のターゲットコレクションではなくWikitudeアカウント全体に対してカウントされます。カウントする対象はアップロードの回数ではなく、ある特定のアカウントの下でターゲットコレクションに現在保存されているターゲットの数です。
-
スキャン: スキャンとは実質的に、Client APIによるWikitude SDKからCloud Recognitioサービスへの呼び出しのことです。すべての製品版トークンでは、1つのWikitudeアカウントあたり1か月に1,000,000回のスキャンが許可されています。メモ: 連続認識モードを使用すると、呼び出しが連続的に繰り返されます。
ターゲットコレクション内のターゲットの最大数
1つのターゲットコレクションには最大50,000のターゲットを保持できます。
Cloud Recognitionサービスのトライアルトークン
Cloud Recognitionサービスを無償で試すために、各Wikitudeアカウントにトライアルトークンが付属しています。このトライアルトークンには、開発者がサービスの機能を試用およびテストするのに十分な量の割り当て制限が設定されています。トライアルトークンの制限は以下のとおりです。
- ターゲット: 50,000
- スキャン: 1か月あたり1,000
トライアルトークンを取得するには、ライセンスページを参照してください。トライアルトークンは、Target Manager Frontendに直接統合されます。
製品版ライセンス
製品版ライセンスは、こちらからご購入いただけます。