واجهة برمجة تطبيقات تشغيل Azure Kinect

توفر عدة تطوير برامج أداة الاستشعار واجهة برمجة تطبيقات لتسجيل بيانات الجهاز إلى ملف بتنسيق Matroska (mkv.). يخزن تنسيق حاوية Matroska مقاطع الفيديو وعينات IMU ومعايرة الجهاز. يمكن إنشاء التسجيلات باستخدام أداة سطر الأوامر المساعدة المتوفرة k4arecorder. كذلك يمكن تخصيص التسجيلات وتسجيلها مباشرةً باستخدام واجهة برمجة تطبيقات التسجيل.

لمزيد من المعلومات حول واجهة برمجة تطبيقات التسجيل، راجع k4a_record_create().

لمزيد من المعلومات حول مواصفات تنسيق الملفات Matroska، راجع صفحة تنسيق ملفات التسجيل.

استخدام واجهة برمجة التطبيقات الخاصة بالتشغيل

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

فتح ملف تسجيل

في المثال التالي، نفتح تسجيلاً باستخدام k4a_playback_open()، ونطبع طول التسجيل، ثم نغلق الملف باستخدام k4a_playback_close().

k4a_playback_t playback_handle = NULL;
if (k4a_playback_open("recording.mkv", &playback_handle) != K4A_RESULT_SUCCEEDED)
{
    printf("Failed to open recording\n");
    return 1;
}

uint64_t recording_length = k4a_playback_get_last_timestamp_usec(playback_handle);
printf("Recording is %lld seconds long\n", recording_length / 1000000);

k4a_playback_close(playback_handle);

قراءة اللقطات المُسجَّلة

بمجرد فتح الملف، يمكننا بدء قراءة اللقطات المُسجَّلة من التسجيل. في هذا المثال التالي، نقرأ كل لقطة من اللقطات في الملف.

k4a_capture_t capture = NULL;
k4a_stream_result_t result = K4A_STREAM_RESULT_SUCCEEDED;
while (result == K4A_STREAM_RESULT_SUCCEEDED)
{
    result = k4a_playback_get_next_capture(playback_handle, &capture);
    if (result == K4A_STREAM_RESULT_SUCCEEDED)
    {
        // Process capture here
        k4a_capture_release(capture);
    }
    else if (result == K4A_STREAM_RESULT_EOF)
    {
        // End of file reached
        break;
    }
}
if (result == K4A_STREAM_RESULT_FAILED)
{
    printf("Failed to read entire recording\n");
    return 1;
}

البحث داخل التسجيل

بمجرد وصولنا إلى نهاية الملف، قد نرغب في العودة وقراءته مرة أخرى. يمكن إجراء هذه العملية من خلال القراءة للخلف باستخدام k4a_playback_get_previous_capture()، ولكنها قد تكون بطيئة للغاية وفقاً لطول التسجيل. بدلاً من ذلك، يمكننا استخدام الوظيفة k4a_playback_seek_timestamp() للانتقال إلى نقطة معينة في الملف.

في هذا المثال، نحدد الطوابع الزمنية بالميكرو ثانية للبحث عن نقاط مختلفة في الملف.

