Overzicht van runtime-SDK

Artikel
07/30/2021
7 minuten om te lezen

Deze sectie biedt een overzicht op hoog niveau van de Object Anchors Runtime SDK, die wordt gebruikt om objecten te detecteren met behulp van een Object Anchors model. U krijgt inzicht in hoe een object wordt weergegeven en waarvoor de verschillende onderdelen worden gebruikt.

Alle typen die hieronder worden beschreven, vindt u in een van de volgende naamruimten: Microsoft.Azure.ObjectAnchors, Microsoft.Azure.ObjectAnchors.Diagnostics en Microsoft.Azure.ObjectAnchors.SpatialGraph.

Typen

ObjectModel

Een ObjectModel vertegenwoordigt de geometrie van een fysiek object en codeert de benodigde parameters voor detectie en houdingsschatting. Deze moet worden gemaakt met behulp van de Object Anchors service. Vervolgens kan een toepassing het gegenereerde modelbestand laden met behulp van de Object Anchors API en query's uitvoeren op de mesh die in dat model is ingesloten voor visualisatie.

ObjectSearchArea

Een ObjectSearchArea geeft de ruimte op om te zoeken naar een of meer objecten. Het wordt gedefinieerd door een knooppunt-id voor ruimtelijke grafieken en ruimtelijke grenzen in het coördinaatsysteem dat wordt vertegenwoordigd door de knooppunt-id van de ruimtelijke grafiek. De Object Anchors Runtime SDK ondersteunt vier typen grenzen, namelijk het weergaveveld, het begrendingsvak, de bol en een locatie.

AccountInformation

Een AccountInformation slaat de id, de sleutel en het domein voor uw Azure Object Anchors account op.

ObjectAnchorsSession

Een ObjectAnchorsSession vertegenwoordigt een Azure Object Anchors sessie die wordt gebruikt om ObjectObserver-exemplaren te maken die worden gebruikt om objecten in de fysieke wereld te detecteren.

ObjectObserver

Een ObjectObserver laadt objectmodellen, detecteert hun exemplaren en rapporteert 6-DoF-houdingen van elk exemplaar in HoloLens coördinaatsysteem.

Hoewel elk objectmodel of exemplaar van een waarnemer wordt gemaakt, zijn hun levensduur onafhankelijk. Een toepassing kan een waarnemer verwijderen en het objectmodel of exemplaar blijven gebruiken.

ObjectQuery

Een ObjectQuery vertelt een objectwaarnemer hoe objecten van een bepaald model kunnen worden gevonden. Het biedt de volgende in te stellen parameters, waarvan de standaardwaarden kunnen worden opgehaald uit een objectmodel.

MinSurfaceCoverage

De eigenschap MinSurfaceCoverage geeft de waarde aan die een exemplaar als gedetecteerd moet beschouwen.

Voor elke objectkandidaat berekent een waarnemer de verhouding van overlappende oppervlakken tussen het getransformeerde objectmodel en de scène. Vervolgens wordt die kandidaat voor toepassing alleen vermeld wanneer de dekkingsverhouding boven een bepaalde drempelwaarde ligt.

IsExpectedToBeStandingOnGroundPlane

De eigenschap IsExpectedToBeStandingOnGroundPlane geeft aan of het doelobject naar verwachting op het grondvlak staat.

Een grondvlak is de laagste horizontale verdieping in het zoekgebied. Het biedt een goede beperking voor de mogelijke objecthoudingen. Door deze vlag in te stellen, kan de waarnemer de houding in een beperkte ruimte inschatten en kan de nauwkeurigheid worden verbeterd. Deze parameter wordt genegeerd als het model niet op de grond mag staan.

ExpectedMaxVerticalOrientationInDegrees

De eigenschap ExpectedMaxVerticalOrientationInDegrees geeft de verwachte maximale hoek aan in graden tussen de uprichting van een objectin exemplaar en de ernst.

