Bagikan melalui

Cara membuat dan menemukan jangkar menggunakan Azure Spatial Anchors di Objective-C

  • Artikel

Azure Spatial Anchors memungkinkan Anda menggunakan jangkar yang sama di dunia antara perangkat yang berbeda. Layanan ini mendukung beberapa lingkungan pengembangan yang berbeda. Dalam artikel ini, kita akan mendalami cara menggunakan Azure Spatial Anchors SDK, di Objective-C, untuk:

  • Menyiapkan dan mengelola sesi Azure Spatial Anchors dengan benar.
  • Membuat dan mengatur properti pada jangkar lokal.
  • Mengunggahnya ke cloud.
  • Menemukan dan menghapus jangkar spasial cloud.

Prasyarat

Untuk menyelesaikan panduan ini, pastikan Anda telah:

Cross Platform

Menginisialisasi sesi

Titik masuk utama untuk SDK adalah kelas yang mewakili sesi Anda. Umumnya Anda akan mendeklarasikan bidang di kelas yang mengelola tampilan dan sesi AR asli Anda.

Pelajari selengkapnya tentang kelas ASACloudSpatialAnchorSession.

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

Mengonfigurasikan autentikasi

Untuk mengakses layanan, Anda perlu menyediakan kunci akun, token akses, atau token autentikasi Microsoft Entra. Anda juga dapat membaca selengkapnya tentang ini di halaman Konsep Autentikasi.

Kunci Akun

Kunci Akun adalah informasi masuk yang memungkinkan aplikasi Anda untuk mengautentikasi dengan layanan Azure Spatial Anchors. Tujuan yang dimaksudkan dari Kunci Akun adalah untuk membantu Anda memulai dengan cepat. Terutama selama fase pengembangan integrasi aplikasi Anda dengan Azure Spatial Anchors. Dengan demikian, Anda dapat menggunakan Kunci Akun dengan menyematkannya di aplikasi klien Anda selama pengembangan. Saat Anda maju di luar pengembangan, sangat disarankan untuk pindah ke mekanisme autentikasi tingkat produksi, didukung oleh Token Akses, atau autentikasi pengguna Microsoft Entra. Untuk mendapatkan Kunci Akun untuk pengembangan, kunjungi akun Azure Spatial Anchors Anda, dan navigasikan ke tab "Kunci".

Pelajari selengkapnya tentang kelas ASASessionConfiguration.

    _cloudSession.configuration.accountKey = @"MyAccountKey";

Token Akses

Token Akses adalah metode yang lebih kuat untuk mengautentikasi dengan Spatial Anchors Azure. Terutama saat Anda menyiapkan aplikasi Anda untuk penyebaran produksi. Ringkasan pendekatan ini adalah untuk menyiapkan layanan ujung belakang yang dapat diautentikasi dengan aman oleh aplikasi klien Anda. Antarmuka layanan ujung belakang Anda dengan AAD pada runtime dan dengan Layanan Token Aman Spatial Anchors Azure untuk meminta Token Akses. Token ini kemudian dikirim ke aplikasi klien dan digunakan dalam SDK untuk mengautentikasi dengan Spatial Anchors Azure.

    _cloudSession.configuration.accessToken = @"MyAccessToken";

Jika token akses belum diatur, Anda harus menangani kejadian TokenRequired, atau menerapkan metode tokenRequired pada protokol delegasi.

Anda dapat menangani kejadian secara sinkron dengan mengatur properti pada argumen kejadian.

Pelajari selengkapnya tentang metode protokol tokenRequired.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        args.accessToken = @"MyAccessToken";
    }

Jika Anda harus menjalankan tugas asinkron di handler, Anda dapat menunda pengaturan token dengan meminta obhek deferral, lalu menyelesaikannya, seperti dalam contoh berikut.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
        [myGetTokenAsync callback:^(NSString *myToken) {
            if (myToken) args.accessToken = myToken;
            [deferral complete];
        }];
    }

Autentikasi Microsoft Entra

Azure Spatial Anchors juga memungkinkan aplikasi untuk mengautentikasi dengan token ID Microsoft Entra (Direktori Aktif) pengguna. Misalnya, Anda dapat menggunakan token Microsoft Entra untuk berintegrasi dengan Azure Spatial Anchors. Jika Enterprise mempertahankan pengguna di ID Microsoft Entra, Anda dapat menyediakan token Microsoft Entra pengguna di Azure Spatial Anchors SDK. Melakukannya memungkinkan Anda mengautentikasi langsung ke layanan Azure Spatial Anchors untuk akun yang merupakan bagian dari penyewa Microsoft Entra yang sama.

    _cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";

Seperti token akses, jika token Microsoft Entra tidak diatur, Anda harus menangani peristiwa TokenRequired, atau menerapkan metode tokenRequired pada protokol delegasi.

Anda dapat menangani kejadian secara sinkron dengan mengatur properti pada argumen kejadian.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        args.authenticationToken = @"MyAuthenticationToken";
    }

