# dlib C++ Library - thresholding_abstract.h

    // Copyright (C) 2006  Davis E. King (davis@dlib.net)
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_THRESHOLDINg_ABSTRACT_
    #ifdef DLIB_THRESHOLDINg_ABSTRACT_

    #include "../pixel.h"

    namespace dlib
    {

    // ----------------------------------------------------------------------------------------

        const unsigned char on_pixel = 255;
        const unsigned char off_pixel = 0;

    // ----------------------------------------------------------------------------------------

        template <
            typename image_type
            >
        typename pixel_traits<typename image_traits<image_type>::pixel_type>::basic_pixel_type
        partition_pixels (
            const image_type& img
        );
        /*!
            requires
                - image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - pixel_traits<typename image_traits<image_type>::pixel_type>::has_alpha == false
            ensures
                - Finds a threshold value that would be reasonable to use with
                  threshold_image(img, threshold).  It does this by finding the threshold that
                  partitions the pixels in img into two groups such that the sum of absolute
                  deviations between each pixel and the mean of its group is minimized.
        !*/

        template <
            typename image_type,
            typename ...T
            >
        void partition_pixels (
            const image_type& img,
            typename pixel_traits<typename image_traits<image_type>::pixel_type>::basic_pixel_type& pix_thresh,
            T&& ...more_thresholds
        );
        /*!
            requires
                - image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - pixel_traits<typename image_traits<image_type>::pixel_type>::has_alpha == false
                - more_thresholds == a bunch of parameters of the same type as pix_thresh.
            ensures
                - This version of partition_pixels() finds multiple partitions rather than just
                  one partition.  It does this by first partitioning the pixels just as the
                  above partition_pixels(img) does.  Then it forms a new image with only pixels
                  >= that first partition value and recursively partitions this new image.
                  However, the recursion is implemented in an efficient way which is faster than
                  explicitly forming these images and calling partition_pixels(), but the
                  output is the same as if you did.  For example, suppose you called
                  partition_pixels(img, t1, t2, t3).  Then we would have:
                    - t1 == partition_pixels(img)
                    - t2 == partition_pixels(an image with only pixels with values >= t1 in it)
                    - t3 == partition_pixels(an image with only pixels with values >= t2 in it)
        !*/

    // ----------------------------------------------------------------------------------------

        template <
            typename in_image_type,
            typename out_image_type
            >
        void threshold_image (
            const in_image_type& in_img,
            out_image_type& out_img,
            typename pixel_traits<typename image_traits<in_image_type>::pixel_type>::basic_pixel_type thresh
        );
        /*!
            requires
                - in_image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - out_image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - pixel_traits<typename image_traits<out_image_type>::pixel_type>::grayscale == true
                - pixel_traits<typename image_traits<in_image_type>::pixel_type>::has_alpha == false
                - pixel_traits<typename image_traits<out_image_type>::pixel_type>::has_alpha == false
            ensures
                - #out_img == the thresholded version of in_img (in_img is converted to a grayscale
                  intensity image if it is color).  Pixels in in_img with grayscale values >= thresh
                  have an output value of on_pixel and all others have a value of off_pixel.
                - #out_img.nc() == in_img.nc()
                - #out_img.nr() == in_img.nr()
        !*/

        template <
            typename image_type
            >
        void threshold_image (
            image_type& img,
            typename pixel_traits<typename image_traits<image_type>::pixel_type>::basic_pixel_type thresh
        );
        /*!
            requires
                - it is valid to call threshold_image(img,img,thresh);
            ensures
                - calls threshold_image(img,img,thresh);
        !*/

        template <
            typename in_image_type,
            typename out_image_type
            >
        void threshold_image (
            const in_image_type& in_img,
            out_image_type& out_img
        );
        /*!
            requires
                - it is valid to call threshold_image(in_img,out_img,partition_pixels(in_img));
            ensures
                - calls threshold_image(in_img,out_img,partition_pixels(in_img));
        !*/

        template <
            typename image_type
            >
        void threshold_image (
            image_type& img
        );
        /*!
            requires
                - it is valid to call threshold_image(img,img,partition_pixels(img));
            ensures
                - calls threshold_image(img,img,partition_pixels(img));
        !*/

    // ----------------------------------------------------------------------------------------

        template <
            typename in_image_type,
            typename out_image_type
            >
        void hysteresis_threshold (
            const in_image_type& in_img,
            out_image_type& out_img,
            typename pixel_traits<typename image_traits<in_image_type>::pixel_type>::basic_pixel_type lower_thresh,
            typename pixel_traits<typename image_traits<in_image_type>::pixel_type>::basic_pixel_type upper_thresh
        );
        /*!
            requires
                - in_image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - out_image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - pixel_traits<typename image_traits<out_image_type>::pixel_type>::grayscale == true
                - pixel_traits<typename image_traits<in_image_type>::pixel_type>::has_alpha == false
                - pixel_traits<typename image_traits<out_image_type>::pixel_type>::has_alpha == false
                - is_same_object(in_img, out_img) == false
            ensures
                - #out_img == the hysteresis thresholded version of in_img (in_img is converted to a
                  grayscale intensity image if it is color). Pixels in in_img with grayscale
                  values >= upper_thresh have an output value of on_pixel and all others have a
                  value of off_pixel unless they are >= lower_thresh and are connected to a pixel
                  with a value >= upper_thresh, in which case they have a value of on_pixel.  Here
                  pixels are connected if there is a path between them composed of pixels that
                  would receive an output of on_pixel.
                - #out_img.nc() == in_img.nc()
                - #out_img.nr() == in_img.nr()
        !*/

        template <
            typename in_image_type,
            typename out_image_type
            >
        void hysteresis_threshold (
            const in_image_type& in_img,
            out_image_type& out_img
        );
        /*!
            requires
                - in_image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - out_image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h
                - pixel_traits<typename image_traits<out_image_type>::pixel_type>::grayscale == true
                - pixel_traits<typename image_traits<in_image_type>::pixel_type>::has_alpha == false
                - pixel_traits<typename image_traits<out_image_type>::pixel_type>::has_alpha == false
                - is_same_object(in_img, out_img) == false
            ensures
                - performs: hysteresis_threshold(in_img, out_img, t1, t2) where the thresholds
                  are first obtained by calling partition_pixels(in_img, t1, t2).
        !*/

    // ----------------------------------------------------------------------------------------

    }

    #endif // DLIB_THRESHOLDINg_ABSTRACT_