Översikt över Runtime SDK

Det här avsnittet innehåller en översikt på hög nivå ö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 poseuppskattning. Den måste skapas med hjälp av tjänsten Object Anchors. Sedan kan ett program läsa in den genererade modellfilen med hjälp av API:et Object Anchors och köra frågor mot det inbäddade nätet i modellen för visualisering.

ObjectSearchArea

Ett ObjectSearchArea anger det utrymme som ska sökas efter ett eller flera objekt. Det definieras av ett rumsligt grafnod-ID och rumsliga gränser i koordinatsystemet som representeras av det rumsliga grafnod-ID:t. Object Anchors Runtime SDK stöder fyra typer av gränser, nämligen visningsfält, avgränsningsruta, 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-koordinatsystemet.

Även om alla objektmodeller eller instanser skapas från en övervakare är deras livslängd oberoende. Ett program kan ta bort en övervakare och fortsätta att använda objektmodellen eller instansen.

ObjectQuery

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

MinSurfaceCoverage

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

För varje objektkandidat beräknar en övervakare förhållandet mellan överlappande ytor mellan transformerad objektmodell och scen. Sedan rapporterar den kandidaten till programmet endast 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 golvet i sökområdet. Det ger goda begränsningar för möjliga objektpositioner. Om du aktiverar den här flaggan vägleder du observatören att uppskatta posen 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 uppriktningen för en objektinstans och gravitationen.

Den här parametern ger en annan begränsning för uppriktningen för en uppskattad pose. Om ett objekt till exempel är rätt kan den här parametern vara 0. Objektfästpunkter ska inte identifiera objekt som skiljer sig från modellen. Om en modell är uppåtriktad identifierar den inte en instans som har lagts ned åt sidan. En ny modell skulle användas för sidolayout. Samma regel gäller för artikulering.

MaxScaleChange

Egenskapen MaxScaleChange anger den maximala objektskalningsändringen (inom 0 ~ 1) när det gäller rumslig mappning. Den uppskattade skalan tillämpas på omvandlade objekthörn centrerad efter ursprung och axeljusterad. 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 rumslig mappning på det fysiska objektet.

SearchAreas

Egenskapen SearchAreas anger en matris med rumsliga gränser där objekt ska hittas.

Övervakaren söker efter objekt i unionsområdet 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

En 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 posen är.

En instans skapas genom att anropa ObjectObserver.DetectAsync metoden och uppdateras sedan automatiskt i bakgrunden när den är vid liv. Ett program kan lyssna på tillståndsändringshändelsen på en viss instans eller ändra spårningsläget för att pausa/återuppta uppdateringen. En instans tas automatiskt bort från övervakaren när spårningen går förlorad.

ObjectDiagnosticsSession

ObjectDiagnosticSession registrerar diagnostik och skriver data till ett arkiv.

Ett diagnostikarkiv innehåller scenpunktsmolnet, observatörens status 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.

Användning och information om Runtime SDK

Det här avsnittet bör ge dig grunderna i 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 API:et ObjectObserver.IsSupported() för att avgöra om Object Anchors stöds på enheten innan de använder den. Om API:et ObjectObserver.IsSupported() returnerar falsekontrollerar du att programmet har aktiverat spatialPerception-funktionen och\eller uppgradera till det 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 objektövervakare och läser in de modeller som genereras av objektfästpunktsmodellens konverteringstjänst.

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.

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

Som standard spåras varje identifierad instans automatiskt av övervakaren. Vi kan också ändra dessa instanser genom att ändra deras spårningsläge eller lyssna på deras tillstånd ändrade 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" - 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();
}

I den tillstånds ändrade händelsen kan vi fråga det senaste tillståndet eller ta bort en instans om den förlorade spårningen.

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

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