Release notes

# Release 19.2

Release date: Oct 10, 2016
Major Changes in this Release:

    New Features:
       - Updates to the deep learning API:
          - Added tools for making convolutional neural network based object detectors.  See
            dnn_mmod_ex.cpp example program.
          - Added annotation() to tensor so you can associate any object you want with a tensor.
          - Made layer_details() part of the SUBNET interface so that user defined layer
            details objects can access each other. Also added the input_layer() global function
            for accessing the input layer specifically.
          - alias_tensor can now create aliases of const tensors.
          - Added set_all_bn_running_stats_window_sizes().
          - Added visit_layers_backwards(), visit_layers_backwards_range(), and
            visit_layers_range().
          - Computational layers can now optionally define map_input_to_output() and
            map_output_to_input() member functions.  If all layers of a network provide these
            functions then the new global functions input_tensor_to_output_tensor() and
            output_tensor_to_input_tensor() can be used to map between the network's input and
            output tensor coordinates.  This is important for fully convolutional object
            detectors since they need to map between the image space and final feature space.
            These new functions are important for tools like the new MMOD detector.
          - Added input_rgb_image_pyramid.
       - Image Processing
          - The imglab command line tool has these new options: --min-object-size, --rmempty,
            --rmlabel, --rm-if-overlaps, and --sort-num-objects.  I also changed the behavior of
            --split so that it simply partitions the data and is an invertible operation.
          - Added mmod_rect
          - Added an overload of load_image_dataset() that outputs directly to mmod_rect
            instead of rectangle.
          - Added image_dataset_file::shrink_big_images(). So now load_image_dataset() can load
            a dataset of high resolution files at a user requested lower resolution.
          - Added box_intersection_over_union().
          - Added create_tiled_pyramid(), image_to_tiled_pyramid(), and tiled_pyramid_to_image().
          - Added random_cropper
       - Upgraded dlib's mex wrapper tooling to enable easy binding of C++ classes to MATLAB
         objects.
       - Added nearest_rect()
       - Added find_upper_quantile()
       - Added count_steps_without_decrease_robust().
       - Added get_double_in_range() to dlib::rand.

    Non-Backwards Compatible Changes:
       - C++11 is now required to use dlib.
       - Changed pinv() so it interprets its tol argument relative to the largest singular
         value of the input matrix rather than as an absolute tolerance.  This should generally
         improve results, but could change the output in some cases.
       - Renamed the class members of test_box_overlap so they are less confusing.
       - Updates to the deep learning API:
          - Changed the DNN API so that sample_expansion_factor is a runtime variable rather
            than a compile time constant. This also removes it from the input layer interface
            since the DNN core now infers its value at runtime. Therefore, users that define their
            own input layers don't need to specify it anymore.
          - Changed DEFAULT_BATCH_NORM_EPS from 1e-5 to 1e-4.
          - Changed the default batch normalization running stats window from 1000 to 100.

    Bug fixes:
       - Made the relational operators constexpr so they don't accidentally cause compilation
         errors when they get pulled into the scope of template metaprogramming expressions.
       - Fixed all/source.cpp not compiling in some instances.
       - CMake scripts now do a better job detecting things like C++11 support, the presence of
         CUDA, and other system specific details that could cause the build to fail if not
         properly configured.
       - Fixed a bug in imglab's --cluster option where it would output xml files with empty
         entries if the input xml file contained unannotated images.
       - Fixed imglab's --cluster option not working with relative paths.

    Other:
       - Made the thread local variables that hold the cudnn and cublas context objects not
         destruct and recreate themselves when you switch devices.  Instead, they keep a table
         of context objects, for each thread and device, reusing as necessary. This prevents
         churn in the context objects when you are switching back and forth between devices
         inside a single thread, making things run more efficiently for some CUDA based
         workflows.
       - Made the message argument of the DLIB_ASSERT and DLIB_CASSERT macros optional.
       - Made thread_pool and parallel_for propagate exceptions from task threads to calling
         code rather than killing the application if a task thread throws.
       - Changed imglab --resample so that it never changes the aspect ratio of an image.
       - Made the check in dnn_trainer for convergence more robust. Previously, if we
         encountered a bad mini-batch that made the loss value suddenly jump up by a larger than
         normal value it could make the trainer think we converged. Now the test is robust to
         transient spikes in loss value.  Additionally, the dnn_trainer will now check if the
         loss has been increasing before it saves the state to disk. If it detects that the loss
         has been going up then instead of saving to disk it recalls the previously good state.
         This way, if we hit a really bad mini-batch during training which negatively effects
         the model in a significant way, the dnn_trainer will automatically revert back to an
         earlier good state.

