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

    #include "scan_image_pyramid_abstract.h"
    #include <vector>
    #include "../geometry.h"

    namespace dlib
    {

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

        template <
            typename image_scanner_type
            >
        std::vector<rectangle> determine_object_boxes (
            const image_scanner_type& scanner,
            const std::vector<rectangle>& rects,
            double min_match_score
        );
        /*!
            requires
                - 0 < min_match_score <= 1
                - image_scanner_type == an implementation of the scan_image_pyramid
                  object defined in dlib/image_processing/scan_image_pyramid_tools_abstract.h
            ensures
                - returns a set of object boxes which, when used as detection
                  templates with the given scanner, can attain at least
                  min_match_score alignment with every element of rects.  Note that
                  the alignment between two rectangles A and B is defined as
                    (A.intersect(B).area())/(double)(A+B).area()
        !*/

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

        template <
            typename image_scanner_type
            >
        std::vector<rectangle> determine_object_boxes (
            const image_scanner_type& scanner,
            const std::vector<std::vector<rectangle> >& rects,
            double min_match_score
        );
        /*!
            requires
                - 0 < min_match_score <= 1
                - image_scanner_type == an implementation of the scan_image_pyramid
                  object defined in dlib/image_processing/scan_image_pyramid_tools_abstract.h
            ensures
                - copies all rectangles in rects into a std::vector<rectangle> object, call it
                  R.  Then this function returns determine_object_boxes(scanner,R,min_match_score).
                  That is, it just called the version of determine_object_boxes() defined above
                  and returns the results.
        !*/

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

        template <
            typename image_scanner_type
            >
        void setup_grid_detection_templates (
            image_scanner_type& scanner,
            const std::vector<std::vector<rectangle> >& rects,
            unsigned int cells_x,
            unsigned int cells_y,
            double min_match_score = 0.75
        );
        /*!
            requires
                - cells_x > 0
                - cells_y > 0
                - 0 < min_match_score <= 1
                - image_scanner_type == an implementation of the scan_image_pyramid
                  object defined in dlib/image_processing/scan_image_pyramid_tools_abstract.h
            ensures
                - uses determine_object_boxes(scanner,rects,min_match_score) to obtain a set of
                  object boxes and then adds them to the given scanner object as detection templates.
                  Also uses create_grid_detection_template(object_box, cells_x, cells_y) to create
                  each feature extraction region.  Therefore, the detection templates will extract
                  features from a regular grid inside each object box.
        !*/

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

        template <
            typename image_scanner_type
            >
        void setup_grid_detection_templates_verbose (
            image_scanner_type& scanner,
            const std::vector<std::vector<rectangle> >& rects,
            unsigned int cells_x,
            unsigned int cells_y,
            double min_match_score = 0.75
        );
        /*!
            requires
                - cells_x > 0
                - cells_y > 0
                - 0 < min_match_score <= 1
                - image_scanner_type == an implementation of the scan_image_pyramid
                  object defined in dlib/image_processing/scan_image_pyramid_tools_abstract.h
            ensures
                - this function is identical to setup_grid_detection_templates() except
                  that it also outputs the selected detection templates to standard out.
        !*/

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

    }

    #endif // DLIB_SCAN_IMaGE_PYRAMID_TOOLS_ABSTRACT_H__