Re: [gsoc] Discuss thresholding API design

From: Stefan Seefeld (stefan_at_[hidden])
Date: 2019-05-30 00:05:57

On 2019-05-29 7:15 a.m., Mateusz Loskot wrote:

> Hi,
>
> Miral and I, we have been brainstorming on what would be a clear yet
> optimal interface for the thresholding, on Gitter and comments at
> https://github.com/BoostGSoC19/gil-miral/pull/1
>
> This made me think the issue of interface design for new algorithms is 
> more general,
> not just specific to the thresholding. I think it may be worth to set 
> some common
> guidelines, to tune ourselves w.r.t. interface design in the direction 
> that may be
> preferred in GIL.

While I think I understand your concern (and mostly agree), I'm not sure 
it's useful or even possible to provide general guidelines. Designing 
good APIs is hard, requires domain knowledge and almost always involves 
judgment calls.

But we can try... :-)

> ### Problem Example
>
> For instance, OpenCV takes approach of single function to 'kill'em 
> all', i.e.
> cv::threshold, that takes multiple parameters where combination of 
> values and
> flags is significant
> https://docs.opencv.org/4.1.0/d7/d1b/group__imgproc__misc.html#gae8a4a146d1ca78c626a53577199e9c57 
>
>
> In this approach documentation is crucial to explain what combination 
> is valid,
> when `maxval` is used (e.g. with THRESH_BINARY) and when ignored.

Yeah, I agree this is not a good design. :-)

For once, the abstraction seems more harm- than useful. In addition to 
the special-casing of what parameter combinations are valid, I'd reason 
that some of the functions are in fact doing something else. For 
example, I'm having a hard time understanding the concept behind the 
"INV" variants. Shouldn't that be a separate operation ? Why is 
inversion mixed into the thresholding to begin with ? Is that such a 
common combination ?

Sometimes the rationale to combine multiple "variants" into a single 
call is that the implementations share a lot of code. In that case it 
might be better to put a common _impl function into some `detail` 
namespace and then call that from different frontend functions with 
suitable parameters.

A different point is about runtime- vs. compile-time parameters. Both 
are possible, and which to choose may depend on typical usage, as well 
as implementation techniques.

I agree with you that for the example you chose, distinct functions will 
actually make the API more readable.

(And for the record: I also agree that the mailing list is a better fit 
for such design discussions than a gitter or other channel)

Best,

Stefan
-- 
       ...ich hab' noch einen Koffer in Berlin...