Ensure all examples build without error (boostorg#628)

* Added all missing examples, dodgy Jamfile still
* Fixed attributions and Jamfile indent
* One readme per example: synopsis, build and exec reqs
* Cleaned up example/convolve2d.cpp
* Added example target to root Jamfile

Closes boostorg#436

Jamfile

@@ -7,4 +7,5 @@
 #  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 # please order by name to ease maintenance
+build-project example ;
 build-project test ;

example/Jamfile

@@ -11,6 +11,7 @@ import regex ;
 import testing ;
 
 using libjpeg : : : : true ; # work around bug on master
+using libpng : : : : true ;
 
 project
     : # requirements
@@ -19,6 +20,7 @@ project
 # TODO: Add missing examples
 
 local sources =
+    adaptive_he.cpp
     adaptive_threshold.cpp
     affine.cpp
     anisotropic_diffusion.cpp
@@ -27,12 +29,18 @@ local sources =
     dynamic_image.cpp
     harris.cpp
     hessian.cpp
+    histogram_equalization.cpp
+    histogram_matching.cpp
     histogram.cpp
+    hough_transform_circle.cpp
+    hough_transform_line.cpp
     interleaved_ptr.cpp
     mandelbrot.cpp
     morphology.cpp
     packed_pixel.cpp
+    rasterizer_circle.cpp
     rasterizer_ellipse.cpp
+    rasterizer_line.cpp
     resize.cpp
     sobel_scharr.cpp
     threshold.cpp
@@ -44,11 +52,13 @@ local targets ;
 
 for local s in $(sources)
 {
-    targets +=
-        [ compile $(s) :
-            [ ac.check-library /libjpeg//libjpeg : <library>/libjpeg//libjpeg : <build>no ]
-        ]
-        ;
+targets +=
+    [ exe [ regex.replace $(s)  ".cpp" "" ] :
+        $(s)
+	/libjpeg//libjpeg
+	/libpng//libpng
+    ]
+    ;
 }
 
 alias examples : $(targets) ;

example/README.md

@@ -3,43 +3,12 @@
 This directory contains
 
 - examples of C++ programs using GIL
+- a documentation file describing the synopsis, build and execution requirements for each example
 - configuration files for Boost.Build command line and CMake integration for popular IDEs.
 
 We provide Boost.Build (`Jamfile`) and CMake (`CMakeLists.txt`)
 configurations to build the examples.
 See the [CONTRIBUTING.md](../CONTRIBUTING.md)
 for details on how to run `b2` and `cmake` for Boost.GIL.
 
-Each example is build as a separate executable.
-Each executable generates its output as `out-<example_name>.jpg`.
-For example, the `resize.cpp` example generates the image `out-resize.jpg`.
-
-The following C++ examples are included:
-
-1. `resize.cpp`
-   Scales an image using bilinear or nearest-neighbour resampling.
-
-2. `affine.cpp`
-   Performs an arbitrary affine transformation on the image.
-
-3. `convolution.cpp`
-   Convolves the image with a Gaussian kernel.
-
-4. `mandelbrot.cpp`
-   Creates a synthetic image defining the Mandelbrot set.
-
-5. `interleaved_ptr.cpp`
-   Illustrates how to create a custom pixel reference and iterator.
-   Creates a GIL image view over user-supplied data without the need to cast to GIL pixel type.
-
-6. `x_gradient.cpp`
-   Horizontal gradient, from the tutorial
-
-7. `histogram.cpp`
-   Algorithm to compute the histogram of an image
-
-8. `packed_pixel.cpp`
-   Illustrates how to create a custom pixel model - a pixel whose channel size is not divisible by bytes.
-
-9. `dynamic_image.cpp`
-   Example of using images whose type is instantiated at run time.
+Each example is built as a separate executable.

example/adaptive_he.cpp

@@ -13,6 +13,13 @@
 
 using namespace boost::gil;
 
+// Demonstrates Adaptive Histogram Equalization (AHE)
+
+// See also:
+// histogram.cpp - General use of histograms in GIL
+// histogram_equalization.cpp - Regular Histogram Equalization
+// histogram_matching.cpp - Reference-based histogram computation
+
 int main()
 {
     gray8_image_t img;

example/adaptive_he.md

@@ -0,0 +1,20 @@
+# Adaptive Histogram Equalization
+
+Adaptive Histogram Equalization (AHE) capabilities in GIL are demonstrated by the program `adaptive_he`, compiled from the sources `example/adaptive_he.cpp`.
+
+## Synopsis
+`adaptive_he`
+
+The program doesn't take any argument on the command line.
+
+`adaptive_he` expects to find an image called `test_adaptive.png` in the current directory, and produces the image `out-adaptive.png` in return.
+
+## Specific requirements
+
+### Build requirements
+- A C++ compiler compliant with C++11 or above
+- The PNG library installed and configured.
+
+### Execution requirements
+- `adaptive_he` expects to find an image called `test_adaptive.png` in the current directory.
+

example/adaptive_threshold.cpp

@@ -5,12 +5,22 @@
 // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 //
+
 #include <boost/gil.hpp>
 #include <boost/gil/extension/io/png.hpp>
 #include <iostream>
 
 using namespace boost::gil;
 
+// Demonstrates Adaptive Thresholding
+
+// threshold_adaptive works following either the mean or the gaussian method, and accepts also a direction
+// The direction indicates whether the pixels are assigned the max value when their values are greater
+// than the threshold (regular), or when they are less than the threshold (inverse)
+// threshold_adaptive is defined in include/boost/gil/image_processing/threshold.hpp
+// See also:
+// threshold.cpp - Simple thresholding
+
 int main()
 {
     gray8_image_t img;

example/adaptive_threshold.md

@@ -0,0 +1,23 @@
+# Adaptive Thresholding
+
+Adaptive Thresholding capabilities in GIL are demonstrated by the program `adaptive_threshold`, compiled from the sources `example/adaptive_threshold.cpp`.
+
+## Synopsis
+`adaptive_threshold`
+
+The program doesn't take any argument on the command line.
+
+`adaptive_threshold` expects to find an image called `test_adaptive.png` in the current directory, and produces one image for each thresholding method: 
+- `out-threshold-adaptive-mean.png`
+- `out-threshold-adaptive-mean-inv.png`
+- `out-threshold-adaptive-gaussian.png`
+- `out-threshold-adaptive-gaussian-inv.png`.
+
+## Specific requirements
+
+### Build requirements
+- A C++ compiler compliant with C++11 or above
+- The PNG library installed and configured.
+
+### Execution requirements
+- `adaptive_threshold` expects to find an image called `test_adaptive.png` in the current directory.

example/affine.cpp

@@ -5,12 +5,17 @@
 // See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt
 //
+
 #include <boost/gil.hpp>
 #include <boost/gil/extension/io/jpeg.hpp>
 #include <boost/gil/extension/numeric/sampler.hpp>
 #include <boost/gil/extension/numeric/resample.hpp>
 
-// Example for resample_pixels() in the numeric extension
+// Performs an arbitrary affine transformation on the image.
+
+// This example relies on the matrices and functions available in GIL to define the operation,
+// in include/boost/gil/extension/numeric/affine.hpp
+// and calls resample_pixels(), avaiable in the numeric extension, to apply it
 
 int main()
 {

example/affine.md

@@ -0,0 +1,19 @@
+# Affine transformation
+
+Affine transformation capabilities in GIL are demonstrated by the program `affine`, compiled from the sources `example/affine.cpp`.
+
+## Synopsis
+`affine`
+
+The program doesn't take any argument on the command line.
+
+`affine` expects to find an image called `test.jpg` in the current directory, and produces an image in return, where the transformations have been applied: `out-affine.jpg`
+
+## Specific requirements
+
+### Build requirements
+- A C++ compiler compliant with C++11 or above
+- The JPEG library installed and configured.
+
+### Execution requirements
+- `affine` expects to find an image called `test.jpg` in the current directory.

example/anisotropic_diffusion.cpp

@@ -5,6 +5,7 @@
 // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 //
+
 #include <boost/gil/algorithm.hpp>
 #include <boost/gil/extension/io/png.hpp>
 #include <boost/gil/image.hpp>
@@ -20,6 +21,12 @@
 
 namespace gil = boost::gil;
 
+// Demonstrates Anisotropic Diffusion
+
+// This example uses the Perona-Malik's diffusion algorithm, which is the default in GIL.
+// In addition, Gaussian conductivity and two wide range conductivity functions are also available.
+// see include/boost/gil/image_processing/diffusion.hpp
+
 void gray_version(std::string const& input_path, std::string const& output_path,
                   unsigned int iteration_count, float kappa)
 {

example/anisotropic_diffusion.md

@@ -0,0 +1,22 @@
+# Anisotropic diffusion
+
+Anisotropic diffusion capabilities in GIL are demonstrated by the program `anisotropic_diffusion`, compiled from the sources `example/anisotropic_diffusion.cpp`.
+
+## Synopsis
+`anisoptropic_diffusion input.png output.png gray|rgb iterations kappa`
+- The first parameter must be the full path to an existing image in the JPEG format for `anisoptropic_diffusion` to process
+- The second parameter is the full path to the output image of `anisotropic_diffusion`. The directory will *not* be created and must exist.
+- The third parameter is the colour space: either `gray` or `rgb`
+- The fourth parameter is the number of iterations, which *must* be a positive integer
+- The fifth and last parameter is the value of the kappa constant
+
+Note that both the input and the ouput images must be in the PNG format.
+
+## Specific requirements
+
+### Build requirements
+- A C++ compiler compliant with C++11 or above
+- The PNG library installed and configured.
+
+### Execution requirements
+`anisotropic_diffusion` has no specific execution requirements.

example/convolution.cpp

@@ -4,12 +4,24 @@
 // Distributed under the Boost Software License, Version 1.0
 // See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt
+
 #include <boost/gil.hpp>
 #include <boost/gil/extension/io/jpeg.hpp>
 #include <boost/gil/extension/numeric/kernel.hpp>
 #include <boost/gil/extension/numeric/convolve.hpp>
 
-// Example for convolve_rows() and convolve_cols() in the numeric extension
+// Convolves the image with a Gaussian kernel.
+
+// Note that the kernel can be fixed or resizable:
+// kernel_1d_fixed<float, N> k(matrix, centre) produces a fixed kernel
+// kernel_1d<float> k(matrix, size, centre) produces a resizable kernel
+
+// Work can be done row by row and column by column, as in this example,
+// using the functions convolve_rows and convolve_cols (or their _fixed counterpart)
+// but the header boost/gil/extension/numeric/convolve.hpp also offers the function convolve_1d which combines the two.
+
+// See also:
+// convolve2d.cpp - Convolution with 2d kernels
 
 int main() {
     using namespace boost::gil;

example/convolution.md

@@ -0,0 +1,19 @@
+# Convolution
+
+Convolution capabilities in GIL are demonstrated by the program `convolution`, compiled from the sources `example/convolution.cpp`.
+
+## Synopsis
+`convolution`
+
+The program doesn't take any argument on the command line.
+
+`convolution` expects to find an image called `test.jpg` in the current directory, and produces two images in return, where the filters have been applied: `out-convolution.jpg` and `out-convolution2.jpg`
+
+## Specific requirements
+
+### Build requirements
+- A C++ compiler compliant with C++11 or above
+- The JPEG library installed and configured.
+
+### Execution requirements
+- `convolution` expects to find an image called `test.jpg` in the current directory.

example/convolve2d.cpp

@@ -1,18 +1,35 @@
+// 
+// Copyright 2019 Miral Shah <[email protected]>
+// 
+// Distributed under the Boost Software License, Version 1.0 
+// See accompanying file LICENSE_1_0.txt or copy at 
+// http://www.boost.org/LICENSE_1_0.txt 
+// 
+
 #include <vector>
 #include <iostream>
 #include <boost/gil/extension/numeric/kernel.hpp>
 #include <boost/gil/extension/numeric/convolve.hpp>
 #include <boost/gil/extension/io/png.hpp>
 
 #include <boost/gil/extension/io/jpeg.hpp>
+
 using namespace boost::gil;
 using namespace std;
+
+// Convolves the image with a 2d kernel.
+
+// Note that the kernel can be fixed or resizable:
+// kernel_2d_fixed<float, N> k(elements, centre_y, centre_x) produces a fixed kernel
+// kernel_2d<float> k(elements, size, centre_y, centre_x) produces a resizable kernel
+// The size of the kernel matrix is deduced as the square root of the number of the elements (9 elements yield a 3x3 matrix)
+
+// See also:
+// convolution.cpp - Convolution with 2d kernels
+
+
 int main()
 {
-    //gray8_image_t img;
-    //read_image("test_adaptive.png", img, png_tag{});
-    //gray8_image_t img_out(img.dimensions());
-
     gray8_image_t img;
     read_image("src_view.png", img, png_tag{});
     gray8_image_t img_out(img.dimensions()), img_out1(img.dimensions());
@@ -21,21 +38,16 @@ int main()
     detail::kernel_2d<float> kernel(v.begin(), v.size(), 1, 1);
     detail::convolve_2d(view(img), kernel, view(img_out1));
 
-    //write_view("out-convolve2d.png", view(img_out), png_tag{});
-    write_view("out-convolve2d.png", view(img_out1), jpeg_tag{});
+    write_view("out-convolve2d.png", view(img_out1), png_tag{});
 
-
-    //------------------------------------//
     std::vector<float> v1(3, 1.0f / 3.0f);
     kernel_1d<float> kernel1(v1.begin(), v1.size(), 1);
 
     detail::convolve_1d<gray32f_pixel_t>(const_view(img), kernel1, view(img_out), boundary_option::extend_zero);
     write_view("out-convolve_option_extend_zero.png", view(img_out), png_tag{});
 
-    if (equal_pixels(view(img_out1), view(img_out)))cout << "convolve_option_extend_zero" << endl;
-
-    cout << "done\n";
-    cin.get();
+    if (equal_pixels(view(img_out1), view(img_out)))
+      cout << "convolve_option_extend_zero" << endl;
 
     return 0;
 }