Add reader for hamamatsu .img format

[pietsjoh]

Add support for reading Hamamatsu's .img file format.

Progress of the PR

• basic parsing of the file
• map metadata
• add tests,
• update docstring (if appropriate),
• add an changelog entry in the upcoming_changes folder (see upcoming_changes/README.rst),
• Check formatting changelog entry in the readthedocs doc build of this PR (link in github checks)
• cover different acquisition modes with testfiles
• reproduce plots
• update tests after problem fix
• ready for review.

Minimal example of the bug fix or the new feature

from rsciio.hamatsu import file_reader
file_reader("file.img", reader="Hamamatsu")

[codecov]

Codecov Report

Patch coverage: 85.54% and project coverage change: +0.18% 🎉

Comparison is base (9d0f04f) 83.75% compared to head (73cd7d6) 83.94%.
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #87      +/-   ##
==========================================
+ Coverage   83.75%   83.94%   +0.18%     
==========================================
  Files          74       76       +2     
  Lines        9800    10132     +332     
  Branches     2163     2210      +47     
==========================================
+ Hits         8208     8505     +297     
- Misses       1097     1114      +17     
- Partials      495      513      +18     

Files Changed	Coverage Δ
rsciio/hamamatsu/_api.py	85.36% <85.36%> (ø)
rsciio/hamamatsu/__init__.py	100.00% <100.00%> (ø)

... and 13 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jlaehne]

@Attolight-NTappy and @gkusch - I know you are happy using the tiff import of Hamamatsu Streak images, but maybe you could also have a look at this reader for the Hamamatsu format?

[gkusch]

I will try to export a Streak in the Format next time I am at the microscope and compare with .tiff Currently measurements done with the Attolight Software controlling the Streak will be autosaved as .tiff so not super relevant for us in general. Are there any inherent advantages of this format vs tif or is it more a matter of providing choice?

[jlaehne]

I will try to export a Streak in the Format next time I am at the microscope and compare with .tiff Currently measurements done with the Attolight Software controlling the Streak will be autosaved as .tiff so not super relevant for us in general. Are there any inherent advantages of this format vs tif or is it more a matter of providing choice?

According to the Hamamatsu specs, img supports 32 bit data, while their tif export supports only 16 bit data.
See https://github.com/bigphatjan/itex2ascii/blob/master/HiPicFileFormat.pdf

Both readers do read in the original_metadata. The one for img already maps some information to metadata.

But I'm curious what your comparison would give.

[pietsjoh]

While reproducing plots, I discovered some problems. I didn't put much thought into reading the data block, because I thought it was just a block of continuous data. Hopefully, changing the endianness fixes the problem. But the plot still slightly differs compared to the original from a matlab script (which performs multiple steps). I will further check this and try to reproduce it exactly.

[pietsjoh]

While reproducing plots, I discovered some problems. I didn't put much thought into reading the data block, because I thought it was just a block of continuous data. Hopefully, changing the endianness fixes the problem. But the plot still slightly differs compared to the original from a matlab script (which performs multiple steps). I will further check this and try to reproduce it exactly.

The problem is fixed now.

[jlaehne]

Indeed, the data looks good now. I compared a real dataset for which I have both the .img and .tif files.

[jlaehne]

According to the Hamamatsu specs, img supports 32 bit data, while their tif export supports only 16 bit data.
See https://github.com/bigphatjan/itex2ascii/blob/master/HiPicFileFormat.pdf

We should include this format documentation in the documentation under File Specifications for later reference.

[jlaehne]

Add to index.rst

[pietsjoh]

It is added in docs/supported_formats/index.rst.

[jlaehne]

Add use_uniform_signal_axis parameter, e.g. by copying the docstring from jobin-yvon (or by adding it to _docstrings)

[pietsjoh]

I copied it for now and will do a follow up PR, where I add this to _docstrings and move the signal axis fit to utils.