Přehled sady Runtime SDK

Tato část obsahuje základní přehled sady SDK modulu Runtime Ukotvení objektů, která se používá k detekci objektů pomocí modelu Ukotvení objektů. Získáte představu o tom, jak je objekt reprezentován a k čemu se používají různé komponenty.

Všechny typy popsané níže najdete v jednom z následujících oborů názvů: Microsoft.Azure.ObjectAnchors, Microsoft.Azure.ObjectAnchors.Diagnostics a Microsoft.Azure.ObjectAnchors.SpatialGraph.

Typy

ObjectModel

ObjectModel představuje geometrii fyzického objektu a zakóduje nezbytné parametry pro detekci a odhad pozice. Musí se vytvořit pomocí služby Object Anchors. Aplikace pak může načíst vygenerovaný soubor modelu pomocí rozhraní API ukotvení objektů a dotazovat se na síť vloženou v daném modelu pro vizualizaci.

ObjectSearchArea

ObjectSearchArea určuje prostor, který má hledat jeden nebo více objektů. Definuje ho ID uzlu prostorového grafu a prostorové hranice v souřadnicovém systému reprezentované ID uzlu prostorového grafu. Sada SDK modulu runtime Ukotvení objektů podporuje čtyři typy hranic, konkrétně pole zobrazení, ohraničující rámeček, sphere a umístění.

Informace o účtu

AccountInformation ukládá ID, klíč a doménu pro váš účet Azure Object Anchors.

ObjectAnchorsSession

ObjectAnchorsSession představuje relaci Azure Object Anchors, která se používá k vytváření instancí ObjectObserver používaných k detekci objektů ve fyzickém světě.

ObjectObserver

ObjectObserver načte objektové modely, detekuje jejich instance a hlásí 6-DoF pozice každé instance v souřadnicového systému HoloLens.

I když se z pozorovatele vytvoří jakýkoli objektový model nebo instance, jejich životnosti jsou nezávislé. Aplikace může zlikvidovat pozorovatele a nadále používat objektový model nebo instanci.

Objectquery

ObjectQuery říká pozorovateli objektu, jak najít objekty daného modelu. Poskytuje následující vyladěné parametry, jejichž výchozí hodnoty lze načíst z objektového modelu.

MinSurfaceCoverage

MinSurfaceCoverage vlastnost označuje hodnotu, která se má zvážit instance, jak bylo zjištěno.

Pro každého kandidáta objektu pozorovatel vypočítá poměr překrývajících se ploch mezi transformovaným objektovým modelem a scénou a pak hlásí, že kandidát na aplikaci je pouze v případě, že poměr pokrytí překročí danou prahovou hodnotu.

IsExpectedToBeStandingOnGroundPlane

IsExpectedToBeStandingOnGroundPlane vlastnost indikuje, zda cílový objekt má stát na pozemní rovině.

Pozemní rovina je nejnižší vodorovná podlaha ve vyhledávací oblasti. Poskytuje dobré omezení pro možné pozice objektu. Zapnutím tohoto příznaku provedete pozorovatele , aby odhadl pozici v omezeném prostoru a mohl by zlepšit přesnost. Tento parametr bude ignorován, pokud model nemá stát na pozemní rovině.

ExpectedMaxVerticalOrientationInDegrees

ExpectedMaxVerticalOrientationInDegrees vlastnost označuje očekávaný maximální úhel ve stupních mezi směrem nahoru instance objektu a závažnosti.

Tento parametr poskytuje další omezení směru nahoru odhadované pozice. Pokud je například objekt vpravo, může být tento parametr 0. Ukotvení objektů by nemělo rozpoznát objekty, které se liší od modelu. Pokud je model v pořádku, nerozpozná se instance položená vedle sebe. Pro boční rozložení by se použil nový model. Stejné pravidlo platí pro artikulaci.

MaxScaleChange

MaxScaleChange Vlastnost označuje maximální změnu měřítka objektu (v rámci 0 ~ 1) s ohledem na prostorové mapování. Odhadované měřítko se použije u transformovaných vrcholů objektů zarovnaných na střed a na ose. Odhadované měřítka nemusí být skutečným měřítkem mezi modelem CAD a jeho fyzickou reprezentací, ale některé hodnoty, které aplikaci umožňují vykreslit objektový model v blízkosti prostorového mapování fyzického objektu.

SearchAreas

SearchAreas vlastnost označuje pole prostorových hranic, kde najít objekty.

Pozorovatel vyhledá objekty ve sjednocovacím prostoru všech vyhledávacích oblastí zadaných v dotazu. V této verzi vrátíme maximálně jeden objekt s nejvyšší jistotou, abychom snížili latenci.

Instance ObjectInstance

ObjectInstance představuje hypotetickou pozici, kde instance daného modelu může být v souřadnicovém systému HoloLens. Každá instance se dodává s vlastností, SurfaceCoverage která označuje, jak dobrá je odhadovaná pozice.

Instance se vytvoří voláním ObjectObserver.DetectAsync metody a pak se automaticky aktualizuje na pozadí při živém stavu. Aplikace může naslouchat změněné události stavu v konkrétní instanci nebo změnit režim sledování tak, aby se aktualizace pozastavila nebo obnovila. Při ztrátě sledování se instance automaticky odebere z pozorovatele.

ObjectDiagnosticsSession

ObjectDiagnosticSession zaznamenává diagnostiku a zapisuje data do archivu.

Archiv diagnostiky zahrnuje cloud bodu scény, stav pozorovatele a informace o modelech. Tyto informace jsou užitečné k identifikaci možných problémů s modulem runtime. Další informace najdete v nejčastějších dotazech.

Využití a podrobnosti sady Runtime SDK

Tato část by vám měla poskytnout základní informace o používání sady Runtime SDK. Měl by vám poskytnout dostatečný kontext k procházení ukázkových aplikací, abyste viděli, jak se objektové kotvy používají holisticky.

Inicializace

Aplikace musí rozhraní API volat ObjectObserver.IsSupported() , aby se zjistilo, jestli je ukotvení objektů na zařízení podporované, než ho použijete. ObjectObserver.IsSupported() Pokud se rozhraní API vrátífalse, zkontrolujte, jestli aplikace povolila funkci spatialPerception a nebo upgradujte na nejnovější operační systém HoloLens.

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ále aplikace vytvoří pozorovatel objektu a načte potřebné modely vygenerované službou převodu modelu 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.

Aplikace vytvoří dotaz pro detekci instancí tohoto modelu v rámci prostoru.

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

Ve výchozím nastavení bude každá zjištěná instance automaticky sledována pozorovatelem. Volitelně můžeme s těmito instancemi manipulovat změnou jejich režimu sledování nebo nasloucháním události změny stavu.

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

V události změny stavu můžeme zadat dotaz na nejnovější stav nebo likvidovat instanci v případě ztráty sledování.

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

Aplikace může také volitelně zaznamenat jednu nebo více diagnostických relací pro offline ladění.

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

Nakonec uvolníme prostředky tím, že odstraníme všechny objekty.

using Microsoft.Azure.ObjectAnchors;

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

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