Release notes

Release 19.15

Release date: Jul 13, 2018
Major Changes in this Release:
New Features and Improvements:

Non-Backwards Compatible Changes:

Bug fixes:
   - Fixed sub_image() in the Python API not working correctly for non-8bit images.
   - Last release broke have_same_dimensions(). The version specific to images
     was being used for tensors, which is incorrect and caused some of the DNN
     tooling to malfunction.


Release 19.14

Release date: Jul 07, 2018
Major Changes in this Release:
New Features and Improvements:
   - Added a --split-train-test option to imglab.
   - Added a max runtime option to the oca solver and structural object
     detection trainer.
   - Added an option to do translational jittering of the bounding boxes in the
     shape_predictor_trainer.  Using this option allows you to train
     shape_predictors that are somewhat more robust against variation in
     detection box placement. 
   - Added an optional thread_pool argument to find_max_global() and
     find_min_global() to allow for parallel execution of objective function calls.
   - Added auto_train_rbf_classifier(), a tool that trains a RBF-SVM without requiring the user
     to supply any hyperparameters.
   - Added polygon_area()
   - The image view objects now implement the generic image interface.
   - Updates to the Python API:
       - Added Python bindings for: extract_image_chip(),
         extract_image_chips(), center(), get_histogram(), sub_image(),
         polygon_area(), auto_train_rbf_classifier(), reduced(),
         translate_rect(), spatially_filter_image(),
         spatially_filter_image_separable(), num_separable_filters(),
         threshold_filter_singular_values(), max_point(),
         max_point_interpolated(), zero_border_pixels().  Also added an option
         for training nuclear norm regularized HOG detectors.
       - Added a bunch of new overloads and operators for existing Python types.
       - Made decision functions more viewable from python.  You can now inspect
         the contents of the functions rather than them being completely opaque.
       - Made it so you can call the std::vector<detectors> version of
         the object_detector constructor from python. So now you can pack
         multiple detectors into one object via the python API.
       - Allow batched face recognition for greater performance.

Non-Backwards Compatible Changes:

Bug fixes:
   - Fixed the point and dpoint operator + doing subtraction in the Python API.
   - Fixed label_connected_blobs_watershed() not giving contiguous labels as outputs. 
   - Fixed AVX detection not working correctly on some systems.
   - Fixed dlib.threshold_image() ignoring the optional thresh argument in the Python API.
   - Fixed hough_transform::find_pixels_voting_for_lines(). It would sometimes
     include a pixel multiple times in the output lists.
   - Made the routines that rotate image datasets use the rectangle_transform
     instead of the bad old way that only really worked for square boxes.  This
     improves placement of such rotated rectangular boxes.


Release 19.13

Release date: May 26, 2018
Major Changes in this Release:
New Features and Improvements:
   - Added a lot of new Python bindings.  You can now use these things from Python:
      - gaussian_blur(), label_connected_blobs(), randomly_color_image(), jet(),
        skeleton(), find_line_endpoints(), get_rect(), shrink_rect(), grow_rect(),
        image_gradients, label_connected_blobs_watershed(), convert_image(),
        convert_image_scaled(), dpoint, centered_rect(), centered_rects(), length(),
        as_grayscale(), pyramid_down, find_bright_keypoints(), find_bright_lines(),
        find_dark_lines(), find_dark_keypoints(), suppress_non_maximum_edges(),
        find_peaks(), hysteresis_threshold(), sobel_edge_detector(), equalize_histogram(),
        resize_image(), hough_transform, remove_incoherent_edge_pixels(),
        normalize_image_gradients(), line, signed_distance_to_line(), distance_to_line(),
        reverse(), intersect(), count_points_on_side_of_line(),
        count_points_between_lines(), dot(), normalize(), point_transform_projective,
        find_projective_transform(), inv(), transform_image(), angle_between_lines(),
        extract_image_4points(), load_grayscale_image(), min_barrier_distance(). 
      - Added a .add_overlay_circle() to dlib.image_window.  Also made .add_overlay()
        take lines.
      - Added the *_corner() routines to rectangle and drectangle and made these 
        objects constructable from instances of each other.
   - Made the Python extension module automatically enable AVX instructions if the host
     machine supports them.  So you never need to say --yes USE_AVX_INSTRUCTIONS anymore
     when installing dlib.

   - New C++ routines:
      - Added an image_window::add_overlay() overload for line object.
      - Added angle_between_lines()
      - Added extract_image_4points()
      - Added is_convex_quadrilateral(), find_convex_quadrilateral(), and no_convex_quadrilateral.
      - Added python_list_to_array()
      - Added min_barrier_distance() 

