253 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _v4l2-meta-fmt-d4xx:4 5*******************************6V4L2_META_FMT_D4XX ('D4XX')7*******************************8 9Intel D4xx UVC Cameras Metadata10 11 12Description13===========14 15Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC16payload headers, following the Microsoft(R) UVC extension proposal [1_]. That17means, that the private D4XX metadata, following the standard UVC header, is18organised in blocks. D4XX cameras implement several standard block types,19proposed by Microsoft, and several proprietary ones. Supported standard metadata20types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),21and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This22document describes proprietary metadata types, used by D4xx cameras.23 24V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of25V4L2_META_FMT_UVC with the only difference, that it also includes proprietary26payload header data. D4xx cameras use bulk transfers and only send one payload27per frame, therefore their headers cannot be larger than 255 bytes.28 29This document implements Intel Configuration version 3 [9_].30 31Below are proprietary Microsoft style metadata types, used by D4xx cameras,32where all fields are in little endian order:33 34.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|35 36 37.. flat-table:: D4xx metadata38 :widths: 1 239 :header-rows: 140 :stub-columns: 041 42 * - **Field**43 - **Description**44 * - :cspan:`1` *Depth Control*45 * - __u32 ID46 - 0x8000000047 * - __u32 Size48 - Size in bytes, include ID (all protocol versions: 60)49 * - __u32 Version50 - Version of this structure. The documentation herein covers versions 1,51 2 and 3. The version number will be incremented when new fields are52 added.53 * - __u32 Flags54 - A bitmask of flags: see [2_] below55 * - __u32 Gain56 - Gain value in internal units, same as the V4L2_CID_GAIN control, used to57 capture the frame58 * - __u32 Exposure59 - Exposure time (in microseconds) used to capture the frame60 * - __u32 Laser power61 - Power of the laser LED 0-360, used for depth measurement62 * - __u32 AE mode63 - 0: manual; 1: automatic exposure64 * - __u32 Exposure priority65 - Exposure priority value: 0 - constant frame rate66 * - __u32 AE ROI left67 - Left border of the AE Region of Interest (all ROI values are in pixels68 and lie between 0 and maximum width or height respectively)69 * - __u32 AE ROI right70 - Right border of the AE Region of Interest71 * - __u32 AE ROI top72 - Top border of the AE Region of Interest73 * - __u32 AE ROI bottom74 - Bottom border of the AE Region of Interest75 * - __u32 Preset76 - Preset selector value, default: 0, unless changed by the user77 * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]78 - 0: off, 1: on, same as __u32 Laser mode for v179 * - __u8 RFU byte (v3 only)80 - Spare byte for future use81 * - __u16 LED Power (v3 only)82 - Led power value 0-360 (F416 SKU)83 * - :cspan:`1` *Capture Timing*84 * - __u32 ID85 - 0x8000000186 * - __u32 Size87 - Size in bytes, include ID (all protocol versions: 40)88 * - __u32 Version89 - Version of this structure. The documentation herein corresponds to90 version xxx. The version number will be incremented when new fields are91 added.92 * - __u32 Flags93 - A bitmask of flags: see [3_] below94 * - __u32 Frame counter95 - Monotonically increasing counter96 * - __u32 Optical time97 - Time in microseconds from the beginning of a frame till its middle98 * - __u32 Readout time99 - Time, used to read out a frame in microseconds100 * - __u32 Exposure time101 - Frame exposure time in microseconds102 * - __u32 Frame interval103 - In microseconds = 1000000 / framerate104 * - __u32 Pipe latency105 - Time in microseconds from start of frame to data in USB buffer106 * - :cspan:`1` *Configuration*107 * - __u32 ID108 - 0x80000002109 * - __u32 Size110 - Size in bytes, include ID (v1:36, v3:40)111 * - __u32 Version112 - Version of this structure. The documentation herein corresponds to113 version xxx. The version number will be incremented when new fields are114 added.115 * - __u32 Flags116 - A bitmask of flags: see [4_] below117 * - __u8 Hardware type118 - Camera hardware version [5_]119 * - __u8 SKU ID120 - Camera hardware configuration [6_]121 * - __u32 Cookie122 - Internal synchronisation123 * - __u16 Format124 - Image format code [7_]125 * - __u16 Width126 - Width in pixels127 * - __u16 Height128 - Height in pixels129 * - __u16 Framerate130 - Requested frame rate per second131 * - __u16 Trigger132 - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger133 * - __u16 Calibration count (v3 only)134 - Calibration counter, see [4_] below135 * - __u8 GPIO input data (v3 only)136 - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)137 * - __u32 Sub-preset info (v3 only)138 - Sub-preset choice information, see [4_] below139 * - __u8 reserved (v3 only)140 - RFU byte.141 142.. _1:143 144[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5145 146.. _2:147 148[2] Depth Control flags specify which fields are valid: ::149 150 0x00000001 Gain151 0x00000002 Exposure152 0x00000004 Laser power153 0x00000008 AE mode154 0x00000010 Exposure priority155 0x00000020 AE ROI156 0x00000040 Preset157 0x00000080 Emitter mode158 0x00000100 LED Power159 160.. _3:161 162[3] Capture Timing flags specify which fields are valid: ::163 164 0x00000001 Frame counter165 0x00000002 Optical time166 0x00000004 Readout time167 0x00000008 Exposure time168 0x00000010 Frame interval169 0x00000020 Pipe latency170 171.. _4:172 173[4] Configuration flags specify which fields are valid: ::174 175 0x00000001 Hardware type176 0x00000002 SKU ID177 0x00000004 Cookie178 0x00000008 Format179 0x00000010 Width180 0x00000020 Height181 0x00000040 Framerate182 0x00000080 Trigger183 0x00000100 Cal count184 0x00000200 GPIO Input Data185 0x00000400 Sub-preset Info186 187.. _5:188 189[5] Camera model: ::190 191 0 DS5192 1 IVCAM2193 194.. _6:195 196[6] 8-bit camera hardware configuration bitfield: ::197 198 [1:0] depthCamera199 00: no depth200 01: standard depth201 10: wide depth202 11: reserved203 [2] depthIsActive - has a laser projector204 [3] RGB presence205 [4] Inertial Measurement Unit (IMU) presence206 [5] projectorType207 0: HPTG208 1: Princeton209 [6] 0: a projector, 1: an LED210 [7] reserved211 212.. _7:213 214[7] Image format codes per video streaming interface:215 216Depth: ::217 218 1 Z16219 2 Z220 221Left sensor: ::222 223 1 Y8224 2 UYVY225 3 R8L8226 4 Calibration227 5 W10228 229Fish Eye sensor: ::230 231 1 RAW8232 233.. _8:234 235[8] The "Laser mode" has been replaced in version 3 by three different fields.236"Laser" has been renamed to "Emitter" as there are multiple technologies for237camera projectors. As we have another field for "Laser Power" we introduced238"LED Power" for extra emitter.239 240The "Laser mode" __u32 fields has been split into: ::241 1 __u8 Emitter mode242 2 __u8 RFU byte243 3 __u16 LED Power244 245This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward246compatible with the same data format and they are supported. See [2_] for which247attributes are valid.248 249.. _9:250 251[9] LibRealSense SDK metadata source:252https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h253