Added the following functions:

    make_uniform_lbp_image()
    extract_histogram_descriptors()
    extract_uniform_lbp_descriptors()
    extract_highdim_face_lbp_descriptors()
    compute_lda_transform()
    compute_equal_error_rate()

dlib/image_transforms.h

@@ -17,6 +17,7 @@
 #include "image_transforms/segment_image.h"
 #include "image_transforms/interpolation.h"
 #include "image_transforms/fhog.h"
+#include "image_transforms/lbp.h"
 
 #endif // DLIB_IMAGE_TRANSFORMs_
 

dlib/image_transforms/lbp.h

+// Copyright (C) 2014  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_LBP_Hh_
+#define DLIB_LBP_Hh_
+
+#include "lbp_abstract.h"
+#include "../image_processing/generic_image.h"
+#include "assign_image.h"
+#include "../pixel.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename image_type2
+        >
+    void make_uniform_lbp_image (
+        const image_type& img_,
+        image_type2& lbp_
+    )
+    {
+        const static unsigned char uniform_lbps[] = {
+            0, 1, 2, 3, 4, 58, 5, 6, 7, 58, 58, 58, 8, 58, 9, 10, 11, 58, 58, 58, 58, 58,
+            58, 58, 12, 58, 58, 58, 13, 58, 14, 15, 16, 58, 58, 58, 58, 58, 58, 58, 58, 58,
+            58, 58, 58, 58, 58, 58, 17, 58, 58, 58, 58, 58, 58, 58, 18, 58, 58, 58, 19, 58,
+            20, 21, 22, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58,
+            58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 23, 58, 58, 58, 58, 58,
+            58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 24, 58, 58, 58, 58, 58, 58, 58, 25, 58,
+            58, 58, 26, 58, 27, 28, 29, 30, 58, 31, 58, 58, 58, 32, 58, 58, 58, 58, 58, 58,
+            58, 33, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 34, 58, 58,
+            58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58,
+            58, 58, 58, 58, 58, 58, 58, 58, 58, 35, 36, 37, 58, 38, 58, 58, 58, 39, 58, 58,
+            58, 58, 58, 58, 58, 40, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58, 58,
+            58, 41, 42, 43, 58, 44, 58, 58, 58, 45, 58, 58, 58, 58, 58, 58, 58, 46, 47, 48,
+            58, 49, 58, 58, 58, 50, 51, 52, 58, 53, 54, 55, 56, 57
+        };
+
+        COMPILE_TIME_ASSERT(sizeof(uniform_lbps) == 256);
+
+        const_image_view<image_type> img(img_);
+        image_view<image_type2> lbp(lbp_);
+
+        lbp.set_size(img.nr(), img.nc());
+
+        // set all the border pixels to the "non-uniform LBP value".
+        assign_border_pixels(lbp, 1, 1, 58);
+
+        typedef typename image_traits<image_type>::pixel_type pixel_type;
+        typedef typename pixel_traits<pixel_type>::basic_pixel_type basic_pixel_type;
+
+        for (long r = 1; r+1 < img.nr(); ++r)
+        {
+            for (long c = 1; c+1 < img.nc(); ++c)
+            {
+                const basic_pixel_type pix = get_pixel_intensity(img[r][c]);
+                unsigned char b1 = 0;
+                unsigned char b2 = 0;
+                unsigned char b3 = 0;
+                unsigned char b4 = 0;
+                unsigned char b5 = 0;
+                unsigned char b6 = 0;
+                unsigned char b7 = 0;
+                unsigned char b8 = 0;
+
+                unsigned char x = 0;
+                if (get_pixel_intensity(img[r-1][c-1]) > pix) b1 = 0x80; 
+                if (get_pixel_intensity(img[r-1][c  ]) > pix) b2 = 0x40;
+                if (get_pixel_intensity(img[r-1][c+1]) > pix) b3 = 0x20;
+                x |= b1;
+                if (get_pixel_intensity(img[r  ][c-1]) > pix) b4 = 0x10;
+                x |= b2;
+                if (get_pixel_intensity(img[r  ][c+1]) > pix) b5 = 0x08;
+                x |= b3;
+                if (get_pixel_intensity(img[r+1][c-1]) > pix) b6 = 0x04;
+                x |= b4;
+                if (get_pixel_intensity(img[r+1][c  ]) > pix) b7 = 0x02;
+                x |= b5;
+                if (get_pixel_intensity(img[r+1][c+1]) > pix) b8 = 0x01;
+
+                x |= b6;
+                x |= b7;
+                x |= b8;
+
+                lbp[r][c] = uniform_lbps[x];
+            }
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename T
+        >
+    void extract_histogram_descriptors (
+        const image_type& img_,
+        const point& loc,
+        std::vector<T>& histograms,
+        const unsigned int cell_size = 10,
+        const unsigned int block_size = 4,
+        const unsigned int max_val = 58
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(cell_size >= 1 && block_size >= 1 && max_val < 256 && 
+                    (unsigned int)max(mat(img_)) <= max_val,
+            "\t void extract_histogram_descriptors()"
+            << "\n\t Invalid inputs were given to this function."
+            << "\n\t cell_size:      " << cell_size
+            << "\n\t block_size:     " << block_size
+            << "\n\t max_val:        " << max_val
+            << "\n\t max(mat(img_)): " << max(mat(img_))
+            );
+
+        typedef typename image_traits<image_type>::pixel_type pixel_type;
+        COMPILE_TIME_ASSERT((is_same_type<pixel_type, unsigned char>::value));
+
+        const_image_view<image_type> img(img_);
+
+        const rectangle area = get_rect(img);
+        const rectangle window = centered_rect(loc, block_size*cell_size, block_size*cell_size);
+        unsigned int cell_top = window.top();
+        for (unsigned int br = 0; br < block_size; ++br)
+        {
+            unsigned int cell_left = window.left();
+            for (unsigned int bc = 0; bc < block_size; ++bc)
+            {
+                // figure out the cell boundaries
+                rectangle cell(cell_left, cell_top, cell_left+cell_size-1, cell_top+cell_size-1);
+                cell = cell.intersect(area);
+
+                // make the actual histogram for this cell
+                unsigned int hist[256] = {0};
+                for (long r = cell.top(); r <= cell.bottom(); ++r)
+                {
+                    for (long c = cell.left(); c <= cell.right(); ++c)
+                    {
+                        hist[img[r][c]]++;
+                    }
+                }
+
+                // copy histogram into the output.
+                histograms.insert(histograms.end(), hist, hist + max_val+1);
+
+                cell_left += cell_size;
+            }
+            cell_top += cell_size;
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename T
+        >
+    void extract_uniform_lbp_descriptors (
+        const image_type& img,
+        std::vector<T>& feats,
+        const unsigned int cell_size = 10
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT(cell_size >= 1,
+            "\t void extract_uniform_lbp_descriptors()"
+            << "\n\t Invalid inputs were given to this function."
+            << "\n\t cell_size:      " << cell_size
+            );
+
+        feats.clear();
+        array2d<unsigned char> lbp;
+        make_uniform_lbp_image(img, lbp);
+        for (long r = 0; r < lbp.nr(); r+=cell_size)
+        {
+            for (long c = 0; c < lbp.nc(); c+=cell_size)
+            {
+                const rectangle cell = rectangle(c,r,c+cell_size-1,r+cell_size-1).intersect(get_rect(lbp));
+                // make the actual histogram for this cell
+                unsigned int hist[59] = {0};
+                for (long r = cell.top(); r <= cell.bottom(); ++r)
+                {
+                    for (long c = cell.left(); c <= cell.right(); ++c)
+                    {
+                        hist[lbp[r][c]]++;
+                    }
+                }
+
+                // copy histogram into the output.
+                feats.insert(feats.end(), hist, hist + 59);
+            }
+        }
+
+        for (unsigned long i = 0; i < feats.size(); ++i)
+            feats[i] = std::sqrt(feats[i]);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename T
+        >
+    void extract_highdim_face_lbp_descriptors (
+        const image_type& img,
+        const full_object_detection& det,
+        std::vector<T>& feats
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_CASSERT(det.num_parts() == 68,
+            "\t void extract_highdim_face_lbp_descriptors()"
+            << "\n\t Invalid inputs were given to this function."
+            << "\n\t det.num_parts(): " << det.num_parts()
+            );
+
+        const unsigned long num_scales = 5; 
+        feats.clear();
+        dlib::vector<double,2> l, r;
+        double cnt = 0;
+        // Find the center of the left eye by averaging the points around 
+        // the eye.
+        for (unsigned long i = 36; i <= 41; ++i) 
+        {
+            l += det.part(i);
+            ++cnt;
+        }
+        l /= cnt;
+
+        // Find the center of the right eye by averaging the points around 
+        // the eye.
+        cnt = 0;
+        for (unsigned long i = 42; i <= 47; ++i) 
+        {
+            r += det.part(i);
+            ++cnt;
+        }
+        r /= cnt;
+
+        // We only do feature extraction from these face parts.  These are things like the
+        // corners of the eyes and mouth and stuff like that.
+        std::vector<point> parts;
+        parts.reserve(30);
+        parts.push_back(l);
+        parts.push_back(r);
+        parts.push_back(det.part(17));
+        parts.push_back(det.part(21));
+        parts.push_back(det.part(22));
+        parts.push_back(det.part(28));
+        parts.push_back(det.part(36));
+        parts.push_back(det.part(39));
+        parts.push_back(det.part(42));
+        parts.push_back(det.part(45));
+        parts.push_back(det.part(27));
+        parts.push_back(det.part(28));
+        parts.push_back(det.part(29));
+        parts.push_back(det.part(30));
+        parts.push_back(det.part(31));
+        parts.push_back(det.part(35));
+        parts.push_back(det.part(33));
+        parts.push_back(det.part(48));
+        parts.push_back(det.part(54));
+        parts.push_back(det.part(51));
+        parts.push_back(det.part(57));
+
+        array2d<unsigned char> lbp;
+        make_uniform_lbp_image(img, lbp);
+        for (unsigned long i = 0; i < parts.size(); ++i)
+            extract_histogram_descriptors(lbp, parts[i], feats);
+
+        if (num_scales > 1)
+        {
+            pyramid_down<4> pyr;
+            image_type img_temp;
+            pyr(img, img_temp);
+            unsigned long num_pyr_calls = 1;
+
+            // now pull the features out at coarser scales
+            for (unsigned long iter = 1; iter < num_scales; ++iter)
+            {
+                // now do the feature extraction
+                make_uniform_lbp_image(img_temp, lbp);
+                for (unsigned long i = 0; i < parts.size(); ++i)
+                    extract_histogram_descriptors(lbp, pyr.point_down(parts[i],num_pyr_calls), feats);
+
+                if (iter+1 < num_scales)
+                {
+                    pyr(img_temp);
+                    ++num_pyr_calls;
+                }
+            }
+        }
+
+        for (unsigned long i = 0; i < feats.size(); ++i)
+            feats[i] = std::sqrt(feats[i]);
+
+        DLIB_ASSERT(feats.size() == 99120, feats.size());
+    }
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_LBP_Hh_
+

dlib/image_transforms/lbp_abstract.h

+// Copyright (C) 2014  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_LBP_ABSTRACT_Hh_
+#ifdef DLIB_LBP_ABSTRACT_Hh_
+
+#include "../image_processing/generic_image.h"
+#include "../pixel.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename image_type2
+        >
+    void make_uniform_lbp_image (
+        const image_type& img,
+        image_type2& lbp
+    );
+    /*!
+        requires
+            - image_type == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h 
+            - image_type2 == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h 
+            - image_type2 should contain a grayscale pixel type such as unsigned char.
+        ensures
+            - #lbp.nr() == img.nr()
+            - #lbp.nc() == img.nc()
+            - This function extracts the uniform local-binary-pattern feature at every pixel
+              and stores it into #lbp.  In particular, we have the following for all valid 
+              r and c:
+                - #lbp[r][c] == the uniform LBP for the 3x3 pixel window centered on img[r][c].  
+                  In particular, this is a value in the range 0 to 58 inclusive. 
+            - We use the idea of uniform LBPs from the paper: 
+                Face Description with Local Binary Patterns: Application to Face Recognition
+                by Ahonen, Hadid, and Pietikainen.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename T
+        >
+    void extract_histogram_descriptors (
+        const image_type& img,
+        const point& loc,
+        std::vector<T>& histograms,
+        const unsigned int cell_size = 10,
+        const unsigned int block_size = 4,
+        const unsigned int max_val = 58
+    );
+    /*!
+        requires
+            - image_type == an image object that implements the interface defined in
+              dlib/image_processing/generic_image.h 
+            - image_type contains unsigned char valued pixels.
+            - All pixel values in img are <= max_val
+            - cell_size >= 1
+            - block_size >= 1
+            - max_val < 256
+        ensures
+            - This function extracts histograms of pixel values from block_size*block_size
+              windows in the area in img immediately around img[loc.y()][loc.x()].  The
+              histograms are appended onto the end of #histograms.  Each window is
+              cell_size pixels wide and tall.  Moreover, the windows do not overlap.
+            - #histograms.size() == histograms.size() + block_size*block_size*(max_val+1)
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename T
+        >
+    void extract_uniform_lbp_descriptors (
+        const image_type& img,
+        std::vector<T>& feats,
+        const unsigned int cell_size = 10
+    );
+    /*!
+        requires
+            - cell_size >= 1
+        ensures
+            - Extracts histograms of uniform local-binary-patterns from img.  The
+              histograms are densely tiled windows that are cell_size pixels wide and tall.
+              The windows do not overlap and cover all of img.
+            - #feats.size() == 59*(number of windows that fit into img)
+              (i.e. #feats contains the LBP histograms)
+            - We will have taken the square root of all the histogram elements.  That is,
+              #feats[i] is the square root of the number of LBPs that appeared in its
+              corresponding window.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename image_type,
+        typename T
+        >
+    void extract_highdim_face_lbp_descriptors (
+        const image_type& img,
+        const full_object_detection& det,
+        std::vector<T>& feats
+    );
+    /*!
+        requires
+            - det.num_parts() == 68
+        ensures
+            - This function extracts the high-dimensional LBP feature described in the
+              paper:
+                Blessing of Dimensionality: High-dimensional Feature and Its Efficient
+                Compression for Face Verification by Dong Chen, Xudong Cao, Fang Wen, and
+                Jian Sun
+            - #feats == the high-dimensional LBP descriptor.  It is the concatenation of
+              many LBP histograms, each extracted from different scales and from different
+              windows around different face landmarks.  We also take the square root of
+              each histogram element before storing it into #feats.
+            - #feats.size() == 99120
+            - This function assumes img has already been aligned and normalized to a
+              standard size.
+            - This function assumes det contains a human face detection with face parts
+              annotated using the annotation scheme from the iBUG 300-W face landmark
+              dataset.  This means that det.part(i) gives the locations of different face
+              landmarks according to the iBUG 300-W annotation scheme.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_LBP_ABSTRACT_Hh_
+

dlib/statistics.h

@@ -11,6 +11,7 @@
 #include "statistics/cca.h"
 #include "statistics/average_precision.h"
 #include "statistics/vector_normalizer_frobmetric.h"
+#include "statistics/lda.h"
 
 #endif // DLIB_STATISTICs_H_ 
 

dlib/statistics/lda.h

+// Copyright (C) 2014  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_LDA_Hh_
+#define DLIB_LDA_Hh_
+
+#include "lda_abstract.h"
+#include "../algs.h"
+#include <map>
+#include "../matrix.h"
+#include <vector>
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    namespace impl
+    {
+
+        inline std::map<unsigned long,unsigned long> make_class_labels(
+            const std::vector<unsigned long>& row_labels
+        )
+        {
+            std::map<unsigned long,unsigned long> class_labels;
+            for (unsigned long i = 0; i < row_labels.size(); ++i)
+            {
+                const unsigned long next = class_labels.size();
+                if (class_labels.count(row_labels[i]) == 0)
+                    class_labels[row_labels[i]] = next;
+            }
+            return class_labels;
+        }
+
+    // ------------------------------------------------------------------------------------
+
+        template <
+            typename T
+            >
+        matrix<T,0,1> center_matrix (
+            matrix<T>& X
+        )
+        {
+            matrix<T,1> mean;
+            for (long r = 0; r < X.nr(); ++r)
+                mean += rowm(X,r);
+            mean /= X.nr();
+
+            for (long r = 0; r < X.nr(); ++r)
+                set_rowm(X,r) -= mean;
+
+            return trans(mean);
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        >
+    void compute_lda_transform (
+        matrix<T>& X,
+        matrix<T,0,1>& mean,
+        const std::vector<unsigned long>& row_labels,
+        unsigned long lda_dims = 500,
+        unsigned long extra_pca_dims = 200
+    )
+    {
+        std::map<unsigned long,unsigned long> class_labels = impl::make_class_labels(row_labels);
+        // LDA can only give out at most class_labels.size()-1 dimensions so don't try to
+        // compute more than that.
+        lda_dims = std::min(lda_dims, class_labels.size()-1);
+
+        // make sure requires clause is not broken
+        DLIB_CASSERT(class_labels.size() > 1,
+            "\t void compute_lda_transform()"
+            << "\n\t You can't call this function if the number of distinct class labels is less than 2."
+            );
+        DLIB_CASSERT(X.size() != 0 && (long)row_labels.size() == X.nr() && lda_dims != 0,
+            "\t void compute_lda_transform()"
+            << "\n\t Invalid inputs were given to this function."
+            << "\n\t X.size():          " << X.size()
+            << "\n\t row_labels.size(): " << row_labels.size()
+            << "\n\t lda_dims:          " << lda_dims
+            );
+
+
+        mean = impl::center_matrix(X);
+        // Do PCA to reduce dims
+        matrix<T> pu,pw,pv;
+        svd_fast(X, pu, pw, pv, lda_dims+extra_pca_dims, 4);
+        pu.set_size(0,0); // free RAM, we don't need pu.
+        X = X*pv;
+
+
+        matrix<T> class_means(class_labels.size(), X.nc());
+        class_means = 0;
+        matrix<T,0,1> class_counts(class_labels.size());
+        class_counts = 0;
+
+        // First compute the means of each class
+        for (unsigned long i = 0; i < row_labels.size(); ++i)
+        {
+            const unsigned long class_idx = class_labels[row_labels[i]];
+            set_rowm(class_means,class_idx) += rowm(X,i);
+            class_counts(class_idx)++;
+        }
+        class_means = inv(diagm(class_counts))*class_means;
+        // subtract means from the data
+        for (unsigned long i = 0; i < row_labels.size(); ++i)
+        {
+            const unsigned long class_idx = class_labels[row_labels[i]];
+            set_rowm(X,i) -= rowm(class_means,class_idx);
+        }
+
+        // Note that we are using the formulas from the paper Using Discriminant
+        // Eigenfeatures for Image Retrieval by Swets and Weng.
+        matrix<T> Sw = trans(X)*X;
+        matrix<T> Sb = trans(class_means)*class_means;
+        matrix<T> A, H;
+        matrix<T,0,1> W;
+        svd3(Sw, A, W, H);
+        W = sqrt(W);
+        W = reciprocal(round_zeros(W,max(W)*1e-5));
+        A = trans(H*diagm(W))*Sb*H*diagm(W);
+        matrix<T> v,s,u;
+        svd3(A, v, s, u);
+        matrix<T> tform = H*diagm(W)*u;
+        // pick out only the number of dimensions we are supposed to for the output, unless
+        // we should just keep them all, then don't do anything. 
+        if ((long)lda_dims <= tform.nc())
+        {
+            rsort_columns(tform, s);
+            tform = colm(tform, range(0, lda_dims-1));
+        }
+
+        X = trans(pv*tform);
+        mean = X*mean;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    inline std::pair<double,double> compute_equal_error_rate (
+        const std::vector<double>& low_vals,
+        const std::vector<double>& high_vals 
+    )
+    {
+        std::vector<std::pair<double,int> > temp;
+        temp.reserve(low_vals.size()+high_vals.size());
+        for (unsigned long i = 0; i < low_vals.size(); ++i)
+            temp.push_back(std::make_pair(low_vals[i], -1));
+        for (unsigned long i = 0; i < high_vals.size(); ++i)
+            temp.push_back(std::make_pair(high_vals[i], +1));
+
+        std::sort(temp.begin(), temp.end());
+
+        if (temp.size() == 0)
+            return std::make_pair(0,0);
+
+        double thresh = temp[0].first;
+
+        unsigned long num_low_wrong = low_vals.size();
+        unsigned long num_high_wrong = 0;
+        double low_error = num_low_wrong/(double)low_vals.size();
+        double high_error = num_high_wrong/(double)high_vals.size();
+        for (unsigned long i = 0; i < temp.size() && high_error < low_error; ++i)
+        {
+            thresh = temp[i].first;
+            if (temp[i].second > 0)
+            {
+                num_high_wrong++;
+                high_error = num_high_wrong/(double)high_vals.size();
+            }
+            else
+            {
+                num_low_wrong--;
+                low_error = num_low_wrong/(double)low_vals.size();
+            }
+        }
+
+        return std::make_pair((low_error+high_error)/2, thresh);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_LDA_Hh_
+

dlib/statistics/lda_abstract.h

+// Copyright (C) 2014  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_LDA_ABSTRACT_Hh_
+#ifdef DLIB_LDA_ABSTRACT_Hh_
+
+#include <map>
+#include "../matrix.h"
+#include <vector>
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T
+        >
+    void compute_lda_transform (
+        matrix<T>& X,
+        matrix<T,0,1>& M,
+        const std::vector<unsigned long>& row_labels,
+        unsigned long lda_dims = 500,
+        unsigned long extra_pca_dims = 200
+    );
+    /*!
+        requires
+            - X.size() != 0
+            - row_labels.size() == X.nr()
+            - The number of distinct values in row_labels > 1
+            - lda_dims != 0
+        ensures
+            - We interpret X as a collection X.nr() of input vectors, where each row of X
+              is one of the vectors.
+            - We interpret row_labels[i] as the label of the vector rowm(X,i).
+            - This function performs the dimensionality reducing version of Linear
+              discriminant analysis.  That is, you give it a set of labeled vectors and it
+              returns a linear transform that maps the input vectors into a new space that
+              is good for distinguishing between the different classes.  In particular,
+              this function finds matrices Z and M such that:
+                - Given an put vector x, Z*x-M, is the transformed version of x.  That is,
+                  Z*x-M maps x into a space where x vectors that share the same class label
+                  are near each other. 
+                - Z*x-M results in the transformed vectors having zero expected mean.
+                - Z.nr() <= lda_dims
+                  (it might be less than lda_dims if there are not enough distinct class
+                  labels to support lda_dims dimensions).
+                - Z.nc() == X.nc()
+                - We overwrite the input matrix X and store Z in it.  Therefore, the
+                  outputs of this function are in X and M.
+            - In order to deal with very high dimensional inputs, we perform PCA internally
+              to map the input vectors into a space of at most lda_dims+extra_pca_dims
+              prior to performing LDA.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    std::pair<double,double> compute_equal_error_rate (
+        const std::vector<double>& low_vals,
+        const std::vector<double>& high_vals 
+    );
+    /*!
+        ensures
+            - This function finds a threshold T that best separates the elements of
+              low_vals from high_vals by selecting the threshold with equal error rate.  In
+              particular, we try to pick a threshold T such that:
+                - for all valid i:
+                    - high_vals[i] >= T
+                - for all valid i:
+                    - low_vals[i] < T
+              Where the best T is determined such that the fraction of low_vals >= T is the
+              same as the fraction of high_vals < T.
+            - Let ERR == the equal error rate.  I.e. the fraction of times low_vals >= T
+              and high_vals < T.  Note that 0 <= ERR <= 1.
+            - returns make_pair(ERR,T) 
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_LDA_ABSTRACT_Hh_
+
+