Share via

Penyiapan awal World Locking Tools

  • Artikel

Penyiapan Slimmest yang mungkin

Tutorial di sini langkah-langkah melalui pengaturan minimal untuk bangun dan berjalan dengan semua yang ada di aplikasi Anda yang dikunci di dunia, tanpa tindakan lebih lanjut (misalnya, jangkar spasial) diperlukan. Ini ada di sampel repositori saudara untuk repositori ini.

Panduan mulai cepat

Pendekatan yang kurang terperinci secara konseptual dan lebih pragmatis untuk mengintegrasikan WLT ke dalam proyek dapat ditemukan di sini. Jika sesuai, ini mereferensikan kembali ke halaman yang lebih menyeluruh ini. Meskipun ini benar-benar masalah preferensi pribadi pendekatan mana yang lebih tepat, baca cepat halaman Sebelum memulai dapat menjadi penghemat waktu di mana untuk mencuatkan energi dalam dokumentasi ini.

Lingkungan yang didukung

World Locking Tools for Unity saat ini menargetkan aplikasi UWP untuk keluarga perangkat HoloLens. HoloLens asli (x86) dan HoloLens 2 (ARM64) didukung.

Dukungan eksperimental untuk platform lain tersedia melalui Subsistem AR Unity.

Build integrasi berkelanjutan (CI) World Locking Tools memvalidasi dengan Unity2018.4.6f1 dengan Visual Studio 2017. Namun, pengembangan WLT yang luas juga telah dilakukan menggunakan gamut versi Unity2018, dan berbagai Unity2019. Visual Studio 2017 dan Visual Studio 2019 telah digunakan dalam pengembangan alat.

Jika Anda mengalami masalah kompatibilitas dengan versi Unity dan/atau Visual Studio lainnya, kami akan senang mendengarnya! Cara terbaik untuk melaporkan masalah adalah melalui portal masalah di GitHub.

Latar belakang yang diasumsikan

Diasumsikan bahwa orang yang ingin mengintegrasikan solusi World Locking Tools ke dalam proyek mereka sudah terbiasa dengan dasar-dasar membangun dan menyebarkan aplikasi untuk keluarga perangkat HoloLens. Jika tidak, ada beberapa referensi hebat di akhir artikel ini.

Lapisan World Locking Tools

World Locking Tools dipecah menjadi empat lapisan. Dengan panah yang menunjuk ke lapisan tergantung pada, grafik dependensi langsung terlihat seperti ini:

Diagram Lapisan

Garis putus-putus menunjukkan dependensi opsional.

Sementara lapisan Contoh menggunakan MixedRealityToolkit (MRTK), tidak ada lapisan lain yang memiliki dependensi eksternal, dan fungsionalitas penuh tersedia kompatibel dengan tetapi independen dari MRTK.

Catatan lebih lanjut tentang dependensi Aplikasi mengikuti di bawah ini.

Lapisan dapat diringkas sebagai berikut:

Plugin

Antarmuka imperatif yang memungkinkan komunikasi langsung dengan DLL Mesin. Masalah umum seperti marshaling argumen dicapai di sini, dan beberapa pembuatan beberapa fungsi yang sering digunakan dalam kombinasi menjadi arahan komposit. Ini tetap merupakan antarmuka C# tingkat rendah ke C++ DLL yang mendasar. Penggunaan langsungnya tersedia, tetapi tidak diperlukan atau disarankan.

Core

Inti adalah enkapulasi dari semua langkah yang diperlukan untuk mendapatkan manfaat ruang world-locked World Locking Tools yang stabil, dipaketkan ke dalam antarmuka deklaratif. Aplikasi yang berfungsi diharapkan untuk dikirim hanya menggunakan fungsionalitas dari Core.

Alat

Alat ini sebagian besar bersifat diagnostik. Visualisasi proses World Locking Tools disertakan dalam formulir yang mudah ditambahkan ke proyek apa pun yang menggunakan World Locking Tools.

Utilitas lain yang nyaman disertakan, tetapi diharapkan akan membantu dalam memulai pengkodian solusi kustom, daripada menjadi solusi akhir seperti yang ditawarkan Core.

Contoh

