updated docs

docs/docs/algorithms.xml

@@ -25,6 +25,7 @@
          <name>Tools</name>
          <item>bigint</item> 
          <item>disjoint_subsets</item> 
+         <item>disjoint_subsets_sized</item> 
          <item nolink="true">
             <name>Quantum Computing</name>
             <sub>
@@ -463,6 +464,20 @@
       </component>
       
       
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>disjoint_subsets_sized</name>
+         <file>dlib/disjoint_subsets.h</file>
+         <spec_file link="true">dlib/disjoint_subsets/disjoint_subsets_sized_abstract.h</spec_file>
+         <description>
+                This object is just like <a href="#disjoint_subsets">disjoint_subsets</a> except that it
+                also keeps track of the size of each set.
+         </description>
+
+      </component>
+      
+      
    <!-- ************************************************************************* -->
 
       <component>

docs/docs/imaging.xml

@@ -222,6 +222,7 @@
          <item>rotate_image_dataset</item> 
          <item>extract_image_chips</item> 
          <item>random_cropper</item> 
+         <item>jitter_image</item> 
          <item>sub_image</item> 
       </section>
 
@@ -480,6 +481,7 @@
 
             <example>train_shape_predictor.py.html</example>
             <example>face_landmark_detection.py.html</example>
+            <example>face_alignment.py.html</example>
          </examples>
                                  
       </component>
@@ -1740,6 +1742,22 @@
          </examples>
       </component>
 
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>jitter_image</name>
+         <file>dlib/image_transforms.h</file>
+         <spec_file link="true">dlib/image_transforms/interpolation_abstract.h</spec_file>
+         <description>        
+            Randomly jitters an image by slightly rotating, scaling, and translating it.
+            There is also a 50% chance it will be mirrored left to right.
+         </description>
+         <examples>
+            <example>dnn_metric_learning_on_images_ex.cpp.html</example>
+            <example>dnn_face_recognition_ex.cpp.html</example>
+         </examples>
+      </component>
+
    <!-- ************************************************************************* -->
 
       <component>

docs/docs/main_menu.xml

@@ -143,14 +143,30 @@
          <item nolink="true">
             <name>Examples: Python</name>
             <sub>
+               <item>
+                  <name>Global Optimization</name>
+                  <link>global_optimization.py.html</link>
+               </item>
                <item>
                   <name>Face Clustering</name>
                   <link>face_clustering.py.html</link>
                </item>
+               <item>
+                  <name>Face Jittering/Augmentation</name>
+                  <link>face_jitter.py.html</link>
+               </item>
+               <item>
+                  <name>Face Alignment</name>
+                  <link>face_alignment.py.html</link>
+               </item>
                <item>
                   <name>Video Object Tracking</name>
                   <link>correlation_tracker.py.html</link>
                </item>
+               <item>
+                  <name>Binary Classification</name>
+                  <link>svm_binary_classifier.py.html</link>
+               </item>
                <item>
                   <name>Face Landmark Detection</name>
                   <link>face_landmark_detection.py.html</link>
@@ -232,6 +248,14 @@
                   <name>Deep Face Recognition</name>
                   <link>dnn_face_recognition_ex.cpp.html</link>
                </item>
+               <item>
+                  <name>Deep Learning Semantic Segmentation Trainer</name>
+                  <link>dnn_semantic_segmentation_train_ex.cpp.html</link>
+               </item>
+               <item>
+                  <name>Deep Learning Semantic Segmentation</name>
+                  <link>dnn_semantic_segmentation_ex.cpp.html</link>
+               </item>
                <item>
                   <name>Deep Learning Vehicle Detection</name>
                   <link>dnn_mmod_find_cars_ex.cpp.html</link>

docs/docs/ml.xml

@@ -209,6 +209,10 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
                   <name>htan</name>
                   <link>dlib/dnn/layers_abstract.h.html#htan_</link>
                </item>