# Release 19.1

Release date: Aug 13, 2016
Major Changes in this Release:

    New Features:
       - Support for cuDNN 5.1
       - dlib::async() and dlib::default_thread_pool().
       - rectangle_transform
       - imglab tool: added --resample, --ignore, --files, and --extract-chips
         command line options.  Also added convert_imglab_paths_to_relative and
         copy_imglab_dataset scripts.
       - Evgeniy Fominov made the shape_predictor trainer multi-threaded and faster.
       - sutr90 contributed support for the CIELab color space.  See the new lab_pixel.

    Non-Backwards Compatible Changes:
       - All the cmake utility scripts were moved to dlib/cmake_utils.
       - Code that #includes the shape_predictor can now only be compiled with
         compilers that support C++11 lambda functions.

    Bug fixes:
       - Made CMake scripts work in a wider range of environments.
       - Fixed compile time errors on various platforms.
       - Fixed bad multi-threading support in the MATLAB mex wrapper.
       - Fixed bug in cuDNN binding that could sometimes cause NaN outputs.
       - Fixed bad convergence testing in DNN tooling for very small datasets.

    Other:

# Release 19.0

Release date: Jun 25, 2016
Major Changes in this Release:

    New Features:
       - A deep learning toolkit using CPU and/or GPU hardware.  Some major elements
         of this are:
          - Clean and fully documented C++11 API
          - Clean tutorials: see dnn_introduction_ex.cpp and dnn_introduction2_ex.cpp
          - Uses cuDNN v5.0
          - Multi-GPU support
          - Automatic learning rate adjustment
          - A pretrained 1000 class Imagenet classifier (see dnn_imagenet_ex.cpp)
       - Optimization Tools
          - Added find_optimal_parameters()
          - Added elastic_net class
          - Added the option to use the elastic net regularizer to the OCA solver.
          - Added an option to solve the L2-loss version of the SVM objective function to svm_c_linear_dcd_trainer.
          - Added solve_qp_box_constrained()
       - Image Processing
          - Added random_color_transform, disturb_colors(), and apply_random_color_offset().
          - load_image() now supports loading GIF files.
       - Many improvements to the MATLAB binding API
          - Automatically link to MATLAB's Intel MKL when used on linux.
          - struct support
          - mex functions can have up to 20 arguments instead of 10.
          - In place operation.  Made column major matrices directly wrap MATLAB
            matrix objects when used inside mex files.  This way, if you use
            matrix_colmajor or fmatrix_colmajor in a mex file it will not do any
            unnecessary copying or transposing.
          - Catch ctrl+c presses in MATLAB console.  Allowing early termination of mex functions.
          - When used inside mex files, DLIB_ASSERTS won't kill the MATLAB process,
            just throw an exception.
          - Made cerr print in MATLAB as a red warning message.
       - load_mnist_dataset()
       - Added a constructor for seeding rand with a time_t.
       - Added subm_clipped()
       - Added unserialize.
       - Added running_gradient

    Non-Backwards Compatible Changes:
       - Everything in dlib/matlab/call_matlab.h is now in the dlib namespace.
       - DLIB_TEST() and DLIB_TEST_MSG() macros now require you to terminate them with a ;

    Bug fixes:
       - Fixed bug in 10 argument version of call_matlab() and also cleaned up a few
         minor things.
       - setup.py and CMake scripts work in a few more contexts.
       - Fixed compiler errors in visual studio 2015.
       - Fixed a bug in gaussian_blur() that caused messed up outputs when big
         sigma values were used on some pixel types.
       - Fixed minor bugs in join_rows() and join_cols(). They didn't work when one
         of the matrices was empty.

    Other:
       - Made CMake scripts uniformly require CMake version 2.8.4.
       - Faster fHOG feature extraction / face detection
       - CMake scripts now enable C++11 by default
       - Gave array2d and matrix move constructors and move assignment operators.  Matrix
         can also now be created from initializer lists.

