Experiment metadata

Data created during experiments includes additional information such as the exposure, and gain settings. We can access the Dataset obtained during an experiment from the dataset attribute of the MCAM object.

>>> from owl.instruments import MCAM
>>> mcam = MCAM()
>>> mcam.dataset
<xarray.Dataset>
Dimensions:                                      (image_x: 6, image_y: 9, reflection_illumination.led_number: 377, reflection_illumination.rgb: 3, reflection_illumination.yx: 2, transmission_illumination.led_number: 377, transmission_illumination.rgb: 3, transmission_illumination.yx: 2, x: 4096, y: 3120)
Coordinates:
  * reflection_illumination.led_number           (reflection_illumination.led_number) int64 ...
  * reflection_illumination.rgb                  (reflection_illumination.rgb) object ...
  * transmission_illumination.led_number         (transmission_illumination.led_number) int64 ...
  * transmission_illumination.rgb                (transmission_illumination.rgb) object ...
  * image_x                                      (image_x) int64 0 1 2 3 4 5
  * image_y                                      (image_y) int64 0 1 2 ... 7 8
  * y                                            (y) int64 0 1 2 ... 3118 3119
  * x                                            (x) int64 0 1 2 ... 4094 4095
  * transmission_illumination.yx                 (transmission_illumination.yx) <U1 ...
    transmission_illumination.led_positions      (transmission_illumination.led_number, transmission_illumination.yx) float64 ...
    transmission_illumination.chroma             (transmission_illumination.led_number) <U3 ...
  * reflection_illumination.yx                   (reflection_illumination.yx) <U1 ...
    reflection_illumination.led_positions        (reflection_illumination.led_number, reflection_illumination.yx) float64 ...
    reflection_illumination.chroma               (reflection_illumination.led_number) <U3 ...
    exif_orientation                             int64 8
Data variables:
    images                                       (image_y, image_x, y, x) uint8
    acquisition_count                            (image_y, image_x) int64 0
    trigger                                      (image_y, image_x) int64 0
    exposure                                     (image_y, image_x) float64
    bayer_pattern                                (image_y, image_x) <U4
    software_timestamp                           (image_y, image_x) datetime64[ns]
    digital_red_gain                             (image_y, image_x) float64
    digital_green1_gain                          (image_y, image_x) float64
    digital_blue_gain                            (image_y, image_x) float64
    digital_green2_gain                          (image_y, image_x) float64
    analog_gain                                  (image_y, image_x) float64
    digital_gain                                 (image_y, image_x) float64
    acquisition_index                            (image_y, image_x) int64
    latest_acquisition_index                     int64 0
    z_stage                                      float64 0.0
    transmission_illumination.state              (transmission_illumination.led_number, transmission_illumination.rgb) float64
    reflection_illumination.state                (reflection_illumination.led_number, reflection_illumination.rgb) float64

A few key DataArray’s have been added to the Dataset. Namely, exposure, gain, acquisition_count. The MCAM object only stores the last acquisition.

The pixel data can be directly accessed by accessing the mcam_data DataArray within the dataset:

>>> mcam.dataset['images']
<xarray.DataArray 'images' (image_y: 9, image_x: 6, y: 3120, x: 4096)>
Coordinates:
 * image_x                               (image_x) int64 0 1 2 3 4 5
 * image_y                               (image_y) int64 0 1 2 3 4 5 6 7 8
 * y                                      (y) int64 0 1 2 3 ... 3117 3118 3119
 * x                                      (x) int64 0 1 2 3 ... 4093 4094 4095
   exif_orientation                       int64 8

and contains information pertaining to the location of each pixel on the underlying imaging sensors. To obtain the underlying NumPy array, utilize the data attribute of the returned DataArray.

>>> mcam.dataset['images'].data
array([[[[ 83,  83,  83, ...,  86,  85,  84],
         [ 83,  87,  81, ...,  87,  83,  87],
         [ 81,  87,  83, ...,  85,  86,  85],
         ...,
         [ 87,  85,  87, ...,  84,  85,  85],
         [ 85,  84,  87, ...,  84,  87,  84],
         [ 84,  84,  86, ...,  88,  84,  84]]]], dtype=uint8)

The exposure refers to the exposure setting that was set each of the given cameras. For example, if we acquire a full field of view with an exposure of 100 ms, and an image from a single micro-camera with an exposure of 50 ms, the resulting exposure DataArray would take on the following values:

