Ringkasan SDK Runtime

Bagian ini memberikan ringkasan tingkat tinggi dari SDK Runtime Object Anchors, yang digunakan untuk mendeteksi objek menggunakan model Object Anchors. Anda akan mendapatkan pemahaman tentang cara suatu objek direpresentasikan dan untuk apa berbagai komponen digunakan.

Semua jenis yang ada di bawah dapat ditemukan di namespace layanan berikut: Microsoft.Azure.ObjectAnchors, Microsoft.Azure.ObjectAnchors.Diagnostics, dan Microsoft.Azure.ObjectAnchors.SpatialGraph.

Jenis

ObjectModel

ObjectModel mewakili geometri objek fisik dan mengkodekan parameter yang diperlukan untuk deteksi dan estimasi pose. Itu harus dibuat menggunakan layanan Object Anchors. Kemudian aplikasi dapat memuat file model yang dihasilkan menggunakan Object Anchors API dan mengkueri mesh yang disematkan dalam model tersebut untuk visualisasi.

ObjectSearchArea

ObjectSearchArea menentukan ruang untuk mencari satu atau beberapa objek. Ini didefinisikan oleh ID node grafik spasial dan batas spasial dalam sistem koordinat yang diwakili oleh ID node grafik spasial. SDK Runtime Object Anchors mendukung empat jenis batas, yaitu, bidang pandang, kotak pembatas, bola, dan lokasi.

AccountInformation

AccountInformation menyimpan ID, Kunci, dan Domain untuk akun Azure Object Anchors Anda.

ObjectAnchorsSession

ObjectAnchorsSession mewakili sesi Azure Object Anchors yang digunakan untuk membuat instans ObjectObserver yang digunakan untuk mendeteksi objek di dunia fisik.

ObjectObserver

ObjectObserver memuat model objek, mendeteksi instans-nya, dan melaporkan pose 6-DoF dari setiap instans dalam sistem koordinat HoloLens.

Meskipun setiap model objek atau instans dibuat dari pengamat, masa pakainya berbeda. Aplikasi dapat membuang pengamat dan terus menggunakan model objek atau instans.

ObjectQuery

ObjectQuery memberi tahu pengamat objek cara menemukan objek dari model tertentu. Ini menyediakan parameter yang dapat disetel berikut, yang nilai defaultnya dapat diambil dari model objek.

MinSurfaceCoverage

Properti MinSurfaceCoverage menunjukkan nilai untuk mempertimbangkan instans sebagai terdeteksi.

Untuk setiap kandidat objek, pengamat menghitung rasio permukaan yang tumpang tindih antara model objek yang ditransformasi dan pemandangan, kemudian melaporkan kandidat tersebut ke aplikasi hanya jika rasio cakupan di atas ambang batas yang diberikan.

IsExpectedToBeStandingOnGroundPlane

Properti IsExpectedToBeStandingOnGroundPlane menunjukkan apakah objek target diharapkan berdiri di bidang dasar.

Bidang dasar adalah lantai horizontal terendah di area pencarian. Ini memberikan batasan yang baik pada kemungkinan pose objek. Mengaktifkan tanda ini akan memandu pengamat untuk memperkirakan pose dalam ruang terbatas dan dapat meningkatkan akurasi. Parameter ini akan diabaikan jika model tidak seharusnya berdiri di bidang dasar.

ExpectedMaxVerticalOrientationInDegrees

Properti ExpectedMaxVerticalOrientationInDegrees menunjukkan sudut maksimum yang diharapkan dalam derajat antara arah atas dari instans objek dan gravitasi.

Parameter ini memberikan batasan lain pada arah naik dari perkiraan pose. Misalnya, jika sebuah objek berada di atas kanan, parameter ini bisa menjadi 0. Object Anchors tidak seharusnya mendeteksi objek yang berbeda dari model. Jika model berada di atas kanan, maka model tidak akan mendeteksi instans yang diletakkan miring. Model baru akan digunakan untuk tata letak miring. Aturan yang sama berlaku untuk artikulasi.

MaxScaleChange

Properti MaxScaleChange menunjukkan perubahan skala objek maksimum (dalam 0 ~ 1) sehubungan dengan pemetaan spasial. Skala perkiraan diterapkan pada simpul objek yang ditransformasik yang berpusat pada asal dan disejajarkan dengan sumbu. Skala yang diperkirakan mungkin bukan skala sebenarnya antara model CAD dan representasi fisiknya, tetapi beberapa nilai yang memungkinkan aplikasi merender model objek yang dekat dengan pemetaan spasial pada objek fisik.

