Çalışma Zamanı SDK'sı Genel Bakış

Bu bölüm, Nesne Tutturucuları modeli kullanan nesneleri algılamak için kullanılan Nesne Tutturucuları Çalışma Zamanı SDK'sına üst düzey bir genel bakış sağlar. Bir nesnenin nasıl temsil edildiklerine ve çeşitli bileşenlerin ne için kullanıldığına ilişkin bilgi edineceksiniz.

Aşağıda açıklanan tüm türler şu ad alanlarının birinde bulunabilir: Microsoft.Azure.ObjectAnchors, Microsoft.Azure.ObjectAnchors.Diagnostics ve Microsoft.Azure.ObjectAnchors.SpatialGraph.

Türler

ObjectModel

ObjectModel fiziksel bir nesnenin geometrisini temsil eder ve algılama ve poz tahmini için gerekli parametreleri kodlar. Nesne Bağlayıcıları hizmeti kullanılarak oluşturulmalıdır. Ardından bir uygulama, Object Anchors API'sini kullanarak oluşturulan model dosyasını yükleyebilir ve görselleştirme için bu modele eklenmiş ağı sorgulayabilir.

ObjectSearchArea

ObjectSearchArea, bir veya birden çok nesnenin aranacak alanını belirtir. Uzamsal grafik düğümü kimliği ve uzamsal grafik düğümü kimliğiyle temsil edilen koordinat sisteminde uzamsal sınırlar ile tanımlanır. Object Anchors Runtime SDK'sı, görünüm alanı, sınırlayıcı kutu, küre ve bir konum olmak üzere dört tür sınırı destekler.

AccountInformation

AccountInformation, Azure Object Anchors hesabınızın Kimliğini, Anahtarını ve Etki Alanını depolar.

ObjectAnchorsSession

ObjectAnchorsSession, fiziksel dünyadaki nesneleri algılamak için kullanılan ObjectObserver örnekleri oluşturmak için kullanılan bir Azure Object Anchors oturumunu temsil eder.

ObjectObserver

ObjectObserver nesne modellerini yükler, örneklerini algılar ve HoloLens koordinat sisteminde her örneğin 6-DoF pozlarını raporlar.

Herhangi bir nesne modeli veya örneği bir gözlemciden oluşturulsa da yaşam süreleri bağımsızdır. Uygulama bir gözlemciyi atabilir ve nesne modelini veya örneğini kullanmaya devam edebilir.

Objectquery

ObjectQuery, nesne gözlemcisine belirli bir modelin nesnelerini nasıl bulacağını söyler. Varsayılan değerleri bir nesne modelinden alınabilen aşağıdaki ayarlanabilir parametreleri sağlar.

MinSurfaceCoverage

MinSurfaceCoverage özelliği, algılanan bir örneği dikkate alınacak değeri gösterir.

Her nesne adayı için, bir gözlemci dönüştürülen nesne modeli ile sahne arasındaki çakışan yüzeylerin oranını hesaplar, ardından bu adayı yalnızca kapsam oranı belirli bir eşiğin üzerinde olduğunda uygulamaya bildirir.

IsExpectedToBeStandingOnGroundPlane

IsExpectedToBeStandingOnGroundPlane özelliği, hedef nesnenin zemin düzleminde durmasının beklenip beklenmediğini gösterir.

Zemin düzlemi, arama alanındaki en düşük yatay zemindir. Olası nesne pozları üzerinde iyi bir kısıtlama sağlar. Bu bayrağın açılması, gözlemciye pozu sınırlı bir alanda tahmin etme konusunda yol gösterir ve doğruluğu artırabilir. Modelin zemin düzleminde durması gerekmiyorsa bu parametre yoksayılır.

ExpectedMaxVerticalOrientationInDegrees

ExpectedMaxVerticalOrientationInDegrees özelliği, nesne örneğinin yukarı yönü ile yerçekimi arasında derece cinsinden beklenen maksimum açıyı gösterir.

Bu parametre, tahmini bir pozun yukarı yönünde başka bir kısıtlama sağlar. Örneğin, bir nesne sağdan yukarıysa, bu parametre 0 olabilir. Nesne Yer İşaretlerinin modelden farklı nesneleri algılaması gerekmez. Bir model sağ taraftaysa, dışarıdan yerleştirilmiş bir örneği algılamaz. Yan aşağı düzen için yeni bir model kullanılır. Aynı kural ifade için de geçerlidir.