Lapisan Contoh mencoba menyajikan sampel pengaturan skenario umum saat menggunakan World Locking Tools, dan praktik terbaik dalam integrasi World Locking Tools ke dalam berbagai skenario.

Setiap dependensi MRTK yang diperlukan untuk UX dan manipulasi objek dibatasi untuk skrip dan prefab di lapisan Contoh. Ini membuat lapisan bawah bebas dari dependensi eksternal apa pun.

Skrip dan aset dalam lapisan Contoh tidak diharapkan untuk diintegrasikan langsung ke dalam produk pengiriman, meskipun tidak ada larangan terhadapnya. Sebaliknya, konstruksi mereka mendukung kesederhanaan dan kejelasan atas penggunaan kembali dan efisiensi.

Aplikasi

Secara umum, Aplikasi hanya perlu mengambil dependensi pada World Locking Tools Core.

Selama pengembangan, banyak visualisasi dan pembantu lainnya untuk memahami perilaku tak terduga tersedia di lapisan Alat. Pembantu ini idealnya akan dilucuti dari aplikasi jadi, atau setidaknya dinonaktifkan. Tentu saja, mereka gratis untuk kegunaan lain juga, baik dalam bentuk mereka saat ini atau dimodifikasi. Lihat lisensi untuk detailnya.

Untuk penggunaan tingkat lanjut, dan eksperimen kemampuan penuh World Locking Tools, lapisan Plugin menawarkan akses imperatif tingkat rendah ke DLL Mesin.

Jika akses ke lapisan Plugin menjadi diperlukan, mungkin menunjuk ke kekurangan di permukaan API yang ditawarkan di lapisan Core. Tim World Locking Tools selalu ingin mengisi celah seperti itu. Pertimbangkan untuk berkontribusi wawasan tersebut kepada tim. Lihat berkontribusi.

Catatan peringatan tentang panjang jalur penginstalan

Beberapa versi MRTK memiliki masalah dengan jalur penginstalan yang panjang. Panjang jalur lengkap subfolder dalam dalam dalam penginstalan MRTK dapat melebihi batas jalur Windows (260 karakter). Jika kesalahan build formulir berikut muncul:

DirectoryNotFoundException: Could not find a part of the path "D:\MyOverTwentyEightCharacterLongLengthInstallPath\MixedReality-WorldLockingTools-Unity\Assets\MRTK\MixedRealityToolkit.Providers\WindowsMixedReality\DotNetAdapter\Plugins\net46\Microsoft.Windows.MixedReality.DotNetWinRT\Editor\Microsoft.Windows.MixedReality.DotNetWinRT.Editor.asmdef"

tetapi file sebenarnya ada di drive, maka masalahnya kemungkinan panjang jalur. Tim MRTK menyadari hal ini dan berupaya meningkatkannya (catatan: Saya yakin mereka telah melakukan peningkatan besar di sini dan itu tidak lagi menjadi masalah). Sementara itu, solusinya adalah mempersingkat awalan jalur dengan kombinasi hal berikut:

  1. Instal proyek Unity ke akar jalur panjang yang lebih pendek, misalnya, "D:\Proj"
  2. Jika mengkloning repositori, kloning akar Alat Penguncian Dunia menjadi sesuatu yang lebih pendek dari default "\MixedReality-WorldLockingTools-Unity", misalnya:
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

Batas jalur ini umumnya bukan masalah dengan Alat Penguncian Dunia itu sendiri, karena tidak menggunakan struktur folder yang sedalam itu.

Menambahkan World Locking Tools ke proyek Unity

Catatan

Berikut ini menjelaskan penginstalan manual Alat dan dependensi World Locking. Proses penginstalan yang jauh lebih efisien tersedia melalui Alat Fitur Mixed Reality. Penginstalan melalui Alat Fitur dijelaskan di sini. Jika Alat Fitur menginstal WLT, Anda dapat melewati hal berikut dan melanjutkan untuk menambahkan WLT ke adegan Anda

World Locking Tools mengandalkan nuget untuk menginstal Mesin Dunia Beku yang mendasar.

