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

    #include "../geometry.h"
    #include <vector>
    #include "box_overlap_testing_abstract.h"
    #include "full_object_detection_abstract.h"

    namespace dlib
    {

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

        template <
            typename image_scanner_type
            >
        class object_detector
        {
            /*!
                REQUIREMENTS ON image_scanner_type
                    image_scanner_type must be an implementation of
                    dlib/image_processing/scan_image_pyramid_abstract.h or
                    dlib/image_processing/scan_fhog_pyramid.h or
                    dlib/image_processing/scan_image_custom.h or
                    dlib/image_processing/scan_image_boxes_abstract.h

                WHAT THIS OBJECT REPRESENTS
                    This object is a tool for detecting the positions of objects in an image.
                    In particular, it is a simple container to aggregate an instance of an image
                    scanner (i.e. scan_image_pyramid, scan_fhog_pyramid, scan_image_custom, or
                    scan_image_boxes), the weight vector needed by one of these image scanners,
                    and finally an instance of test_box_overlap.  The test_box_overlap object
                    is used to perform non-max suppression on the output of the image scanner
                    object.

                    Note further that this object can contain multiple weight vectors.  In this
                    case, it will run the image scanner multiple times, once with each of the
                    weight vectors.  Then it will aggregate the results from all runs, perform
                    non-max suppression and then return the results.  Therefore, the object_detector
                    can also be used as a container for a set of object detectors that all use
                    the same image scanner but different weight vectors.  This is useful since
                    the object detection procedure has two parts.  A loading step where the
                    image is loaded into the scanner, then a detect step which uses the weight
                    vector to locate objects in the image.  Since the loading step is independent
                    of the weight vector it is most efficient to run multiple detectors by
                    performing one load into a scanner followed by multiple detect steps.  This
                    avoids unnecessarily loading the same image into the scanner multiple times.
            !*/
        public:
            typedef typename image_scanner_type::feature_vector_type feature_vector_type;

            object_detector (
            );
            /*!
                ensures
                    - This detector won't generate any detections when
                      presented with an image.
                    - #num_detectors() == 0
            !*/

            object_detector (
                const object_detector& item
            );
            /*!
                ensures
                    - #*this is a copy of item
                    - #get_scanner() == item.get_scanner()
                      (note that only the "configuration" of item.get_scanner() is copied.
                      I.e. the copy is done using copy_configuration())
            !*/

            object_detector (
                const image_scanner_type& scanner,
                const test_box_overlap& overlap_tester,
                const feature_vector_type& w
            );
            /*!
                requires
                    - w.size() == scanner.get_num_dimensions() + 1
                    - scanner.get_num_detection_templates() > 0
                ensures
                    - When the operator() member function is called it will
                      invoke scanner.detect(w,dets,w(w.size()-1)), suppress
                      overlapping detections, and then report the results.
                    - when #*this is used to detect objects, the set of
                      output detections will never contain any overlaps
                      with respect to overlap_tester.  That is, for all
                      pairs of returned detections A and B, we will always
                      have: overlap_tester(A,B) == false
                    - #get_w() == w
                    - #get_overlap_tester() == overlap_tester
                    - #get_scanner() == scanner
                      (note that only the "configuration" of scanner is copied.
                      I.e. the copy is done using copy_configuration())
                    - #num_detectors() == 1
            !*/

            object_detector (
                const image_scanner_type& scanner,
                const test_box_overlap& overlap_tester,
                const std::vector<feature_vector_type>& w
            );
            /*!
                requires
                    - for all valid i:
                        - w[i].size() == scanner.get_num_dimensions() + 1
                    - scanner.get_num_detection_templates() > 0
                    - w.size() > 0
                ensures
                    - When the operator() member function is called it will invoke
                      get_scanner().detect(w[i],dets,w[i](w[i].size()-1)) for all valid i.  Then it
                      will take all the detections output by the calls to detect() and suppress
                      overlapping detections, and finally report the results.
                    - when #*this is used to detect objects, the set of output detections will
                      never contain any overlaps with respect to overlap_tester.  That is, for
                      all pairs of returned detections A and B, we will always have:
                        overlap_tester(A,B) == false
                    - for all valid i:
                        - #get_w(i) == w[i]
                    - #num_detectors() == w.size()
                    - #get_overlap_tester() == overlap_tester
                    - #get_scanner() == scanner
                      (note that only the "configuration" of scanner is copied.
                      I.e. the copy is done using copy_configuration())
            !*/

            explicit object_detector (
                const std::vector<object_detector>& detectors
            );
            /*!
                requires
                    - detectors.size() != 0
                    - All the detectors must use compatibly configured scanners.  That is, it
                      must make sense for the weight vector from one detector to be used with
                      the scanner from any other.
                    - for all valid i:
                        - detectors[i].get_scanner().get_num_dimensions() == detectors[0].get_scanner().get_num_dimensions()
                          (i.e. all the detectors use scanners that use the same kind of feature vectors.)
                ensures
                    - Very much like the above constructor, this constructor takes all the
                      given detectors and packs them into #*this.  That is, invoking operator()
                      on #*this will run all the detectors, perform non-max suppression, and
                      then report the results.
                    - When #*this is used to detect objects, the set of output detections will
                      never contain any overlaps with respect to overlap_tester.  That is, for
                      all pairs of returned detections A and B, we will always have:
                        overlap_tester(A,B) == false
                    - #num_detectors() == The sum of detectors[i].num_detectors() for all valid i.
                    - #get_overlap_tester() == detectors[0].get_overlap_tester()
                    - #get_scanner() == detectors[0].get_scanner()
                      (note that only the "configuration" of scanner is copied.  I.e. the copy
                      is done using copy_configuration())
            !*/

            unsigned long num_detectors (
            ) const;
            /*!
                ensures
                    - returns the number of weight vectors in this object.  Since each weight
                      vector logically represents an object detector, this returns the number
                      of object detectors contained in this object.
            !*/

            const feature_vector_type& get_w (
                unsigned long idx = 0
            ) const;
            /*!
                requires
                    - idx < num_detectors
                ensures
                    - returns the idx-th weight vector loaded into this object.  All the weight vectors
                      have the same dimension and logically each represents a different detector.
            !*/

            const test_box_overlap& get_overlap_tester (
            ) const;
            /*!
                ensures
                    - returns the overlap tester used by this object
            !*/

            const image_scanner_type& get_scanner (
            ) const;
            /*!
                ensures
                    - returns the image scanner used by this object.
            !*/

            object_detector& operator= (
                const object_detector& item
            );
            /*!
                ensures
                    - #*this is a copy of item
                    - #get_scanner() == item.get_scanner()
                      (note that only the "configuration" of item.get_scanner() is
                      copied.  I.e. the copy is done using copy_configuration())
                    - returns #*this
            !*/

            struct rect_detection
            {
                double detection_confidence;
                unsigned long weight_index;
                rectangle rect;
            };

            template <
                typename image_type
                >
            void operator() (
                const image_type& img,
                std::vector<rect_detection>& dets,
                double adjust_threshold = 0
            );
            /*!
                requires
                    - img == an object which can be accepted by image_scanner_type::load()
                ensures
                    - Performs object detection on the given image and stores the detected
                      objects into #dets.  In particular, we will have that:
                        - #dets is sorted such that the highest confidence detections come
                          first.  E.g. element 0 is the best detection, element 1 the next
                          best, and so on.
                        - #dets.size() == the number of detected objects.
                        - #dets[i].detection_confidence == The strength of the i-th detection.
                          Larger values indicate that the detector is more confident that
                          #dets[i] is a correct detection rather than being a false alarm.
                          Moreover, the detection_confidence is equal to the detection value
                          output by the scanner minus the threshold value stored at the end of
                          the weight vector in get_w(#dets[i].weight_index).
                        - #dets[i].weight_index == the index for the weight vector that
                          generated this detection.
                        - #dets[i].rect == the bounding box for the i-th detection.
                    - #get_scanner() will have been loaded with img. Therefore, you can call
                      #get_scanner().get_feature_vector() to obtain the feature vectors or
                      #get_scanner().get_full_object_detection() to get the
                      full_object_detections for the resulting object detection boxes.
                    - The detection threshold is adjusted by having adjust_threshold added to
                      it.  Therefore, an adjust_threshold value > 0 makes detecting objects
                      harder while a negative value makes it easier.  Moreover, the following
                      will be true for all valid i:
                        - #dets[i].detection_confidence >= adjust_threshold
                      This means that, for example, you can obtain the maximum possible number
                      of detections by setting adjust_threshold equal to negative infinity.
            !*/

            struct full_detection
            {
                double detection_confidence;
                unsigned long weight_index;
                full_object_detection rect;
            };

            template <
                typename image_type
                >
            void operator() (
                const image_type& img,
                std::vector<full_detection>& dets,
                double adjust_threshold = 0
            );
            /*!
                requires
                    - img == an object which can be accepted by image_scanner_type::load()
                ensures
                    - This function is identical to the above operator() routine, except that
                      it outputs full_object_detections instead of rectangles.  This means that
                      the output includes part locations.  In particular, calling this function
                      is the same as calling the above operator() routine and then using
                      get_scanner().get_full_object_detection() to resolve all the rectangles
                      into full_object_detections.  Therefore, this version of operator() is
                      simply a convenience function for performing this set of operations.
            !*/

            template <
                typename image_type
                >
            std::vector<rectangle> operator() (
                const image_type& img,
                const adjust_threshold = 0
            );
            /*!
                requires
                    - img == an object which can be accepted by image_scanner_type::load()
                ensures
                    - This function is identical to the above operator() routine, except that
                      it returns a std::vector<rectangle> which contains just the bounding
                      boxes of all the detections.
            !*/

            template <
                typename image_type
                >
            void operator() (
                const image_type& img,
                std::vector<std::pair<double, rectangle> >& dets,
                double adjust_threshold = 0
            );
            /*!
                requires
                    - img == an object which can be accepted by image_scanner_type::load()
                ensures
                    - performs object detection on the given image and stores the
                      detected objects into #dets.  In particular, we will have that:
                        - #dets is sorted such that the highest confidence detections
                          come first.  E.g. element 0 is the best detection, element 1
                          the next best, and so on.
                        - #dets.size() == the number of detected objects.
                        - #dets[i].first gives the "detection confidence", of the i-th
                          detection.  This is the detection value output by the scanner minus
                          the threshold value stored at the end of the weight vector in get_w().
                        - #dets[i].second == the bounding box for the i-th detection.
                    - #get_scanner() will have been loaded with img. Therefore, you can call
                      #get_scanner().get_feature_vector() to obtain the feature vectors or
                      #get_scanner().get_full_object_detection() to get the
                      full_object_detections for the resulting object detection boxes.
                    - The detection threshold is adjusted by having adjust_threshold added to
                      it.  Therefore, an adjust_threshold value > 0 makes detecting objects
                      harder while a negative value makes it easier.  Moreover, the following
                      will be true for all valid i:
                        - #dets[i].first >= adjust_threshold
                      This means that, for example, you can obtain the maximum possible number
                      of detections by setting adjust_threshold equal to negative infinity.
            !*/

            template <
                typename image_type
                >
            void operator() (
                const image_type& img,
                std::vector<std::pair<double, full_object_detection> >& dets,
                double adjust_threshold = 0
            );
            /*!
                requires
                    - img == an object which can be accepted by image_scanner_type::load()
                ensures
                    - This function is identical to the above operator() routine, except that
                      it outputs full_object_detections instead of rectangles.  This means that
                      the output includes part locations.  In particular, calling this function
                      is the same as calling the above operator() routine and then using
                      get_scanner().get_full_object_detection() to resolve all the rectangles
                      into full_object_detections.  Therefore, this version of operator() is
                      simply a convenience function for performing this set of operations.
            !*/

            template <
                typename image_type
                >
            void operator() (
                const image_type& img,
                std::vector<full_object_detection>& dets,
                double adjust_threshold = 0
            );
            /*!
                requires
                    - img == an object which can be accepted by image_scanner_type::load()
                ensures
                    - This function is identical to the above operator() routine, except that
                      it doesn't include a double valued score.  That is, it just outputs the
                      full_object_detections.
            !*/
        };

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

        template <typename T>
        void serialize (
            const object_detector<T>& item,
            std::ostream& out
        );
        /*!
            provides serialization support.  Note that this function only saves the
            configuration part of item.get_scanner().  That is, we use the scanner's
            copy_configuration() function to get a copy of the scanner that doesn't contain any
            loaded image data and we then save just the configuration part of the scanner.
            This means that any serialized object_detectors won't remember any images they have
            processed but will otherwise contain all their state and be able to detect objects
            in new images.
        !*/

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

        template <typename T>
        void deserialize (
            object_detector<T>& item,
            std::istream& in
        );
        /*!
            provides deserialization support
        !*/

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

    }

    #endif // DLIB_OBJECT_DeTECTOR_ABSTRACT_H__