Non-Backwards Compatible Changes:

Bug fixes:
   - Fixed numpy_image and pybind11 crashing python sometimes when certain types of
     conversions are attempted.
   - Fixed some python functions not taking as wide a range of image types as they did in
     previous dlib versions.

Release 19.12

Release date: May 19, 2018
Major Changes in this Release:
New Features and Improvements:
   - Added Python interface to threshold_image() and partition_pixels().

Non-Backwards Compatible Changes:
   - In the Python API, renamed dlib.save_rgb_image() to dlib.save_image().

Bug fixes:
   - Dlib 19.11 had a bug that caused the Python interface to reject grayscale images.
     This has been fixed.

Release 19.11

Release date: May 17, 2018
Major Changes in this Release:
New Features and Improvements:
   - Deep Learning
      - Added resize_to layer.
      - Made loss_multiclass_log_per_pixel use CUDA. This greatly accelerates 
        training with this loss layer.
   - Image Processing
      - Added normalize_image_gradients() and remove_incoherent_edge_pixels().
      - Added neighbors_24 (for use with label_connected_blobs())
      - Added partition_pixels() and made threshold_image() use it to find the
        default threshold if none is given. Also depreciated
        auto_threshold_image() since using partition_pixels() to pick the
        threshold is superior.
      - Added overload of hysteresis_threshold() that uses partition_pixels()
        to select thresholds.
      - Added encode_8_pixel_neighbors() and find_line_endpoints().
      - Added image_gradients, a tool for computing multi-scale first and
        second order image gradients. 
      - Added find_bright_lines(), find_dark_lines(), find_bright_keypoints(),
        and find_dark_keypoints(). 
      - Added label_connected_blobs_watershed().
      - Added find_peaks().
      - Added find_pixels_voting_for_lines(), find_strong_hough_points(),
        and perform_generic_hough_transform() to the hough_transform.
   - Improved the stopping condition of the solve_qp_box_constrained() and
     solve_qp_box_constrained_blockdiag() quadratic program solvers.
   - Made find_min_single_variable() more numerically stable.
   - Make visual studio build with all cores when building dlib.
   - Added steal_memory() to the matrix.
   - Improved the workflow for adding part annotations in imglab.  You can now
     use shift+click to rapidly add parts to an object.  Each part will
     automatically receive an integer label.
   - Added .begin() and .end() to array2d.
   - Added the line class and some related utility functions.
   - Added centered_rects().
   - Added numpy_image, which is a simple type safe interface to numpy arrays.
     It is also a fully functional dlib image class, making interfacing dlib's
     image processing to Python much cleaner.  

Non-Backwards Compatible Changes:
   - All CUDA code in dlib was moved to dlib/cuda.

Bug fixes:
   - Replaced all the old Python C APIs interfacing to numpy with the new
     numpy_image.  This fixed some reference counting errors as a result.
   - Fixed load_bmp() not loading certain types of BMP images. 
   - Fixed compile time bugs when trying to use CBLAS in some unusual environments.
   - Fixed bug in global_function_search's constructor that takes initial function
     evaluations. It wasn't assigning these values into the entire state of the
     solver.
   - Fixed compile time error in the matlab bindings.  Also, fixed cell arrays
     of complex types not binding correctly.
   - Renamed BOOST_JOIN to DLIB_BOOST_JOIN to prevent name clashes when working
     with boost.
   - Fixed bug in hysteresis_threshold() that could cause incorrect output.
   - The last release of dlib added more ODR violation checks.  However, these
     could erroneously trigger when using Visual Studio and CUDA in certain
     workflows.  This has been fixed.
   - Fixed matrix objects not working correctly when sized greater than 4GB in
     Visual Studio.

Release 19.10

