Add docs for histogram

boostorg · Jun 26, 2020 · 48e083c · 48e083c
1 parent 79b66e1
commit 48e083c
Show file tree

Hide file tree

Showing 13 changed files with 155 additions and 0 deletions.
diff --git a/doc/histogram/core/create_a_histogram.rst b/doc/histogram/core/create_a_histogram.rst
@@ -0,0 +1,35 @@
+.. _create_histogram:
+
+Create a histogram
+==================
+
+**Method 1** - Using the histogram constructor
+
+Syntax::
+
+    histogram<Type1, Type2, Type3,... TypeN> 
+
+Type1 .. TypeN correspond to the axis type of the N axes in the histogram
+
+Example: If we want a 3D histogram of Axis1 of type `int`, Axis2 of type `float` and Axis3 of type `std::string`
+we would do it this way::
+
+    histogram<int, float, std::string> h;
+
+And done.
+
+**Method 2** - Using make_histogram()
+
+There is an alternative way to create the histogram directly from
+a GIL image view.
+
+Syntax::
+
+    auto h = make_histogram(view(image));
+
+where *image* could be a `gray8_image_t`/`rgb8_image_t` object read from source.
+
+
+
+
+
diff --git a/doc/histogram/core/cumulative_histogram.rst b/doc/histogram/core/cumulative_histogram.rst
@@ -0,0 +1,4 @@
+.. _cumulative_histogram:
+
+Making a cumulative hsitogram
+=============================
diff --git a/doc/histogram/core/extend_support.rst b/doc/histogram/core/extend_support.rst
@@ -0,0 +1,4 @@
+.. _extend_support:
+
+Extending
+=========
diff --git a/doc/histogram/core/fill_it.rst b/doc/histogram/core/fill_it.rst
@@ -0,0 +1,4 @@
+.. _fill_it:
+
+Fill histogram
+==================
diff --git a/doc/histogram/core/index.rst b/doc/histogram/core/index.rst
@@ -0,0 +1,18 @@
+Histogram
+=========
+
+The GIL documentation sections listed below are dedicated to describe the
+histogram class and functions used in many image processing algorithms.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of Contents
+
+   overview
+   create_a_histogram
+   fill_it
+   make_a_sub_histogram
+   cumulative_histogram
+   stl_compatibility
+   entend_support
+   limitations.rst
diff --git a/doc/histogram/core/limitations.rst b/doc/histogram/core/limitations.rst
@@ -0,0 +1,4 @@
+.. _limitations:
+
+Limitations
+===========
diff --git a/doc/histogram/core/make_a_sub_histogram.rst b/doc/histogram/core/make_a_sub_histogram.rst
@@ -0,0 +1,4 @@
+.. _sub_histogram:
+
+Making a sub-histogram
+======================
diff --git a/doc/histogram/core/overview.rst b/doc/histogram/core/overview.rst
@@ -0,0 +1,28 @@
+Overview
+========
+
+.. contents::
+   :local:
+   :depth: 1
+
+Description
+-----------
+
+The histogram class is built on top of std::unordered_map to keep it compatible with other
+STL algorithms. It can support any number of axes (known at compile time i.e. during class
+instantiation). Suitable conversion routines from GIL image constructs to the histogram bin 
+key are shipped with the class itself.
+
+
+Tutorials
+---------
+The following flow is recommended:
+    #. :ref:`create_histogram`
+    #. :ref:`fill_it`
+    #. :ref:`sub_histogram`
+    #. :ref:`cumulative_histogram`
+    #. :ref:`stl_compat`
+    #. :ref:`extend_support`
+    #. :ref:`limitations`
+
+.. note:: To try out these tutorials you need to get a clone of the repository, since it is not yet released.
diff --git a/doc/histogram/core/stl_compatibilty.rst b/doc/histogram/core/stl_compatibilty.rst
@@ -0,0 +1,4 @@
+.. _stl_compat:
+
+STL compatibility
+=================
diff --git a/doc/histogram/extension/index.rst b/doc/histogram/extension/index.rst
@@ -0,0 +1,12 @@
+Histogram
+=========
+
+The GIL documentation sections listed below are dedicated to describe the
+usage of external containers as histograms for GIL images.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of Contents
+
+   overview
+   std
diff --git a/doc/histogram/extension/overview.rst b/doc/histogram/extension/overview.rst
@@ -0,0 +1,32 @@
+Overview
+========
+
+.. contents::
+   :local:
+   :depth: 1
+
+Description
+-----------
+Apart from the default class supplied by Boost.GIL, there are also provisions to
+use external containers like from std::vector, std::map, boost::histogram etc. These
+are provided as extensions. 
+
+
+Extensions
+----------
+Currently the following are available:
+    #. std::vector (1D histogram support)
+    #. std::map (1D histogram support)
+    #. std::array (1D histogram support)
+    #. std::unordered_map (1D histogram support)
+    #. boost::histogram
+
+
+Adding an external container
+----------------------------
+The workflow should be:
+    #. Provide overloads for fill_histogram(must), make_histogram(optional) etc. in a new file preferably named after the container type in extensions/histogram/.
+    #. Add tests to test/extensions/histogram.
+    #. Add docs to docs/histogram/extensions.
+    #. Other cmake,Jamfile,config etc. file changes.
+
diff --git a/doc/histogram/extension/std.rst b/doc/histogram/extension/std.rst
@@ -0,0 +1,4 @@
+.. _std:
+
+STD extension
+=============
diff --git a/doc/index.rst b/doc/index.rst
@@ -26,6 +26,7 @@ Core Library Documentation
 
    design/index
    image_processing/index
+   histogram/core/index
    API Reference <./reference/index.html#://>
 
 Extensions Documentation
@@ -37,6 +38,7 @@ Extensions Documentation
    io
    toolbox
    numeric
+   histogram/extension/index
 
 Examples
 --------