Add histogram class and related functionality

[codejaeger]

Description

This contains the initial implementation of histogram functionality for STL containers for GIL images. Basic tests checking for correctness of histogram have been provided. Usage syntax and distinction between compatible and incompatible containers have been illustrated in a example file.

There was some dicussion regarding the name of the function (which now is image_histogram) in the mailing thread (link). I chose on 'image_histogram' since the name 'histogram' is used as the class name in Boost.Histogram and might cause problems in namespace mix-up. Another option could be histogram_1d since these functions are meant for that purpose.

Dependency

Optional - Docs for the this implementation are running in a parallel PR #503.

References

Discussions on boost-gil mailing threads.

Tasklist

• Add test case(s)
• Provide documentation
• Ensure all CI builds pass - R.I.P. Travis CI
• Review and approve

[lpranam]

I have some objections with the code format(template parameters) I don't find the really appealing to the eyes but I maybe wrong. @mloskot what are your suggestions on it!

[codejaeger]

I have ideas I would like to share further on the current approach.
I added a diagram to explain better

This approach might ease extending the implementation design in the future to support both multi dimensional histograms and external containers.
In brief, I chose this approach because

• it will simplify the usage for the end user (just deal with the simple function call syntax)
• handle cases like when a call is made to histogram_2d with a specific container type but the image provided is gray scale so the underlying implementation should call histogram_1d_impl
• simplify providing extensions of other container types, at most they need to replicate the procedure if not use the already present implementation

So basically the first overloads make sure appropriate type checks are performed on both image and container type. The second overload would choose to call the overload specific to the requirements and the third overload can be easily extended to support higher dimensional containers (of any type).
I would like to know if this seems right or there will be some unwanted implications of using this approach.

[mloskot]

@codejaeger I'm reviewing this PR, but please feel free to apply any changes you need.

---

@codejaeger A bit of update to my comment:

The example/histogram.cpp is a bit too hard to follow. An example is supposed to be a minimum sample of code that presents how to use a feature.
I'd suggest the following approach:

1. You've implemented histogram class and computation of histogram, then add sample of code how to define, construct and compute histogram.
2. You've added histogram equalization, then, in that example/histogram.cpp, show how to use it.
3. ...

Finally, for the example, I'd suggest to stick to the 1D histogram and grayscale image.
You can always add shadow file example/histogram_color.cpp with equivalent for colour (e.g. RGB) image.

---

@lpranam What's your take on this PR, I recall you had objections to some of the design choices. Please, forgive me that I had not reacted to that discussion in timely manner and that I can't remember exactly what was that about.

[codejaeger]

@codejaeger I'm reviewing this PR, but please feel free to apply any changes you need.

@codejaeger A bit of update to my comment:

The example/histogram.cpp is a bit too hard to follow. An example is supposed to be a minimum sample of code that presents how to use a feature.

@mloskot I agree it is difficult enough to read for anyone. The file started as an example and became more of a test in the later revisions. I will update it at once. I could also add block comments to separate out different sections of implementations (like create a histogram, fill it etc.).

Although I don't expect anyone to come to this file for reference since I aim to make the docs self sufficient, I will make the changes required. Thanks for the suggestion.

[mloskot]

@codejaeger

The file started as an example and became more of a test in the later revisions.

Yes, that is quite common approach.

Although I don't expect anyone to come to this file for reference since I aim to make the docs self sufficient, I will make the changes required.

What you can do is to use the file to combine the snippets from the docs, so you can be sure they compile.

Ideally, if the examples in the docs are self-contained and are compile-tested when the docs are built, but I don't know how to achieve it in Sphinx. That is one of reasons why we may consider switch to AsciiDoc as some point in future

[codejaeger]

@mloskot , @lpranam I have

1. updated the example file for histogram
2. reduced the warnings from the tests and example
3. Added Doxygen comments for the new changes
   Unless the CI checks fail it is ready for review now.

[mloskot]

@codejaeger Thanks for the update.

Something is wrong with the histogram example, see https://ci.appveyor.com/project/stefanseefeld/gil/builds/34407783/job/fw3u0ba7yno9rdui

The last build job of AppVeyor is CMake-based which builds examples too.

[codejaeger]

Thanks @mloskot for pointing out the bug. I hope it gets fixed with the last commit.

[mloskot]

I don't have any major issues to report about this PR, so I'm happy to approve it.
The only 'unresolved' comments are about the x<space><space>=<space>y formatting due to use of the clang-format and pointed out by @lpranam which I'd consider not a stopper issue that can be addressed after the merge along with other updates or improvements that are applicable post-merge.

@codejaeger Once again, thanks for your contributions