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

• Egység
• Objective-C
• Swift
• Android Java
• C++/NDK
• C++/WinRT

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 a Unityben 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:

• Olvassa el az Azure Spatial Anchors áttekintését.
• Az 5 perces rövid útmutatók egyike befejeződött.
• Alapszintű ismeretek a C#-ról és a Unityről.
• Alapszintű ismeretek az ARCore-ról, ha Androidot vagy IOS-t szeretne használni, az ARKitet.

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.

    CloudSpatialAnchorSession cloudSession;
    // In your view handler
    this.cloudSession = 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.

    this.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.

    this.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 TokenRequiredDelegate delegáltról.

    this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs 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ó.

    this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
    {
        var deferral = args.GetDeferral();
        string myToken = await MyGetTokenAsync();
        if (myToken != null) 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.

    this.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.

    this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs 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ó.

    this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
    {
        var deferral = args.GetDeferral();
        string myToken = await MyGetTokenAsync();
        if (myToken != null) args.AuthenticationToken = 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.

További információ a Start metódusról.

#if UNITY_ANDROID || UNITY_IOS
    this.cloudSession.Session = aRSession.subsystem.nativePtr.GetPlatformPointer();
#elif UNITY_WSA || WINDOWS_UWP
    // No need to set a native session pointer for HoloLens.
#else
    throw new NotSupportedException("The platform is not supported.");
#endif

    this.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.

#if UNITY_ANDROID || UNITY_IOS
    XRCameraFrame xRCameraFrame;
    if (aRCameraManager.subsystem.TryGetLatestFrame(cameraParams, out xRCameraFrame))
    {
        long latestFrameTimeStamp = xRCameraFrame.timestampNs;

        bool newFrameToProcess = latestFrameTimeStamp > lastFrameProcessedTimeStamp;

        if (newFrameToProcess)
        {
            session.ProcessFrame(xRCameraFrame.nativePtr.GetPlatformPointer());
            lastFrameProcessedTimeStamp = latestFrameTimeStamp;
        }
    }
#endif

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 SessionUpdatedDelegate delegáltról.

    this.cloudSession.SessionUpdated += (object sender, SessionUpdatedEventArgs args) =>
    {
        var status = args.Status;
        if (status.UserFeedback == SessionUserFeedback.None) return;
        this.feedback = $"Feedback: {Enum.GetName(typeof(SessionUserFeedback), status.UserFeedback)} -" +
            $" Recommend Create={status.RecommendedForCreateProgress: 0.#%}";
    };

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 spawning an object within the scene
    Vector3 hitPosition = new Vector3();
#if UNITY_ANDROID || UNITY_IOS
    Vector2 screenCenter = new Vector2(0.5f, 0.5f);
    List<ARRaycastHit> aRRaycastHits = new List<ARRaycastHit>();
    if(arRaycastManager.Raycast(screenCenter, aRRaycastHits) && aRRaycastHits.Count > 0)
    {
        ARRaycastHit hit = aRRaycastHits[0];
        hitPosition = hit.pose.position;
    }
#elif WINDOWS_UWP || UNITY_WSA
    RaycastHit hit;
    if (this.TryGazeHitTest(out hit))
    {
        hitPosition = hit.point;
    }
#endif

    Quaternion rotation = Quaternion.AngleAxis(0, Vector3.up);
    this.localAnchor = GameObject.Instantiate(/* some prefab */, hitPosition, rotation);
    this.localAnchor.AddComponent<CloudNativeAnchor>();

    // 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.
    CloudNativeAnchor cloudNativeAnchor = this.localAnchor.GetComponent<CloudNativeAnchor>();
    if (cloudNativeAnchor.CloudAnchor == null) { await cloudNativeAnchor.NativeToCloud(); }  
    CloudSpatialAnchor cloudAnchor = cloudNativeAnchor.CloudAnchor;
    await this.cloudSession.CreateAnchorAsync(cloudAnchor);
    this.feedback = $"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 GetSessionStatusAsync metódusról.

    SessionStatus value = await this.cloudSession.GetSessionStatusAsync();
    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.

    CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor() { LocalAnchor = localAnchor };
    cloudAnchor.AppProperties[@"model-type"] = @"frame";
    cloudAnchor.AppProperties[@"label"] = @"my latest picture";
    await this.cloudSession.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.

További információ az UpdateAnchorPropertiesAsync metódusról.

    CloudSpatialAnchor anchor = /* locate your anchor */;
    anchor.AppProperties[@"last-user-access"] = @"just now";
    await this.cloudSession.UpdateAnchorPropertiesAsync(anchor);

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 GetAnchorPropertiesAsync metódusról.

    var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
    if (anchor != null)
    {
        anchor.AppProperties[@"last-user-access"] = @"just now";
        await this.cloudSession.UpdateAnchorPropertiesAsync(anchor);
    }

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árat tulajdonságról.

    cloudAnchor.Expiration = DateTimeOffset.Now.AddDays(7);

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.

További információ a CreateWatcher metódusról.

    AnchorLocateCriteria criteria = new AnchorLocateCriteria();
    criteria.Identifiers = new string[] { @"id1", @"id2", @"id3" };
    this.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ó az AnchorLocatedDelegate-meghatalmazottról .

    this.cloudSession.AnchorLocated += (object sender, AnchorLocatedEventArgs args) =>
    {
        switch (args.Status)
        {
            case LocateAnchorStatus.Located:
                CloudSpatialAnchor foundAnchor = args.Anchor;
                // Go add your anchor to the scene...
                break;
            case LocateAnchorStatus.AlreadyTracked:
                // This anchor has already been reported and is being tracked
                break;
            case LocateAnchorStatus.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 LocateAnchorStatus.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.

További információ a DeleteAnchorAsync metódusról.

Horgony törlése a hely keresése után (ajánlott)

    await this.cloudSession.DeleteAnchorAsync(cloudAnchor);
    // Perform any processing you may want when delete finishes

Horgony törlése hely keresése nélkül

Ha nem talál egy horgonyt, de mégis törölni szeretné, használhatja az GetAnchorPropertiesAsync API-t, amely bemenetként egy anchorId azonosítót használ az CloudSpatialAnchor objektum lekéréséhez. Ezután átadhatja ezt az objektumot DeleteAnchorAsync a törléshez.

var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
await this.cloudSession.DeleteAnchorAsync(anchor);

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.

    this.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ás módszerről.

    this.cloudSession.Reset();

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

További információ az Elidegenítési módszerről.

    this.cloudSession.Dispose();

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