+               <item>
+                  <name>softmax_all</name>
+                  <link>dlib/dnn/layers_abstract.h.html#softmax_all_</link>
+               </item>
                <item>
                   <name>softmax</name>
                   <link>dlib/dnn/layers_abstract.h.html#softmax_</link>
@@ -230,6 +234,18 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
                   <name>EXAMPLE_LOSS_LAYER</name>
                   <link>dlib/dnn/loss_abstract.h.html#EXAMPLE_LOSS_LAYER_</link>
                </item>
+               <item>
+                  <name>loss_dot</name>
+                  <link>dlib/dnn/loss_abstract.h.html#loss_dot_</link>
+               </item>
+               <item>
+                  <name>loss_epsilon_insensitive</name>
+                  <link>dlib/dnn/loss_abstract.h.html#loss_epsilon_insensitive_</link>
+               </item>
+               <item>
+                  <name>loss_ranking</name>
+                  <link>dlib/dnn/loss_abstract.h.html#loss_ranking_</link>
+               </item>
                <item>
                   <name>loss_binary_hinge</name>
                   <link>dlib/dnn/loss_abstract.h.html#loss_binary_hinge_</link>
@@ -264,10 +280,10 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
                </item>
                <item>
                   <name>loss_mean_squared_per_pixel</name>
-                  <link>#loss_mean_squared_per_pixel_</link>
+                  <link>dlib/dnn/loss_abstract.h.html#loss_mean_squared_per_pixel_</link>
                </item>
                <item>
-                  <name>loss_mean_squared_multioutput_</name>
+                  <name>loss_mean_squared_multioutput</name>
                   <link>dlib/dnn/loss_abstract.h.html#loss_mean_squared_multioutput_</link>
                </item>
             </sub>
@@ -498,6 +514,8 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
             <example>dnn_metric_learning_ex.cpp.html</example>
             <example>dnn_metric_learning_on_images_ex.cpp.html</example>
             <example>dnn_face_recognition_ex.cpp.html</example>
+            <example>dnn_semantic_segmentation_ex.cpp.html</example>
+            <example>dnn_semantic_segmentation_train_ex.cpp.html</example>
          </examples>
       </component>
 
@@ -525,6 +543,7 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
             <example>dnn_mmod_train_find_cars_ex.cpp.html</example>
             <example>dnn_metric_learning_ex.cpp.html</example>
             <example>dnn_metric_learning_on_images_ex.cpp.html</example>
+            <example>dnn_semantic_segmentation_train_ex.cpp.html</example>
          </examples>
       </component>
 
@@ -552,6 +571,7 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
             <example>dnn_face_recognition_ex.cpp.html</example>
             <example>dnn_mmod_face_detection_ex.cpp.html</example>
             <example>dnn_mmod_dog_hipsterizer.cpp.html</example>
+            <example>dnn_semantic_segmentation_train_ex.cpp.html</example>
          </examples>
       </component>
 
@@ -1204,6 +1224,7 @@ Davis E. King. <a href="http://jmlr.csail.mit.edu/papers/volume10/king09a/king09
          <examples>
             <example>svm_pegasos_ex.cpp.html</example>
             <example>svm_sparse_ex.cpp.html</example>
+            <example>svm_binary_classifier.py.html</example>
          </examples>
       </component>
       

docs/docs/release_notes.xml

@@ -11,6 +11,133 @@
 <!-- **************************************************************************************  -->
 
 <current>
