Add pixel bitdepth to START message

[sdebionne]

With Stream2, is there a way to get the pixel bitdepth on the receiver side (after sending arm to the detector)? AFAIKT, this information is not available in the start message and I would suggest that it is added. Or is there a way to infer this information from other parameters?

[diego-gaemperle]

Hi @sdebionne
May I ask you to provide us with your use case for the bit depth? Generally, we could just add the information we already provide with the SIMPLON API or the one that can be found in the image message / data (data_type). However, I think it's more useful to understand what you need and why to improve our interface or to come up with ideas to generically solve the issue.

In the SIMPLON API you can get the value using:

• /detector/config/bit_depth_image

Thanks Diego

[sdebionne]

Hi @diego-gaemperle, our acquisition system is distributed with multiple processes running on different computers. In the system, one single process is responsible of the control (and talk to the SIMPLON API) while the others are STREAM2 receivers.
On the receiver side, we get pretty much all the information we need about the data we are about to collect in the START message, without calling the SIMPLON API, but the bitdepth. We get the bitdepth (as elem_size) in the IMAGE message but that is too late to prepare the processing/saving as the acquisition has already started.

The general idea is that the receiver should be autonomous and not need to call SIMPLON to handle / process the data.

Hoping that makes sense...

[sdebionne]

Or maybe that is a use case for the user_data field?

[kalcutter]

@sdebionne yes, the user_data field could be used for this.

[diego-gaemperle]

We will discuss this internally, but I think it's reasonable to add this information to the start message.

For the time being, I would suggest using user_data to store this information in the start message.

[sdebionne]

It looks like the current implementation does not parse the user_data:

struct stream2_start_msg
{
    enum stream2_msg_type type;
    uint64_t series_id;
    char* series_unique_id;

    char* arm_date;
    double beam_center_x;
    double beam_center_y;
    struct stream2_array_text_string channels;
    double count_time;
    bool countrate_correction_enabled;
    struct stream2_typed_array countrate_correction_lookup_table;
    char* detector_description;
    char* detector_serial_number;
    double detector_translation[3];
    struct stream2_flatfield_map flatfield;
    bool flatfield_enabled;
    double frame_time;
    struct stream2_goniometer goniometer;
    uint64_t image_size_x;
    uint64_t image_size_y;
    double incident_energy;
    double incident_wavelength;
    uint64_t number_of_images;
    struct stream2_pixel_mask_map pixel_mask;
    bool pixel_mask_enabled;
    double pixel_size_x;
    double pixel_size_y;
    uint64_t saturation_value;
    char* sensor_material;
    double sensor_thickness;
    struct stream2_threshold_energy_map threshold_energy;
    bool virtual_pixel_interpolation_enabled;
};

Or shall I look somewhere else?

[sdebionne]

Shall I assume that user_data stands right after the struct?

unsigned char* user_data = ((unsigned char*) msg) + sizeof(stream2_start_msg);

What about padding?

[sdebionne]

On the SIMPLON side, when I try to set the config of the stream API with user_data, I get:

PUT /stream/api/1.8.0/config HTTP/1.1
Content-Type: application/json
Content-Length: 89

{"mode":{"value":"enabled"},"format":{"value":"cbor"},"user_data":{"bit_depth_image":32}}

HTTP/1.1 404 Not Found
date: Wed, 22 Feb 2023 16:04:05 GMT
content-length: 32
content-type: text/plain; charset=utf-8

error during request: path error

It looks like the parameters can not be set individually (e.g. PUT .../config/format)?

I would be grateful if you could provide an example how to use the user_data with Stream2...

[kalcutter]

To set user_data just set the "header_appendix" or "image_appendix" as in stream V1:

    requests.put(
        f"http://{DCU_IP}/stream/api/1.8.0/config",
        data=json.dumps(
            {
                "header_appendix": {"value": {"bit_depth_image": 32}}
            }
        ),
    ).raise_for_status()

[kalcutter]

The C example currently doesn't parse user_data at all.

[kalcutter]

@sdebionne I have implemented the user_data field here: https://github.com/kalcutter/dectris-documentation/commits/stream2-user_data.

This branch adds user_data field parsing to stream2.c and generic printing to example.c. The field is represented by a new stream2_user_data struct which is a pointer and length into the original CBOR buffer. You will need to parse the user_data CBOR bytes yourself (e.g. using tinycbor) according to your exact needs and fields you expect. example.c shows how to use tinycbor to print the user_data CBOR to stdout.

[GDYendell]

Just to confirm, header_appendix appears as user_data on the start message and image_appendix appears as user_data on the image messages?

[kalcutter]

Just to confirm, header_appendix appears as user_data on the start message and image_appendix appears as user_data on the image messages?

Correct.

[sdebionne]

@kalcutter I try your implementation of the user_data but I am not sure what I am supposed to get in stream2_user_data? A JSON string A CborValue?

With "header_appendix": {"value": {"bit_depth_image": 32}}, I get 19 bytes :

a1 6f 62 69 74 5f 64 65 70 74 68 5f 69 6d 61 67 65 18 20 00  ¡obit_depth_image. .

[kalcutter]

@sdebionne Yes its CBOR. You will need to parse the CBOR bytes yourself (e.g. using tinycbor). See my comment above.

To see the cbor structure you can also visualize it here (e.g. in paste your hex bytes):
https://cbor.me/?bytes=a1%206f%2062%2069%2074%205f%2064%2065%2070%2074%2068%205f%2069%206d%2061%2067%2065%2018%2020%2000