Översikt över Runtime SDK

Det här avsnittet innehåller en översikt över Object Anchors Runtime SDK, som används för att identifiera objekt med hjälp av en Object Anchors-modell. Du får en förståelse för hur ett objekt representeras och vad de olika komponenterna används till.

Alla typer som beskrivs nedan finns i något av följande namnområden: Microsoft.Azure.ObjectAnchors, Microsoft.Azure.ObjectAnchors.Diagnostics och Microsoft.Azure.ObjectAnchors.SpatialGraph.

Typer

ObjectModel

En ObjectModel representerar ett fysiskt objekts geometri och kodar nödvändiga parametrar för identifiering och poseringsuppskattning. Den måste skapas med hjälp av Object Anchors tjänsten. Sedan kan ett program läsa in den genererade modellfilen med hjälp Object Anchors API och fråga nät som är inbäddade i modellen för visualisering.

ObjectSearchArea

Ett ObjectSearchArea anger vilket utrymme som ska sökas efter ett eller flera objekt. Den definieras av ett nod-ID för rumslig graf och rumsliga gränser i koordinatsystemet som representeras av nod-ID:t för den rumsliga grafen. Den Object Anchors Runtime SDK stöder fyra typer av gränser, nämligen visningsfält, avgränsare, sfär och en plats.

AccountInformation

En AccountInformation lagrar ID, nyckel och domän för ditt Azure Object Anchors konto.

ObjectAnchorsSession

En ObjectAnchorsSession representerar en Azure Object Anchors session som används för att skapa ObjectObserver-instanser som används för att identifiera objekt i den fysiska världen.

ObjectObserver

En ObjectObserver läser in objektmodeller, identifierar deras instanser och rapporterar 6-DoF-poser för varje instans i HoloLens koordinatsystem.

Även om en objektmodell eller instans skapas från en observerare är deras livslängd oberoende. Ett program kan ta bort en observerare och fortsätta att använda objektmodellen eller instansen.

ObjectQuery

En ObjectQuery talar om för en objektobservatör hur objekt för en viss modell ska hittas. Den innehåller följande parametrar, vars standardvärden kan hämtas från en objektmodell.

MinSurfaceCoverage

Egenskapen MinSurfaceCoverage anger värdet för att betrakta en instans som upptäckt.

För varje objektkandidat beräknar en observerare förhållandet mellan de överlappande ytorna mellan den transformerade objektmodellen och scenen. Därefter rapporterar den bara att kandidaten ska tillämpas när täckningsförhållandet är över ett visst tröskelvärde.

IsExpectedToBeStandingOnGroundPlane

Egenskapen IsExpectedToBeStandingOnGroundPlane anger om målobjektet förväntas stå på markplanet.

Ett markplan är det lägsta vågräta ordet i sökområdet. Det ger bra begränsningar för möjliga objektställning. Om du slår på den här flaggan vägleder du observerar att uppskatta attityden i ett begränsat utrymme och kan förbättra noggrannheten. Den här parametern ignoreras om modellen inte ska stå på markplanet.

ExpectedMaxVerticalOrientationInDegrees

Egenskapen ExpectedMaxVerticalOrientationInDegrees anger den förväntade maximala vinkeln i grader mellan en objektinstanss uppåtriktning och allvarlighetsgrader.

Den här parametern ger en annan begränsning i uppåtriktningen för en beräknad attityd. Om ett objekt till exempel har rätt värde kan den här parametern vara 0. Object Anchors ska inte identifiera objekt som skiljer sig från modellen. Om en modell är höger kommer den inte att identifiera en instans som har lagts åt sidan. En ny modell skulle användas för layouten sida ned. Samma regel gäller för artikulation.

MaxScaleChange