Jika menambahkan Alat Penguncian Dunia ke proyek yang ada, disarankan untuk memulai dengan proyek yang telah diverifikasi untuk membangun dan menyebarkan ke perangkat HoloLens. Ini akan membantu memisahkan masalah dengan mendapatkan aplikasi untuk dijalankan di HoloLens di tempat pertama, yang dapat rumit, dari masalah dengan Alat Penguncian Dunia. Kemudian lanjutkan ke bagian penginstalan Mesin FrozenWorld dan Aset Alat Penguncian Dunia di bawah ini.

Penginstalan Mesin FrozenWorld

DLL Mesin Dunia Beku dapat diperoleh dari NuGet baik menggunakan utilitas NuGet For Unity yang sangat baik, atau secara manual.

Menggunakan NuGet For Unity

Pastikan umpan nuget.org berada di sumber. Periksa di Unity > Edit > Preferensi > NuGet untuk Unity. Jika tidak, baik:

Gunakan Tambahkan GUI Sumber Baru di Unity > Edit > Preferences > NuGet For Unity untuk menambahkan berbagi yang sama.

  • Ganti "Sumber Baru" dengan nama pilihan Anda (misalnya, "NuGet").
  • Ganti "source_path" dengan "http://www.nuget.org/api/v2/".

Setelah mengonfirmasi umpan nuget.org, di Unity > NuGet > Kelola Paket NuGet, temukan dan instal versi terbaru Microsoft.MixedReality.FrozenWorld.Engine. (Cari "FrozenWorld".)

Untuk memperbarui ke versi yang lebih baru, buka Unity > NuGet > Kelola Paket NuGet lagi, dan temukan paket FrozenWorld.Engine dan pilih Perbarui. Catatan: Anda mungkin harus ke tab Updates untuk menemukan versi yang Anda cari.

Penginstalan DLL Mesin Dunia Beku Manual

Gunakan editor teks untuk menambahkan packageSources baris ke Aset/NuGet.config, misalnya:

  <packageSources>
    <add key="NuGet" value="http://www.nuget.org/api/v2/" />
  </packageSources>

Jika Anda belum memiliki file Aset/NuGet.config, Anda dapat menyalinnya dari repositori github World Locking Tools.

Menggunakan editor teks, tambahkan paket DLL Mesin Dunia Beku ke Aset/packages.config, misalnya:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>

Sekali lagi, jika Anda belum memiliki file Aset/packages.config, Anda bisa mendapatkan file dari repositori github World Locking Tools, atau cukup salin di atas ke dalam file teks yang disebut "Aset/packages.config".

Setelah menyiapkan NuGet.config dan packages.config, instal dengan:

  1. Dapatkan nuget.exe terbaru dari unduhan NuGet.
  2. Pastikan nuget.exe berada di jalur Anda (di sini saya akan berasumsi itu disalin ke Aset).
  3. Buka jendela perintah PowerShell dan ubah direktori ke folder Aset.
  4. Jalankan perintah berikut:
.\nuget.exe restore

Untuk meningkatkan ke versi yang lebih baru:

  1. Perbarui nomor versi FrozenWorld.Engine dalam file packages.config di atas ke versi yang diinginkan (misalnya, version="1.0.0" menjadi version="1.0.1").
  2. Hapus apa pun di folder Aset/Paket yang dimulai dengan "Microsoft.MixedReality.Unity.FrozenWorld.Engine".
  3. Jalankan ulang nuget.exe seperti di atas.

Aset Alat Penguncian Dunia

Impor file Alat Penguncian .unitypackage Dunia yang diperlukan ke dalam proyek (metode pilihan), atau salin. Mereka dapat dipindahkan ke sub-folder dalam Aset untuk mengeluarkannya dari jalan untuk pengembangan aplikasi.

File stabil .unitypackage terbaru dapat ditemukan di Alat Penguncian Dunia untuk Rilis Unity.

Lapisan WorldLocking.Core dan Engine pasti akan diperlukan, jadi paket penginstalan minimal adalah WorldLockingCoreEngine.unitypackage.

Untuk menentukan lapisan lain apa yang mungkin diperlukan, lihat diskusi lapisan Alat Penguncian Dunia dan dependensinya di atas. Setiap lapisan terkandung dalam satu paket Unity.

