MATLAB: Add function bfGetPlaneAtZCT.m and improve range checking for bfGetPlane

[mkitti]

For MATLAB users, it is confusing on how to use bfGetPlane to get a particular plane at a ZCT coordinate. This pull request adds a function bfGetPlaneZCT that handles that exact scenario and all of the 0-indexing to 1-indexing issues per this thread:
https://forum.image.sc/t/ijm-getdataset-crashing-matlab/27210/9

Additionally this adds a function bfTestInRange.m which provides more efficient range checking than using ismember while producing more readable errors.

bfGetPlane range checking for width and height is done only once.

[mkitti]

It appears I should close this in light of #3183

[sbesson]

Hi @mkitti, #3183 was opened within the context of the investigation to migrate the Bio-Formats MATLAB toolbox to its own source code repository. The migration is still incomplete and we have not been able to come back and finish it so far. In addition to merging the latest upstream changes, what would be needed is some review on the packaging and daily CI integration, some testing of the generated artifacts as well as a review of the Bio-Formats documentation and release process. Until then, the decoupled repository has been marked as experimental and the production code is still maintained in this repository. I will close #3183 to avoid confusion.

[sbesson]

On the PR itself, if I understand correctly, the primary benefit of the new range helper method is performance. Do you have a typical number of planes worth using for testing?

About the newly introduced function, I certainly see the benefit of allowing to pass individual z,c,t coordinates rather than linear indices. An alternative implementation would be to keep using the same function name but support both linear indices and triplets in the signature e.g.

bfGetPlane(r, 1);  % Get the first plane
bfGetPlane(r, 1, 1, 1, 1000, 1000); % Get a 1000x1000 tile from the first plane
bfGetPlane(r, [1, 1, 1]); % Get the plane at Z,C,T coordinates (1,1,1)
bfGetPlane(r, [1, 1, 1], 1, 1, 1000, 1000); % Get a 1000x1000 tile from the plane at Z,C,T coordinates (1,1,1)

Do you have particular thoughts about this second option?

[mkitti]

Hi @sbesson,

1. The new helper method also gives user friendly error messages. It separately detects if the error is because the argument is i) not a scalar, ii) not an integer, or iii) not within the range.

>> test = @(x) bfTestInRange(x,'x',500);
>> test([1 2])
Error using bfTestInRange (line 33)
x value, [1  2], is not scalar

Error in @(x)bfTestInRange(x,'x',500)
 
>> test(1.1)
Error using bfTestInRange (line 40)
x value, 1.1, is not an integer

Error in @(x)bfTestInRange(x,'x',500)
 
>> test(501)
Error using bfTestInRange (line 47)
x value, 501, is not between 1 and 500

Error in @(x)bfTestInRange(x,'x',500)

2. The new helper method is faster and has much better scaling properties:
   

3. Modifying the function signature of bfGetPlane to accept zct coordinates would not be a good idea and could lead to cryptic or silent errors. My intuitive thought would be if vector input were acceptable for the plane index then maybe this would deliver planes i, j, and k.

[mkitti]

In thinking about this, vectorizing the plane index would be a really good idea actually. We would just need to loop lines 73 to the end.

I would be willing to take some responsibility for working on the MATLAB interface and splitting it out. Is there anything I should do to get more connected?

[dgault]

Hi @mkitti, our apologies for the delay with this MATLAB issue. We will target this PR for the next Bio-Formats patch release 6.3.1.

We our also looking at various options for ways in which yourself and others can contribute to the MATLAB interface development longer term and will come back to you once we have a better process in place.

[mkitti]

Hi @dgault, no worries regarding the delay. Just let me know what would be useful in either the near or long term. For example, I can see that a diff where bfGetPlane.m is not modified might be easier to accept sooner rather than later.

[mkitti]

For the long term, I am wondering if there should be a more consistent interface across the different languages.

Following clij there is something attractive to having an API that works consistently, to the copy and paste level, across Python, Jython, and MATLAB:

https://twitter.com/haesleinhuepf/status/1187367287973728256

[dgault]

Having carried out some further testing I am happy to go ahead and include the new functions for the release of 6.4.0. This should offer improved behaviour for users without breaking any existing usage.

Longer term we will likely have to come back and relook at updating the API as part of the larger work on the next gen of OME formats as well as looking into ways that make it easier for the community to contribute.

Thanks again @mkitti for your contributions and my apologies of the long delay in getting this included in an official release.