253 lines
7.3 KiB
ReStructuredText
253 lines
7.3 KiB
ReStructuredText
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
|
|
|
|
.. _v4l2-meta-fmt-d4xx:
|
|
|
|
*******************************
|
|
V4L2_META_FMT_D4XX ('D4XX')
|
|
*******************************
|
|
|
|
Intel D4xx UVC Cameras Metadata
|
|
|
|
|
|
Description
|
|
===========
|
|
|
|
Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
|
|
payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
|
|
means, that the private D4XX metadata, following the standard UVC header, is
|
|
organised in blocks. D4XX cameras implement several standard block types,
|
|
proposed by Microsoft, and several proprietary ones. Supported standard metadata
|
|
types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
|
|
and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
|
|
document describes proprietary metadata types, used by D4xx cameras.
|
|
|
|
V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
|
|
V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
|
|
payload header data. D4xx cameras use bulk transfers and only send one payload
|
|
per frame, therefore their headers cannot be larger than 255 bytes.
|
|
|
|
This document implements Intel Configuration version 3 [9_].
|
|
|
|
Below are proprietary Microsoft style metadata types, used by D4xx cameras,
|
|
where all fields are in little endian order:
|
|
|
|
.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
|
|
|
|
|
|
.. flat-table:: D4xx metadata
|
|
:widths: 1 2
|
|
:header-rows: 1
|
|
:stub-columns: 0
|
|
|
|
* - **Field**
|
|
- **Description**
|
|
* - :cspan:`1` *Depth Control*
|
|
* - __u32 ID
|
|
- 0x80000000
|
|
* - __u32 Size
|
|
- Size in bytes, include ID (all protocol versions: 60)
|
|
* - __u32 Version
|
|
- Version of this structure. The documentation herein covers versions 1,
|
|
2 and 3. The version number will be incremented when new fields are
|
|
added.
|
|
* - __u32 Flags
|
|
- A bitmask of flags: see [2_] below
|
|
* - __u32 Gain
|
|
- Gain value in internal units, same as the V4L2_CID_GAIN control, used to
|
|
capture the frame
|
|
* - __u32 Exposure
|
|
- Exposure time (in microseconds) used to capture the frame
|
|
* - __u32 Laser power
|
|
- Power of the laser LED 0-360, used for depth measurement
|
|
* - __u32 AE mode
|
|
- 0: manual; 1: automatic exposure
|
|
* - __u32 Exposure priority
|
|
- Exposure priority value: 0 - constant frame rate
|
|
* - __u32 AE ROI left
|
|
- Left border of the AE Region of Interest (all ROI values are in pixels
|
|
and lie between 0 and maximum width or height respectively)
|
|
* - __u32 AE ROI right
|
|
- Right border of the AE Region of Interest
|
|
* - __u32 AE ROI top
|
|
- Top border of the AE Region of Interest
|
|
* - __u32 AE ROI bottom
|
|
- Bottom border of the AE Region of Interest
|
|
* - __u32 Preset
|
|
- Preset selector value, default: 0, unless changed by the user
|
|
* - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
|
|
- 0: off, 1: on, same as __u32 Laser mode for v1
|
|
* - __u8 RFU byte (v3 only)
|
|
- Spare byte for future use
|
|
* - __u16 LED Power (v3 only)
|
|
- Led power value 0-360 (F416 SKU)
|
|
* - :cspan:`1` *Capture Timing*
|
|
* - __u32 ID
|
|
- 0x80000001
|
|
* - __u32 Size
|
|
- Size in bytes, include ID (all protocol versions: 40)
|
|
* - __u32 Version
|
|
- Version of this structure. The documentation herein corresponds to
|
|
version xxx. The version number will be incremented when new fields are
|
|
added.
|
|
* - __u32 Flags
|
|
- A bitmask of flags: see [3_] below
|
|
* - __u32 Frame counter
|
|
- Monotonically increasing counter
|
|
* - __u32 Optical time
|
|
- Time in microseconds from the beginning of a frame till its middle
|
|
* - __u32 Readout time
|
|
- Time, used to read out a frame in microseconds
|
|
* - __u32 Exposure time
|
|
- Frame exposure time in microseconds
|
|
* - __u32 Frame interval
|
|
- In microseconds = 1000000 / framerate
|
|
* - __u32 Pipe latency
|
|
- Time in microseconds from start of frame to data in USB buffer
|
|
* - :cspan:`1` *Configuration*
|
|
* - __u32 ID
|
|
- 0x80000002
|
|
* - __u32 Size
|
|
- Size in bytes, include ID (v1:36, v3:40)
|
|
* - __u32 Version
|
|
- Version of this structure. The documentation herein corresponds to
|
|
version xxx. The version number will be incremented when new fields are
|
|
added.
|
|
* - __u32 Flags
|
|
- A bitmask of flags: see [4_] below
|
|
* - __u8 Hardware type
|
|
- Camera hardware version [5_]
|
|
* - __u8 SKU ID
|
|
- Camera hardware configuration [6_]
|
|
* - __u32 Cookie
|
|
- Internal synchronisation
|
|
* - __u16 Format
|
|
- Image format code [7_]
|
|
* - __u16 Width
|
|
- Width in pixels
|
|
* - __u16 Height
|
|
- Height in pixels
|
|
* - __u16 Framerate
|
|
- Requested frame rate per second
|
|
* - __u16 Trigger
|
|
- Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
|
|
* - __u16 Calibration count (v3 only)
|
|
- Calibration counter, see [4_] below
|
|
* - __u8 GPIO input data (v3 only)
|
|
- GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
|
|
* - __u32 Sub-preset info (v3 only)
|
|
- Sub-preset choice information, see [4_] below
|
|
* - __u8 reserved (v3 only)
|
|
- RFU byte.
|
|
|
|
.. _1:
|
|
|
|
[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
|
|
|
|
.. _2:
|
|
|
|
[2] Depth Control flags specify which fields are valid: ::
|
|
|
|
0x00000001 Gain
|
|
0x00000002 Exposure
|
|
0x00000004 Laser power
|
|
0x00000008 AE mode
|
|
0x00000010 Exposure priority
|
|
0x00000020 AE ROI
|
|
0x00000040 Preset
|
|
0x00000080 Emitter mode
|
|
0x00000100 LED Power
|
|
|
|
.. _3:
|
|
|
|
[3] Capture Timing flags specify which fields are valid: ::
|
|
|
|
0x00000001 Frame counter
|
|
0x00000002 Optical time
|
|
0x00000004 Readout time
|
|
0x00000008 Exposure time
|
|
0x00000010 Frame interval
|
|
0x00000020 Pipe latency
|
|
|
|
.. _4:
|
|
|
|
[4] Configuration flags specify which fields are valid: ::
|
|
|
|
0x00000001 Hardware type
|
|
0x00000002 SKU ID
|
|
0x00000004 Cookie
|
|
0x00000008 Format
|
|
0x00000010 Width
|
|
0x00000020 Height
|
|
0x00000040 Framerate
|
|
0x00000080 Trigger
|
|
0x00000100 Cal count
|
|
0x00000200 GPIO Input Data
|
|
0x00000400 Sub-preset Info
|
|
|
|
.. _5:
|
|
|
|
[5] Camera model: ::
|
|
|
|
0 DS5
|
|
1 IVCAM2
|
|
|
|
.. _6:
|
|
|
|
[6] 8-bit camera hardware configuration bitfield: ::
|
|
|
|
[1:0] depthCamera
|
|
00: no depth
|
|
01: standard depth
|
|
10: wide depth
|
|
11: reserved
|
|
[2] depthIsActive - has a laser projector
|
|
[3] RGB presence
|
|
[4] Inertial Measurement Unit (IMU) presence
|
|
[5] projectorType
|
|
0: HPTG
|
|
1: Princeton
|
|
[6] 0: a projector, 1: an LED
|
|
[7] reserved
|
|
|
|
.. _7:
|
|
|
|
[7] Image format codes per video streaming interface:
|
|
|
|
Depth: ::
|
|
|
|
1 Z16
|
|
2 Z
|
|
|
|
Left sensor: ::
|
|
|
|
1 Y8
|
|
2 UYVY
|
|
3 R8L8
|
|
4 Calibration
|
|
5 W10
|
|
|
|
Fish Eye sensor: ::
|
|
|
|
1 RAW8
|
|
|
|
.. _8:
|
|
|
|
[8] The "Laser mode" has been replaced in version 3 by three different fields.
|
|
"Laser" has been renamed to "Emitter" as there are multiple technologies for
|
|
camera projectors. As we have another field for "Laser Power" we introduced
|
|
"LED Power" for extra emitter.
|
|
|
|
The "Laser mode" __u32 fiels has been split into: ::
|
|
1 __u8 Emitter mode
|
|
2 __u8 RFU byte
|
|
3 __u16 LED Power
|
|
|
|
This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward
|
|
compatible with the same data format and they are supported. See [2_] for which
|
|
attributes are valid.
|
|
|
|
.. _9:
|
|
|
|
[9] LibRealSense SDK metadata source:
|
|
https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h
|