Karena beberapa Contoh Alat Penguncian Dunia menggunakan fitur dari MRTK, rekam jepret MRTK yang kompatibel disertakan dengan Contoh unitypackage. Untuk rilis MRTK terbaru, lihat di sini.

Menambahkan Alat Penguncian Dunia ke adegan Unity

Catatan

Langkah-langkah yang tercantum di bawah ini semuanya otomatis dalam utilitas adegan Konfigurasi WLT, yang dapat ditemukan di menu Mixed Reality Toolkit > Utilities > World Locking Tools. Menu Configuraton

Dalam proyek Unity yang berisi mesin FrozenWorld (dari nuget.org), impor lapisan Aset Alat Penguncian Dunia yang diinginkan (tetapi setidaknya WorldLocking.Core), dan secara opsional MRTK. Kemudian buat adegan baru (atau buka adegan yang ada).

Catatan

Tambahkan simpul tambahan di akar hierarki kamera. Simpul ini akan digunakan untuk menyesuaikan kamera terlacak kepala ke ruang terkunci dunia. (Jika menggunakan MRTK, GameObject baru ini akan menjadi induk dari MixedRealityPlayspace.)

Pengalaman inti

Seret prefab WorldLockingManager dari Aset/WorldLocking.Core/Prefabs ke adegan Anda. Tempatnya di tempat kejadian tidak masalah, tetapi seharusnya tidak berada di pohon kamera. Lihat contoh adegan untuk konfigurasi yang disarankan.

Ada pengaturan yang tersedia pada prefab WorldLockingManager, tetapi membiarkannya ke nilai default disarankan untuk memulai.

Lihat Konteks Alat Penguncian Dunia untuk penjelasan tentang opsi yang disajikan.

[Opsional] MRTK

Alat Penguncian Dunia melengkapi dengan tetapi ortogonal untuk MRTK. Penggunaan MRTK bersama dengan World Locking Tools sepenuhnya opsional.

Meskipun demikian, sampel World Locking Tools dibangun menggunakan MRTK, dan MRTK umumnya sangat berharga dalam mengembangkan jenis aplikasi MR yang paling diuntungkan dari World Locking Tools.

Jika menggunakan MRTK, daripada menggunakan rekam jepret yang disertakan dengan contoh, disarankan untuk menambahkan versi terbaru setidaknya paket berikut:

  • MixedReality.Toolkit
  • MixedReality.Toolkit.Providers
  • MixedReality.Toolkit.Services
  • MixedReality.Toolkit.SDK

[Opsional] Memvisualisasikan jangkar yang kenyal dan terkunci di dunia

Ini memerlukan penambahan WorldLocking.Tools ke Aset proyek.

Jika Anda ingin memvisualisasikan jangkar Anda, seret prefab AnchorGraphVisual dari Aset/WorldLocking.Tools/Prefabs ke adegan Anda. Kotak centang untuk mengalihkan aspek visualisasi di inspektur ada di WorldLockingManager.

Sebagai diagnostik, visualisasi WorldLocking.Tools tidak sangat dioptimalkan, dan akan mengurangi performa jauh sebelum waktu pemrosesan Alat Penguncian Dunia inti menjadi relevan.

[Opsional] Dasbor sederhana untuk kontrol parameter dalam Mixed Reality

HUD sederhana tersedia, yang dapat digunakan untuk mengontrol WorldLockingManager pada runtime dari dalam MR. Ini disediakan dalam paket Contoh. Meskipun dapat digunakan apa adanya, mereka dimaksudkan sebagai pola saat membangun fitur serupa ke dalam sistem tampilan dan UX aplikasi sendiri.

Seret di prefab WorldLocking.Examples/Prefabs/Dashboard, dan arahkan bidang Anchor Visualizer-nya ke Visualizer di bagian sebelumnya.

Memigrasikan adegan yang ada ke Alat Penguncian Dunia

Perubahan terbesar ketika pindah ke World Locking Tools adalah bahwa tidak ada lagi persyaratan untuk menggunakan jangkar spasial ke objek virtual kunci dunia.