+New Features and Improvements:
+   - added disjoint_subsets_sized
+   - added semantic segmentation example: dnn_semantic_segmentation_ex.cpp and dnn_semantic_segmentation_train_ex.cpp
+   - optimization:
+      - Added upper_bound_function object.
+      - Added solve_trust_region_subproblem_bounded()
+      - Added tools for doing global optimization. The main new tools here are find_max_global() and global_function_search.
+      - Updated model_selection_ex.cpp and optimization_ex.cpp to use these new tools.
+   - Added loss_ranking_ layer 
+   - Added loss_epsilon_insensitive_ layer
+   - Added softmax_all layer.
+   - Added loss_dot layer
+   - made log loss layers more numerically stable.
+   - Upgraded the con_ layer so that you can set the nr or nc to 0 in the layer
+     specification and this means "make the filter cover the whole input image
+     dimension". So it's just an easy way to make a filter sized exactly so that
+     it will have one output along that dimension.
+   - Add support for non-scale-invariant MMOD
+   - Python API for get_face_chips() which allows you to extract aligned face images.
+   - Also added python binding for count_steps_without_decrease() and count_steps_without_decrease_robust().
+   - Added jitter_image()
+   - Various improvements to cmake scripts.
+      - Added USE_NEON_INSTRUCTIONS cmake option.
+   - Added get_integer() and get_integer_in_range() to dlib::rand.
+   - Add get_net parameter that allows to call the function without forcing flush to disk.
+   - Sometimes the loss_mmod_ layer could experience excessively long runtime
+     during early iterations since the model might produce a huge number of false
+     alarms while the detector is still bad. Processing all these detections can
+     cause it to run slowly until the model is good enough to avoid really
+     excessive amounts of false alarms. This change puts more of a limit on the
+     number of false alarms processed during those early iterations and avoids
+     the slowdown.
+   - chol() will use a banded cholesky algorithm for banded matrices, making it much faster in these cases.
+   - Changed tensor so that, when reallocating memory, it frees any existing
+     memory *before* allocating new memory. It used to be the other way around
+     which caused momentary spikes of increased memory usage. This could put you
+     over the total memory available in some cases which is obviously less than
+     ideal behavior.
+   - Made resizable_tensor objects not perform a reallocation if they are
+     resized to be smaller. Instead, they now behave like std::vector in that
+     they just change their nominal size but keep the same memory, only
+     reallocating if they are resized to something larger than their underlying
+     memory block. This change makes some uses of dlib faster, in particular,
+     running networks on a large set of images of differing sizes will now run
+     faster since there won't be any GPU reallocations, which are notoriously
+     slow.
+   - Upgraded the input layer so you can give
+     input&lt;std::array&lt;matrix&lt;T&gt;,K&gt;&gt; types as input layer
+     specifications. This will create input tensors with K channels.
+   - Changed the timing code to use the C++11 high resolution clock and
+     atomics. This makes the timing code a lot more precise.
+   - Made the loss dumping between learning rate changes a little more relaxed.
+     In particular, rather than just dumping exactly 400 of the last loss values,
+     it now dumps 400 + 10% of the loss buffer. This way, the amount of the dump
+     is proportional to the steps without progress threshold. This is better
+     because when the user sets the steps without progress to something larger it
+     probably means you need to look at more loss values to determine that we
+     should stop, so dumping more in that case ought to be better.
+
+Non-Backwards Compatible Changes:
+   - Changed the random_cropper's set_min_object_size() routine to take min box
+     dimensions in the same format as the mmod_options object (i.e. two lengths
+     measured in pixels). This should make defining random_cropping strategies
+     that are consistent with MMOD settings much more straightforward since you
+     can just take the mmod_options settings and give them to the random_cropper
+     and it will do the right thing.
+   - Changed the mean squared loss layers to return a loss that's the MSE, not
+     0.5*MSE. The only thing this effects is the logging messages that print
+     during training, which were confusing since the reported loss was half the
+     size you would expect.
+   - Changed test_regression_function() and cross_validate_regression_trainer()
+     to output 2 more statistics, which are the mean absolute error and the
+     standard deviation of the absolute error. This means these functions now
+     return 4D rather than 2D vectors. I also made test_regression_function()
+     take a non-const reference to the regression function so that DNN objects
+     can be tested.
+   - Fixed shape_predictor_trainer padding so that it behaves as it used to. In
+     dlib 19.7 the padding code was changed and accidentally doubled the size of
+     the applied padding when in the older (and still default) landmark_relative
+     padding mode. It's not a huge deal either way, but this change reverts back
+     to the intended behavior.
+   - Changed test_regression_function() and cross_validate_regression_trainer()
+     to output correlation rather than squared correlation.  Also added two more
+     outputs: average absolute error and the standard deviation of the absolute
+     error. 
+
+Bug fixes:
+   - Fixed DLIB_ISO_CPP_ONLY not building.
+   - Fixed toMat() not compiling in some cases.
+   - Significantly reduced the compile time of the DNN example programs in visual studio.
+   - Fixed a few image processing functions that weren't using the generic image interface.
+   - Fixed a bug in the random_cropper where it might crash due to division by 0 if small images are given as input.
+   - Fixed a bug in how the mmod_options automatically determines detection window sizes. It would pick a bad size in some cases.
+   - Fixed load_image_dataset()'s skip_empty_images() option. It wasn't
+     skipping images that only have ignore boxes when you load into mmod_rects
+     like it should have been.
+   - Changed graph construction for chinese_whispers() so that each face is
+     always included in the edge graph. If it isn't then the output labels from
+     chinese_whispers would be missing faces in this degenerate case. So
+     basically this fixes a bug where chinese_whispers(), when called from
+     python, would sometimes return a labels array that doesn't include labels
+     for all the inputs.
+   - Fixed a bug in dlib's MS Windows GUI code that was introduced a little
+     while back when we switched everything to std::shared_ptr. Turns out
+     std::shared_ptr has some surprising limitations. This change fixes a bug
+     where the program crashes or hangs sometimes during program shutdown.
+   - Fixed error in TIME_THIS(). It was still printing in seconds when it said minutes in the output.
+   - Adding missing implementation of tabbed_display::selected_tab
+   - Changed the windows signaler and mutex code to use the C++11 thread
+     library instead of the old win32 functions. I did this to work around how
+     windows unloads dlls. In particular, during dll unload windows will kill all
+     threads, THEN it will destruct global objects. So this leads to problems
+     where a global obejct that owns threads tries to tell them to shutdown and
+     everything goes wrong. The specific problem this code change fixes is when
+     signaler::broadcast() is called on a signaler that was being waited on by
+     one of these abruptly killed threads. In that case, the old code would
+     deadlock inside signaler::broadcast(). This new code doesn't seem to have
+     that problem, thereby mitigating the windows dll unload behavior in some
+     situations.
+   - Fixed DLIB_STACK_TRACE macro.
+
+
+</current>
+
+<!-- **************************************************************************************  -->
+
+<old name="19.7" date="Sep 17, 2017">
 New Features and Improvements:
    - Deep Learning:
       - The CNN+MMOD detector is now a multi-class detector.  In particular,