Egenskapen MaxScaleChange anger den maximala objektskalningsändringen (inom 0 ~ 1) med avseende på rumslig mappning. Den uppskattade skalan tillämpas på transformerade objekthörn som är centrerade vid ursprung och axeljusterade. Uppskattade skalor kanske inte är den faktiska skalan mellan en CAD-modell och dess fysiska representation, men vissa värden som gör att appen kan återge en objektmodell nära spatial mappning på det fysiska objektet.

Sökområden

Egenskapen SearchAreas anger en matris med rumsliga gränser där objekt ska sökas efter.

Observerar söker efter objekt i det gemensamma utrymmet för alla sökområden som anges i en fråga. I den här versionen returnerar vi högst ett objekt med högsta konfidens för att minska svarstiden.

ObjectInstance

Ett ObjectInstance representerar en hypotetisk position där en instans av en viss modell kan finnas i HoloLens koordinatsystemet. Varje instans levereras med en SurfaceCoverage egenskap som anger hur bra den uppskattade attityden är.

En instans skapas genom att metoden ObjectObserver.DetectAsync anropas och uppdateras sedan automatiskt i bakgrunden när den är levande. Ett program kan lyssna på den tillståndsändring som har ändrats på en viss instans eller ändra spårningsläget för att pausa/återuppta uppdateringen. En instans tas automatiskt bort från observerarn när spårningen går förlorad.

ObjectDiagnosticsSession

ObjectDiagnosticSession registrerar diagnostik och skriver data till ett arkiv.

Ett diagnostikarkiv innehåller scenplatsmolnet, övervakningsstatus och information om modellerna. Den här informationen är användbar för att identifiera möjliga körningsproblem. Mer information finns i Vanliga frågor och svar.

Runtime SDK-användning och information

Det här avsnittet innehåller grunderna för hur du använder Runtime SDK. Det bör ge dig tillräckligt med kontext för att bläddra igenom exempelprogrammen för att se hur Object Anchors används holistiskt.

Initiering

Program måste anropa ObjectObserver.IsSupported() API:et för att avgöra Object Anchors stöds på enheten innan de används. Om API:et returnerar kontrollerar du att programmet har aktiverat ObjectObserver.IsSupported() false spatialPerception-funktionen och\eller uppgraderar till den senaste HoloLens operativsystemet.

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
}

Därefter skapar programmet en objektobservatör och läser in nödvändiga modeller som genereras av Object Anchors-modellkonverteringstjänsten.

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.

Programmet skapar en fråga för att identifiera instanser av modellen inom ett utrymme.

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

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

#if WINDOWS_UWP
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.
IList<ObjectInstance> detectedObjects = await observer.DetectAsync(query);

Som standard spåras varje identifierat instans automatiskt av observeraren. Vi kan också ändra dessa instanser genom att ändra deras spårningsläge eller lyssna på deras tillståndsändade händelse.

using Microsoft.Azure.ObjectAnchors;

foreach (ObjectInstance instance in detectedObjects)
{
    // Supported modes:
    // "LowLatencyCoarsePosition"    - Consumes less CPU cycles thus fast to
    //                                 update the state.
    // "HighLatencyAccuratePosition" - (Not yet implemented) 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();
}

I den tillståndsför ändrade händelsen kan vi köra frågor mot det senaste tillståndet eller ta bort en instans om spårningen har gått förlorad.

using Microsoft.Azure.ObjectAnchors;

var InstanceChangedHandler = new Windows.Foundation.TypedEventHandler<ObjectInstance, ObjectInstanceChangedEventArgs>((sender, args) =>
{
    // Try to query the current instance state.
    ObjectInstanceState? state = sender.TryGetCurrentState();

    if (state.HasValue)
    {
        // Process latest state via state.Value.
        // An object pose includes scale, 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.
        sender.Dispose();
    }
});

Ett program kan också registrera en eller flera diagnostiksessioner för felsökning 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"));

Slutligen släpper vi resurser genom att ta bort alla objekt.

using Microsoft.Azure.ObjectAnchors;

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

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