Clarified the exact size of the HOG feature maps produced by

extract_fhog_features().  Also fixed a minor bug where empty planar HOG feature
maps had 0 planes in them rather than 31 empty planes as the spec says they
should.

dlib/image_transforms/fhog.h

@@ -637,7 +637,12 @@ namespace dlib
         int filter_cols_padding = 1
     ) 
     {
-        return impl_fhog::impl_extract_fhog_features(img, hog, cell_size, filter_rows_padding, filter_cols_padding);
+        impl_fhog::impl_extract_fhog_features(img, hog, cell_size, filter_rows_padding, filter_cols_padding);
+        // If the image is too small then the above function outputs an empty feature map.
+        // But to make things very uniform in usage we require the output to still have the
+        // 31 planes (but they are just empty).
+        if (hog.size() == 0)
+            hog.resize(31);
     }
 
     template <
@@ -653,7 +658,7 @@ namespace dlib
         int filter_cols_padding = 1
     ) 
     {
-        return impl_fhog::impl_extract_fhog_features(img, hog, cell_size, filter_rows_padding, filter_cols_padding);
+        impl_fhog::impl_extract_fhog_features(img, hog, cell_size, filter_rows_padding, filter_cols_padding);
     }
 
 // ----------------------------------------------------------------------------------------

dlib/image_transforms/fhog_abstract.h

@@ -61,8 +61,11 @@ namespace dlib
               area of a hog image (note that you should use the following planar version of
               extract_fhog_features() instead of the interlaced version if you want to use
               spatially_filter_image() on a hog image).
-            - #hog.nr() is approximately equal to img.nr()/cell_size + filter_rows_padding-1.
-            - #hog.nc() is approximately equal to img.nc()/cell_size + filter_cols_padding-1.
+            - #hog.nr() == max(round(img.nr()/(double)cell_size)-2,0) + filter_rows_padding-1.
+            - #hog.nc() == max(round(img.nc()/(double)cell_size)-2,0) + filter_cols_padding-1.
+              (i.e.  Each output dimension is roughly 1/cell_size the original size but
+              there is a one cell_size border all around the image that is lost and then we
+              add on any additional padding that is requested.)
             - for all valid r and c:
                 - #hog[r][c] == the FHOG vector describing the cell centered at the pixel location 
                   fhog_to_image(point(c,r),cell_size,filter_rows_padding,filter_cols_padding) in img.

dlib/test/fhog.cpp

@@ -60,6 +60,10 @@ namespace
         {
             dlib::array<array2d<float> > hog;
             extract_fhog_features(img, hog, sbin);
+            DLIB_TEST(hog.size() == 31);
+            DLIB_TEST_MSG(hog[0].nr() == max(static_cast<int>(img.nr()/(double)sbin+0.5)-2,0),
+                hog[0].nr() << "   " << max(static_cast<int>(img.nr()/(double)sbin+0.5)-2,0));
+            DLIB_TEST(hog[0].nc() == max(static_cast<int>(img.nc()/(double)sbin+0.5)-2,0));
 
             DLIB_TEST(hog.size() == 31);
             for (long o = 0; o < (long)hog.size(); ++o)
@@ -88,18 +92,28 @@ namespace
                 img.set_size(i,i);
                 assign_all_pixels(img, i);
                 extract_fhog_features(img, hog);
+
+                DLIB_TEST(hog.size() == 31);
+                DLIB_TEST(hog[0].nr() == max(static_cast<int>(img.nr()/8.0+0.5)-2,0));
+                DLIB_TEST(hog[0].nc() == max(static_cast<int>(img.nc()/8.0+0.5)-2,0));
             }
             for (int i = 1; i < 10; ++i)
             {
                 img.set_size(i,i+1);
                 assign_all_pixels(img, i);
                 extract_fhog_features(img, hog);
+                DLIB_TEST(hog.size() == 31);
+                DLIB_TEST(hog[0].nr() == max(static_cast<int>(img.nr()/8.0+0.5)-2,0));
+                DLIB_TEST(hog[0].nc() == max(static_cast<int>(img.nc()/8.0+0.5)-2,0));
             }
             for (int i = 1; i < 10; ++i)
             {
                 img.set_size(i+1,i);
                 assign_all_pixels(img, i);
                 extract_fhog_features(img, hog);
+                DLIB_TEST(hog.size() == 31);
+                DLIB_TEST(hog[0].nr() == max(static_cast<int>(img.nr()/8.0+0.5)-2,0));
+                DLIB_TEST(hog[0].nc() == max(static_cast<int>(img.nc()/8.0+0.5)-2,0));
             }
         }