@@ -50,7 +177,7 @@ Bug fixes:
      exactly right when boxes were auto-ignored.  There weren't any practical
      user facing problems due to this, but it has nevertheless been fixed. 
 
-</current>
+</old>
 
 <!-- **************************************************************************************  -->
 

docs/docs/term_index.xml

@@ -122,6 +122,7 @@
 
          <term file="ml.html" name="dnn_trainer" include="dlib/dnn.h"/>
 
+         <term file="dlib/dnn/trainer_abstract.h.html" name="force_flush_to_disk" include="dlib/dnn.h"/>
          <term file="dlib/dnn/loss_abstract.h.html" name="EXAMPLE_LOSS_LAYER_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/loss_abstract.h.html" name="loss_binary_hinge_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/loss_abstract.h.html" name="loss_binary_log_" include="dlib/dnn.h"/>
@@ -129,6 +130,9 @@
          <term file="dlib/dnn/loss_abstract.h.html" name="loss_multiclass_log_per_pixel_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/loss_abstract.h.html" name="loss_multiclass_log_per_pixel_weighted_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/loss_abstract.h.html" name="loss_mean_squared_per_pixel_" include="dlib/dnn.h"/>
+         <term file="dlib/dnn/loss_abstract.h.html" name="loss_ranking_" include="dlib/dnn.h"/>
+         <term file="dlib/dnn/loss_abstract.h.html" name="loss_dot_" include="dlib/dnn.h"/>
+         <term file="dlib/dnn/loss_abstract.h.html" name="loss_epsilon_insensitive_" include="dlib/dnn.h"/>
          <term file="ml.html" name="loss_metric_" include="dlib/dnn.h"/>
          <term file="ml.html" name="loss_mean_squared_" include="dlib/dnn.h"/>
          <term file="ml.html" name="loss_mean_squared_multioutput_" include="dlib/dnn.h"/>
