updated docs

docs/docs/imaging.xml

@@ -88,6 +88,7 @@
          <item>scan_image_boxes</item>
          <item>find_candidate_object_locations</item>
          <item>test_box_overlap</item>
+         <item>remove_unobtainable_rectangles</item>
          <item>setup_hashed_features</item>
          <item nolink="true">
             <name>Scan Image Pyramid Tools</name>
@@ -1765,6 +1766,26 @@
                                  
       </component>
             
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>remove_unobtainable_rectangles</name>
+         <file>dlib/image_processing.h</file>
+         <spec_file link="true">dlib/image_processing/remove_unobtainable_rectangles_abstract.h</spec_file>
+         <description>        
+            Recall that the <a href="#scan_image_pyramid">scan_image_pyramid</a> and 
+            <a href="#scan_image_boxes">scan_image_boxes</a> objects can't produce
+            all possible rectangles as object detections since they only
+            consider a limited subset of all possible object positions.
+            Therefore, when training an object detector that uses these tools
+            you must make sure the training data does not contain any object
+            locations that are unobtainable by the image scanning model.
+            The remove_unobtainable_rectangles() routine is a tool to filter out
+            these unobtainable rectangles from the training.
+         </description>
+                                 
+      </component>
+            
    <!-- ************************************************************************* -->
 
       <component>

docs/docs/term_index.xml

@@ -1215,6 +1215,7 @@
          <term file="imaging.html" name="surf_point"              include="dlib/image_keypoint.h"/>
 
          <term file="imaging.html" name="test_box_overlap"        include="dlib/image_processing.h"/>
+         <term file="imaging.html" name="remove_unobtainable_rectangles"        include="dlib/image_processing.h"/>
          <term file="imaging.html" name="object_detector"         include="dlib/image_processing.h"/>
          <term file="imaging.html" name="full_object_detection"   include="dlib/image_processing.h"/>
          <term file="dlib/image_processing/full_object_detection_abstract.h.html" name="all_parts_in_rect" include="dlib/image_processing.h"/>