|
1 | | -# Synchronous Data Stream - File Format |
| 1 | +# Schema and Templates Files |
2 | 2 |
|
3 | | -The **SDS Framework** uses a binary data file format to store the individual data streams. It supports the recording and playback of multiple data streams that may have jitters. Therefore each stream contains timeslot information that allows to correlate the data streams as it is for example required in a sensor fusion application. |
| 3 | +This folder contains: |
4 | 4 |
|
5 | | -The binary data format (stored in `*.<n>.sds` data files) has a record structure with a variable size. Each record has the following format: |
| 5 | +## Schema for SDS Metadata file |
6 | 6 |
|
7 | | -1. **timeslot**: record timeslot in tick-frequency (32-bit unsigned integer, little endian) |
8 | | -2. **data size**: number of data bytes in the record (32-bit unsigned integer, little endian) |
9 | | -3. **binary data**: SDS stream (little endian, no padding) as described with the `*.sds.yml` file. |
| 7 | +- Schema description [`sds.schema.json`](sds.schema.json) for SDS Metadata files. |
| 8 | +- [Audio format](./audio_format/) metadata file templates. |
| 9 | +- [Image format](./image_format/) metadata file templates |
10 | 10 |
|
11 | | -The content of each data stream is described in a [YAML](https://en.wikipedia.org/wiki/YAML) metadata file that is created by the user. |
| 11 | +See [SDS-Framework - Theory of Operation - SDS Metadata Format](https://arm-software.github.io/SDS-Framework/main/theory.html#sds-metadata-format) for detailed description. |
12 | 12 |
|
13 | | -## YAML Format |
| 13 | +## Schema for SDSIO Control file |
14 | 14 |
|
15 | | -The following section defines the YAML format of this metadata file. The file `sds.schema.json` is a schema description of the SDS Format Description. |
| 15 | +- Schema description [`sdsio.schema.json`](sdsio.schema.json) for SDS Metadata files. |
16 | 16 |
|
17 | | -`sds:` | Start of the SDS Format Description |
18 | | -:------------------------------------|--------------------------------------------------- |
19 | | - `name:` | Name of the Synchronous Data Stream (SDS) |
20 | | - `description:` | Additional descriptive text (optional) |
21 | | - `frequency:` | Capture frequency of the SDS |
22 | | - `tick-frequency:` | Tick frequency of the timeslot value (optional); default: 1000 for 1 millisecond interval |
23 | | - `content:` | List of values captured (see below) |
24 | | - |
25 | | -`content:` | List of values captured (in the order of the data file) |
26 | | -:------------------------------------|--------------------------------------------------- |
27 | | -`- value:` | Name of the value |
28 | | - `type:` | Data type of the value |
29 | | - `offset:` | Offset of the value (optional); default: 0 |
30 | | - `scale:` | Scale factor of the value (optional); default: 1.0 |
31 | | - `unit:` | Physical unit of the value (optional); default: no units |
32 | | - `image:` | Image format metadata (optional) |
33 | | - |
34 | | -### Image Format Metadata Fields |
35 | | - |
36 | | -The `image` fields provide metadata for image data captured in the SDS stream. When a content item represents image data, `image` describes the format, dimensions, and memory layout. |
37 | | - |
38 | | -`image:` | Image stream metadata (all fields required except where noted) |
39 | | -:------------------------------------|--------------------------------------------------- |
40 | | - `pixel_format:` | Pixel format identifier (enum) |
41 | | - `width:` | Number of pixels per row (integer, minimum: 1) |
42 | | - `height:` | Number of rows (integer, minimum: 1) |
43 | | - `stride_bytes:` | Bytes per row for single-plane formats (required for single-plane) |
44 | | - `planes:` | Per-plane stride array for multi-plane formats (required for multi-plane) |
45 | | - |
46 | | -The `pixel_format` field accepts the following identifiers: |
47 | | - |
48 | | -- **Single-plane formats**: `RAW8`, `RAW10`, `RGB565`, `RGB888`, `YUYV`, `UYVY` |
49 | | -- **Multi-plane formats**: `NV12`, `NV21`, `I420`, `NV16`, `NV61`, `YUV422P`, `YUV444`, `YUV444P` |
50 | | - |
51 | | -## Examples |
52 | | - |
53 | | -### Sensor Data Stream |
54 | | - |
55 | | -This example defines a data stream with the name "sensorX" that contains the values of a gyroscope, temperature sensor, and additional raw data (that are not further described). |
56 | | - |
57 | | - |
58 | | - |
59 | | -The binary data that are coming form this sensors are stored in data files with the following file format: `<sensor-name>.<file-index>.sds`. In this example the files names could be: |
60 | | - |
61 | | -```yml |
62 | | - sensorX.0.sds # capture 0 |
63 | | - sensorX.1.sds # capture 1 |
64 | | -``` |
65 | | - |
66 | | -The following `sensorX.sds.yml` provides the format description of the SDS `sensorX` binary data files and maybe used by data conversion utilities and data viewers. |
67 | | - |
68 | | -```yml |
69 | | -sds: # describes a synchronous data stream |
70 | | - name: sensorX # user defined name |
71 | | - description: Gyroscope stream with 1KHz, plus additional user data |
72 | | - frequency: 1000 |
73 | | - content: |
74 | | - - value: x # Value name is 'x' |
75 | | - type: uint16_t # stored using a 16-bit unsigned int |
76 | | - scale: 0.2 # value is scaled by 0.2 |
77 | | - unit: dps # base unit of the value |
78 | | - - value: y |
79 | | - type: uint16_t |
80 | | - scale: 0.2 |
81 | | - unit: dps |
82 | | - - value: z |
83 | | - type: uint16_t |
84 | | - unit: dps # scale 1.0 is default |
85 | | - - value: temp |
86 | | - type: float |
87 | | - unit: degree Celsius |
88 | | - - value: raw |
89 | | - type: uint16_t # raw data, no scale or unit given |
90 | | - - value: flag |
91 | | - type: uint32_t:1 # a single bit stored in a 32-bit int |
92 | | -``` |
93 | | -
|
94 | | -### Video Frame Stream |
95 | | -
|
96 | | -This example shows a video stream capturing RGB888 frames at 30 Hz. Each frame is 640x480 pixels with 3 bytes per pixel (RGB), requiring a stride of 1920 bytes per row. |
97 | | -
|
98 | | -```yml |
99 | | -sds: |
100 | | - name: Camera stream |
101 | | - description: RGB888 video capture at 30 fps |
102 | | - frequency: 30 |
103 | | - content: |
104 | | - - value: frame |
105 | | - type: uint8_t |
106 | | - image: |
107 | | - pixel_format: RGB888 |
108 | | - width: 640 |
109 | | - height: 480 |
110 | | - stride_bytes: 1920 # 640 pixels * 3 bytes/pixel |
111 | | -``` |
| 17 | +See [SDS-Framework - Utilities - SDSIO Control File](https://arm-software.github.io/SDS-Framework/main/utilities.html#sdsio-control-file-sdsioyml) for detailed description. |
0 commit comments