AnchorLocateCriteria クラスについてUnderstanding the AnchorLocateCriteria class

この記事では、アンカーを照会する場合に使用できるさまざまなオプションについて説明します。In this article you will learn the different options you can use when querying an anchor. AnchorLocateCriteria クラス、そのオプション、およびオプションの有効な組み合わせについて見ていきます。We will go over the AnchorLocateCriteria class, its options and valid option combinations.

アンカーの検索条件Anchor locate criteria

AnchorLocateCriteria クラスは、以前に作成したアンカーをサービスに照会する場合に役立ちます。The AnchorLocateCriteria class helps you query the service for previously created anchors. ウォッチャーごとに 1 つの AnchorLocateCriteria オブジェクトをいつでも使用できます。One AnchorLocateCriteria object may be used per watcher at any time. 各 AnchorLocateCriteria オブジェクトには、次のプロパティのうち 1 つだけ 含める必要があります: IdentifiersNearAnchorNearDeviceEach AnchorLocateCriteria object must include exactly one of the following properties: Identifiers, NearAnchor, or NearDevice. 必要に応じて、StrategyBypassCacheRequestedCategories などの追加のプロパティを設定することもできます。Additional properties such as Strategy, BypassCache, and RequestedCategories can be set if desired.

PropertiesProperties

ご利用のウォッチャーでは、次のプロパティのうち 1 つだけ を定義します。Define exactly one of the following properties in your watcher:

識別子Identifiers

既定値: 空の文字列配列Default Value: empty string array

Identifiers を使用すると、検索するアンカーについてアンカー ID のリストを定義できます。Using Identifiers, you can define a list of anchor IDs for anchors you would like to locate. アンカー ID は、アンカーの作成が正常に完了すると、最初に返されます。Anchor IDs are initially returned to you after successful anchor creation. Identifiers を指定した場合、AnchorLocateCriteria では、要求されたアンカーのセットをアンカー ID と一致するアンカーに制限します。With Identifiers specified, AnchorLocateCriteria restricts the set of requested anchors to anchors with matching anchor IDs. このプロパティは、文字列配列を使用して指定されます。This property is specified using a string array.

NearAnchorNearAnchor

既定値: 設定されていませんDefault Value: not set

NearAnchor を使用すると、AnchorLocateCriteria で、要求されたアンカーのセットを選択されたアンカーから必要な距離内にあるアンカーに制限するように指定することができます。Using NearAnchor, you can specify that AnchorLocateCriteria restricts the set of requested anchors to anchors within a desired distance away from a chosen anchor. この選択したアンカーを、ソース アンカーとして指定する必要があります。You must provide this chosen anchor as the source anchor. また、ソース アンカーからの必要な距離を設定し、返されるアンカーの最大数を設定して、検索にさらに制限をかけることもできます。You may also set the desired distance away from the source anchor, and the maximum number of anchors returned, to further limit the search. このプロパティは、NearAnchorCriteria オブジェクトを使用して指定します。This property is specified using a NearAnchorCriteria object.

NearDeviceNearDevice

既定値: 設定されていませんDefault Value: not set

NearDevice を使用すると、AnchorLocateCriteria で、要求されたアンカーのセットをデバイスの物理的な場所の近くにあるものに制限するように指定することができます。Using NearDevice, you can specify that AnchorLocateCriteria restricts the set of requested anchors to those close to the device’s physical location. 有効になっているセンサーを使用すれば、デバイス周辺のアンカーを容易に検出することができます。Any enabled sensors will be used to help discover anchors around your device. アンカーを検出できる可能性を最大限に高めるには、該当するすべてのセンサーへのセッション アクセスを許可するように SensorCapabilities を構成する必要があります。To have the best chance of finding anchors, you should configure SensorCapabilities to give the session access to all appropriate sensors. このプロパティの設定方法および使用方法の詳細については、「粗い再局在化 - Azure Spatial Anchors | Microsoft Docs」ならびに C#Objective-CSwiftJavaC++/NDKC++/WinRT で "粗い再局在化を使用してアンカーを作成および検索する方法" を参照してください。For more information on setting up and using this property, see Coarse Relocalization - Azure Spatial Anchors | Microsoft Docs and How to create and locate anchors using coarse relocalization in C#, Objective-C, Swift, Java, C++/NDK, C++/WinRT. このプロパティは、NearDeviceCriteria オブジェクトを使用して指定します。This property is specified using a NearDeviceCriteria object.

追加のプロパティAdditional properties

BypassCacheBypassCache

既定値: falseDefault Value: false

