Understanding the AnchorLocateCriteria class
In this article you will learn the different options you can use when querying an anchor. We will go over the AnchorLocateCriteria class, its options and valid option combinations.
Anchor locate criteria
The AnchorLocateCriteria class helps you query the service for previously created anchors. One AnchorLocateCriteria object may be used per watcher at any time. Each AnchorLocateCriteria object must include exactly one of the following properties: Identifiers, NearAnchor, or NearDevice. Additional properties such as Strategy, BypassCache, and RequestedCategories can be set if desired.
Properties
Define exactly one of the following properties in your watcher:
Identifiers
Default Value: empty string array
Using Identifiers, you can define a list of anchor IDs for anchors you would like to locate. Anchor IDs are initially returned to you after successful anchor creation. With Identifiers specified, AnchorLocateCriteria restricts the set of requested anchors to anchors with matching anchor IDs. This property is specified using a string array.
NearAnchor
Default Value: not set
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. This property is specified using a NearAnchorCriteria object.
NearDevice
Default Value: not set
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. To have the best chance of finding anchors, you should configure SensorCapabilities to give the session access to all appropriate sensors. 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. This property is specified using a NearDeviceCriteria object.
Additional properties
BypassCache
Default Value: false
When an anchor has been created or found in a session, it is also stored in the cache. With this property set to false, any subsequent query in the same session will return the cached value. No request to the ASA service is made.
RequestedCategories
Default Value: Properties | Spatial
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. This property can be specified using the AnchorDataCategory enum.
| AnchorDataCategory Enum Value | Returned Data |
|---|---|
| None | No data is returned |
| Properties | Anchor properties including AppProperties are returned. |
| Spatial | Spatial information about an anchor is returned. |
Strategy
Default Value: AnyStrategy
Strategy further defines how anchors should be located. The Strategy property may be specified using a LocateStrategy enum.
| LocateStrategy Enum Value | Description |
|---|---|
| AnyStrategy | This strategy permits the system to use combinations of VisualInformation and Relationship strategies to find anchors. |
| VisualInformation | 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. 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. Currently, this strategy is only permitted in conjunction with the NearAnchor or Identifiers properties. 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. |
Valid combinations of LocateStrategy and AnchorLocateCriteria properties
Not all combinations of Strategy and AnchorLocateCriteria properties are currently permitted by the system. The following table shows the allowed combinations:
| Property | AnyStrategy | Relationship | VisualInformation |
|---|---|---|---|
| Identifiers | ✓ | ✓ | ✓ |
| NearAnchor | ✓ (will default to Relationship) | ✓ | |
| NearDevice | ✓ | ✓ |
Next steps
See How to create and locate anchors using Azure Spatial Anchors for some more examples using the AnchorLocateCriteria class.