@@ -160,6 +164,7 @@
          <term file="dlib/dnn/layers_abstract.h.html" name="sig_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/layers_abstract.h.html" name="htan_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/layers_abstract.h.html" name="softmax_" include="dlib/dnn.h"/>
+         <term file="dlib/dnn/layers_abstract.h.html" name="softmax_all_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/layers_abstract.h.html" name="add_prev_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/layers_abstract.h.html" name="concat_" include="dlib/dnn.h"/>
          <term file="dlib/dnn/layers_abstract.h.html" name="inception" include="dlib/dnn.h"/>
@@ -257,6 +262,10 @@
          <term file="optimization.html" name="find_min"                    include="dlib/optimization.h"/>
          <term file="optimization.html" name="find_min_box_constrained"    include="dlib/optimization.h"/>
          <term file="optimization.html" name="find_max_box_constrained"    include="dlib/optimization.h"/>
+         <term file="optimization.html" name="find_max_global"             include="dlib/global_optimization.h"/>
+         <term file="optimization.html" name="find_min_global"             include="dlib/global_optimization.h"/>
+         <term file="optimization.html" name="global_function_search"             include="dlib/global_optimization.h"/>
+         <term file="optimization.html" name="upper_bound_function"             include="dlib/global_optimization.h"/>
          <term file="optimization.html" name="max_cost_assignment"         include="dlib/optimization.h"/>
          <term link="optimization.html#max_cost_assignment" name="Hungarian Algorithm"         include="dlib/optimization.h"/>
          <term file="optimization.html" name="max_sum_submatrix"           include="dlib/optimization.h"/>
@@ -290,10 +299,11 @@
          <term link="dlib/graph_cuts/min_cut_abstract.h.html#node_label" name="FREE_NODE" include="dlib/graph_cuts.h" />
 
          <term file="optimization.html" name="solve_trust_region_subproblem"  include="dlib/optimization.h"/>
+         <term file="optimization.html" name="solve_trust_region_subproblem_bounded"  include="dlib/optimization.h"/>
          <term file="optimization.html" name="find_min_single_variable"       include="dlib/optimization.h"/>
          <term file="optimization.html" name="find_min_using_approximate_derivatives" include="dlib/optimization.h"/>
          <term file="optimization.html" name="find_min_bobyqa"                include="dlib/optimization.h"/>
-         <term file="optimization.html" name="find_optimal_parameters"        include="dlib/optimization/find_optimal_parameters.h"/>
+         <!-- DEPRECATED  <term file="optimization.html" name="find_optimal_parameters"        include="dlib/optimization/find_optimal_parameters.h"/> -->
          <term file="optimization.html" name="elastic_net"                    include="dlib/optimization/elastic_net.h"/>
          <term file="optimization.html" name="solve_qp_box_constrained"       include="dlib/optimization.h"/>
          <term file="optimization.html" name="solve_qp_box_constrained_blockdiag"       include="dlib/optimization.h"/>
@@ -348,6 +358,7 @@
          <term file="algorithms.html" name="create_max_margin_projection_hash" include="dlib/lsh.h"/>
          <term file="imaging.html" name="randomly_sample_image_features"   include="dlib/statistics.h"/>
          <term file="algorithms.html" name="disjoint_subsets"              include="dlib/disjoint_subsets.h"/>
+         <term file="algorithms.html" name="disjoint_subsets_sized"        include="dlib/disjoint_subsets.h"/>
          <term link="algorithms.html#disjoint_subsets" name="union-find"   include="dlib/disjoint_subsets.h"/>
          <term file="linear_algebra.html" name="rectangle"                 include="dlib/geometry.h"/>
          <term file="linear_algebra.html" name="drectangle"                 include="dlib/geometry.h"/>