Horgonyok létrehozása és megkeresése az Azure Spatial Anchors használatával az Objective-C-ben
Az Azure Spatial Anchors lehetővé teszi a horgonyok megosztását a világ különböző eszközei között. Számos különböző fejlesztési környezetet támogat. Ebben a cikkben bemutatjuk, hogyan használhatja az Azure Spatial Anchors SDK-t az Objective-C-ben a következő célokra:
- Azure Spatial Anchors-munkamenet helyes beállítása és kezelése.
- Tulajdonságok létrehozása és beállítása a helyi horgonyokon.
- Töltse fel őket a felhőbe.
- Keresse meg és törölje a felhőbeli térbeli horgonyokat.
Előfeltételek
Az útmutató elvégzéséhez győződjön meg arról, hogy rendelkezik a következővel:
- Olvassa el az Azure Spatial Anchors áttekintését.
- Az 5 perces rövid útmutatók egyike befejeződött.
- Alapszintű ismeretek az Objective-C-ről.
- Alapszintű ismeretek az ARKitről.
A munkamenet inicializálása
Az SDK fő belépési pontja a munkamenetet képviselő osztály. Általában deklarál egy mezőt az osztályban, amely kezeli a nézetet és a natív AR-munkamenetet.
További információ az ASACloudSpatialAnchorSession osztályról.
ASACloudSpatialAnchorSession *_cloudSession;
// In your view handler
_cloudSession = [[ASACloudSpatialAnchorSession alloc] init];
Hitelesítés beállítása
A szolgáltatás eléréséhez meg kell adnia egy fiókkulcsot, hozzáférési jogkivonatot vagy Microsoft Entra hitelesítési jogkivonatot. Erről a hitelesítési koncepció oldalán is olvashat bővebben.
Fiókkulcsok
A fiókkulcsok olyan hitelesítő adatok, amelyek lehetővé teszik az alkalmazás számára az Azure Spatial Anchors szolgáltatással való hitelesítést. A fiókkulcsok célja, hogy segítsenek a gyors kezdésben. Különösen az alkalmazás Azure Spatial Anchors-nal való integrációjának fejlesztési fázisában. Így a fiókkulcsokat úgy használhatja, hogy beágyazza őket az ügyfélalkalmazásaiba a fejlesztés során. A fejlesztésen túlmutató fejlődés során erősen ajánlott éles szintű hitelesítési mechanizmusra váltani, amelyet az Access-jogkivonatok vagy a Microsoft Entra felhasználói hitelesítés támogat. Ha fejlesztési fiókkulcsot szeretne beszerezni, látogasson el az Azure Spatial Anchors-fiókjába, és lépjen a "Kulcsok" fülre.
További információ az ASASessionConfiguration osztályról.
_cloudSession.configuration.accountKey = @"MyAccountKey";
Access Tokens
Az Access-jogkivonatok egy robusztusabb módszer az Azure Spatial Anchors használatával történő hitelesítésre. Különösen akkor, ha előkészíti az alkalmazást egy éles üzembe helyezésre. Ennek a módszernek az összefoglalása egy háttérszolgáltatás beállítása, amellyel az ügyfélalkalmazás biztonságosan hitelesíthető. A háttérszolgáltatás felületei futtatókörnyezetben az AAD-vel és az Azure Spatial Anchors Secure Token Service-sel, hogy hozzáférési jogkivonatot igényeljenek. Ezt a jogkivonatot ezután kézbesíti az ügyfélalkalmazásnak, és az SDK-ban használja az Azure Spatial Anchors használatával történő hitelesítéshez.
_cloudSession.configuration.accessToken = @"MyAccessToken";
Ha nincs beállítva hozzáférési jogkivonat, akkor kezelnie kell az eseményt TokenRequired
, vagy implementálnia kell a tokenRequired
metódust a delegált protokollon.
Az esemény szinkron módon kezelhető az eseményargumentumok tulajdonságának beállításával.
További információ a tokenRequired protokoll metódusáról.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
args.accessToken = @"MyAccessToken";
}
Ha aszinkron munkát kell végrehajtania a kezelőben, elhalaszthatja a jogkivonat beállítását úgy, hogy egy deferral
objektumot kér le, majd végrehajtja, ahogy az alábbi példában is látható.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) args.accessToken = myToken;
[deferral complete];
}];
}
Microsoft Entra authentication
Az Azure Spatial Anchors lehetővé teszi az alkalmazások számára a Microsoft Entra ID (Active Directory) jogkivonatokkal való hitelesítést is. A Microsoft Entra-jogkivonatokkal például integrálható az Azure Spatial Anchors szolgáltatással. Ha egy vállalat microsoft entra-azonosítóban tart fenn felhasználókat, az Azure Spatial Anchors SDK-ban megadhat egy felhasználó Microsoft Entra-jogkivonatot. Ezzel lehetővé teszi, hogy közvetlenül hitelesítse magát az Azure Spatial Anchors szolgáltatásban egy olyan fiók esetében, amely ugyanahhoz a Microsoft Entra-bérlőhöz tartozik.
_cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";
A hozzáférési jogkivonatokhoz hasonlóan, ha nincs beállítva Microsoft Entra-jogkivonat, a TokenRequired eseményt kell kezelnie, vagy implementálnia kell a tokenRequired metódust a delegált protokollon.
Az esemény szinkron módon kezelhető az eseményargumentumok tulajdonságának beállításával.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
args.authenticationToken = @"MyAuthenticationToken";
}
Ha aszinkron munkát kell végrehajtania a kezelőben, elhalaszthatja a jogkivonat beállítását úgy, hogy egy deferral
objektumot kér le, majd végrehajtja, ahogy az alábbi példában is látható.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) args.authenticationToken = myToken;
[deferral complete];
}];
}
A tár beállítása
Meghívás Start()
a munkamenet környezeti adatok feldolgozásának engedélyezéséhez.
A munkamenet által kiváltott események kezeléséhez állítsa a delegate
munkamenet tulajdonságát egy objektumra, például a nézetre. Ennek az objektumnak implementálnia kell a protokollt SSCCloudSpatialAnchorSessionDelegate
.
További információ a kezdési módszerről.
_cloudSession.session = self.sceneView.session;
_cloudSession.delegate = self;
[_cloudSession start];
Keretek megadása a munkamenethez
A térbeli horgony munkamenet a felhasználó körüli tér leképezésével működik. Ez segít meghatározni, hogy hol találhatók a horgonyok. A mobilplatformok (iOS > Android) natív hívást igényelnek a kameracsatornához, hogy képkockákat szerezzenek be a platform AR-kódtárából. Ezzel szemben a HoloLens folyamatosan vizsgálja a környezetet, így nincs szükség konkrét hívásra, mint a mobilplatformokon.
További információ a processFrame metódusról.
[_cloudSession processFrame:_sceneView.session.currentFrame];
Visszajelzés küldése a felhasználónak
Írhat kódot a munkamenet frissített eseményének kezeléséhez. Ez az esemény minden alkalommal aktiválódik, amikor a munkamenet javítja a környezet megértését. Így a következőt végezheti el:
UserFeedback
Az osztály használatával visszajelzést küldhet a felhasználónak az eszköz áthelyezésekor, és a munkamenet frissíti a környezet megértését. Ehhez- Határozza meg, hogy mikor van elég nyomon követett térbeli adat a térbeli horgonyok létrehozásához. Ezt a beállítással vagy a .-val
ReadyForCreateProgress
RecommendedForCreateProgress
határozhatja meg. HaReadyForCreateProgress
1 felett van, elegendő adatunk van a felhőbeli térbeli horgony mentéséhez, de azt javasoljuk, hogy várjon, amígRecommendedForCreateProgress
az 1-et meghaladja.
További információ a sessionUpdated protokoll metódusról.
- (void)sessionUpdated:(ASACloudSpatialAnchorSession *)cloudSession :(ASASessionUpdatedEventArgs *)args {
ASASessionStatus *status = [args status];
if (status.userFeedback == ASASessionUserFeedbackNone) return;
_feedback = [NSString
stringWithFormat:@"Feedback: %@ - Recommend Create=%.0f%%",
FeedbackToString(status.userFeedback),
status.recommendedForCreateProgress * 100.f];
}
Felhőbeli térbeli horgony létrehozása
Felhőbeli térbeli horgony létrehozásához először hozzon létre egy horgonyt a platform AR-rendszerében, majd hozzon létre egy felhőbeli megfelelőt. A metódust CreateAnchorAsync()
használja.
További információ az ASACloudSpatialAnchor osztályról.
// Create a local anchor, perhaps by hit-testing and creating an ARAnchor
NSArray<ARHitTestResult *> *hits = [_sceneView.session.currentFrame hitTest:CGPointMake(0.5, 0.5) types:ARHitTestResultTypeEstimatedHorizontalPlane];
if ([hits count] == 0) return;
// The hitTest method sorts the resulting list by increasing distance from the camera
// The first hit result will usually be the most relevant when responding to user input
ARAnchor *localAnchor = [[ARAnchor alloc] initWithTransform:hits[0].worldTransform];
[_sceneView.session addAnchor:localAnchor];
// If the user is placing some application content in their environment,
// you might show content at this anchor for a while, then save when
// the user confirms placement.
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Save Failed:%@", error.localizedDescription];
return;
}
_feedback = [NSString stringWithFormat:@"Created a cloud anchor with ID=%@", cloudAnchor.identifier];
}];
A korábban leírtaknak megfelelően elegendő környezeti adatra van szüksége, mielőtt új felhőbeli térbeli horgonyt próbálna létrehozni. Ez azt jelenti ReadyForCreateProgress
, hogy 1 felett kell lennie, bár azt javasoljuk, hogy várjon, amíg RecommendedForCreateProgress
1 felett van.
További információ a getSessionStatusWithCompletionHandler metódusról.
[_cloudSession getSessionStatusWithCompletionHandler:^(ASASessionStatus *value, NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Session status error:%@", error.localizedDescription];
return;
}
if (value.recommendedForCreateProgress < 1.0f) return;
// Issue the creation request ...
}];
Tulajdonságok beállítása
A felhőbeli térbeli horgonyok mentésekor dönthet úgy, hogy hozzáad néhány tulajdonságot. Például a mentett objektum típusát vagy az alapvető tulajdonságokat, például azt, hogy engedélyezve kell-e az interakcióhoz. Ez a felderítéskor hasznos lehet: azonnal renderelheti az objektumot a felhasználó számára, például egy üres tartalommal rendelkező képkeretet. Ezután egy másik letöltés a háttérben további állapotadatokat kap, például a keretben megjelenítendő képet.
További információ az appProperties tulajdonságról.
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
cloudAnchor.appProperties = @{ @"model-type" : @"frame", @"label" : @"my latest picture" };
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// ...
});
Tulajdonságok frissítése
A horgony tulajdonságainak frissítéséhez használja a metódust UpdateAnchorProperties()
. Ha két vagy több eszköz egyszerre próbálja frissíteni ugyanazon horgony tulajdonságait, optimista egyidejűségi modellt használunk. Ami azt jelenti, hogy az első írás nyer. Minden más írásnál "Egyidejűség" hibaüzenet jelenik meg: a tulajdonságok frissítésére lenne szükség, mielőtt újra próbálkozna.
További információ az updateAnchorProperties metódusról.
ASACloudSpatialAnchor *anchor = /* locate your anchor */;
[anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
[_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
if (error) _feedback = [NSString stringWithFormat:@"Updating Properties Failed:%@", error.localizedDescription];
}];
A szolgáltatásban való létrehozás után nem frissítheti a horgony helyét – új horgonyt kell létrehoznia, és törölnie kell a régit az új pozíció nyomon követéséhez.
Ha nem kell megtalálnia egy horgonyt a tulajdonságainak frissítéséhez, használhatja a GetAnchorPropertiesAsync()
metódust, amely tulajdonságokat CloudSpatialAnchor
tartalmazó objektumot ad vissza.
További információ a getAnchorProperties metódusról.
[_cloudSession getAnchorProperties:@"anchorId" withCompletionHandler:^(SCCCloudSpatialAnchor *anchor, NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Getting Properties Failed:%@", error.localizedDescription];
return;
}
if (anchor) {
[anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
[_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
// ...
}];
}
}];
Lejárat beállítása
A horgonyt úgy is konfigurálhatja, hogy egy adott időpontban automatikusan lejárjon a jövőben. Ha egy horgony lejár, az már nem lesz elhelyezve vagy frissítve. A lejárat csak a horgony létrehozásakor állítható be, mielőtt a felhőbe mentené. A lejárat későbbi frissítése nem lehetséges. Ha nincs beállítva lejárat a horgony létrehozásakor, a horgony csak akkor jár le, ha manuálisan törölték.
További információ a lejárati tulajdonságról.
int secondsInAWeek = 60 * 60 * 24 * 7;
NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) secondsInAWeek];
cloudAnchor.expiration = oneWeekFromNow;
Felhőbeli térbeli horgony megkeresése
Az Azure Spatial Anchors használatának egyik fő oka a korábban mentett felhőbeli térbeli horgony megkeresése. Ehhez a "Figyelőket" használjuk. Egyszerre csak egy Figyelőt használhat; több figyelő nem támogatott. A Figyelő többféleképpen is megkeresheti a felhőbeli térbeli horgonyt (más néven horgonykeresési stratégiákat). Egyszerre egy stratégiát használhat egy figyelőn.
- Keresse meg a horgonyokat azonosító alapján.
- Keresse meg a korábban található horgonyhoz csatlakoztatott horgonyokat. A horgonykapcsolatokról itt olvashat.
- Keresse meg a horgonyt durva áthelyezéssel.
Megjegyzés:
Minden alkalommal, amikor megkeres egy horgonyt, az Azure Spatial Anchors megkísérli használni az összegyűjtött környezeti adatokat a horgony vizuális információinak bővítéséhez. Ha problémát tapasztal egy horgony megkeresése során, hasznos lehet horgonyt létrehozni, majd többször megkeresni a különböző szögekből és megvilágítási körülményekből.
Ha a felhőbeli térbeli horgonyokat azonosító alapján tárolja, a felhőbeli térbeli horgonyazonosítót az alkalmazás háttérszolgáltatásában tárolhatja, és akadálymentessé teheti az összes olyan eszköz számára, amely megfelelően hitelesítheti azt. Erre példa : Oktatóanyag: Térbeli horgonyok megosztása eszközök között.
Példányosítson egy AnchorLocateCriteria
objektumot, állítsa be a keresett azonosítókat, és hívja meg a CreateWatcher
metódust a munkamenetben a saját AnchorLocateCriteria
megadásával.
További információ a createWatcher metódusról.
ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
criteria.identifiers = @[ @"id1", @"id2", @"id3" ];
[_cloudSession createWatcher:criteria];
A figyelő létrehozása után az esemény minden AnchorLocated
kért horgonynál aktiválódik. Ez az esemény akkor aktiválódik, ha egy horgony található, vagy ha a horgony nem található. Ha ez a helyzet bekövetkezik, az ok az állapotban lesz feltüntetve. Miután egy figyelő összes horgonyát feldolgozta, megtalálta vagy nem találta, az LocateAnchorsCompleted
esemény kigyullad. Figyelőnként legfeljebb 35 azonosító lehet.
További információ a anchorLocated protokoll metódusról.
- (void)anchorLocated:(ASACloudSpatialAnchorSession *)cloudSession :(ASAAnchorLocatedEventArgs *)args {
ASALocateAnchorStatus status = [args status];
switch (status) {
case ASALocateAnchorStatusLocated: {
ASACloudSpatialAnchor *foundAnchor = [args anchor];
// Go add your anchor to the scene...
}
break;
case ASALocateAnchorStatusAlreadyTracked:
// This anchor has already been reported and is being tracked
break;
case ASALocateAnchorStatusNotLocatedAnchorDoesNotExist:
// The anchor was deleted or never existed in the first place
// Drop it, or show UI to ask user to anchor the content anew
break;
case ASALocateAnchorStatusNotLocated:
// The anchor hasn't been found given the location data
// The user might in the wrong location, or maybe more data will help
// Show UI to tell user to keep looking around
break;
}
Horgonyok törlése
A már nem használt horgonyok törlése ajánlott eljárás a fejlesztési folyamat és a gyakorlatok korai szakaszában, hogy az Azure-erőforrásokat megtisztítsa.
További információ a deleteAnchor metódusról.
[_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// Perform any processing you may want when delete finishes
}];
A munkamenet szüneteltetése, alaphelyzetbe állítása vagy leállítása
A munkamenet ideiglenes leállításához meghívhatja Stop()
a következőt: . Ha így tesz, akkor is leállítja a figyelők és a környezet feldolgozását, ha meghívja ProcessFrame()
. Ezután meghívhatja Start()
a feldolgozás folytatásához. A folytatáskor a munkamenetben már rögzített környezeti adatok megmaradnak.
További információ a stop metódusról.
[_cloudSession stop];
A munkamenetben rögzített környezeti adatok alaphelyzetbe állításához meghívhatja Reset()
azokat.
További információ az alaphelyzetbe állítási módszerről.
[_cloudSession reset];
A munkamenet-kiadás után a megfelelő törléshez minden hivatkozás.
_cloudSession = NULL;
További lépések
Ebben az útmutatóban megismerhette, hogyan hozhat létre és kereshet horgonyokat az Azure Spatial Anchors SDK használatával. A horgonykapcsolatokról a következő útmutatóban olvashat bővebben.