HDF5 file format

The data of a qpimage.QPImage or qpimage.QPSeries can be stored on disk, using the h5file parameter upon class instantiation. This section describes the scheme used to store the data using the HDF5 file format.


The following graph visualized the HDF5 file structure of a QPImage instance:

graph example {
    graph [rankdir=LR];
    QPImage [shape="folder", label="/"];
    amplitude [shape="folder"];
    phase [shape="folder"];
    raw [shape="component"];
    bg_data [shape="folder"];
    data [shape="component"];
    fit [shape="component"];
    "..." [shape="box"];
    "estimate_bg_from_mask" [shape="component"];
    QPImage -- amplitude;
    QPImage -- phase;
    amplitude -- raw;
    amplitude -- bg_data;
    bg_data -- data;
    bg_data -- fit;
    bg_data -- "estimate_bg_from_mask";
    phase -- "...";


These attributes of the root group (/) describe physical parameters of the data:

key description
medium index refractive index of the medium
pixel size detector pixel size [m]
time acquisition time of the image [s]
wavelength imaging wavelength [m]

These other attributes may be used by e.g. data simulators such as qpsphere or cellsino:

key description
identifier image identifier
qpimage version qpimage software version used
sim center Simulation: center of object [px]
sim index Simulation: refractive index of object
sim model Simulation: model used
sim radius Simulation: object radius [m]


Both groups, amplitude and phase, do not hold attributes. Each of the groups contain a dataset called raw (the raw image, by default stored as 32bit floating point values) and a group called bg_data which contains information about background correction. If background correction was used, then the bg_data group may contain the following datasets:

  • data: simple background image
  • fit: fitted background image; has the additional attributes fit_offset, fit_profile, and border_px (see qpimage.core.QPImage.compute_bg() for possible values)
  • estimate_bg_from_mask: binary mask image that defines regions in raw that resemble background data; used for background fitting

All of these datasets have the same shape as raw. The data and fit datasets form the background data that are internally removed from the raw data when requesting the QPImage.amp or QPImage.pha properties.


The following graph visualized the HDF5 file structure of a QPSeries instance (with a total of 48 QPImages):

graph example {
    node [shape="folder"];
    graph [rankdir=LR, center=1];
    QPSeries [label="/"]
    qp1 [label="qpi_1"]
    qp2 [label="qpi_2"]
    a1 [shape="box", label=ampltitude];
    a2 [shape="box", label=phase];
    d0 [shape="box", label="..."];
    d1 [shape="box", label="..."];
    d2 [shape="box", label="..."];
    d3 [shape="box", label="..."];
    d4 [shape="box", label="..."];
    qp3 [label="qpi_47"]
    QPSeries -- qp1;
    qp1 -- a1;
    qp1 -- a2;
    a1 -- d0;
    a2 -- d1;
    QPSeries -- qp2;
    qp2 -- d2;
    QPSeries -- d4;
    QPSeries -- qp3;
    qp3 -- d3;

Note that the name of each QPImage group always starts with “qpi_” and that the enumeration does not contain leading zeros. The root node (/) of a QPSeries may have the identifier attribute.