search

nexusformat / definitions

Definitions of the NeXus Standard File Structure and Contents
https://manual.nexusformat.org/
Other
26 stars 55 forks source link

Improve documentation for NXtomo and NXtomophase #1267

Open Gigarrum opened 1 year ago

Gigarrum commented 1 year ago

I will point out some things that I consider that are problems on NXtomo and NXtomophase application definitions so we can discuss and enhance them:

  1. NXtomo and NXtomophase documentation uses different terms for the same thing: While on NXtomo the term flat is used on NXtomophase the term used is bright_field. Considering that one of NeXus objectives is to create a data dictionary for X-ray/Neutron/Muon experimental data, I consider standardizing how flat/bright field is called between application definitions from similar tecniques crucial. If flat and bright are not the same information, documenting what NXtomophase means by bright seems important.

  2. NXtomo and NXtomophase structures detected data in different ways: While on NXtomo flat,dark and projections are stored in the same array in the data field from a NXdetector group, on NXtomophase it is split and stored in the data field from 3 different NXdetector groups. Checking the NXdetector, the NXtomo definitions seems to follow more precisely how NXdetector class defines to save the data, however If both representations are possible and acceptable, should we add new fields to NXdetector group class in order to document this other type of organization for detected data?

  3. NXtomophase defines 3 NXdetector groups inside NXintrument: The problem is that all of them probably refers to the same device making the existance of 3 NXdetectors group incoherent in my opinion. According to NeXus NXDetector base class documentation, that class defines "A detector, detector bank, or multidetector", that said, having 3 NXdetectors named according to the respective data inside it and refering to data acquired from the same device seems a structural problem in the NXtomophase definition. If data requires to be split and stored separately, in my opinion, the correct way would be something like this:

NXinstrument   detector:NXdetector      bright_field NX_INT (Rank: 3, Dimensions: [nBrightFrames, xSize, ySize])      dark_field NX_INT (Rank: 3, Dimensions: [nDarkFrames, xSize, ySize])      data NX_INT (Rank: 4, Dimensions: [nSampleFrames, nPhase, xSize, ySize])

  1. detector flat field and detected flat field ambiguity: The term flat field seems commonly used in tomography to define "data acquired by the detector without beam" and it is also used in by detectors producers to define the correction flat field used. NXdetector class has a field called "flatfield" to store the applied correction flat field and use a magic number in "image_key" field to encode which acquired data is a flat field. This ambiguity may cause confusion. Due to that, is it possible to avoid using the same term for both things but maintaining the usage of terms that tomography specialist uses? (If topic 1 was already discussed and the conclusion is that bright field is a possible technical synonym, maybe it could be used for the "image_key")
phyy-nx commented 1 year ago

Discussion from Code Camp:

  1. NXtomo flat field is different than NXtomophase bright field
  2. NXtomo and NXtomophase data structures derive from differences in what is being collected. NXtomo doesn't include the multiple phases that NXtomophase does
  3. The use of 3 detectors was just the choice of the original application definition designer. It could have been done with one detector and three NXdata objects instead, or by adding more fields as you say.
  4. The NXdetector flatfield is for the simple case where someone is including calibration constants for a detector. The NXtomo image_key with its magic number that indicates what kind of image each frame is in the data includes an option for flat field, but that's a dynamic flat field taken during the experiment.

Thanks @PeterC-DLS for the clarifications.

Philosophy from the Code camp: the ideas in 3. above would be a breaking change for NXtomophase, so regardless of whether they are acceptable, the software that implements reading and writing phase-contrast imaging data would need to know about it. A more gentle change would be additive fields that would for example use only one NXdetector but with three fields representing scans with that detector. Then the documentation could be updated to indicate which fields are now more preferred.

All this said! How can we improve the documentation of NXtomo and NXtomophase so it's more clear for new users of NeXus?