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

• 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 Swiftben 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 Swiftrő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.

    var _cloudSession : ASACloudSpatialAnchorSession? = nil
    // In your view handler
    _cloudSession = ASACloudSpatialAnchorSession()

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.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        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ó.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        let deferral = args.getDeferral()
        myGetTokenAsync( withCompletionHandler: { (myToken: String?) in
            if (myToken != nil) {
                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.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        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ó.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        let deferral = args.getDeferral()
        myGetTokenAsync( withCompletionHandler: { (myToken: String?) in
            if (myToken != nil) {
                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(self.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 RecommendedForCreateProgresshatá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 sessionUpdated protokoll metódusról.

    internal func sessionUpdated(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASASessionUpdatedEventArgs!) {
        let status = args.status!
        if (status.userFeedback.isEmpty) {
            return
        }
        _feedback = "Feedback: \(FeedbackToString(userFeedback:status.userFeedback)) - Recommend Create=\(status.recommendedForCreateProgress * 100)"
    }

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
    var localAnchor : ARAnchor? = nil
    let hits = self.sceneView.session.currentFrame?.hitTest(CGPoint(x:0.5, y:0.5), types: ARHitTestResult.ResultType.estimatedHorizontalPlane)
    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
    localAnchor = ARAnchor(transform:hits![0].worldTransform)
    self.sceneView.session.add(anchor: _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.
    var cloudAnchor : ASACloudSpatialAnchor? = nil
    cloudAnchor = ASACloudSpatialAnchor()
    cloudAnchor!.localAnchor = localAnchor
    _cloudSession?.createAnchor(cloudAnchor!, withCompletionHandler: { (error: Error?) in
        if (error != nil) {
            _feedback = "Save Failed:\(error!.localizedDescription)"
            return
        }
        _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 getStatusWithCompletionHandler metódusról.

    _cloudSession?.getStatusWithCompletionHandler( { (value:ASASessionStatus, error:Error?) in
        if (error != nil) {
            _feedback = "Session status error:\(error!.localizedDescription)"
            return
        }
        if (value!.recommendedForCreateProgress <> 1.0) {
            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.

    var cloudAnchor : ASACloudSpatialAnchor? = nil
    cloudAnchor = ASACloudSpatialAnchor()
    cloudAnchor!.localAnchor = localAnchor
    cloudAnchor!.appProperties = [ "model-type" : "frame", "label" : "my latest picture" ]
    _cloudSession?.createAnchor(cloudAnchor!, withCompletionHandler: { (error: Error?) in
        // ...
    })

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.

    var anchor : ASACloudSpatialAnchor? = /* locate your anchor */;
    anchor!.appProperties["last-user-access"] = "just now"
    _cloudSession?.updateAnchorProperties(anchor!, withCompletionHandler: { (error:Error?) in
        if (error != nil) {
            _feedback = "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: { (anchor:SCCCloudSpatialAnchor?, error:Error?) in
        if (error != nil) {
            _feedback = "Getting Properties Failed:\(error!.localizedDescription)"
        }
        if (anchor != nil) {
            anchor!.appProperties["last-user-access"] = "just now"
            _cloudSession?.updateAnchorProperties(anchor!, withCompletionHandler: { (error:Error?) in
                // ...
            })
        }
    })

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.

    let secondsInAWeek = 60.0 * 60.0 * 24.0 * 7.0
    let oneWeekFromNow = Date(timeIntervalSinceNow: 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 AnchorLocateCriteriamegadásával.

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

    let criteria = ASAAnchorLocateCriteria()!
    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.

    internal func anchorLocated(_ cloudSession: ASACloudSpatialAnchorSession!, _ args: ASAAnchorLocatedEventArgs!) {
        let status = args.status
        switch (status) {
        case ASALocateAnchorStatus.located:
            let foundAnchor = args.anchor
            // Go add your anchor to the scene...
            break
        case ASALocateAnchorStatus.alreadyTracked:
            // This anchor has already been reported and is being tracked
            break
        case ASALocateAnchorStatus.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 ASALocateAnchorStatus.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 törlési módszerről.

    _cloudSession?.delete(cloudAnchor!, withCompletionHandler: { (error: Error?) in
        // 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 = nil

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