# Release 18.18

Release date: Oct 28, 2015
Major Changes in this Release:

    New Features:
       - Added the set_ptrm() routine for assigning dlib::matrix objects to arbitrary
         memory blocks.

    Non-Backwards Compatible Changes:

    Bug fixes:
       - Fixed a bug that caused cmake to not provide the correct preprocessor
         definitions until cmake was run twice. This was causing some projects to
         not build properly.

    Other:
       - Improvements to build system:
          - Ehsan Azarnasab contributed a setup.py so the dlib Python API can be
            installed via the usual 'python setup.py install' command.
          - Séverin Lemaignan upgraded dlib's CMake scripts so they include an
            install target.  Now dlib can be installed system wide by executing
            'cmake PATH_TO_DLIB; make install'.  This also includes installing the
            appropriate scripts for CMake's find_package(dlib) to work.

# Release 18.17

Release date: Aug 15, 2015
Major Changes in this Release:

    New Features:
       - More clustering tools:
          - Added bottom_up_cluster() and find_clusters_using_angular_kmeans()
            routines.
          - Added a --cluster option to the imglab tool.  This lets you cluster
            objects into groups of similar appearance/pose.
       - Improved the shape_predictor.  In particular, it can now be learned from
         datasets where some landmarks are missing.  The shape_predictor also now
         outputs a sparse feature vector that encodes which leafs are used on each
         tree to make a prediction.

    Non-Backwards Compatible Changes:
       - extract_highdim_face_lbp_descriptors() produces slightly different output.

    Bug fixes:
       - Fixed a minor bug in extract_highdim_face_lbp_descriptors() which was
         pointed out by Yan Xu. One of the face locations was mistakenly used twice
         while another was skipped. This change breaks backwards compatibility with
         the previous feature extraction output but should slightly improve
         accuracy of classifiers trained using these features.
       - Fixed jet() and heatmap() so they work on empty images.
       - The SQLite transaction object did not function correctly when compiled
         in a C++11 program.  Since its destructor can throw, an exception
         specification needed to be added indicating that this was possible since
         destructors are now noexcept by default in C++11.
       - Fixed a bug pointed out by Ernesto Tapia that could cause matrix
         expressions that involve sub matrix views (e.g. colm) to produce the wrong
         results when the BLAS bindings were enabled.
       - Added an if to avoid a possible division by zero inside spectral_cluster().
       - Fixed a bug in parse_xml(). It failed to check if the given input stream
         was valid before trying to parse it.

    Other:

# Release 18.16

Release date: Jun 3, 2015
Major Changes in this Release:

    New Features:
       - Added a linear model predictive control solver.  See the mpc_ex.cpp example
         program for details.
       - Thanks to Patrick Snape, the correlation_tracker can now be used from Python.

    Non-Backwards Compatible Changes:
       - The camera_transform's second operator() method now takes 3 arguments
         instead of 2.  This is to allow it to output the z distance in addition to
         scale.

    Bug fixes:
       - Fixed a bug in the eigenvalue_decomposition which could occur when a
         symmetric matrix was used along with the LAPACK bindings.
       - Fixed a bug where the last column of data in a file wasn't loaded on some
         OS X machines when load_libsvm_formatted_data() was called.

    Other:
       - Added a hard iteration limit to a number of the SVM solvers.
       - Adrian Rosebrock graciously setup an OS X machine for dlib testing, which
         resulted in improved CMake python scripts on OS X machines.
       - Improved the way overlapping points are rendered by the perspective_window.

# Release 18.15