Release date: Mar 19, 2018
Major Changes in this Release:
New Features and Improvements:
   - Deep Learning:
      - Added scale_ layer, allowing implementation of squeeze-and-excitation networks.
      - Added loss_multimulticlass_log: used for learning a collection of multi-class classifiers.
   - Added a random forest regression tool. See random_forest_regression_trainer.
   - Added make_bounding_box_regression_training_data()
   - Added isotonic_regression
   - Added momentum_filter, rect_filter, find_optimal_momentum_filter(), and
     find_optimal_rect_filter().
   - Added binomial_random_vars_are_different() and event_correlation().
   - Added xcorr_fft(), a routine for efficiently performing large cross-correlations using the FFT.
   - Added the ramdump type decorator for invoking faster serialization routines.
   - Added check_serialized_version()
   - Added max_scoring_element() and min_scoring_element()
   - Made orthogonalize() faster.
   - Updates to the Python API:
      - Added interface to the global_function_search object.  This is a more general
        interface to the solver used by find_max_global().
      - Added support for variadic Python functions in find_max_global().
      - Added rect_filter and find_optimal_rect_filter().
      - Added make_bounding_box_regression_training_data()
      - Added the image_dataset_metadata routines for parsing XML datasets.
      - Added rvm_trainer
      - Added probability_that_sequence_is_increasing() 
      - Added dlib.__time_compiled__ field
      - Added num_threads to shape_predictor_training_options.
      - Added CUDA controlling routines such as set_device() and 
        set_dnn_prefer_smallest_algorithms().

Non-Backwards Compatible Changes:
   - Changed CMake so that there is only the dlib target and it isn't forced to
     be static.  Instead, the build type will toggle based on the state of CMake's
     BUILD_SHARED_LIBS variable.  So there is no longer a dlib_shared target.
   - Changed the integer types used to represent sizes from 32bits to 64bits in numerous
     places, such as in the tensor object.  This should be a backwards compatible change
     for nearly all client code.

Bug fixes:
   - Fixed memory leak in java swig array binding tool.
   - Fixed windows include order problem in all/source.cpp file.
   - Fixed cont_ layers not printing the correct num_filters parameter when they were 
     printed to std::cout or to XML.
   - Fixed some code not handling OBJECT_PART_NOT_PRESENT values correctly.
   - Fixed fft_inplace() not compiling for compile time sized matrices.
   - The shape_predictor_trainer could have very bad runtime for some really
     bad parameter settings.  This has been fixed and also warning messages about
     really bad training data or parameters have been added.
   - Fixed the decayed running stats objects so they use unbiased estimators.


Release 19.9

Release date: Jan 22, 2018
Major Changes in this Release:
New Features and Improvements:
   - Switched the Python API from Boost.Python to pybind11.  This means Python
     users don't need to install Boost anymore, making building dlib's Python API
     much easier.
   - Made the sparse version of svd_fast() use multiple CPU cores.
   - Changed the behavior of imglab's --flip option.  It will now attempt to
     adjust any object part labels so that the flipped dataset has the same
     average part layout as the source dataset. There is also a new --flip-basic 
     option that behaves like the old --flip. However, most people flipping a
     dataset with part annotations will want to use --flip.  For more details
     see: http://blog.dlib.net/2018/01/correctly-mirroring-datasets.html

Non-Backwards Compatible Changes:
   - Removed std::auto_ptr from dlib's old (and depreciated) smart pointers. 

Bug fixes:
   - Fixed global_optimization.py not working in Python 3.


Release 19.8

Release date: Dec 19, 2017
Major Changes in this Release:
New Features and Improvements:
   - Added a global optimizer, find_max_global(), which is suitable for
     optimizing expensive functions with many local optima.  For example, you
     can use it for hyperparameter optimization.  See model_selection_ex.cpp
     for an example.
   - Updates to the deep learning tooling:
      - Added semantic segmentation examples: dnn_semantic_segmentation_ex.cpp
        and dnn_semantic_segmentation_train_ex.cpp
      - New layers: loss_ranking, loss_epsilon_insensitive, softmax_all, and loss_dot.
      - Made log loss layers more numerically stable.
      - Upgraded the con layer so you can set the number of rows or columns to
        0 in the layer specification. Doing this means "make the filter cover
        the whole input image dimension".  This provides an easy way to make a
        filter sized so it will have one output along that dimension,
        effectively making it like a fully connected layer operating on a row
        or column.
      - Added support for non-scale-invariant MMOD.
      - Added an optional parameter to dnn_trainer::get_net() that allows you
        to call the function without forcing a state flush to disk.
      - Sometimes the loss_mmod layer could experience excessively long runtime
        during early training iterations.  This has been optimized and is now
        much faster.
      - Optimized the tensor's management of GPU memory.  It now uses less memory
        in some cases.  It will also not perform a reallocation if resized to a
        smaller size.  Instead, tensors 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<std::array<matrix<T>,K>> types as input. Doing
        this will create input tensors with K channels.
   - Added disjoint_subsets_sized
   - Added Python APIs: get_face_chips(), count_steps_without_decrease(),
     count_steps_without_decrease_robust(), and jitter_image().
   - Various improvements to CMake scripts: e.g. improved warning and error
     messages, added USE_NEON_INSTRUCTIONS option.
   - chol() will use a banded Cholesky algorithm for banded matrices, making it
     much faster in these cases.
   - Changed the timing code to use the C++11 high resolution clock and
     atomics. This makes the timing code a lot more precise.

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 more straightforward since you can
     simply 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 might naively expect.
   - Changed the outputs of test_regression_function() and cross_validate_regression_trainer().
     These functions now output 4D rather than 2D vectors.  The new output is:
     mean squared error, correlation, mean absolute error, and standard
     deviation of absolute error.  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 it behaves as it used to. In
     dlib 19.7 the padding code was changed and accidentally doubled the size
     of the applied padding in some cases. It's not a huge deal either way, but
     this change reverts back to the previous behavior.

