Bagikan melalui

Cara membuat dan menemukan jangkar menggunakan Azure Spatial Anchors di C++/WinRT

  • 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 C++/WinRT, 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 CloudSpatialAnchorSession.

    CloudSpatialAnchorSession m_cloudSession{ nullptr };

    m_cloudSession = CloudSpatialAnchorSession();

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

    auto configuration = m_cloudSession.Configuration();
    configuration.AccountKey(LR"(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.

    auto configuration = m_cloudSession.Configuration();
    configuration.AccessToken(LR"(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 delegasi TokenRequiredDelegate.

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
        args.AccessToken(LR"(MyAccessToken)");
    });

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

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
        auto deferral = args.GetDeferral();
        MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
            if (!myToken.empty()) 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.

    auto configuration = m_cloudSession.Configuration();
    configuration.AuthenticationToken(LR"(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.

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
        args.AuthenticationToken(LR"(MyAuthenticationToken)");
    });

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

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
        auto deferral = args.GetDeferral();
        MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
            if (!myToken.empty()) args.AuthenticationToken(myToken);
            deferral.Complete();
        });
    });

Menyiapkan sesi

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

Untuk menangani kejadian yang ditimbulkan oleh sesi Anda, pasang handler kejadian.

Pelajari selengkapnya tentang metode Mulai.

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

    m_cloudSession->ProcessFrame(ar_frame_);

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 delegasi SessionUpdatedDelegate.

    m_sessionUpdatedToken = m_cloudSession.SessionUpdated(winrt::auto_revoke, [this](auto&&, auto&& args)
    {
        auto status = args.Status();
        if (status.UserFeedback() == SessionUserFeedback::None) return;
        m_feedback = LR"(Feedback: )" + FeedbackToString(status.UserFeedback()) + LR"( -)" +
            LR"( Recommend Create=)" + FormatPercent(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 CloudSpatialAnchor.

    // Initialization
    SpatialStationaryFrameOfReference m_stationaryReferenceFrame = nullptr;
    HolographicDisplay defaultHolographicDisplay = HolographicDisplay::GetDefault();
    SpatialLocator spatialLocator = defaultHolographicDisplay.SpatialLocator();
    m_stationaryReferenceFrame = spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();

    // Create a local anchor, perhaps by positioning a SpatialAnchor a few meters in front of the user
    SpatialAnchor localAnchor{ nullptr };
    PerceptionTimestamp timestamp = PerceptionTimestampHelper::FromHistoricalTargetTime(DateTime::clock::now());
    SpatialCoordinateSystem currentCoordinateSystem = m_attachedReferenceFrame.GetStationaryCoordinateSystemAtTimestamp(timestamp);
    SpatialPointerPose pose = SpatialPointerPose::TryGetAtTimestamp(currentCoordinateSystem, timestamp);

    // Get the gaze direction relative to the given coordinate system.
    const float3 headPosition = pose.Head().Position();
    const float3 headDirection = pose.Head().ForwardDirection();

    // The anchor is positioned two meter(s) along the user's gaze direction.
    constexpr float distanceFromUser = 2.0f; // meters
    const float3 gazeAtTwoMeters = headPosition + (distanceFromUser * headDirection);

    localAnchor = SpatialAnchor::TryCreateRelativeTo(currentCoordinateSystem, gazeAtTwoMeters);

    // 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 = CloudSpatialAnchor();
    cloudAnchor.LocalAnchor(localAnchor);
    co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);
    m_feedback = LR"(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 GetSessionStatusAsync.

    SessionStatus status = co_await m_cloudSession.GetSessionStatusAsync();
    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 metode AppProperties.

    CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
    cloudAnchor.LocalAnchor(localAnchor);
    auto properties = m_cloudAnchor.AppProperties();
    properties.Insert(LR"(model-type)", LR"(frame)");
    properties.Insert(LR"(label)", LR"(my latest picture)");
    co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);

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

    CloudSpatialAnchor anchor = /* locate your anchor */;
    anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
    co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);

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

    CloudSpatialAnchor anchor = co_await m_cloudSession.GetAnchorPropertiesAsync(LR"(anchorId)");
    if (anchor != nullptr)
    {
        anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
        co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);
    }

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 metode Expiration.

    const int64_t oneWeekFromNowInHours = 7 * 24;
    const DateTime oneWeekFromNow = DateTime::clock::now() + std::chrono::hours(oneWeekFromNowInHours);
    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.

    AnchorLocateCriteria criteria = AnchorLocateCriteria();
    criteria.Identifiers({ LR"(id1)", LR"(id2)", LR"(id3)" });
    auto cloudSpatialAnchorWatcher = m_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 delegasi AnchorLocatedDelegate.

    m_anchorLocatedToken = m_cloudSession.AnchorLocated(winrt::auto_revoke, [this](auto&&, auto&& args)
    {
        switch (args.Status())
        {
            case LocateAnchorStatus::Located:
            {
                CloudSpatialAnchor foundAnchor = args.Anchor();
            }
                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;
        }
    });

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

    co_await m_cloudSession.DeleteAnchorAsync(cloudAnchor);
    // 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.

    m_cloudSession.Stop();

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

Pelajari selengkapnya tentang metode Reset.

    m_cloudSession.Reset();

Untuk membersihkan dengan benar setelah sesi merilis semua referensi.

    m_cloudSession = nullptr;

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