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

Horgonyok létrehozása és megkeresése az Azure Spatial Anchors használatával az Objective-C-ben

  • 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 az Objective-C-ben a következő célokra:

  • 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ó az ASACloudSpatialAnchorSession osztályról.

    ASACloudSpatialAnchorSession *_cloudSession;
    // In your view handler
    _cloudSession = [[ASACloudSpatialAnchorSession alloc] init];

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.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)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ó.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
        [myGetTokenAsync callback:^(NSString *myToken) {
            if (myToken) 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.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)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ó.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
        [myGetTokenAsync callback:^(NSString *myToken) {
            if (myToken) 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:_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 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 sessionUpdated protokoll metódusról.

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

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

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

    [_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 ...
    }];

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.

    ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
    cloudAnchor.localAnchor = localAnchor;
    cloudAnchor.appProperties = @{ @"model-type" : @"frame", @"label" : @"my latest picture" };
    [_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
        // ...
    });

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.

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

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:^(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) {
                // ...
            }];
        }
    }];

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.

    int secondsInAWeek = 60 * 60 * 24 * 7;
    NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) 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.

    ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
    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.

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

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

    [_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
        // 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 = NULL;

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