search

Photon-HDF5 / photon-hdf5

Photon-HDF5 Reference Documentation
http://photon-hdf5.readthedocs.io/
3 stars 3 forks source link

PEP: Per-pixel TCSPC info #36

Open tritemio opened 8 years ago

tritemio commented 8 years ago

This is a Photon-HDF5 Enhancement Proposal (PEP). This proposal builds upon PEP #33 (i.e. PEP #33 is required).

Summary

Currently, the TCSPC information (bins duration, number of bins) are fields in nanotimes_specs. The idea is that these are properties of the nanotimes array in the same way the timestamps_unit is a property of the timestamps array. However, in the case in which each detector has a separate TCSPC acquisition chain these properties (e.g. TCSPC bin with) could be different. This can happen in multichannel TCSPC hardware used with SPAD arrays, or when a separate discrete TACs are used for each detector. Admittedly, this is not a very common situation but we have encountered it in our setups.

We need a way to save TCSPC info on a per pixel/detector basis.

Proposal

According to PEP #33, we need a way to save some per pixel (or per detector) parameter. PEP proposes to add detectors groups to the setup group for the purpose. We can add the per-pixel TCSPC info in the detectors groups as well, but only in case it is different between detectors in the same spot.

Reading a file would work as follow. The user check if there is a nanotimes array. If there is it checks if there is a nanotimes_specs group with the TCSPC info. Currently this group is mandatory for a file which contains nanotimes. With this proposal we will keep this group mandatory in all cases where all detectors included the nanotimes array have the same TCSPC parameters (so for the common case nothing changes).

But in cases where different detectors in the same nanotimes array have different TCSPC parameters (e.g. different TCSPC bin width) then we mandate that the nanotimes_specs group to be absent (so a user cannot accidentally load bogus data) and the per-pixel TCSPC info will be placed inside the detectors group (and having this TCSPC info is mandatory).

The names of the nanotimes_specs fields will not change, they will just be moved to the detectors group and only in this specific corner-case when TCSPC parameters are different across detectors.

detectors/
    counts
    ...
    nanotimes_specs/
        tcspc_unit: (array of float) array of TAC/TDC bin size (in seconds).
        tcspc_num_bins: (array of integers) array of number of TAC/TDC bins.

If accepted, this will be part of Photon-HDF5 0.5.

tritemio commented 8 years ago

As always comments are accepted from anybody interested in the Photon-HDF5 format.

tritemio commented 7 years ago

Since /setup/detectors contains arrays (one element per pixel) the nanotimes_specs will not be scalar anymore but arrays. I also propose putting the two fields directly in /setup:

detectors/
    counts
    ...
    tcspc_unit: (array of float) array of TAC/TDC bin size (in seconds).
    tcspc_num_bins: (array of integers) array of number of TAC/TDC bins.
tritemio commented 7 years ago

This feature is now documented in the 0.5 specification draft:

and supported by phconvert ( dev branch).

tritemio commented 7 years ago