SearchAreas

Properti SearchAreas menunjukkan array batas spasial tempat menemukan objek.

Pengamat akan mencari objek di ruang gabungan semua area penelusuran yang ditentukan dalam kueri. Dalam rilis ini, kami akan mengembalikan paling banyak satu objek dengan keyakinan tertinggi untuk mengurangi latensi.

ObjectInstance

ObjectInstance mewakili posisi hipotetis tempat instans dari model tertentu dapat berada dalam sistem koordinat HoloLens. Setiap contoh dilengkapi dengan properti SurfaceCoverage untuk menunjukkan seberapa bagus perkiraan pose.

Sebuah instans dibuat dengan memanggil metode ObjectObserver.DetectAsync, kemudian diperbarui secara otomatis di latar belakang saat hidup. Aplikasi dapat mendengarkan peristiwa yang diubah statusnya pada instans tertentu atau mengubah mode pelacakan untuk menjeda/melanjutkan pembaruan. Instans akan dihapus secara otomatis dari pengamat saat pelacakan hilang.

ObjectDiagnosticsSession

ObjectDiagnosticSession merekam diagnostik dan menulis data ke arsip.

Arsip diagnostik mencakup cloud titik adegan, status pengamat, dan informasi tentang model. Informasi ini berguna untuk mengidentifikasi kemungkinan masalah runtime. Untuk informasi selengkapnya, lihat Tanya Jawab Umum.

Menggunakan dan detail SDK runtime

Bagian ini akan memberi Anda cara dasar menggunakan Runtime SDK. Ini akan memberi Anda konteks yang cukup untuk menelusuri aplikasi sampel untuk melihat bagaimana Object Anchors digunakan secara holistik.

Inisialisasi

Aplikasi perlu memanggil ​​API ObjectObserver.IsSupported() untuk menentukan apakah Object Anchors didukung pada perangkat sebelum menggunakannya. Jika API ObjectObserver.IsSupported() mengembalikan false, periksa apakah aplikasi telah mengaktifkan kemampuan spatialPerception dan\atau tingkatkan ke OS HoloLens terbaru.

using Microsoft.Azure.ObjectAnchors;

if (!ObjectObserver.IsSupported())
{
    // Handle the error
}

// This call should grant the access we need.
ObjectObserverAccessStatus status = await ObjectObserver.RequestAccessAsync();
if (status != ObjectObserverAccessStatus.Allowed)
{
    // Handle the error
}

Selanjutnya, aplikasi membuat pengamat objek dan memuat model yang diperlukan yang dihasilkan oleh layanan konversi model Object Anchors.

using Microsoft.Azure.ObjectAnchors;

// Note that you need to provide the Id, Key and Domain for your Azure Object
// Anchors account.
Guid accountId = new Guid("[your account id]");
string accountKey = "[your account key]";
string accountDomain = "[your account domain]";

AccountInformation accountInformation = new AccountInformation(accountId, accountKey, accountDomain);
ObjectAnchorsSession session = new ObjectAnchorsSession(accountInformation);
ObjectObserver observer = session.CreateObjectObserver();

// Load a model into a byte array. The model could be a file, an embedded
// resource, or a network stream.
byte[] modelAsBytes;
ObjectModel model = await observer.LoadObjectModelAsync(modelAsBytes);

// Note that after a model is loaded, its vertices and normals are transformed
// into a centered coordinate system for the ease of computing the object pose.
// The rigid transform can be retrieved through the `OriginToCenterTransform`
// property.

Aplikasi membuat kueri untuk mendeteksi contoh model tersebut dalam ruang.

#if WINDOWS_UWP || DOTNETWINRT_PRESENT
#define SPATIALCOORDINATESYSTEM_API_PRESENT
#endif

using Microsoft.Azure.ObjectAnchors;
using Microsoft.Azure.ObjectAnchors.SpatialGraph;
using Microsoft.Azure.ObjectAnchors.Unity;
using UnityEngine;

// Get the coordinate system.
SpatialGraphCoordinateSystem? coordinateSystem = null;

#if SPATIALCOORDINATESYSTEM_API_PRESENT
SpatialCoordinateSystem worldOrigin = ObjectAnchorsWorldManager.WorldOrigin;
if (worldOrigin != null)
{
    coordinateSystem = await Task.Run(() => worldOrigin.TryToSpatialGraph());
}
#endif

