Megosztás a következőn keresztül:

Horgonyok létrehozása és megkeresése az Azure Spatial Anchors használatával a Javában

  • Cikk

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 Javában a következőre:

  • 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:

Cross Platform

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ó a CloudSpatialAnchorSession osztályról.

    private CloudSpatialAnchorSession mCloudSession;
    // In your view handler
    mCloudSession = new CloudSpatialAnchorSession();

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ó a SessionConfiguration osztályról.

    mCloudSession.getConfiguration().setAccountKey("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.

    mCloudSession.getConfiguration().setAccessToken("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 TokenRequiredListener felületről.

    mCloudSession.addTokenRequiredListener(args -> {
        args.setAccessToken("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ó.

    mCloudSession.addTokenRequiredListener(args -> {
        CloudSpatialAnchorSessionDeferral deferral = args.getDeferral();
        MyGetTokenAsync(myToken -> {
            if (myToken != null) args.setAccessToken(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.

    mCloudSession.getConfiguration().setAuthenticationToken("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.

    mCloudSession.addTokenRequiredListener(args -> {
        args.setAuthenticationToken("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ó.

    mCloudSession.addTokenRequiredListener(args -> {
        CloudSpatialAnchorSessionDeferral deferral = args.getDeferral();
        MyGetTokenAsync(myToken -> {
            if (myToken != null) args.setAuthenticationToken(myToken);
            deferral.complete();
        });
    });

A munkamenet 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 csatoljon egy eseménykezelőt.

    mCloudSession.setSession(mSession);
    mCloudSession.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.

    mCloudSession.processFrame(mSession.update());

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 ReadyForCreateProgressRecommendedForCreateProgresshatározhatja meg. Ha ReadyForCreateProgress 1 felett van, elegendő adatunk van a felhőbeli térbeli horgony mentéséhez, de azt javasoljuk, hogy várjon, amíg RecommendedForCreateProgress az 1-et meghaladja.

További információ a SessionUpdatedListener felületről.

    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()));
    });

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ó a CloudSpatialAnchor osztályról.

    // 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);
    }

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.

    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);
    }

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.

    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);
    // ...

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.

    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);
    }

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.

    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);
    }

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.

    Date now = new Date();
    Calendar cal = Calendar.getInstance();
    cal.setTime(now);
    cal.add(Calendar.DATE, 7);
    Date oneWeekFromNow = cal.getTime();
    cloudAnchor.setExpiration(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 AnchorLocateCriteriamegadásával.

    AnchorLocateCriteria criteria = new AnchorLocateCriteria();
    criteria.setIdentifiers(new String[] { "id1", "id2", "id3" });
    mCloudSession.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ó az AnchorLocatedListener felületről.

    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;
        }
    });

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.

    Future deleteAnchorFuture = mCloudSession.deleteAnchorAsync(cloudAnchor);
    // Perform any processing you may want when delete finishes (deleteAnchorFuture is done)

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.

    mCloudSession.stop();

A munkamenetben rögzített környezeti adatok alaphelyzetbe állításához meghívhatja Reset()azokat.

    mCloudSession.reset();

A munkamenet után a megfelelő tisztításhoz hívja meg a () parancsot close().

    mCloudSession.close();

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.

Horgonykapcsolatok