To standardize image transfer between camera streaming applications and image-driven applications, the following format shall be used for transferring images. The ZMQ message consists of a multipart message with each frame/part described below.
This message format is prepared to support multiple stream cameras.
Message Envelope
| Frame | Field | Description | Type |
|---|---|---|---|
| 1 | topic | Device identification. | Binary String (UTF-8) to identify the device in the following syntax: {DeviceID}/stream |
| 2 | metadata | Metadata | Binary Metadata JSON (UTF-8) |
| 3 | image | Image 1 | Binary |
| 4 ... n | image | Image n – For multi-stream camera | Binary |
Metadata JSON
| Field | Optional | Type | Default | Description |
|---|---|---|---|---|
| version | No | String | 1 | Metadata format version |
| count | No | Integer | 1 | Number of images on message |
| timestamp | No | String | - | Date and Time string UTF-8 ISO8601. Application host datetime. |
| customfields | Yes | String | - | Custom field to be defined by the app creator and handled by the consumers. Might be a simple string or JSON string or else. |
| detail | No | Image Detail Object Array | - | Images details |
Image Detail Object
| Field | Optional | Type | Default | Description |
|---|---|---|---|---|
| id | No | String | - | Unique image identifier. Suggested mnemonic format like {camid}_{camstream}_{datetime} |
| seq | No | Integer | - | Sequential number for the camera image. Starting at 1, incremented by 1 on each frame grabbed. |
| height | No / Yes (encoded formats) | Integer | - | Image Height |
| width | No / Yes (encoded formats) | Integer | - | Image Width |
| formatns | Yes | String | Genicam | Image format namespace. For genicam pixelformat use Genicam and Compressed for compressed formats. 2 |
| format | No | String | - | Image format 1 2 3 |
| linepadding | Yes | Integer | 0 | Number of bytes added on the end of byte stream to reach a multiple of 4 bytes. Eg. an image with 61 pixels, mono8, will have a linepadding of 3, filling the stream to reach 64 bytes. |
| timestamp | Yes | String5 | - | Clock ticks informed by the camera.4 |
| metadata6 | Yes | String | - | Image additional metadata field to be defined by the app creator and handled by the consumers. Might be a simple string or JSON string or else. |
1 For cameras using a Genicam standardized Pixel Format, it is recommended to use the Genicam Naming Convention as described in section 4.35 GenICam_PFNC_2_4.pdf.
2 Additional values can be supported once described in the application documentation.
3 Compressed formats shall be mentioned in the application documentation, being recommended in the fields corresponding to the file extension (e.g., "png", "jpg", "bmp").
4 Timestamp provided by the cameras are Ticks count. This can be referencing the Unix epoch or the number of Ticks since the camera is on or count of Ticks informed/in sync with the PTP server.
5 A string might be used since, in the PTP standard, the Tick count is expected to be an 80-bit number. However, the current Genicam protocol returns a 64-bit integer. A string will be more reliable for future implementations.
6 Cameras capable and with PTP enabled must inform the PTP synchronization status in the metadata. E.g.,
…
"metadata": "{'ptpstatus': 'locked'}"
…
Metadata Example:
{
"version": "1",
"count": 2,
"timestamp": "2014-01-09T13:35:34.000000000+0100",
"customfields": "{'xfield1':1,'xfield2':'abc'}",
"detail":[
{
"id":"mycamera_0_2014-01-09T13:35:34.000000000+0100",
"seq": 3,
"height": 60,
"width": 80,
"format": "png",
"formatns": "Compressed",
"timestamp": "123456",
"metadata": "{'batchid':'batch1','stream':'lowdef'}"
},
{
"id":"mycamera_1_2014-01-09T13:35:34.000000000+0100",
"seq": 3,
"height": 852,
"width": 1280,
"formatns": "Genicam",
"format": "BGR8",
"timestamp": "123456",
"linepadding": 0,
"metadata": "{'batchid':'batch1','stream':'raw'}"
}
]
}