Deze parameter biedt een andere beperking voor de uprichting van een geschatte houding. Als een object bijvoorbeeld rechts omhoog is, kan deze parameter 0 zijn. Object Anchors mag geen objecten detecteren die verschillen van het model. Als een model rechts omhoog is, wordt er geen instantie gedetecteerd die naast elkaar is gelegd. Er wordt een nieuw model gebruikt voor de side-down indeling. Dezelfde regel is van toepassing op de uiting.

MaxScaleChange

De eigenschap MaxScaleChange geeft de maximale wijziging in de objectschaal aan (binnen 0 ~ 1) met betrekking tot ruimtelijke toewijzing. De geschatte schaal wordt toegepast op getransformeerde objectkinnen die zijn gecentreerd op de oorsprong en as uitgelijnd. Geschatte schalen zijn mogelijk niet de werkelijke schaal tussen een CAD-model en de fysieke weergave, maar sommige waarden waarmee de app een objectmodel dicht bij de ruimtelijke toewijzing van het fysieke object kan renderen.

SearchAreas

De eigenschap SearchAreas geeft een matrix van ruimtelijke grenzen aan waar u object(en) kunt vinden.

De waarnemer zoekt naar objecten in de union-ruimte van alle zoekgebieden die zijn opgegeven in een query. In deze release retourneren we ten hoogste één object met de hoogste betrouwbaarheid om de latentie te verminderen.

ObjectInstance

Een ObjectInstance vertegenwoordigt een hypothetische positie waarbij een exemplaar van een bepaald model zich in het HoloLens coördinaatsysteem. Elke instantie wordt geleverd met een SurfaceCoverage eigenschap om aan te geven hoe goed de geschatte houding is.

Er wordt een exemplaar gemaakt door de ObjectObserver.DetectAsync methode aan te roepen en vervolgens automatisch op de achtergrond bij te werken wanneer deze wordt uitgevoerd. Een toepassing kan luisteren naar de statuswijzigingsgebeurtenis op een bepaald exemplaar of de traceringsmodus wijzigen om de update te onderbreken/hervatten. Een exemplaar wordt automatisch uit de waarnemer verwijderd wanneer tracering verloren gaat.

ObjectDiagnosticsSession

De ObjectDiagnosticSession registreert diagnostische gegevens en schrijft gegevens naar een archief.

Een diagnostisch archief bevat de scènepuntwolk, de status van de waarnemer en informatie over de modellen. Deze informatie is handig om mogelijke runtimeproblemen te identificeren. Zie veelgestelde vragen voor meer informatie.

Gebruik en details van runtime-SDK

In deze sectie vindt u de basisbeginselen van het gebruik van de Runtime-SDK. Het geeft u voldoende context om door de voorbeeldtoepassingen te bladeren om te zien hoe Object Anchors holistisch wordt gebruikt.

Initialisatie

Toepassingen moeten de ObjectObserver.IsSupported() API aanroepen om te bepalen of Object Anchors wordt ondersteund op het apparaat voordat deze wordt gebruikt. Als de API retourneert, controleert u of de toepassing de mogelijkheid spatialPerception heeft ingeschakeld ObjectObserver.IsSupported() false en\of upgradet naar de meest recente HoloLens os.

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
}

Vervolgens maakt de toepassing een objectwaarnemer en laadt de benodigde modellen die zijn gegenereerd door de Object Anchors-modelconversieservice.

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.

De toepassing maakt een query om exemplaren van dat model binnen een ruimte te detecteren.

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

Standaard wordt elk gedetecteerd exemplaar automatisch bijgespoord door de waarnemer. Optioneel kunnen we deze exemplaren bewerken door de traceringsmodus te wijzigen of te luisteren naar de gebeurtenis status gewijzigd.

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

In de gebeurtenis Status gewijzigd kunnen we de meest recente status opvragen of een exemplaar verwijderen als het traceringsvolgsysteem verloren gaat.

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

Een toepassing kan eventueel een of meerdere diagnostische sessies opnemen voor offline-debugging.

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

Ten slotte brengen we resources vrij door alle objecten te verwijderen.

using Microsoft.Azure.ObjectAnchors;

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

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