if (!coordinateSystem.HasValue)
{
    Debug.LogError("no coordinate system?");
    return;
}

// Get the search area.
SpatialFieldOfView fieldOfView = new SpatialFieldOfView
{
    Position = Camera.main.transform.position.ToSystem(),
    Orientation = Camera.main.transform.rotation.ToSystem(),
    FarDistance = 4.0f, // Far distance in meters of object search frustum.
    HorizontalFieldOfViewInDegrees = 75.0f, // Horizontal field of view in
                                            // degrees of object search frustum.
    AspectRatio = 1.0f // Aspect ratio (horizontal / vertical) of object search
                       // frustum.
};

ObjectSearchArea searchArea = ObjectSearchArea.FromFieldOfView(coordinateSystem.Value, fieldOfView);

// Optionally change the parameters, otherwise use the default values embedded
// in the model.
ObjectQuery query = new ObjectQuery(model);
query.MinSurfaceCoverage = 0.2f;
query.ExpectedMaxVerticalOrientationInDegrees = 1.5f;
query.MaxScaleChange = 0.1f;
query.SearchAreas.Add(searchArea);

// Detection could take a while, so we run it in a background thread.
IReadOnlyList<ObjectInstance> detectedObjects = await observer.DetectAsync(query);

Secara default, setiap instans yang terdeteksi akan dilacak secara otomatis oleh pengamat. Secara opsional, kami dapat memanipulasi instans ini dengan mengubah mode pelacakannya atau mendengarkan peristiwa perubahan statusnya.

using Microsoft.Azure.ObjectAnchors;

foreach (ObjectInstance instance in detectedObjects)
{
    // Supported modes:
    // "LowLatencyCoarsePosition"    - Consumes less CPU cycles thus fast to
    //                                 update the state.
    // "HighLatencyAccuratePosition" - Uses the device's camera and consumes more CPU
    //                                 cycles thus potentially taking longer
    //                                 time to update the state.
    // "Paused"                      - Stops to update the state until mode
    //                                 changed to low or high.
    instance.Mode = ObjectInstanceTrackingMode.LowLatencyCoarsePosition;

    // Listen to state changed event on this instance.
    instance.Changed += InstanceChangedHandler;

    // Optionally dispose an instance if not interested in it.
    // instance.Dispose();
}

Dalam peristiwa perubahan status, kami dapat mengkueri status terbaru atau membuang instans jika kehilangan pelacakan.

using Microsoft.Azure.ObjectAnchors;

void InstanceChangedHandler(object sender, ObjectInstanceChangedEventArgs args)
{
    // Try to query the current instance state.
    ObjectInstanceState state = sender.TryGetCurrentState();

    if (state != null)
    {
        // Process latest state.
        // An object pose includes rotation and translation, applied in
        // the same order to the object model in the centered coordinate system.
    }
    else
    {
        // This object instance is lost for tracking, and will never be recovered.
        // The caller can detach the Changed event handler from this instance
        // and dispose it.
    }
}

Selain itu, aplikasi secara opsional dapat merekam satu atau beberapa sesi diagnostik untuk penelusuran kesalahan offline.

using Microsoft.Azure.ObjectAnchors;
using Microsoft.Azure.ObjectAnchors.Diagnostics;

string diagnosticsFolderPath = Windows.Storage.ApplicationData.Current.TemporaryFolder.Path;
const uint maxSessionSizeInMegaBytes = uint.MaxValue;

// Recording starts on the creation of a diagnostics session.
ObjectDiagnosticsSession diagnostics = new ObjectDiagnosticsSession(observer, maxSessionSizeInMegaBytes);

// Wait for the observer to do a job.

// Application can report some **pseudo ground-truth** pose for an instance
// acquired from other means.
diagnostics.ReportActualInstanceLocation(instance, coordinateSystem, Vector3.Zero, Quaternion.Identity);

// Close a session and write the diagnostics into an archive at specified location.
await diagnostics.CloseAsync(System.IO.Path.Combine(diagnosticsFolderPath, "diagnostics.zip"));

Akhirnya kami merilis sumber daya dengan membuang semua objek.

using Microsoft.Azure.ObjectAnchors;

foreach (ObjectInstance instance in activeInstances)
{
    instance.Changed -= InstanceChangedHandler;
    instance.Dispose();
}

model.Dispose();
observer.Dispose();