Jika Anda harus menjalankan tugas asinkron di handler, Anda dapat menunda pengaturan token dengan meminta obhek deferral, lalu menyelesaikannya, seperti dalam contoh berikut.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
        [myGetTokenAsync callback:^(NSString *myToken) {
            if (myToken) args.authenticationToken = myToken;
            [deferral complete];
        }];
    }

Menyiapkan pustaka

Panggil Start() untuk mengaktifkan sesi Anda guna memproses data lingkungan.

Untuk menangani kejadian yang ditimbulkan oleh sesi Anda, atur properti delegate sesi Anda menjadi objek, seperti tampilan Anda. Objek ini harus mengimplementasikan protokol SSCCloudSpatialAnchorSessionDelegate.

Pelajari selengkapnya tentang metode mulai.

    _cloudSession.session = self.sceneView.session;
    _cloudSession.delegate = self;
    [_cloudSession start];

Menyediakan bingkai ke sesi

Sesi jangkar spasial bekerja dengan memetakan ruang di sekitar pengguna. Melakukannya membantu menentukan lokasi jangkar. Platform seluler (iOS & Android) memerlukan panggilan asli ke umpan kamera untuk mendapatkan bingkai dari pustaka AR platform Anda. Sebaliknya, HoloLens terus memindai lingkungan, jadi, tidak memerlukan panggilan tertentu seperti pada platform seluler.

Pelajari selengkapnya tentang metode processFrame.

    [_cloudSession processFrame:_sceneView.session.currentFrame];

Memberikan umpan balik kepada pengguna

Anda dapat menulis kode untuk menangani kejadian yang diperbarui sesi. Kejadian ini terjadi setiap kali sesi meningkatkan pemahamannya tentang lingkungan Anda. Dengan melakukannya, memungkinkan Anda:

  • Menggunakan kelas UserFeedback untuk memberikan umpan balik kepada pengguna saat perangkat bergerak dan sesi memperbarui pemahaman lingkungannya. Untuk melakukan ini,
  • Tentukan pada titik apa data spasial yang dilacak tersedia cukup untuk membuat jangkar spasial. Anda menentukan ini dengan ReadyForCreateProgress atau RecommendedForCreateProgress. Setelah ReadyForCreateProgress di atas 1, kita memiliki cukup data untuk menyimpan jangkar spasial cloud, meskipun kami menyarankan Anda menunggu hingga RecommendedForCreateProgress di atas 1 untuk melakukannya.

Pelajari selengkapnya tentang metode protokol sessionUpdated.

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

Menemukan jangkar spasial cloud

Untuk membuat jangkar spasial cloud, Anda pertama-tama membuat jangkar di sistem AR platform, lalu membuat mitra cloud. Anda menggunakan metode CreateAnchorAsync().

Pelajari selengkapnya tentang kelas ASACloudSpatialAnchor.

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

Seperti yang dijelaskan sebelumnya, Anda memerlukan data lingkungan yang memadai yang diambil sebelum mencoba membuat jangkar spasial cloud baru. Artinya ReadyForCreateProgress harus di atas 1, meskipun kami sarankan Anda menunggu sampai RecommendedForCreateProgress di atas 1 untuk melakukannya.

Pelajari selengkapnya tentang metode getSessionStatusWithCompletionHandler.

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

Mengatur properti

Anda dapat memilih untuk menambahkan beberapa properti saat menyimpan jangkar spasial cloud Anda. Seperti jenis objek yang disimpan, atau properti dasar seperti apakah ini harus diaktifkan untuk interaksi. Melakukannya dapat berguna setelah penemuan: Anda dapat segera merender objek untuk pengguna, misalnya bingkai gambar dengan konten kosong. Selanjutnya, unduhan yang berbeda di latar belakang mendapatkan detail status tambahan, misalnya, gambar untuk ditampilkan dalam bingkai.

Pelajari selengkapnya tentang properti appProperties.

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

Memperbarui properti

Untuk memperbarui properti pada jangkar, Anda menggunakan metode UpdateAnchorProperties(). Jika dua atau lebih perangkat mencoba memperbarui properti untuk jangkar yang sama pada saat yang sama, kita menggunakan model konkurensi optimis. Yang berarti tulisan pertama akan menang. Semua tulisan lainnya akan mendapatkan kesalahan "Konkurensi": refresh properti akan diperlukan sebelum mencoba lagi.

Pelajari selengkapnya tentang metode updateAnchorProperties.

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

Anda tidak dapat memperbarui lokasi jangkar setelah dibuat di layanan - Anda harus membuat jangkar baru dan menghapus yang lama untuk melacak posisi baru.

Jika Anda tidak perlu menemukan jangkar untuk memperbarui propertinya, Anda dapat menggunakan metode GetAnchorPropertiesAsync(), yang mengembalikan objek CloudSpatialAnchor dengan properti.

Pelajari selengkapnya tentang metode getAnchorProperties.

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

Mengatur tanggal kedaluwarsa