MaxScaleChange

MaxScaleChange özelliği, uzamsal eşlemeye göre en fazla nesne ölçeği değişikliğini (0 ~ 1 içinde) gösterir. Tahmini ölçek, kaynakta ortalanmış ve eksene hizalanmış dönüştürülmüş nesne köşelerine uygulanır. Tahmini ölçekler, CAD modeli ile fiziksel gösterimi arasındaki gerçek ölçek olmayabilir, ancak uygulamanın fiziksel nesne üzerinde uzamsal eşlemeye yakın bir nesne modeli oluşturmasına izin veren bazı değerler olabilir.

SearchAreas

SearchAreas özelliği, nesnelerin bulunacağı uzamsal sınırlar dizisini gösterir.

Gözlemci, sorguda belirtilen tüm arama alanlarının birleşim alanındaki nesneleri arar. Bu sürümde, gecikme süresini azaltmak için en yüksek güvene sahip en fazla bir nesne döndüreceğiz.

Objectınstance

ObjectInstance, belirli bir modelin örneğinin HoloLens koordinat sisteminde olabileceği varsayımsal bir konumu temsil eder. Her örnek, tahmini pozunun ne kadar iyi olduğunu göstermek için bir SurfaceCoverage özellik ile birlikte gelir.

Yöntem çağrılarak ObjectObserver.DetectAsync bir örnek oluşturulur, ardından etkin olduğunda arka planda otomatik olarak güncelleştirilir. Bir uygulama, belirli bir örnekte durum değişikliği olayını dinleyebilir veya güncelleştirmeyi duraklatmak/sürdürmek için izleme modunu değiştirebilir. İzleme kaybolduğunda bir örnek gözlemciden otomatik olarak kaldırılır.

ObjectDiagnosticsSession

ObjectDiagnosticSession tanılamaları kaydeder ve verileri bir arşive yazar.

Tanılama arşivi sahne noktası bulutunu, gözlemcinin durumunu ve modeller hakkındaki bilgileri içerir. Bu bilgiler olası çalışma zamanı sorunlarını belirlemek için yararlıdır. Daha fazla bilgi için bkz. SSS.

Çalışma zamanı SDK'sı kullanımı ve ayrıntıları

Bu bölümde Çalışma Zamanı SDK'sının nasıl kullanılacağına ilişkin temel bilgiler sağlanmalıdır. Nesne Tutturucularının bütünsel olarak nasıl kullanıldığını görmek için örnek uygulamalara göz atmak için size yeterli bağlam sağlamalıdır.

Başlatma

Uygulamaların, kullanmadan önce cihazda Object Anchors'ın desteklenip desteklenmediğini belirlemek için API'yi çağırması ObjectObserver.IsSupported() gerekir. ObjectObserver.IsSupported() API döndürürsefalse, uygulamanın spatialPerception özelliğini etkinleştirip etkinleştirmediğini denetleyin ve\veya en son HoloLens işletim sistemine yükseltin.

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
}

Ardından uygulama bir nesne gözlemcisi oluşturur ve Object Anchors model dönüştürme hizmeti tarafından oluşturulan gerekli modelleri yükler.

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.

Uygulama, bir alan içindeki modelin örneklerini algılamak için bir sorgu oluşturur.

#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);

Varsayılan olarak, algılanan her örnek gözlemci tarafından otomatik olarak izlenir. İsteğe bağlı olarak izleme modunu değiştirerek veya durum değiştirme olaylarını dinleyerek bu örnekleri işleyebiliriz.

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

Durum değiştirme olayında, en son durumu sorgulayabilir veya izlemeyi kaybederse bir örneği atabiliriz.

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

Ayrıca, bir uygulama isteğe bağlı olarak çevrimdışı hata ayıklama için bir veya birden çok tanılama oturumu kaydedebilir.

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"));

Son olarak tüm nesneleri yok ederek kaynakları serbest bırakıyoruz.

using Microsoft.Azure.ObjectAnchors;

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

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