Vytvoření a vyhledání ukotvení pomocí Azure Spatial Anchors v Objective-C
Azure Spatial Anchors umožňuje sdílet kotvy na světě mezi různými zařízeními. Podporuje několik různých vývojových prostředí. V tomto článku se dozvíte, jak používat sadu Azure Spatial Anchors SDK v Objective-C k:
- Správně nastavte a spravujte relaci Azure Spatial Anchors.
- Vytvořte a nastavte vlastnosti v místních ukotveních.
- Nahrajte je do cloudu.
- Vyhledejte a odstraňte cloudové prostorové kotvy.
Požadavky
K dokončení této příručky se ujistěte, že máte:
- Projděte si přehled Azure Spatial Anchors.
- Dokončili jsme jeden z 5minutových rychlých startů.
- Základní znalosti o Objective-C.
- Základní znalosti o ARKitu
Inicializace relace
Hlavním vstupním bodem sady SDK je třída představující vaši relaci. Obvykle deklarujete pole ve třídě, které spravuje vaši relaci zobrazení a nativní rozšířené reality.
Přečtěte si další informace o třídě ASACloudSpatialAnchorSession .
ASACloudSpatialAnchorSession *_cloudSession;
// In your view handler
_cloudSession = [[ASACloudSpatialAnchorSession alloc] init];
Nastavení ověřování
Pokud chcete získat přístup ke službě, musíte zadat klíč účtu, přístupový token nebo ověřovací token Microsoft Entra. Další informace najdete také na stránce Koncept ověřování.
Klíče účtu
Klíče účtu jsou přihlašovací údaje, které vaší aplikaci umožňují ověřovat se službou Azure Spatial Anchors. Zamýšleným účelem klíčů účtu je pomoct vám rychle začít. Zejména během fáze vývoje integrace vaší aplikace s Azure Spatial Anchors. Klíče účtu můžete použít tak, že je během vývoje vložíte do klientských aplikací. Při pokroku nad rámec vývoje se důrazně doporučuje přejít na ověřovací mechanismus, který je produkční, podporovaný přístupovými tokeny nebo ověřováním uživatelů Microsoft Entra. Pokud chcete získat klíč účtu pro vývoj, navštivte svůj účet Azure Spatial Anchors a přejděte na kartu Klíče.
Přečtěte si další informace o třídě ASASessionConfiguration .
_cloudSession.configuration.accountKey = @"MyAccountKey";
Přístupové tokeny
Přístupové tokeny představují robustnější metodu ověřování pomocí Azure Spatial Anchors. Zvláště při přípravě aplikace na produkční nasazení. Shrnutím tohoto přístupu je nastavení back-endové služby, pomocí které se klientská aplikace může bezpečně ověřit. Rozhraní back-endové služby s AAD za běhu a se službou zabezpečených tokenů Azure Spatial Anchors za účelem vyžádání přístupového tokenu. Tento token se pak doručí do klientské aplikace a použije se v sadě SDK k ověření pomocí Azure Spatial Anchors.
_cloudSession.configuration.accessToken = @"MyAccessToken";
Pokud přístupový token není nastavený, musíte zpracovat TokenRequired událost nebo implementovat metodu tokenRequired v delegovacím protokolu.
Událost můžete zpracovat synchronně nastavením vlastnosti argumentů události.
Přečtěte si další informace o metodě protokolu tokenRequired .
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
args.accessToken = @"MyAccessToken";
}
Pokud potřebujete spustit asynchronní práci v obslužné rutině, můžete odložit nastavení tokenu vyžádáním objektu deferral a jeho dokončením, jako v následujícím příkladu.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) args.accessToken = myToken;
[deferral complete];
}];
}
Ověřování Microsoft Entra
Azure Spatial Anchors také umožňuje aplikacím ověřovat pomocí tokenů Microsoft Entra ID (Active Directory). K integraci s Azure Spatial Anchors můžete například použít tokeny Microsoft Entra. Pokud podnik udržuje uživatele v Microsoft Entra ID, můžete zadat token Microsoft Entra v sadě Azure Spatial Anchors SDK. Díky tomu se můžete ověřit přímo ve službě Azure Spatial Anchors pro účet, který je součástí stejného tenanta Microsoft Entra.
_cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";
Stejně jako u přístupových tokenů platí, že pokud není nastavený token Microsoft Entra, musíte zpracovat událost TokenRequired nebo implementovat metodu tokenRequired v delegovacím protokolu.
Událost můžete zpracovat synchronně nastavením vlastnosti argumentů události.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
args.authenticationToken = @"MyAuthenticationToken";
}
Pokud potřebujete spustit asynchronní práci v obslužné rutině, můžete odložit nastavení tokenu vyžádáním objektu deferral a jeho dokončením, jako v následujícím příkladu.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) args.authenticationToken = myToken;
[deferral complete];
}];
}
Nastavení knihovny
Vyvolá se, Start() aby relace mohla zpracovávat data prostředí.
Pokud chcete zpracovat události vyvolané relací, nastavte delegate vlastnost relace na objekt, jako je zobrazení. Tento objekt musí implementovat SSCCloudSpatialAnchorSessionDelegate protokol.
Přečtěte si další informace o metodě start .
_cloudSession.session = self.sceneView.session;
_cloudSession.delegate = self;
[_cloudSession start];
Poskytnutí rámců do relace
Relace prostorového ukotvení funguje namapováním prostoru kolem uživatele. To vám pomůže určit, kde se kotvy nacházejí. Mobilní platformy (iOS &Android) vyžadují nativní volání kanálu fotoaparátu k získání snímků z knihovny ar vaší platformy. Naproti tomu HoloLens neustále kontroluje prostředí, takže není potřeba provádět konkrétní volání jako na mobilních platformách.
Přečtěte si další informace o metodě processFrame .
[_cloudSession processFrame:_sceneView.session.currentFrame];
Poskytnutí zpětné vazby uživateli
Můžete napsat kód pro zpracování aktualizované události relace. Tato událost se aktivuje pokaždé, když relace zlepšuje pochopení vašeho okolí. To vám umožní:
UserFeedbackPomocí třídy můžete uživateli poskytnout zpětnou vazbu při přesouvání zařízení a relace aktualizuje své znalosti prostředí. Chcete-li to provést,- Určete, v jakém okamžiku je dostatek sledovaných prostorových dat k vytvoření prostorových ukotvení. Určíte to pomocí nebo
ReadyForCreateProgressRecommendedForCreateProgress. JakmileReadyForCreateProgressje nad 1, máme dostatek dat k uložení cloudové prostorové ukotvení, ale doporučujeme počkat, ažRecommendedForCreateProgressbude nad 1, abyste to udělali.
Přečtěte si další informace o metodě protokolu sessionUpdated .
- (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];
}
Vytvoření cloudové prostorové ukotvení
Pokud chcete vytvořit cloudové prostorové ukotvení, nejprve vytvoříte ukotvení v systému rozšířené reality vaší platformy a pak vytvoříte cloudový protějšek. Použijete metodu CreateAnchorAsync() .
Přečtěte si další informace o třídě ASACloudSpatialAnchor .
// 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];
}];
Jak je popsáno výše, potřebujete dostatek dat prostředí zachycených před pokusem o vytvoření nového cloudového prostorového ukotvení. To znamená ReadyForCreateProgress , že musí být vyšší než 1, ale doporučujeme počkat na to, než RecommendedForCreateProgress je 1.
Přečtěte si další informace o metodě getSessionStatusWithCompletionHandler .
[_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 ...
}];
Nastavení vlastností
Při ukládání cloudových prostorových ukotvení můžete přidat některé vlastnosti. Stejně jako typ uloženého objektu nebo základní vlastnosti, jako je to, jestli má být povolena pro interakci. To může být užitečné při zjišťování: objekt můžete okamžitě vykreslit pro uživatele, například rámeček obrázku s prázdným obsahem. Pak se na pozadí zobrazí další podrobnosti o stavu, například obrázek, který se má zobrazit v rámečku.
Přečtěte si další informace o vlastnosti appProperties .
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
cloudAnchor.appProperties = @{ @"model-type" : @"frame", @"label" : @"my latest picture" };
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// ...
});
Aktualizace vlastností
Chcete-li aktualizovat vlastnosti ukotvení, použijte metodu UpdateAnchorProperties() . Pokud se dvě nebo více zařízení pokusí aktualizovat vlastnosti pro stejnou ukotvení najednou, použijeme model optimistické souběžnosti. To znamená, že první zápis vyhraje. Všechny ostatní zápisy se zobrazí chyba Concurrency: Před dalším pokusem by bylo potřeba aktualizovat vlastnosti.
Přečtěte si další informace o metodě updateAnchorProperties .
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];
}];
Umístění ukotvení po vytvoření ve službě nejde aktualizovat – musíte vytvořit novou ukotvení a odstranit starý, abyste mohli sledovat novou pozici.
Pokud nepotřebujete najít ukotvení pro aktualizaci jeho vlastností, můžete použít metodu GetAnchorPropertiesAsync() CloudSpatialAnchor , která vrací objekt s vlastnostmi.
Přečtěte si další informace o metodě getAnchorProperties .
[_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) {
// ...
}];
}
}];
Nastavit vypršení platnosti
V budoucnu je také možné nakonfigurovat, aby platnost ukotvení automaticky vypršela v daném datu. Když vyprší platnost ukotvení, nebude se už nacházet ani aktualizovat. Vypršení platnosti je možné nastavit pouze při vytvoření ukotvení před uložením do cloudu. Aktualizace vypršení platnosti později není možná. Pokud během vytváření ukotvení není nastavené žádné vypršení platnosti, platnost ukotvení vyprší pouze při ručním odstranění.
Přečtěte si další informace o vlastnosti vypršení platnosti .
int secondsInAWeek = 60 * 60 * 24 * 7;
NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) secondsInAWeek];
cloudAnchor.expiration = oneWeekFromNow;
Vyhledání cloudové prostorové ukotvení
Schopnost najít dříve uložené cloudové prostorové ukotvení je jedním z hlavních důvodů použití Azure Spatial Anchors. K tomu používáme "Watchers". Můžete použít pouze jeden Watcher najednou; více sledovacích procesů není podporováno. Sledovací proces může najít cloudové prostorové ukotvení několika různými způsoby (označovaných také jako Strategie hledání ukotvení). Na sledovacím nástroji můžete současně použít jednu strategii.
- Vyhledejte kotvy podle identifikátoru.
- Vyhledejte kotvy připojené k dříve umístěné ukotvení. Tady se dozvíte o relacích ukotvení.
- Vyhledejte kotvu pomocí hrubé relokalizace.
Poznámka:
Při každém vyhledání ukotvení se Azure Spatial Anchors pokusí použít data prostředí shromážděná k rozšíření vizuálních informací na ukotvení. Pokud máte potíže s vyhledáním kotvy, může být užitečné vytvořit kotvu a pak ji několikrát vyhledat z různých úhlů a světelných podmínek.
Pokud lokalizujete cloudové prostorové kotvy podle identifikátoru, můžete uložit identifikátor cloudové prostorové ukotvení v back-endové službě vaší aplikace a zpřístupnit ho všem zařízením, která se u ní můžou správně ověřit. Příklad najdete v tématu Kurz: Sdílení prostorových ukotvení napříč zařízeními.
Vytvořte instanci objektuAnchorLocateCriteria, nastavte identifikátory, které hledáte, a vyvoláte metodu CreateWatcher v relaci zadáním .AnchorLocateCriteria
Přečtěte si další informace o metodě createWatcher .
ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
criteria.identifiers = @[ @"id1", @"id2", @"id3" ];
[_cloudSession createWatcher:criteria];
Po vytvoření sledovacího nástroje se AnchorLocated událost aktivuje pro každou požadovanou ukotvení. Tato událost se aktivuje, když se nachází ukotvení nebo pokud se ukotvení nedá najít. Pokud k této situaci dojde, bude důvod uveden ve stavu. Po zpracování, nalezení nebo nenalezení LocateAnchorsCompleted všech ukotvení sledovacího prvku se událost aktivuje. Počet identifikátorů na sledovací proces je omezený na 35 identifikátorů.
Přečtěte si další informace o metodě protokolu anchorLocated .
- (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;
}
Odstranění ukotvení
Odstranění ukotvení, když už se nepoužívá, je vhodné zahrnout do procesu a postupů vývoje včas, aby se vaše prostředky Azure vyčistily.
Přečtěte si další informace o metodě deleteAnchor .
[_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// Perform any processing you may want when delete finishes
}];
Pozastavení, resetování nebo zastavení relace
Pokud chcete relaci dočasně zastavit, můžete vyvolat Stop(). Tím zastavíte zpracování všech sledovacích procesů a prostředí, a to i v případě, že vyvoláte ProcessFrame(). Potom můžete vyvolat Start() obnovení zpracování. Při obnovení se zachytávají data prostředí, která jsou v relaci zaznamenána.
Přečtěte si další informace o metodě zastavení .
[_cloudSession stop];
Chcete-li obnovit data prostředí zachycená ve vaší relaci, můžete vyvolat Reset().
Přečtěte si další informace o metodě resetování .
[_cloudSession reset];
Správné vyčištění po vydání relace všechny odkazy.
_cloudSession = NULL;
Další kroky
V této příručce jste se dozvěděli, jak vytvořit a najít ukotvení pomocí sady Azure Spatial Anchors SDK. Další informace o relacích ukotvení najdete v další příručce.