<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="stylesheet.xsl"?>

<doc>
   <title>Image Processing</title>

   <!-- ************************************************************************* -->

   <body>
      <br/><br/>

         <p>
            This page documents the functionality present in this library that deals with the
            management and manipulation of images.  One thing to note is that there is no 
            explicit image object.  Instead, everything deals with <a href="containers.html#array2d">
            array2d</a> objects that contain various kinds of pixels.  
         </p>

         <p>
            <h2>Pixel Types</h2>
            Most image handling routines in dlib will accept images containing any pixel type. 
            This is made possible by defining a traits class, <a href="#pixel_traits">pixel_traits</a>, for 
            each possible pixel type.  This traits class enables image processing routines to determine
            how to handle each kind of pixel and therefore only pixels which have a pixel_traits definition
            may be used.  The following list defines all the pixel types which come with pixel_traits definitions.  
            <ul>
               <li><b>RGB</b>
                  <ul> There are two RGB pixel types in dlib, <a href="#rgb_pixel">rgb_pixel</a> and <a href="#bgr_pixel">bgr_pixel</a>.  
                  Each defines a 24bit RGB pixel type.  The bgr_pixel is identical to rgb_pixel except that it lays
                  the color channels down in memory in BGR order rather than RGB order and is therefore useful
                  for interfacing with other image processing tools which expect this format (e.g. <a href="#cv_image">OpenCV</a>). </ul>
               </li>
               <li><b>RGB Alpha</b>
                  <ul>The <a href="#rgb_alpha_pixel">rgb_alpha_pixel</a> is an 8bit per channel RGB pixel with an 8bit alpha channel.</ul>
               </li>
               <li><b>HSI</b>
                  <ul>The <a href="#hsi_pixel">hsi_pixel</a> is a 24bit pixel which represents a point in the Hue Saturation Intensity 
                  (HSI) color space. </ul>
               </li>
               <li><b>Grayscale</b>
                  <ul>Any built in scalar type may be used as a grayscale pixel type.  For example, unsigned char, int, double, etc.</ul>
               </li>
            </ul>


         </p>
   </body>

   <!-- ************************************************************************* -->

   <menu width="150">
    <top>

      <section>
         <name>Pixels</name>
         <item>rgb_pixel</item>
         <item>bgr_pixel</item>
         <item>rgb_alpha_pixel</item>
         <item>hsi_pixel</item>
         <item>pixel_traits</item>
         <item>get_pixel_intensity</item> 
         <item>assign_pixel</item> 
         <item>assign_pixel_intensity</item> 
      </section>

      <section>
         <name>Image I/O</name>
         <item>jpeg_loader</item>
         <item>load_bmp</item> 
         <item>load_dng</item> 
         <item>load_image</item> 
         <item>load_jpeg</item> 
         <item>load_png</item> 
         <item>png_loader</item>
         <item>save_bmp</item> 
         <item>save_dng</item> 
         <item>save_png</item> 
      </section>

      <section>
         <name>Object Detection</name>
         <item>object_detector</item>
         <item>scan_image</item>
         <item>scan_image_pyramid</item>
         <item>test_box_overlap</item>
         <item nolink="true">
            <name>Scan Image Pyramid Tools</name>
            <sub>
               <item>compute_box_dimensions</item>
               <item>create_single_box_detection_template</item>
               <item>create_overlapped_2x2_detection_template</item>
               <item>create_grid_detection_template</item>

               <item>determine_object_boxes</item>
               <item>setup_grid_detection_templates</item>
               <item>setup_grid_detection_templates_verbose</item>
               <item>setup_hashed_features</item>
            </sub>
         </item>
      </section>

      <section>
         <name>Feature Extraction</name>
         <item>get_surf_points</item>
         <item nolink="true">
            <name>SURF Tools</name>
            <sub>
               <item>hessian_pyramid</item>
               <item>compute_surf_descriptor</item>
               <item>haar_x</item>
               <item>haar_y</item>
               <item>get_interest_points</item>
               <item>interest_point</item>
               <item>surf_point</item>
               <item>compute_dominant_angle</item>
            </sub>
         </item>

         <item>hog_image</item>
         <item>fine_hog_image</item>
         <item>poly_image</item>
         <item>hashed_feature_image</item>
         <item>nearest_neighbor_feature_image</item>
      </section>


      <section>
         <name>Edges and Thresholds</name>
         <item>edge_orientation</item> 
         <item>hysteresis_threshold</item> 
         <item>sobel_edge_detector</item> 
         <item>suppress_non_maximum_edges</item> 
         <item>threshold_image</item>
         <item>auto_threshold_image</item>
      </section>

      <section>
         <name>Morphology</name>
         <item>label_connected_blobs</item>
         <item>segment_image</item>
         <item>binary_dilation</item>
         <item>binary_erosion</item>
         <item>binary_open</item>
         <item>binary_close</item>
         <item>binary_intersection</item>
         <item>binary_union</item>
         <item>binary_difference</item>
         <item>binary_complement</item>
      </section>

      <section>
         <name>Filtering</name>
         <item>gaussian_blur</item> 
         <item>spatially_filter_image</item> 
         <item>spatially_filter_image_separable</item> 
         <item>separable_3x3_filter_block_grayscale</item> 
         <item>separable_3x3_filter_block_rgb</item> 
         <item>sum_filter</item> 
         <item>spatially_filter_image_separable_down</item> 
      </section>
 
      <section>
         <name>Miscellaneous</name>

         <item>cv_image</item>
         <item>randomly_color_image</item>

         <item>draw_line</item> 
         <item>fill_rect</item> 
         <item>assign_image</item> 
         <item>assign_image_scaled</item> 
         <item>assign_all_pixels</item> 
         <item>assign_border_pixels</item> 
         <item>equalize_histogram</item> 
         <item>get_histogram</item> 
         <item>pyramid_down</item> 
         <item>pyramid_down_3_2</item> 
         <item>pyramid_down_4_3</item> 
         <item>pyramid_down_5_4</item> 
         <item>zero_border_pixels</item> 
         <item>integral_image</item>
         <item>integral_image_generic</item>

      </section>

    </top>  
   </menu>

   <!-- ************************************************************************* -->
   <!-- ************************************************************************* -->
   <!-- ************************************************************************* -->

   <components>
   
   <!-- ************************************************************************* -->
      
      <component>
         <name>integral_image_generic</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/integral_image_abstract.h</spec_file>
         <description>
                This object is an alternate way of representing image data
                that allows for very fast computations of sums of pixels in 
                rectangular regions.  To use this object you load it with a
                normal image and then you can use the get_sum_of_area()
                member function to compute sums of pixels in a given area in
                constant time.
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>integral_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file>dlib/image_transforms/integral_image_abstract.h</spec_file>
         <description>
            This is a specialization of the <a href="#integral_image_generic">integral_image_generic</a>
            template for the case where sums of pixel values should be represented with 
            longs.  E.g. if you use 8bit pixels in your original images then this is
            the appropriate kind of integral image to use with them.
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>haar_x</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/integral_image_abstract.h</spec_file>
         <description>
            This is a function that operates on an <a href="#integral_image">integral_image</a>
            and allows you to compute the response of a Haar wavelet oriented along
            the X axis.  
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>haar_y</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/integral_image_abstract.h</spec_file>
         <description>
            This is a function that operates on an <a href="#integral_image">integral_image</a>
            and allows you to compute the response of a Haar wavelet oriented along
            the Y axis.  
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>compute_dominant_angle</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/surf_abstract.h</spec_file>
         <description>
            Computes and returns the dominant angle (i.e. the angle of the dominant gradient)
            at a given point and scale in an image.   This function is part of the
            main processing of the SURF algorithm.
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>get_surf_points</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/surf_abstract.h</spec_file>
         <description>
             This function runs the complete SURF algorithm on an input image and 
             returns the points it found.  For a description of what exactly
             the SURF algorithm does you should read the following paper:
             <blockquote>
               SURF: Speeded Up Robust Features
               By Herbert Bay, Tinne Tuytelaars, and Luc Van Gool
             </blockquote>
             <p>
                Also note that there are numerous flavors of the SURF algorithm
                you can put together using the functions in dlib.  The get_surf_points()
                function is just an example of one way you might do so.  
             </p>
         </description>
         <examples>
            <example>surf_ex.cpp.html</example>
         </examples>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>compute_surf_descriptor</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/surf_abstract.h</spec_file>
         <description>
            Computes the 64 dimensional SURF descriptor vector of a box centered
              at a given center point, tilted at a given angle, and sized according to 
              a given scale.  
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->

      <component>
         <name>hog_image</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/hog_abstract.h</spec_file>
         <description>
                This object is a tool for performing the image feature extraction algorithm
                described in the following paper:
                <blockquote>
                    Histograms of Oriented Gradients for Human Detection
                    by Navneet Dalal and Bill Triggs
                </blockquote>
         </description>
         <examples>
            <example>object_detector_ex.cpp.html</example>
         </examples>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>fine_hog_image</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/fine_hog_image_abstract.h</spec_file>
         <description>
            This object is a version of the <a href="#hog_image">hog_image</a> that 
            allows you to extract HOG features at a finer resolution.  
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>poly_image</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/poly_image_abstract.h</spec_file>
         <description>
                This object is a tool for extracting local feature descriptors from an image.
                In particular, it fits polynomials to local pixel patches and
                allows you to query the coefficients of these polynomials.  
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>hashed_feature_image</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/hashed_feature_image_abstract.h</spec_file>
         <description>
                This object is a tool for performing image feature extraction.  In
                particular, it wraps another image feature extractor and converts
                the wrapped image feature vectors into sparse indicator vectors.  It does
                this by hashing each feature vector and then returns a new vector 
                which is zero everywhere except for the position determined by the 
                hash.  

               <br/><br/>
                The following feature extractors can be wrapped by the hashed_feature_image:
               <ul style="margin-top:0em"> 
                  <li><a href="#hog_image">hog_image</a></li>
                  <li><a href="#fine_hog_image">fine_hog_image</a></li>
                  <li><a href="#poly_image">poly_image</a></li>
               </ul>
         </description>
         <examples>
            <example>object_detector_ex.cpp.html</example>
         </examples>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>nearest_neighbor_feature_image</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/nearest_neighbor_feature_image_abstract.h</spec_file>
         <description>
                This object is a tool for performing image feature extraction.  In
                particular, it wraps another image feature extractor and converts
                the wrapped image feature vectors into sparse indicator vectors.  It does
                this by finding the nearest neighbor for each feature vector and returning an
                indicator vector that is zero everywhere except for the position indicated by 
                the nearest neighbor.  

               <br/><br/>
               The following feature extractors can be wrapped by the nearest_neighbor_feature_image:
               <ul style="margin-top:0em"> 
                  <li><a href="#hog_image">hog_image</a></li>
                  <li><a href="#fine_hog_image">fine_hog_image</a></li>
                  <li><a href="#poly_image">poly_image</a></li>
               </ul>
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>hessian_pyramid</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/hessian_pyramid_abstract.h</spec_file>
         <description>
                This object represents an image pyramid where each level in the
                pyramid holds determinants of Hessian matrices for the original 
                input image.  This object can be used to find stable interest
                points in an image.  

               <br/><br/>
                This object is an implementation of the fast Hessian pyramid 
                as described in the paper: 
                <blockquote>
                   SURF: Speeded Up Robust Features
                   By Herbert Bay, Tinne Tuytelaars, and Luc Van Gool
                </blockquote>

                This implementation was also influenced by the very well documented
                OpenSURF library and its corresponding description of how the fast
                Hessian algorithm functions:  
                <blockquote>Notes on the OpenSURF Library by Christopher Evans</blockquote>
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>get_interest_points</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/hessian_pyramid_abstract.h</spec_file>
         <description>
            This function extracts interest points from a <a href="#hessian_pyramid">hessian_pyramid</a>.
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>interest_point</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/hessian_pyramid_abstract.h</spec_file>
         <description>
            This is a simple struct used to represent the interest points returned
            by the <a href="#get_interest_points">get_interest_points</a> function.
         </description>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>surf_point</name>
         <file>dlib/image_keypoint.h</file>
         <spec_file link="true">dlib/image_keypoint/surf_abstract.h</spec_file>
         <description>
            This is a simple struct used to represent the SURF points returned
            by the <a href="#get_surf_points">get_surf_points</a> function.
         </description>
         <examples>
            <example>surf_ex.cpp.html</example>
         </examples>
                                 
      </component>

   <!-- ************************************************************************* -->
      
      <component>
         <name>pixel_traits</name>
         <file>dlib/pixel.h</file>
         <spec_file>dlib/pixel.h</spec_file>
         <description>
            As the name implies, this is a traits class for pixel types. It allows you
            to determine what sort of pixel type you are dealing with.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>hsi_pixel</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            This is a simple struct that represents an HSI colored graphical pixel.  
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>rgb_alpha_pixel</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            This is a simple struct that represents an RGB colored graphical pixel with an 
            alpha channel.  
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>rgb_pixel</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            This is a simple struct that represents an RGB colored graphical pixel.  
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>bgr_pixel</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            This is a simple struct that represents a BGR colored graphical pixel.  
            <p>
            The difference between this object and the <a href="#rgb_pixel">rgb_pixel</a>
            is just that this struct lays its pixels down in memory in BGR order rather
            than RGB order.  You only care about this if you are doing something like
            using the <a href="#cv_image">cv_image</a> object to map an OpenCV image
            into a more object oriented form.
            </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>cv_image</name>
         <file>dlib/opencv.h</file>
         <spec_file link="true">dlib/opencv/cv_image_abstract.h</spec_file>
         <description>
            This object is meant to be used as a simple wrapper around the OpenCV
            IplImage struct.  Using this class template you can turn an IplImage
            object into something that looks like a normal dlib style image object.

            <p>
            So you should be able to use cv_image objects with many of the image
            processing functions in dlib as well as the GUI tools for displaying
            images on the screen.
            </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      
      <component>
         <name>randomly_color_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/randomly_color_image_abstract.h</spec_file>
         <description>
              Randomly generates a mapping from gray level pixel values
              to the RGB pixel space and then uses this mapping to create
              a colored version an image. 
              <p>
                 This function is useful for displaying the results of some image 
                 segmentation.  For example, the output of <a href="#label_connected_blobs">label_connected_blobs</a>
                 or <a href="#segment_image">segment_image</a>.
              </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>assign_pixel</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            assign_pixel() is a templated function that can assign any pixel type to another pixel type.
            It will perform whatever conversion is necessary to make the assignment work.  (E.g. color to 
            grayscale conversion)
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>assign_pixel_intensity</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            assign_pixel_intensity() is a templated function that can change the
            intensity of a pixel.  So if the pixel in question is a grayscale pixel
            then it simply assigns that pixel the given value.  However, if the
            pixel is not a grayscale pixel then it converts the pixel to the
            HSI color space and sets the I channel to the given intensity
            and then converts this HSI value back to the original pixel's 
            color space.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>get_pixel_intensity</name>
         <file>dlib/pixel.h</file>
         <spec_file link="true">dlib/pixel.h</spec_file>
         <description>
            get_pixel_intensity() is a templated function that 
            returns the grayscale intensity of a pixel.  If the pixel isn't a grayscale
            pixel then it converts the pixel to grayscale and returns that value.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>png_loader</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/png_loader_abstract.h</spec_file>
         <description>        
            This object loads a Portable Network Graphics (PNG) image file into 
            an <a href="containers.html#array2d">array2d</a> of <a href="dlib/pixel.h.html">pixels</a>.
            <p>
               Note that you must define DLIB_PNG_SUPPORT if you want to use this object.  You
               must also set your build environment to link to the libpng library.  However,
               if you use CMake and dlib's default CMakeLists.txt file then it will get setup
               automatically (assuming libpng is properly installed on your system).
            </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>jpeg_loader</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/jpeg_loader_abstract.h</spec_file>
         <description>        
            This object loads a JPEG image file into 
            an <a href="containers.html#array2d">array2d</a> of <a href="dlib/pixel.h.html">pixels</a>.
            <p>
               Note that you must define DLIB_JPEG_SUPPORT if you want to use this object.  You
               must also set your build environment to link to the libjpeg library.  However,
               if you use CMake and dlib's default CMakeLists.txt file then it will get setup
               automatically (assuming libjpeg is properly installed in your system).
            </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>load_jpeg</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/jpeg_loader_abstract.h</spec_file>
         <description>        
            This function loads a JPEG image file into 
            an <a href="containers.html#array2d">array2d</a> of <a href="dlib/pixel.h.html">pixels</a>.
            <p>
               Note that you must define DLIB_JPEG_SUPPORT if you want to use this object.  You
               must also set your build environment to link to the libjpeg library.  However,
               if you use CMake and dlib's default CMakeLists.txt file then it will get setup
               automatically (assuming libjpeg is properly installed in your system).
            </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>load_dng</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/image_loader_abstract.h</spec_file>
         <description>        
      This global function loads a dlib DNG file (a lossless compressed image format) into 
      an <a href="containers.html#array2d">array2d</a> of <a href="dlib/pixel.h.html">pixels</a>.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>save_dng</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_saver/image_saver_abstract.h</spec_file>
         <description>        
      This global function saves an image as a dlib DNG file (a lossless 
      compressed image format). 
            <p>
               This routine can save images containing any type of pixel.  However, the DNG format
               can natively store only the following pixel types: <b>rgb_pixel</b>, <b>hsi_pixel</b>,
               <b>rgb_alpha_pixel</b>, <b>uint8</b>, and <b>uint16</b>.  All other pixel
               types will be converted into one of these types as appropriate before being
               saved to disk.
            </p>

         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>save_png</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_saver/save_png_abstract.h</spec_file>
         <description>        
      This global function writes an image to disk as a PNG (Portable Network Graphics) file. 
            <p>
               Note that you must define DLIB_PNG_SUPPORT if you want to use this function.  You
               must also set your build environment to link to the libpng library.  However,
               if you use CMake and dlib's default CMakeLists.txt file then it will get setup
               automatically (assuming libpng is properly installed in your system).
            </p>
            <p>
               This routine can save images containing any type of pixel.  However, save_png() can
               only natively store the following pixel types: <b>rgb_pixel</b>, 
               <b>rgb_alpha_pixel</b>, <b>uint8</b>, and <b>uint16</b>.  All other pixel
               types will be converted into one of these types as appropriate before being
               saved to disk.
            </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>load_image</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/load_image_abstract.h</spec_file>
         <description>        
            This global function takes a file name, looks at its extension, and 
            then loads it into an <a href="containers.html#array2d">array2d</a> of 
            <a href="dlib/pixel.h.html">pixels</a> using the appropriate image 
            loading routine.  The supported types are BMP, PNG, JPEG, and the dlib DNG file format. 

            <p>
               Note that you can only load PNG and JPEG files if you link against
               libpng and libjpeg respectively.
            </p>
         </description>
                                 
         <examples>
            <example>image_ex.cpp.html</example>
         </examples>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>load_bmp</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/image_loader_abstract.h</spec_file>
         <description>        
      This global function loads a MS Windows BMP file into an <a href="containers.html#array2d">array2d</a> of 
      <a href="dlib/pixel.h.html">pixels</a>.
         </description>

      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>load_png</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_loader/png_loader_abstract.h</spec_file>
         <description>        
            This function loads a Portable Network Graphics (PNG) image file into 
            an <a href="containers.html#array2d">array2d</a> of <a href="dlib/pixel.h.html">pixels</a>.
            <p>
               Note that you must define DLIB_PNG_SUPPORT if you want to use this object.  You
               must also set your build environment to link to the libpng library.  However,
               if you use CMake and dlib's default CMakeLists.txt file then it will get setup
               automatically (assuming libpng is properly installed on your system).
            </p>
         </description>

      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>save_bmp</name>
         <file>dlib/image_io.h</file>
         <spec_file link="true">dlib/image_saver/image_saver_abstract.h</spec_file>
         <description>        
            This global function saves an image as a MS Windows BMP file. 

            <p>
               This routine can save images containing any type of pixel.  However, it will
               convert all color pixels into <b>rgb_pixel</b> and grayscale pixels into 
               <b>uint8</b> type before saving to disk.  
            </p>

         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>draw_line</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/draw_abstract.h</spec_file>
         <description>        
            This global function draws a line on an image.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>fill_rect</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/draw_abstract.h</spec_file>
         <description>        
            This global function draws a solid rectangle on an image.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>assign_border_pixels</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/assign_image_abstract.h</spec_file>
         <description>        
            This global function assigns all the pixels in the border of an image to 
            a specific value.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      
      <component>
         <name>assign_all_pixels</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/assign_image_abstract.h</spec_file>
         <description>        
            This global function assigns all the pixels in an image a specific value.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>assign_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/assign_image_abstract.h</spec_file>
         <description>        
            This global function copies one image into another and performs any
            necessary color space conversions to make it work right. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>assign_image_scaled</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/assign_image_abstract.h</spec_file>
         <description>        
            This global function copies one image into another and performs any
            necessary color space conversions to make it work right.  Additionally,
            if the dynamic range of the source image is too big to fit into the destination image
            then it will attempt to perform the appropriate scaling.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>get_histogram</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/equalize_histogram_abstract.h</spec_file>
         <description>        
            This global function computes an image's histogram and returns it in the
            form of a column or row <a href="containers.html#matrix">matrix</a> object.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>edge_orientation</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/edge_detector_abstract.h</spec_file>
         <description>        
            This global function takes horizontal and vertical gradient magnitude
            values and returns the orientation of the gradient. 
         </description>
                                 
      </component>
            
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>equalize_histogram</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/equalize_histogram_abstract.h</spec_file>
         <description>        
            This global function performs histogram equalization on an image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>hysteresis_threshold</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/thresholding_abstract.h</spec_file>
         <description>        
            This global function performs hysteresis thresholding on an image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>sobel_edge_detector</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/edge_detector_abstract.h</spec_file>
         <description>        
            This global function performs spatial filtering on an image using the
            sobel edge detection filters.
         </description>
                                 
         <examples>
            <example>image_ex.cpp.html</example>
         </examples>
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>suppress_non_maximum_edges</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/edge_detector_abstract.h</spec_file>
         <description>        
            This global function performs non-maximum suppression on a gradient
            image.  
         </description>

         <examples>
            <example>image_ex.cpp.html</example>
         </examples>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>zero_border_pixels</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/assign_image_abstract.h</spec_file>
         <description>        
            This global function zeros the pixels on the border of an image.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>spatially_filter_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This global function performs spatial filtering on an image with a user
            supplied filter.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>gaussian_blur</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This global function blurs an image by convolving it with a Gaussian filter.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>spatially_filter_image_separable</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This global function performs spatial filtering on an image with a user
            supplied separable filter.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>spatially_filter_image_separable_down</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This global function performs spatial filtering on an image with a user
            supplied separable filter.  Additionally, it produces a downsampled
            output.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>sum_filter</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This function slides a rectangle over an input image and outputs a new 
            image which contains the sum of pixels inside the rectangle at each
            position in the input image.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>separable_3x3_filter_block_grayscale</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This routine filters part of an image with a user supplied 3x3 separable filter.
            The output is a grayscale sub-image.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>separable_3x3_filter_block_rgb</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/spatial_filtering_abstract.h</spec_file>
         <description>        
            This routine filters part of an image with a user supplied 3x3 separable filter.
            The output is a RGB sub-image.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>pyramid_down</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/image_pyramid_abstract.h</spec_file>
         <description>        
               This is a simple function object to help create image pyramids.  It 
               downsamples an image by half.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>pyramid_down_3_2</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/image_pyramid_abstract.h</spec_file>
         <description>        
               This is a simple function object to help create image pyramids.  It 
               downsamples an image by a ratio of 3 to 2.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>pyramid_down_4_3</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/image_pyramid_abstract.h</spec_file>
         <description>        
               This is a simple function object to help create image pyramids.  It 
               downsamples an image by a ratio of 4 to 3.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>pyramid_down_5_4</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/image_pyramid_abstract.h</spec_file>
         <description>        
               This is a simple function object to help create image pyramids.  It 
               downsamples an image by a ratio of 5 to 4.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>auto_threshold_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/thresholding_abstract.h</spec_file>
         <description>        
            This global function performs a simple binary thresholding on an image.  
            Instead of taking a user supplied threshold
            it computes one from the image using k-means clustering.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>threshold_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/thresholding_abstract.h</spec_file>
         <description>        
            This global function performs a simple binary thresholding on an image with a user
            supplied threshold.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>label_connected_blobs</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/label_connected_blobs_abstract.h</spec_file>
         <description>        
              This function labels each of the connected blobs in an image with a unique integer label.  
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>segment_image</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/segment_image_abstract.h</spec_file>
         <description>        
              Attempts to segment an image into regions which have some visual consistency to them.
              In particular, this function implements the algorithm described in the paper:
              <blockquote>
               Efficient Graph-Based Image Segmentation by Felzenszwalb and Huttenlocher.
              </blockquote>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_dilation</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function performs the morphological operation of dilation on an image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_erosion</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function performs the morphological operation of erosion on an image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_open</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function performs a morphological opening on an image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_close</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function performs a morphological closing on an image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_intersection</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function computes the intersection of two binary images. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_union</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function computes the union of two binary images. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_difference</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function computes the difference of two binary images. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>binary_complement</name>
         <file>dlib/image_transforms.h</file>
         <spec_file link="true">dlib/image_transforms/morphological_operations_abstract.h</spec_file>
         <description>        
            This global function computes the complement of a binary image. 
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>scan_image</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/scan_image_abstract.h</spec_file>
         <description>        
            This global function is a tool for sliding a set of rectangles
            over an image space and finding the locations where the sum of pixels in
            the rectangles exceeds a threshold.  It is useful for implementing
            certain kinds of sliding window classifiers.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>scan_image_pyramid</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/scan_image_pyramid_abstract.h</spec_file>
         <description>        
                This object is a tool for running a sliding window classifier over
                an image pyramid.  This object can also be understood as a general 
                tool for implementing the spatial pyramid models described in the paper:
                <blockquote>
                    Beyond Bags of Features: Spatial Pyramid Matching for Recognizing 
                    Natural Scene Categories by Svetlana Lazebnik, Cordelia Schmid, 
                    and Jean Ponce
                </blockquote>

               <br/><br/>
               The following feature extractors can be used with the scan_image_pyramid object:
               <ul style="margin-top:0em"> 
                  <li><a href="#hashed_feature_image">hashed_feature_image</a></li>
                  <li><a href="#nearest_neighbor_feature_image">nearest_neighbor_feature_image</a></li>
               </ul>
         </description>
         <examples>
            <example>object_detector_ex.cpp.html</example>
            <example>object_detector_advanced_ex.cpp.html</example>
         </examples>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>object_detector</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/object_detector_abstract.h</spec_file>
         <description>        
                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 the <a href="#scan_image_pyramid">scan_image_pyramid</a> 
                class, the weight vector needed by scan_image_pyramid, and  
                an instance of <a href="#test_box_overlap">test_box_overlap</a>.  The test_box_overlap 
                object is used to perform non-max suppression on the output of the 
                scan_image_pyramid object.  
                <p>
                   Note that you can use the 
                   <a href="ml.html#structural_object_detection_trainer">structural_object_detection_trainer</a>
                   to learn the parameters of an object_detector.  See the example programs for an introduction.
                </p>
         </description>
         <examples>
            <example>object_detector_ex.cpp.html</example>
            <example>object_detector_advanced_ex.cpp.html</example>
         </examples>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>test_box_overlap</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/box_overlap_testing_abstract.h</spec_file>
         <description>        
            This object is a simple function object for determining if two 
            <a href="algorithms.html#rectangle">rectangles</a> overlap.  
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>compute_box_dimensions</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/detection_template_tools_abstract.h</spec_file>
         <description>        
            This function is a tool for computing a rectangle with a particular 
            width/height ratio and area.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>create_single_box_detection_template</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/detection_template_tools_abstract.h</spec_file>
         <description>        
            This function is a tool for creating a detection template usable by 
            the <a href="#scan_image_pyramid">scan_image_pyramid</a> object.  This
            particular function creates a detection template with exactly one feature
            extraction region.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>create_overlapped_2x2_detection_template</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/detection_template_tools_abstract.h</spec_file>
         <description>        
            This function is a tool for creating a detection template usable by 
            the <a href="#scan_image_pyramid">scan_image_pyramid</a> object.  This
            particular function creates a detection template with four overlapping feature
            extraction regions.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>create_grid_detection_template</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/detection_template_tools_abstract.h</spec_file>
         <description>        
            This function is a tool for creating a detection template usable by 
            the <a href="#scan_image_pyramid">scan_image_pyramid</a> object.  This
            particular function creates a detection template with a grid of feature
            extraction regions.
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>determine_object_boxes</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/scan_image_pyramid_tools_abstract.h</spec_file>
         <description>        
            The <a href="#scan_image_pyramid">scan_image_pyramid</a> object represents a sliding
            window classifier system.  For it to work correctly it needs to be given a set of
            object boxes which define the size and shape of each sliding window and these windows
            need to be able to match the sizes and shapes of targets the user wishes to detect.
            Therefore, the determine_object_boxes() routine is a tool for computing a set of object boxes
            which can meet this requirement.

         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>setup_grid_detection_templates</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/scan_image_pyramid_tools_abstract.h</spec_file>
         <description>        
            This routine uses <a href="#determine_object_boxes">determine_object_boxes</a> to obtain a set of
              object boxes and then adds them to a <a href="#scan_image_pyramid">scan_image_pyramid</a> object 
              as detection templates.  It also uses <a href="#create_grid_detection_template">create_grid_detection_template</a>
               to create each feature extraction region.  Therefore, the detection templates will extract
              features from a regular grid inside each object box.
         </description>
         <examples>
            <example>object_detector_ex.cpp.html</example>
         </examples>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>setup_grid_detection_templates_verbose</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/scan_image_pyramid_tools_abstract.h</spec_file>
         <description>        
            This function is identical to <a href="#setup_grid_detection_templates">setup_grid_detection_templates</a>
            except that it also outputs information regarding the selected detection templates
            to standard out.
         </description>
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>setup_hashed_features</name>
         <file>dlib/image_processing.h</file>
         <spec_file link="true">dlib/image_processing/scan_image_pyramid_tools_abstract.h</spec_file>
         <description>        
            This is a tool for configuring the <a href="#hashed_feature_image">hashed_feature_image</a> object
            with a random <a href="algorithms.html#projection_hash">projection hash</a>. 
         </description>
         <examples>
            <example>object_detector_ex.cpp.html</example>
         </examples>
                                 
      </component>
            
   <!-- ************************************************************************* -->

   </components>

   <!-- ************************************************************************* -->


</doc>