Bug fixes:
   - 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 were 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_rect
     objects.
   - Fixed a bug where chinese_whispers(), when called from python, would
     sometimes return a labels array that didn'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.  This change
     fixes a bug where the program crashes or hangs sometimes during program
     shutdown.
   - Fixed error in TIME_THIS() introduced in dlib 19.7. It was printing
     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 can lead to
     problems when a global object that owns threads tries to tell them to
     shutdown, since the threads have already vanished.  The new code mitigates
     some of these problems, in particular, there were some cases where
     unloading dlib's python extension would deadlock.  This should now be
     fixed.
   - Fixed compile time errors when either of these macros were enabled:
     DLIB_STACK_TRACE, DLIB_ISO_CPP_ONLY.


Release 19.7

Release date: Sep 17, 2017
Major Changes in this Release:
New Features and Improvements:
   - Deep Learning:
      - The CNN+MMOD detector is now a multi-class detector.  In particular,
        the mmod_rect object now has a string label field which you can use to
        label objects, and the loss_mmod_ layer will learn to label objects with
        those labels.  For an example, see: https://www.youtube.com/watch?v=OHbJ7HhbG74
      - CNN+MMOD detectors are now 2.5x faster.  For instance, this example program
        http://dlib.net/dnn_mmod_find_cars_ex.cpp.html now runs at 98fps instead
        of 39fps.  
   - Added a 5 point face landmarking model that is over 10x smaller than the
     68 point model, runs faster, and works with both HOG and CNN generated
     face detections.  It is now the recommended landmarking model to use for 
     face alignment.  render_face_detections() and get_face_chip_details() have been 
     updated to work with both 5 and 68 point models, so the new 5 point model is
     a drop in replacement for the 68 point model.
   - The imglab tool is slightly improved.  It will display box labels with
     higher relative contrast.  You can also now press END or i to ignore boxes
     in imglab. This is useful because it's a much less stressing hand motion
     to hit END that i in most cases.
   - Added overloads of sub_image() that take raw pointers so you can make
     sub_images of anything. 
   - Changed TIME_THIS() to use std::chrono::high_resolution_clock, so now it's
     much higher precision.
   - Exposed Chinese whispers clustering to Python, added face clustering example.

Non-Backwards Compatible Changes:

Bug fixes:
   - Fixed an error in input_rgb_image_pyramid::image_contained_point(). The
     function might erroneously indicate that a point wasn't inside the original
     image when really it was, causing spurious error messages.
   - mmod_options would pick bad window sizes in some corner cases. This has been fixed.
   - Fixed a bug in the extract layer that trigged when a tensor with a
     different number of samples than the tensor used to initialize the network
     was passed through the layer.
   - The loss_per_missed_target parameter of the loss_mmod_ wasn't being used
     exactly right when boxes were auto-ignored.  There weren't any practical
     user facing problems due to this, but it has nevertheless been fixed. 


Release 19.6

Release date: Aug 28, 2017
Major Changes in this Release:
New Features and Improvements:

Non-Backwards Compatible Changes:

Bug fixes:
   - Fix build error in Visual Studio when CUDA is enabled. 




Old Release Notes