セッション内でアンカーが作成または検索された場合、それはキャッシュにも格納されます。When an anchor has been created or found in a session, it is also stored in the cache. このプロパティを false に設定すると、同じセッション内の後続のクエリからは、キャッシュされた値が返されます。With this property set to false, any subsequent query in the same session will return the cached value. ASA サービスへの要求は行われません。No request to the ASA service is made.

RequestedCategoriesRequestedCategories

既定値: Properties | SpatialDefault Value: Properties | Spatial

このプロパティは、AnchorLocateCriteria を使用してクエリから返されるデータを特定する場合に使用されます。This property is used to determine what data is returned from a query using AnchorLocateCriteria. 既定値を使用するとプロパティと空間データの両方が返されます。プロパティと空間データの両方が必要な場合は、この値を変更しないでください。The default value returns both properties and spatial data, this should not be changed if properties and spatial data are both desired. このプロパティは、AnchorDataCategory 列挙型を使用して指定できます。This property can be specified using the AnchorDataCategory enum.

AnchorDataCategory 列挙値AnchorDataCategory Enum Value 返されるデータReturned Data
なしNone データは返されません。No data is returned
PropertiesProperties AppProperties などのアンカー プロパティが返されます。Anchor properties including AppProperties are returned.
SpatialSpatial アンカーに関する空間情報が返されます。Spatial information about an anchor is returned.

戦略Strategy

既定値: AnyStrategyDefault Value: AnyStrategy

Strategy を使用すると、アンカーの検索方法をさらに定義できます。Strategy further defines how anchors should be located. Strategy プロパティは、LocateStrategy 列挙型を使用して指定できます。The Strategy property may be specified using a LocateStrategy enum.

LocateStrategy 列挙値LocateStrategy Enum Value 説明Description
AnyStrategyAnyStrategy この戦略を使用すると、システムによって VisualInformation と Relationship 戦略の組み合わを使用して、アンカーを検索することができます。This strategy permits the system to use combinations of VisualInformation and Relationship strategies to find anchors.
VisualInformationVisualInformation この方法を指定すると、現在の環境からのビジュアル情報をアンカーのビジュアル占有領域のものと照合することによってアンカーを検索することが試みられます。This strategy attempts to find anchors by matching visual information from the current surroundings to those of the anchor’s visual footprint. アンカーのビジュアル占有領域とは、アンカーに現在関連付けられているビジュアル情報を指します。An anchor’s visual footprint refers to the visual information currently associated with the anchor. このビジュアル情報は、通常、アンカーの作成中に収集されますが、これに限定されるものではありません。This visual information is typically but not exclusively gathered during anchor creation. 現在、この方法は NearDevice または Identifier プロパティとの組み合わせでのみ使用できます。Currently, this strategy is only permitted in conjunction with the NearDevice or Identifiers properties.
リレーションシップRelationship この方法を指定すると、既存の接続されたアンカーを使用してアンカーの検索が試みられます。This strategy attempts to find anchors by making use of existing connected anchors. 現在、この方法は NearAnchor または Identifiers プロパティとの組み合わせでのみ使用できます。Currently, this strategy is only permitted in conjunction with the NearAnchor or Identifiers properties. Identifiers プロパティと組み合わせて使用する場合、同じセッション内でユーザーは、Identifiers 配列で ID が指定されているアンカーへの接続関係が既に確立されているアンカーを事前に検索している必要があります。When used with the Identifiers property, it is required that, in the same session, the user should have previously located an anchor(s) with already established connective relationships to the anchors whose IDs are specified in the Identifiers array.

LocateStrategy と AnchorLocateCriteria プロパティの有効な組み合わせValid combinations of LocateStrategy and AnchorLocateCriteria properties

現在、Strategy と AnchorLocateCriteria プロパティのすべての組み合わせがシステムで許可されているわけではありません。Not all combinations of Strategy and AnchorLocateCriteria properties are currently permitted by the system. 次の表に利用可能な組み合わせを示します。The following table shows the allowed combinations:

プロパティProperty AnyStrategyAnyStrategy リレーションシップRelationship VisualInformationVisualInformation
識別子Identifiers
NearAnchorNearAnchor ✓ (既定では Relationship)✓ (will default to Relationship)
NearDeviceNearDevice

次のステップNext steps

AnchorLocateCriteria クラスを使用したその他の例については、「Azure Spatial Anchors を使用してアンカーを作成および探知する方法」を参照してください。See How to create and locate anchors using Azure Spatial Anchors for some more examples using the AnchorLocateCriteria class.