نظرة عامة على SDK وقت التشغيل

يوفر هذا القسم نظرة عامة عالية المستوى على Object Anchors Runtime SDK، والذي يستخدم للكشف عن الكائنات باستخدام نموذج Object Anchors. ستكتسب فهما لكيفية تمثيل عنصر ما وما هي المكونات المختلفة المستخدمة له.

يمكن العثور على جميع الأنواع الموضحة أدناه في إحدى مساحات الأسماء التالية: Microsoft.Azure.ObjectAnchors وMicrosoft.Azure.ObjectAnchors.Diagnostics وMicrosoft.Azure.ObjectAnchors.SpatialGraph.

الأنواع

ObjectModel

يمثل ObjectModel هندسة الكائن المادي وترميز المعلمات الضرورية للكشف عن ذلك وتقدير الوضع. يجب إنشاؤه باستخدام خدمة Object Anchors. ثم يمكن للتطبيق تحميل ملف النموذج الذي تم إنشاؤه باستخدام واجهة برمجة تطبيقات Object Anchors والاستعلام عن الشبكة المضمنة في هذا النموذج للتصور.

ObjectSearchArea

يحدد ObjectSearchArea المساحة للبحث عن كائن واحد أو عدة كائنات. يتم تعريفه بواسطة معرف عقدة رسم بياني مكاني وقيود مكانية في نظام الإحداثيات ممثلا بمعرف عقدة الرسم البياني المكاني. يدعم Object Anchors Runtime SDK أربعة أنواع من الحدود، وهي حقل العرض ومربع الإحاطة والمجال والموقع.

AccountInformation

يخزن AccountInformation المعرف والمفتاح والمجال لحساب Azure Object Anchors.

ObjectAnchorsSession

يمثل ObjectAnchorsSession جلسة Azure Object Anchors المستخدمة لإنشاء مثيلات ObjectObserver المستخدمة للكشف عن العناصر في العالم الفعلي.

ObjectObserver

يقوم ObjectObserver بتحميل نماذج العناصر، والكشف عن مثيلاتها، والإبلاغ عن وضعيات 6-DoF لكل مثيل في نظام إحداثيات HoloLens.

على الرغم من إنشاء أي نموذج عنصر أو مثيل من مراقب، فإن مدة بقائهم مستقلة. يمكن للتطبيق التخلص من مراقب والاستمرار في استخدام نموذج الكائن أو المثيل.

ObjectQuery

يخبر ObjectQuery مراقب العنصر بكيفية العثور على كائنات نموذج معين. يوفر المعلمات القابلة للضبط التالية، والتي يمكن استرداد قيمها الافتراضية من نموذج عنصر.

MinSurfaceCoverage

تشير الخاصية MinSurfaceCoverage إلى القيمة التي يجب مراعاتها كمثيل تم اكتشافه.

لكل مرشح عنصر، يحسب المراقب نسبة الأسطح المتداخلة بين نموذج الكائن المحول والمشهد، ثم يبلغ عن هذا المرشح للتطبيق فقط عندما تكون نسبة التغطية أعلى من حد معين.

IsExpectedToBeStandingOnGroundPlane

تشير الخاصية IsExpectedToBeStandingOnGroundPlane إلى ما إذا كان من المتوقع أن يقف الكائن الهدف على الطائرة الأرضية.

الطائرة الأرضية هي أدنى طابق أفقي في منطقة البحث. يوفر قيدا جيدا على يطرح الكائن المحتمل. سيؤدي تشغيل هذه العلامة إلى توجيه المراقب لتقدير الوضع في مساحة محدودة ويمكن أن يحسن الدقة. سيتم تجاهل هذه المعلمة إذا لم يكن من المفترض أن يقف النموذج على الطائرة الأرضية.

ExpectedMaxVerticalOrientationInDegrees

تشير الخاصية ExpectedMaxVerticalOrientationInDegrees إلى الزاوية القصوى المتوقعة بالدرجات بين اتجاه مثيل الكائن والجاذبية.

توفر هذه المعلمة قيدا آخر على الاتجاه الأعلى لشكل مقدر. على سبيل المثال، إذا كان العنصر لأعلى اليمين، يمكن أن تكون هذه المعلمة 0. لا يفترض أن تكتشف Object Anchors العناصر المختلفة عن النموذج. إذا كان النموذج لأعلى اليمين، فلن يكتشف مثيلا تم وضعه جنبا إلى أسفل. سيتم استخدام نموذج جديد للتخطيط الجانبي لأسفل. تنطبق نفس القاعدة على التعبير.