Anda juga dapat mengonfigurasi masa berakhir jangkar secara otomatis pada tanggal tertentu di masa mendatang. Ketika jangkar berakhir, jangkar tidak akan lagi ditemukan atau diperbarui. Waktu kedaluwarsa hanya dapat diatur ketika jangkar dibuat sebelum menyimpannya ke cloud. Tidak mungkin memperbarui kedaluwarsa setelahnya. Jika tidak ada waktu kedaluwarsa yang diatur saat pembuatan jangkar, jangkar hanya akan kedaluwarsa saat dihapus secara manual.

Pelajari selengkapnya tentang properti kedaluwarsa.

    int secondsInAWeek = 60 * 60 * 24 * 7;
    NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) secondsInAWeek];
    cloudAnchor.expiration = oneWeekFromNow;

Menemukan jangkar spasial cloud

Mampu menemukan jangkar spasial cloud yang disimpan sebelumnya adalah salah satu alasan utama untuk menggunakan Azure Spatial Anchors. Untuk ini, kami menggunakan "Watchers". Anda hanya dapat menggunakan satu Watcher pada satu waktu; beberapa Pengamat tidak didukung. Ada beberapa cara berbeda (juga dikenal sebagai Jangkar Temukan Strategi) Pengamat dapat menemukan jangkar spasial cloud. Anda dapat menggunakan satu strategi pada watcher pada satu waktu.

  • Cari jangkar dengan pengidentifikasi.
  • Temukan jangkar yang terhubung ke jangkar yang telah ditemukan sebelumnya. Anda dapat belajar tentang hubungan jangkar di sini.
  • Cari jangkar menggunakan relokasi Kasar.

Catatan

Setiap kali Anda menemukan jangkar, Azure Spatial Anchors akan mencoba menggunakan data lingkungan yang dikumpulkan untuk menambah informasi visual pada jangkar. Jika Anda mengalami kesulitan menemukan jangkar, perlu untuk membuat jangkar, lalu temukan beberapa kali dari sudut dan kondisi pencahayaan yang berbeda.

Jika Anda menemukan jangkar spasial cloud dengan pengidentifikasi, Anda dapat menyimpan pengidentifikasi jangkar spasial cloud di layanan back-end aplikasi Anda, dan membuatnya dapat diakses oleh semua perangkat yang dapat mengautentikasinya dengan benar. Untuk contoh ini, lihat Tutorial: Berbagi Spatial Anchors di seluruh perangkat.

Mencontohkan objek AnchorLocateCriteria, atur pengidentifikasi yang Anda cari, dan gunakan metode CreateWatcher pada sesi tersebut dengan menyediakan AnchorLocateCriteria Anda.

Pelajari selengkapnya tentang metode createWatcher.

    ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
    criteria.identifiers = @[ @"id1", @"id2", @"id3" ];
    [_cloudSession createWatcher:criteria];

Setelah watcher Anda dibuat, acara akan AnchorLocated menembak untuk setiap jangkar yang diminta. Peristiwa ini terjadi ketika jangkar berada, atau jika jangkar tidak dapat ditemukan. Jika situasi ini terjadi, alasannya akan dinyatakan dalam status tersebut. Setelah semua jangkar untuk pengamat diproses, ditemukan atau tidak ditemukan, maka peristiwa LocateAnchorsCompleted itu akan menembak. Ada batas 35 pengidentifikasi per pengamat.

Pelajari selengkapnya tentang metode protokol anchorLocated.

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

Hapus jangkar

Menghapus jangkar ketika tidak lagi digunakan adalah praktik yang baik untuk disertakan sejak dini dalam proses dan praktik pengembangan Anda, untuk menjaga kebersihan sumber daya Azure Anda.

Pelajari selengkapnya tentang metode deleteAnchor.

    [_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
        // Perform any processing you may want when delete finishes
    }];

Menjeda, menyetel ulang, atau menghentikan sesi

Untuk menghentikan sesi sementara, Anda dapat memanggil Stop(). Tindakan ini akan menghentikan setiap pengamat dan pemrosesan lingkungan, bahkan jika Anda memanggil ProcessFrame(). Anda selanjutnya dapat memanggil Start() untuk melanjutkan pemrosesan. Ketika melanjutkan, data lingkungan yang sudah diambil dalam sesi akan dipertahankan.

Pelajari selengkapnya tentang metode berhenti.

    [_cloudSession stop];

Untuk menyetel ulang data lingkungan yang telah diambil dalam sesi Anda, Anda dapat memanggil Reset().

Pelajari selengkapnya tentang metode reset.

    [_cloudSession reset];

Untuk membersihkan dengan benar setelah sesi merilis semua referensi.

    _cloudSession = NULL;

Langkah berikutnya

Dalam panduan ini, Anda belajar tentang cara membuat dan menemukan jangkar menggunakan Azure Spatial Anchors SDK. Untuk mempelajari lebih lanjut tentang hubungan jangkar, lanjutkan ke panduan berikutnya.

Hubungan jangkar