Jangkar spasial secara tradisional telah menjadi satu-satunya alat yang tersedia untuk objek individu kunci dunia. Tetapi saat menggunakan Alat Penguncian Dunia, ruang koordinat tempat objek virtual tersebut ada sudah dikunci di dunia. Tidak diperlukan penguncian lebih lanjut.

Tidak hanya jangkar spasial yang tidak perlu, mereka tidak akan berfungsi dengan benar, karena mereka gagal memperhitungkan transformasi tambahan hierarki kamera (seperti transformasi "Playspace" MRTK).

Oleh karena itu, setiap dan semua jangkar spasial harus dihapus dari adegan, dan skrip apa pun yang menambahkan jangkar spasial harus menghentikan melakukannya. Jangkar spasial tidak perlu digantikan oleh apa pun; World Locking Tools akan menjangkarkan target mereka ke dunia nyata.

Jika diinginkan untuk membandingkan penguncian dunia dengan dan tanpa Alat Penguncian Dunia, maka alih-alih menghapus WorldAnchors, mereka dapat diganti dengan ToggleWorldAnchor yang disediakan di WorldLocking.Tools.

ToggleWorldAnchor berfungsi persis sama dengan WorldAnchor, dengan perbedaan penting bahwa ketika World Locking Tools Manager aktif, ia dengan mudah menonaktifkan dirinya sendiri dan keluar dari jalan. Ketika World Locking Tools Manager dinonaktifkan, itu bersifat normal WorldAnchor.

Jika karena alasan lain WorldAnchors masih diperlukan dalam adegan (misalnya, untuk berbagi jaringan), mereka dapat digunakan dengan adaptor, disediakan sebagai WorldAnchorAdapter.

WorldAnchorAdapter mengubah posisi mentah GameObject yang diposisikan oleh WorldAnchor, ke ruang global Unity yang terkunci di dunia, dan kemudian menerapkan transformasi ke objek target. Untuk menggunakannya, daripada menambahkan WorldAnchor langsung ke objek, WorldAnchor harus diterapkan ke objek proksi (biasanya GameObject yang kosong), dan kemudian pada Update() WorldAnchorAdapter membaca pose WorldAnchor, mengubahnya dengan benar, dan menerapkannya ke target.

Penyetelan selesai

Setelah mengikuti langkah-langkah di atas, proyek yang disebarkan ke perangkat akan berjalan disesuaikan oleh Alat Penguncian Dunia untuk mempertahankan ruang terkunci dunia yang stabil secara optimal. Setiap objek tetap yang ditempatkan dalam adegan akan tetap konsisten secara visual baik relatif satu sama lain maupun dengan dunia fisik.

Contoh aplikasi yang tersedia

Sampel adegan, termasuk skrip dan aset disediakan untuk menunjukkan penggunaan kemampuan Alat Penguncian Dunia yang lebih kompleks.

Misalnya, WorldLockedPhysicsSample menyediakan lingkungan sederhana di mana objek yang disimulasikan secara fisik dapat dibuat dan dihapus, berinteraksi satu sama lain dan dengan lingkungan (pemetaan spasial).

Untuk tampilan yang lebih terfokus pada fitur Penyematan Ruang, SpacePin memberikan contoh yang jauh lebih disederhanakan untuk menyelaraskan objek virtual skala besar ke fitur dunia nyata.

RayPins memperluas kemampuan yang diperkenalkan oleh contoh SpacePin, memungkinkan penyematan dunia virtual ke dunia fisik dengan uji sinar terhadap jala spasial.

Referensi untuk memulai

Jika tidak terbiasa dengan dasar-dasar membuat, membangun, dan menyebarkan aplikasi AR ke keluarga perangkat HoloLens, berikut adalah beberapa referensi yang mungkin membantu Anda memulai.

Ringkasan Pengembangan Unity - Unity untuk pengembangan MR/AR.

MR Basics 100 - Panduan memulai pengembangan untuk HoloLens

HoloLens 2 Tutorial - Panduan memulai pengembangan untuk HoloLens 2.

Sistem Koordinat Implikasi ruang koordinat dalam pengembangan AR.

  • Perhatikan bahwa Alat Penguncian Dunia menyelesaikan masalah yang dibahas di sini.

Mengalami masalah?

Lihat panduan pemecahan masalah.