MaxScaleChange

تشير الخاصية MaxScaleChange إلى الحد الأقصى لتغيير مقياس الكائن (ضمن 0 ~ 1) فيما يتعلق بالتعيين المكاني. يتم تطبيق المقياس المقدر على رؤوس الكائنات المحولة المتمركزة في الأصل ومحاذات المحور. قد لا تكون المقاييس المقدرة هي المقياس الفعلي بين نموذج CAD وتمثيله المادي، ولكن بعض القيم التي تسمح للتطبيق بعرض نموذج كائن بالقرب من التعيين المكاني على العنصر الفعلي.

SearchAreas

تشير الخاصية SearchAreas إلى صفيف من الحدود المكانية حيث يمكن العثور على الكائن (العناصر).

سيبحث المراقب عن كائنات في مساحة الاتحاد لكافة مناطق البحث المحددة في استعلام. في هذا الإصدار، سنعيد كائنا واحدا على الأكثر بأعلى ثقة لتقليل زمن الانتقال.

ObjectInstance

يمثل ObjectInstance موضعا افتراضيا حيث يمكن أن يكون مثيل نموذج معين في نظام إحداثيات HoloLens. يأتي كل مثيل مع خاصية SurfaceCoverage للإشارة إلى مدى جود الوضع المقدر.

يتم إنشاء مثيل عن طريق استدعاء ObjectObserver.DetectAsync الأسلوب، ثم تحديثه تلقائيا في الخلفية عند الحياة. يمكن للتطبيق الاستماع إلى حدث الحالة الذي تم تغييره على مثيل معين أو تغيير وضع التعقب لإيقاف التحديث مؤقتا/استئنافه. ستتم إزالة مثيل تلقائيا من المراقب عند فقدان التتبع.

ObjectDiagnosticsSession

يسجل ObjectDiagnosticSession التشخيصات ويكتب البيانات في أرشيف.

يتضمن أرشيف التشخيص سحابة نقطة المشهد وحالة المراقب ومعلومات حول النماذج. هذه المعلومات مفيدة لتحديد مشكلات وقت التشغيل المحتملة. لمزيد من المعلومات، راجع الأسئلة المتداولة.

استخدام SDK لوقت التشغيل وتفاصيله

يجب أن يوفر لك هذا القسم أساسيات كيفية استخدام Runtime SDK. يجب أن يمنحك سياقا كافيا لاستعراض نماذج التطبيقات لمعرفة كيفية استخدام Object Anchors بشكل كلي.

بدء

تحتاج التطبيقات إلى استدعاء ObjectObserver.IsSupported() واجهة برمجة التطبيقات لتحديد ما إذا كان Object Anchors مدعوما على الجهاز قبل استخدامه. ObjectObserver.IsSupported() إذا كانت واجهة برمجة التطبيقات ترجع false، فتحقق من أن التطبيق قد قام بتمكين إمكانية spatialPerception و\أو الترقية إلى أحدث نظام تشغيل 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
}

بعد ذلك، ينشئ التطبيق مراقب كائن ويحمل النماذج الضرورية التي تم إنشاؤها بواسطة خدمة تحويل نموذج 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.

ينشئ التطبيق استعلاما للكشف عن مثيلات هذا النموذج داخل مساحة.

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

بشكل افتراضي، سيتم تعقب كل مثيل تم اكتشافه تلقائيا بواسطة المراقب. يمكننا معالجة هذه المثيلات اختياريا عن طريق تغيير وضع التعقب الخاص بها أو الاستماع إلى حدث تغيير حالتها.

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

في الحالة التي تم تغييرها، يمكننا الاستعلام عن أحدث حالة أو التخلص من مثيل إذا فقد التعقب.

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

أيضا، يمكن للتطبيق اختياريا تسجيل جلسة تشخيص واحدة أو عدة جلسات لتصحيح الأخطاء دون اتصال.

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

وأخيرا نحرر الموارد عن طريق التخلص من جميع الكائنات.

using Microsoft.Azure.ObjectAnchors;

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

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