// Seek to the beginning of the file
if (k4a_playback_seek_timestamp(playback_handle, 0, K4A_PLAYBACK_SEEK_BEGIN) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to the end of the file
if (k4a_playback_seek_timestamp(playback_handle, 0, K4A_PLAYBACK_SEEK_END) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to 10 seconds from the start
if (k4a_playback_seek_timestamp(playback_handle, 10 * 1000000, K4A_PLAYBACK_SEEK_BEGIN) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to 10 seconds from the end
if (k4a_playback_seek_timestamp(playback_handle, -10 * 1000000, K4A_PLAYBACK_SEEK_END) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

قراءة معلومات العلامة

يمكن أن تحتوي التسجيلات أيضاً على بيانات تعريف مختلفة، مثل الرقم التسلسلي للجهاز وإصدارات البرامج الثابتة. يتم تخزين بيانات التعريف هذه في علامات التسجيل، والتي يمكن الوصول إليها باستخدام الوظيفة k4a_playback_get_tag().

// Print the serial number of the device used to record
char serial_number[256];
size_t serial_number_size = 256;
k4a_buffer_result_t buffer_result = k4a_playback_get_tag(playback_handle, "K4A_DEVICE_SERIAL_NUMBER", &serial_number, &serial_number_size);
if (buffer_result == K4A_BUFFER_RESULT_SUCCEEDED)
{
    printf("Device serial number: %s\n", serial_number);
}
else if (buffer_result == K4A_BUFFER_RESULT_TOO_SMALL)
{
    printf("Device serial number too long.\n");
}
else
{
    printf("Tag does not exist. Device serial number was not recorded.\n");
}

قائمة علامات التسجيل

فيما يلي قائمة بجميع العلامات الافتراضية التي قد يتم تضمينها في ملف تسجيل. تتوفر العديد من هذه القيم كجزء من بنية k4a_record_configuration_t، ويمكن قراءتها باستخدام الوظيفة k4a_playback_get_record_configuration().

إذا لم تكن العلامة موجودة، فيُفترض أن تكون لها القيمة الافتراضية.

اسم العلامة	القيمة الافتراضية	الحقل k4a_record_configuration_t	ملاحظات
K4A_COLOR_MODE	"OFF"	color_format / color_resolution	القيم المحتملة: "OFF" و"MJPG_1080P" و"NV12_720P" و"YUY2_720P" وما إلى ذلك
K4A_DEPTH_MODE	"OFF"	depth_mode / depth_track_enabled	القيم المحتملة: "OFF و"NFOV_UNBINNED" و"PASSIVE_IR" وما إلى ذلك
K4A_IR_MODE	"OFF"	depth_mode / ir_track_enabled	القيم المحتملة: "OFF" و"ACTIVE" و"PASSIVE"
K4A_IMU_MODE	"OFF"	imu_track_enabled	القيم المحتملة: "ON" و"OFF"
K4A_CALIBRATION_FILE	"calibration.json"	غير متوفر	راجع k4a_device_get_raw_calibration()
K4A_DEPTH_DELAY_NS	"0"	depth_delay_off_color_usec	يتم تخزين القيمة بالنانو ثانية، وتوفر واجهة برمجة التطبيقات قيم ميكرو ثانية.
K4A_WIRED_SYNC_MODE	"STANDALONE"	wired_sync_mode	القيم المحتملة: "STANDALONE" و"MASTER" و"SUBORDINATE"
K4A_SUBORDINATE_DELAY_NS	"0"	subordinate_delay_off_master_usec	يتم تخزين القيمة بالنانو ثانية، وتوفر واجهة برمجة التطبيقات قيم ميكرو ثانية.
K4A_COLOR_FIRMWARE_VERSION	""	غير متوفر	إصدار البرنامج الثابت لألوان الجهاز، مثلاً "1.x.xx"
K4A_DEPTH_FIRMWARE_VERSION	""	غير متوفر	إصدار البرنامج الثابت لعمق الجهاز، مثلاً "1.x.xx"
K4A_DEVICE_SERIAL_NUMBER	""	غير متوفر	الرقم التسلسلي لجهاز التسجيل
K4A_START_OFFSET_NS	"0"	start_timestamp_offset_usec	راجع مزامنة الطابع الزمني أدناه.
K4A_COLOR_TRACK	بلا	غير متوفر	راجع تنسيق ملف التسجيل - تحديد المقاطع.
K4A_DEPTH_TRACK	بلا	غير متوفر	راجع تنسيق ملف التسجيل - تحديد المقاطع.
K4A_IR_TRACK	بلا	غير متوفر	راجع تنسيق ملف التسجيل - تحديد المقاطع.
K4A_IMU_TRACK	بلا	غير متوفر	راجع تنسيق ملف التسجيل - تحديد المقاطع.

مزامنة الطابع الزمني

يتطلب تنسيق Matroska أن تبدأ التسجيلات بطابع زمني قيمته صفر. عند مزامنة الكاميرات خارجياً، يمكن أن يكون الطابع الزمني الأول من كل جهاز غير صفري.

للاحتفاظ بالطوابع الزمنية الأصلية المأخوذة من الأجهزة فيما بين التسجيل والتشغيل، يخزن الملف إزاحةً لتطبيقها على الطوابع الزمنية.

تُستخدم العلامة K4A_START_OFFSET_NS لتحديد إزاحة طابع زمني بحيث يمكن إعادة مزامنة الملفات بعد التسجيل. يمكن إضافة إزاحة الطابع الزمني هذه إلى كل طابع زمني في الملف لإعادة إنشاء الطوابع الزمنية الأصلية للأجهزة.

تتوفر إزاحة البدء أيضاً في البنية k4a_record_configuration_t.