[gsoc2020] Answer to histogram design questions from Slack

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2020-05-12 13:05:33

Debabrata,

Om the Slack, you asked some good questions about the interfaces for
histogram routines. I decided to collect and copy them from the Slack
here to the mailing list as I find it too easy to miss things from
Slack archives which are not as well structured as the mailing list.

Debabrata wrote on Slack:
> I have a question regarding the histogram functionality to be provided.
> Should we it provide as a template class or a template function?

As you already know, the question is not that simple :)

> I know we had this discussion sometime ago and had suggested using a function
> based approach, but there are some issues we might have missed. Some them
> would be bin overflow for the desired container class, handling signed pixel
> values etc. but all these ofc have workarounds, which I am not sure would be
> ergonomic enough.
>
> (...) the approach of making a template function for the histogram calculation.
> Second I thought about that approach
> for some time , and although it is surely a neater idea , one thing that
> bothers me is that maybe we are putting a lot of expectations from the user,
> in the sense that he has to now think of appropriate containers to call the
> functions, for e.g. if we wanted to calculate 2d histogram of RGB image, we
> need maybe a container of tuples now for one of the axis etc. I am not sure if
> this is a valid design issue , but I would like to get some insights on this
> if possible.

First, I'd consider a question:
do we need to decide on histogram container design at this point?
See below.

> This is what I came up with after considering both the pros and cons.
> Any comments, suggestions and criticisms are most welcome.
> Simplest usage syntax:
> - imgHist(srcview,hist);
> Full Usage syntax:
> - imgHist(srcview,hist,channels,range,colormap,sparsefill,accumulate);

It is possible the variety of parameters will increase even more.
It may be necessary or it may not, but I would argue it is quite early
to see the complete picture of all combinations at this point;
to know exactly what we need from a histogram container.

It may be easier if we shift focus from designing interface of histogram
to working on histogram calculations, for now.
It may be easier to just define a histogram using Boost.Histogram
and use it as in/out parameter of (or return it from) functions.

I'd consider:
- introduce Boost.Histogram as a temporary requirement.
- use it as a container to output/transfer histograms from/in GIL.

Based on such experience, I think, it will be easier to observe GIL specific
requirements for histogram container(s) and how to shape a more generic
interface of functions operating on histogram. We may decide a standard
container of numbers or tuples is enough or we need a basic histogram
class, etc.

Finally, Boost.Histogram is moved to an optional dependency of GIL.

I think piggyback ride on the Boost.Histogram, temporarily while focusing on
calculations and algorithms, will save time and make it easier to understand
what uses of histogram we need, and what kind of container we need.

Debabrata, Pranam, others, what do you think?

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net