>>> mcam.exposure = 100E-3
>>> mcam.acquire_full_field_of_view(()
>>> mcam.exposure = 50E-3
>>> mcam.acquire_new_image(index=(3, 2))
>>> mcam.dataset.exposure
<xarray.DataArray 'exposure' (image_y: 9, image_x: 6)>
array([[0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.04998618, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245],
       [0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245, 0.09999245]])
Coordinates:
  * image_x                                     (image_x) int64 0 1 2 3 4 5
  * image_y                                     (image_y) int64 0 1 2 ... 7 8
    exif_orientation                             int64 8

We notice that a new image was acquired for index (5, 1) and that the all the properties associated with that sensor have been updated in the array.

Detailed list of coordinate variables in the MCAM dataset

Name

Datatype

Shape

Description

image_y

int64

(N_cameras_Y,)

The camera index in the Y direction for the particular micro-camera. For the Falcon, this is an array of shape (9,) with a value of values array([0, 1, 2, 3, 4, 5, 6, 7, 8]).

image_x

int64

(N_cameras_X,)

The camera index in the X direction for the particular micro-camera. For the Falcon, this is an array of shape (6,) with a value of values array([0, 1, 2, 3, 4, 5]).

y

int64

(image_shape_y,)

The pixel index in the Y direction within a given micro-camera.

x

int64

(image_shape_x,)

The pixel index in the X direction within a given micro-camera.

exif_orientation

int64

Scalar

Integer describing the EXIF orientation of the MCAM Dataset. Valid values are integers between 1 and 8 inclusively. See exif for more information.

Detailed list of data variables in the MCAM dataset

If an variable has coordinates of

Name

Datatype

Coordinates

Units

Description

images

uint8

(image_y, image_x, y, x)

0-255

The raw pixel data obtained from the array of image sensors.

exposure

float64

(image_y, image_x)

Seconds

The exposure with with each micro-camera captured the last acquisition.

digital_gain

float64

(image_y, image_x)

Scaling factor

The digital gain with which the image was acquired in a particular micro-camera. This number is only valid if the digital gain for all pixel colors is equal.

analog_gain

float64

(image_y, image_x)

Scaling factor

The analog gain with which the image was acquired in a particular micro-camera.

acquisition_count

int64

(image_y, image_x)

Integer

The number of images that have been acquired with the micro-camera.

software_timestamp

datetime64[ns]

(image_y, image_x)

Datetime

The approximate time when the image from a particular micro-camera was taken.

bayer_pattern

<U4

(image_y, image_x)

Bayer Pattern

If the image is that taken with a sensor that contains a color filter array, this contains information about the pixel ordering in the sensor. Valid values are ['rggb', 'gbbr', 'grbg', 'gbrb'].

latest_acquisition_index

int64

None

Integer

The acquisition of the latest set of images acquired at the same time.

digital_gain_red

float64

(image_y, image_x)

Scaling factor

The digital gain for the red pixels with which the image was acquired in a particular micro-camera.

digital_gain_green1

float64

(image_y, image_x)

Scaling factor

The digital gain for the green pixels adjacent to the red ones with which the image was acquired in a particular micro-camera.

digital_gain_blue

float64

(image_y, image_x)

Scaling factor

The digital gain for the blue pixels with which the image was acquired in a particular micro-camera.

digital_gain_green2

float64

(image_y, image_x)

Scaling factor

The digital gain for the green pixels adjacent to the blue ones with which the image was acquired in a particular micro-camera.

System information

Information about the system that acquired the MCAM Dataset is also saved within the dataset itself as part of the dataset coordinates at the time the MCAM object is opened.

The following coordinates are part of each MCAM Dataset.

Name

Datatype

Description

__owl_version__

<U

The version of the owl package at the time of dataset creation.

__sys_version__

<U

The version returned by import sys; sys.version. This corresponds to the version of the python interpreter.

__owl_sys_info__

<U

The string containing the dictionary returned by import owl; owl.sys_info().

__falcon.build_info.version__

<U

The version of the FPGA logic on the Falcon acquisition system.

__falcon.build_info.configuration__

<U

The build configuration of the FPGA logic on the Falcon acquisition system.

__falcon.build_info.branch__

<U

The branch on which the FPGA logic was built at build time.

__falcon.sensor_board.serial_number__

<U

The sensor board serial number.

__falcon.dna__

<U

The FPGA DNA (serial number).

__z_stage.stage_serial_number__

<U

The serial number of the z-stage, if the z-stage is attached to the system.

__z_stage.ftdi_serial_number__

<U

The serial number of the z-stage FTDI controller, if the z-stage is attached to the system.

__transmission_illumination.serial_number__

<U

The serial number of the transmission illumination board, if the board is attached to the system.

__transmission_illumination.version__

<U

The firmware version of the transmission illumination board, if the board is attached to the system.

__transmission_illumination.device_name__

<U

The device name of the transmission illumination board, if the board is attached to the system.

__reflection_illumination.serial_number__

<U

The serial number of the reflection illumination board, if the board is attached to the system.

__reflection_illumination.version__

<U

The firmware version of the reflection illumination board, if the board is attached to the system.

__reflection_illumination.device_name__

<U

The device name of the reflection illumination board, if the board is attached to the system.