Vytvoření a vyhledání ukotvení pomocí Azure Spatial Anchors v Javě
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 Javě 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 v Javě
- Základní znalosti o ARCore.
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ě CloudSpatialAnchorSession .
private CloudSpatialAnchorSession mCloudSession;
// In your view handler
mCloudSession = new CloudSpatialAnchorSession();
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ě SessionConfiguration .
mCloudSession.getConfiguration().setAccountKey("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.
mCloudSession.getConfiguration().setAccessToken("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 rozhraní TokenRequiredListener .
mCloudSession.addTokenRequiredListener(args -> {
args.setAccessToken("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.
mCloudSession.addTokenRequiredListener(args -> {
CloudSpatialAnchorSessionDeferral deferral = args.getDeferral();
MyGetTokenAsync(myToken -> {
if (myToken != null) args.setAccessToken(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.
mCloudSession.getConfiguration().setAuthenticationToken("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.
mCloudSession.addTokenRequiredListener(args -> {
args.setAuthenticationToken("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.
mCloudSession.addTokenRequiredListener(args -> {
CloudSpatialAnchorSessionDeferral deferral = args.getDeferral();
MyGetTokenAsync(myToken -> {
if (myToken != null) args.setAuthenticationToken(myToken);
deferral.complete();
});
});
Nastavení relace
Vyvolá se, Start() aby relace mohla zpracovávat data prostředí.
Pokud chcete zpracovat události vyvolané relací, připojte obslužnou rutinu události.
mCloudSession.setSession(mSession);
mCloudSession.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.
mCloudSession.processFrame(mSession.update());
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 rozhraní SessionUpdatedListener .
mCloudSession.addSessionUpdatedListener(args -> {
auto status = args->Status();
if (status->UserFeedback() == SessionUserFeedback::None) return;
NumberFormat percentFormat = NumberFormat.getPercentInstance();
percentFormat.setMaximumFractionDigits(1);
mFeedback = String.format("Feedback: %s - Recommend Create=%s",
FeedbackToString(status.getUserFeedback()),
percentFormat.format(status.getRecommendedForCreateProgress()));
});
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ě CloudSpatialAnchor .
// Create a local anchor, perhaps by hit-testing and creating an ARAnchor
Anchor localAnchor = null;
List<HitResult> hitResults = mSession.update().hitTest(0.5f, 0.5f);
for (HitResult hit : hitResults) {
Trackable trackable = hit.getTrackable();
if (trackable instanceof Plane) {
if (((Plane) trackable).isPoseInPolygon(hit.getHitPose())) {
localAnchor = hit.createAnchor();
break;
}
}
}
// 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.
CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor();
cloudAnchor.setLocalAnchor(localAnchor);
Future createAnchorFuture = mCloudSession.createAnchorAsync(cloudAnchor);
CheckForCompletion(createAnchorFuture, cloudAnchor);
// ...
private void CheckForCompletion(Future createAnchorFuture, CloudSpatialAnchor cloudAnchor) {
new android.os.Handler().postDelayed(() -> {
if (createAnchorFuture.isDone()) {
try {
createAnchorFuture.get();
mFeedback = String.format("Created a cloud anchor with ID=%s", cloudAnchor.getIdentifier());
}
catch(InterruptedException e) {
mFeedback = String.format("Save Failed:%s", e.getMessage());
}
catch(ExecutionException e) {
mFeedback = String.format("Save Failed:%s", e.getMessage());
}
}
else {
CheckForCompletion(createAnchorFuture, cloudAnchor);
}
}, 500);
}
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.
Future<SessionStatus> sessionStatusFuture = mCloudSession.getSessionStatusAsync();
CheckForCompletion(sessionStatusFuture);
// ...
private void CheckForCompletion(Future<SessionStatus> sessionStatusFuture) {
new android.os.Handler().postDelayed(() -> {
if (sessionStatusFuture.isDone()) {
try {
SessionStatus value = sessionStatusFuture.get();
if (value.getRecommendedForCreateProgress() < 1.0f) return;
// Issue the creation request...
}
catch(InterruptedException e) {
mFeedback = String.format("Session status error:%s", e.getMessage());
}
catch(ExecutionException e) {
mFeedback = String.format("Session status error:%s", e.getMessage());
}
}
else {
CheckForCompletion(sessionStatusFuture);
}
}, 500);
}
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.
CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor();
cloudAnchor.setLocalAnchor(localAnchor);
Map<String,String> properties = cloudAnchor.getAppProperties();
properties.put("model-type", "frame");
properties.put("label", "my latest picture");
Future createAnchorFuture = mCloudSession.createAnchorAsync(cloudAnchor);
// ...
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.
CloudSpatialAnchor anchor = /* locate your anchor */;
anchor.getAppProperties().put("last-user-access", "just now");
Future updateAnchorPropertiesFuture = mCloudSession.updateAnchorPropertiesAsync(anchor);
CheckForCompletion(updateAnchorPropertiesFuture);
// ...
private void CheckForCompletion(Future updateAnchorPropertiesFuture) {
new android.os.Handler().postDelayed(() -> {
if (updateAnchorPropertiesFuture.isDone()) {
try {
updateAnchorPropertiesFuture.get();
}
catch(InterruptedException e) {
mFeedback = String.format("Updating Properties Failed:%s", e.getMessage());
}
catch(ExecutionException e) {
mFeedback = String.format("Updating Properties Failed:%s", e.getMessage());
}
}
else {
CheckForCompletion1(updateAnchorPropertiesFuture);
}
}, 500);
}
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.
Future<CloudSpatialAnchor> getAnchorPropertiesFuture = mCloudSession.getAnchorPropertiesAsync("anchorId");
CheckForCompletion(getAnchorPropertiesFuture);
// ...
private void CheckForCompletion(Future<CloudSpatialAnchor> getAnchorPropertiesFuture) {
new android.os.Handler().postDelayed(() -> {
if (getAnchorPropertiesFuture.isDone()) {
try {
CloudSpatialAnchor anchor = getAnchorPropertiesFuture.get();
if (anchor != null) {
anchor.getAppProperties().put("last-user-access", "just now");
Future updateAnchorPropertiesFuture = mCloudSession.updateAnchorPropertiesAsync(anchor);
// ...
}
} catch (InterruptedException e) {
mFeedback = String.format("Getting Properties Failed:%s", e.getMessage());
} catch (ExecutionException e) {
mFeedback = String.format("Getting Properties Failed:%s", e.getMessage());
}
} else {
CheckForCompletion(getAnchorPropertiesFuture);
}
}, 500);
}
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í.
Date now = new Date();
Calendar cal = Calendar.getInstance();
cal.setTime(now);
cal.add(Calendar.DATE, 7);
Date oneWeekFromNow = cal.getTime();
cloudAnchor.setExpiration(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
AnchorLocateCriteria criteria = new AnchorLocateCriteria();
criteria.setIdentifiers(new String[] { "id1", "id2", "id3" });
mCloudSession.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 rozhraní AnchorLocatedListener .
mCloudSession.addAnchorLocatedListener(args -> {
switch (args.getStatus()) {
case Located:
CloudSpatialAnchor foundAnchor = args.getAnchor();
// Go add your anchor to the scene...
break;
case AlreadyTracked:
// This anchor has already been reported and is being tracked
break;
case NotLocatedAnchorDoesNotExist:
// 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 NotLocated:
// 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.
Future deleteAnchorFuture = mCloudSession.deleteAnchorAsync(cloudAnchor);
// Perform any processing you may want when delete finishes (deleteAnchorFuture is done)
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.
mCloudSession.stop();
Chcete-li obnovit data prostředí zachycená ve vaší relaci, můžete vyvolat Reset().
mCloudSession.reset();
Chcete-li správně vyčistit po relaci, vyvolejte close().
mCloudSession.close();
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.