Release date: Apr 29, 2015
Major Changes in this Release:

    New Features:
       - Added a number of tools for working with 3D data:
          - Added the perspective_window which is a tool for displaying 3D point clouds.
          - Added camera_transform.  It performs the 3D to 2D mapping needed to visualize 3D
            data.
          - Added point_transform_affine3d as well as functions for creating such transforms:
            rotate_around_x(), rotate_around_y(), rotate_around_z(), and translate_point().
       - Added draw_solid_circle() for drawing on images.
       - Added get_best_hough_point() to the hough_transform.
       - Thanks to Jack Culpepper, the python API for object detection now outputs detection
         confidences.
       - Added lspi, an implementation of the least-squares policy iteration algorithm.

    Non-Backwards Compatible Changes:
       - The shape_predictor and shape_predictor_trainer had a non-optimal behavior when used
         with objects that have non-square bounding boxes. This has been fixed but will cause
         models that were trained with the previous version of dlib to not work as accurately if
         they used non-square boxes. So you might have to retrain your models when updating dlib.

    Bug fixes:
       - Fixed a bug which prevented add_image_rotations() from compiling.

    Other:
       - The imglab tool now allows the user to click and drag annotations around by holding
         shift and right clicking.

# Release 18.14

Release date: Mar 01, 2015
Major Changes in this Release:

    New Features:
       - Added spectral_cluster()
       - Added sub_image() and sub_image_proxy
       - Added set_all_logging_headers()

    Non-Backwards Compatible Changes:

    Bug fixes:
       - Fixed a bug that caused the correlation_tracker to erroneously trigger an assert when
         run in debug mode.

    Other:
       - Improved the usability of the new drectanle object.
       - Optimized extract_fhog_features() for the case where cell_size==1. This makes it about
         4x faster in that case.
       - Made it so you can compose point transform objects via operator *.

# Release 18.13

Release date: Feb 03, 2015
Major Changes in this Release:

    New Features:
       - Added the correlation_tracker object
       - Added the option to force the last weight to 1 to structural_assignment_trainer.
       - Added max_point_interpolated()
       - Added the drectangle object
       - New Python Tools:
          - Patrick Snape contributed a Python binding for the face landmarking tool and
            the general purpose shape prediction/training tools.
          - Vinh Khuc contributed a Python binding for find_candidate_object_locations(),
            dlib's implementation of the selective search object location proposal method.

    Non-Backwards Compatible Changes:

    Bug fixes:
       - Fixed a bug in extract_image_chips() and get_mapping_to_chip() that caused
         incorrect outputs when the requested chip stretched the image unevenly
         vertically or horizontally.
       - Made CMake check that libpng and libjpeg actually contain the link symbols
         they are supposed to since, on some systems, these libraries aren't
         installed correctly and will cause linker errors if used.
       - Fixed assign_border_pixels(img, rect) so that it correctly zeros an image
         when an empty rectangle is supplied. Previously, it did nothing to the
         image in this case.
       - Fixed compute_lda_transform() so it works properly when the class
         covariance matrices are singular even after performing PCA.
       - Fixed a bug in find_similarity_transform(). When given just two points as
         inputs it would sometimes produce a reflection rather than a similarity
         transform.
       - Disabled all bindings to FFTW because FFTW isn't threadsafe.

    Other:
       - Added an example program for dlib's SQLite API and made a few minor
         usability improvements to the API as well.

# Release 18.12

Release date: Dec 20, 2014
Major Changes in this Release:

    New Features:
       - Upgraded fft() and ifft() to support 2D matrices.
       - Added hough_transform
       - Added skeleton() for finding the skeletonization of a binary image.
       - Added distance_to_line(), clip_line_to_rectangle(), min_point(), and max_point().
       - Added a simple API for calling C++ from MATLAB.

    Non-Backwards Compatible Changes:

    Bug fixes:
       - Fixed a compile time error that could happen when calling fft() for
         certain input types.
       - Fixed a compile time error that prevented auto_threshold_image() from
         being used.
       - Fixed name clashes with new version of Boost.
       - Changed Python pickling code so it works with Python 3.
       - Fixed CMake compile time error related to finding fftw.

    Other:
       - Made extract_image_chips() much faster when extracting unscaled image chips.

Old Release Notes