Merge branch 'master' into attributes

Josh Klontz
2 parents 4070e564 24aec81e
Showing 21 changed files with 348 additions and 54 deletions
LICENSE.txt
app/br/br.cpp
openbr/core/cluster.cpp
openbr/core/cluster.h
openbr/core/common.cpp
openbr/core/common.h
openbr/core/eigenutils.cpp
openbr/core/eigenutils.h
openbr/core/eval.cpp
openbr/core/qtutils.cpp
openbr/openbr.cpp
openbr/openbr.h
openbr/openbr_plugin.cpp
openbr/plugins/algorithms.cpp
openbr/plugins/eigen3.cpp
openbr/plugins/format.cpp
openbr/plugins/gallery.cpp
openbr/plugins/gui.cpp
openbr/plugins/independent.cpp
openbr/plugins/stream.cpp
-Copyright 2012-2014 The MITRE Corporation
+Copyright 2012 The MITRE Corporation
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -138,8 +138,8 @@ public:
                 check(parc >= 2 && parc <= 4, "Incorrect parameter count for 'evalClassification'.");
                 br_eval_classification(parv[0], parv[1], parc >= 3 ? parv[2] : "", parc >= 4 ? parv[3] : "");
             } else if (!strcmp(fun, "evalClustering")) {
-                check(parc == 2, "Incorrect parameter count for 'evalClustering'.");
-                br_eval_clustering(parv[0], parv[1]);
+                check((parc >= 2) && (parc <= 3), "Incorrect parameter count for 'evalClustering'.");
+                br_eval_clustering(parv[0], parv[1], parc == 3 ? parv[2] : "");
             } else if (!strcmp(fun, "evalDetection")) {
                 check((parc >= 2) && (parc <= 3), "Incorrect parameter count for 'evalDetection'.");
                 br_eval_detection(parv[0], parv[1], parc == 3 ? parv[2] : "");
@@ -100,7 +100,9 @@ Neighborhood getNeighborhood(const QStringList &amp;simmats)
         int currentRows = -1;
         int columnOffset = 0;
         for (int j=0; j<numGalleries; j++) {
-            cv::Mat m = BEE::readMat(simmats[i*numGalleries+j]);
+            QScopedPointer<br::Format> format(br::Factory<br::Format>::make(simmats[i*numGalleries+j]));
+            br::Template t = format->read();
+            cv::Mat m = t.m();
             if (j==0) {
                 currentRows = m.rows;
                 allNeighbors.resize(currentRows);
@@ -115,8 +117,9 @@ Neighborhood getNeighborhood(const QStringList &amp;simmats)
                     float val = m.at<float>(k,l);
                     if ((i==j) && (k==l)) continue; // Skips self-similarity scores
-                    if ((val != -std::numeric_limits<float>::infinity()) &&
-                        (val != std::numeric_limits<float>::infinity())) {
+                    if (val != -std::numeric_limits<float>::max()
+                        && val != -std::numeric_limits<float>::infinity()
+                        && val != std::numeric_limits<float>::infinity()) {
                         globalMax = std::max(globalMax, val);
                         globalMin = std::min(globalMin, val);
                     }
@@ -157,7 +160,7 @@ Neighborhood getNeighborhood(const QStringList &amp;simmats)
 // Zhu et al. "A Rank-Order Distance based Clustering Algorithm for Face Tagging", CVPR 2011
 br::Clusters br::ClusterGallery(const QStringList &simmats, float aggressiveness, const QString &csv)
 {
-    qDebug("Clustering %d simmat(s)", simmats.size());
+    qDebug("Clustering %d simmat(s), aggressiveness %f", simmats.size(), aggressiveness);
     // Read in gallery parts, keeping top neighbors of each template
     Neighborhood neighborhood = getNeighborhood(simmats);
@@ -275,13 +278,14 @@ float jaccardIndex(const QVector&lt;int&gt; &amp;indicesA, const QVector&lt;int&gt; &amp;indicesB)
 // Evaluates clustering algorithms based on metrics described in
 // Santo Fortunato "Community detection in graphs", Physics Reports 486 (2010)
-void br::EvalClustering(const QString &csv, const QString &input)
+void br::EvalClustering(const QString &csv, const QString &input, QString truth_property)
 {
+    if (truth_property.isEmpty())
+        truth_property = "Label";
     qDebug("Evaluating %s against %s", qPrintable(csv), qPrintable(input));
-    // We assume clustering algorithms store assigned cluster labels as integers (since the clusters are
-    // not named). Direct use of ClusterID is not general -cao
-    QList<int> labels = File::get<int>(TemplateList::fromGallery(input), "ClusterID");
+    TemplateList tList = TemplateList::fromGallery(input);
+    QList<int> labels = tList.indexProperty(truth_property);
     QHash<int, int> labelToIndex;
     int nClusters = 0;
@@ -28,7 +28,7 @@ namespace br
     typedef QVector<Cluster> Clusters;
     Clusters ClusterGallery(const QStringList &simmats, float aggressiveness, const QString &csv);
-    void EvalClustering(const QString &csv, const QString &input);
+    void EvalClustering(const QString &csv, const QString &input, QString truth_property);
     Clusters ReadClusters(const QString &csv);
     void WriteClusters(const Clusters &clusters, const QString &csv);
@@ -76,3 +76,11 @@ QList&lt;float&gt; Common::linspace(float start, float stop, int n) {
     spaced.append(stop);
     return spaced;
 }
+
+QList<int> Common::ind2sub(int dims, int nPerDim, int idx) {
+    QList<int> subIndices;
+    for (int j = 0; j < dims; j++) {
+        subIndices.append(((int)floor( idx / pow((float)nPerDim, j))) % nPerDim);
+    }
+    return subIndices;
+}
@@ -335,6 +335,10 @@ V&lt;T&gt; Downsample(V&lt;T&gt; vals, int k)
     return newVals;
 }
+/*! \brief Converts index into subdimensions.
+*/
+QList<int> ind2sub(int dims, int nPerDim, int idx);
+
 }
 #endif // COMMON_COMMON_H
@@ -67,3 +67,12 @@ void printEigen(Eigen::MatrixXf X) {
 void printSize(Eigen::MatrixXf X) {
     qDebug() << "Rows=" << X.rows() << "\tCols=" << X.cols();
 }
+
+float eigMean(const Eigen::MatrixXf& x) {
+    return x.array().sum() / (x.rows() * x.cols());
+}
+
+float eigStd(const Eigen::MatrixXf& x) {
+    float mean = eigMean(x);
+    return sqrt((x.array() - mean).pow(2).sum() / (x.cols() * x.rows()));
+}
@@ -67,4 +67,55 @@ inline QDataStream &amp;operator&gt;&gt;(QDataStream &amp;stream, Eigen::Matrix&lt; _Scalar, _Row
     return stream;
 }
+/*Compute the mean of the each column (dim == 1) or row (dim == 2)
+  of the matrix*/
+template<typename T>
+Eigen::MatrixBase<T> eigMean(const Eigen::MatrixBase<T>& x,int dim)
+{
+    if (dim == 1) {
+        Eigen::MatrixBase<T> y(1,x.cols());
+        for (int i = 0; i < x.cols(); i++)
+            y(i) = x.col(i).sum() / x.rows();
+        return y;
+    } else if (dim == 2) {
+        Eigen::MatrixBase<T> y(x.rows(),1);
+        for (int i = 0; i < x.rows(); i++)
+            y(i) = x.row(i).sum() / x.cols();
+        return y;
+    }
+    qFatal("A matrix can only have two dimensions");
+}
+
+/*Compute the element-wise mean*/
+float eigMean(const Eigen::MatrixXf& x);
+/*Compute the element-wise mean*/
+float eigStd(const Eigen::MatrixXf& x);
+
+/*Compute the std dev of the each column (dim == 1) or row (dim == 2)
+  of the matrix*/
+template<typename T>
+Eigen::MatrixBase<T> eigStd(const Eigen::MatrixBase<T>& x,int dim)
+{
+    Eigen::MatrixBase<T> mean = eigMean(x, dim);
+    if (dim == 1) {
+        Eigen::MatrixBase<T> y(1,x.cols());
+        for (int i = 0; i < x.cols(); i++) {
+            T value = 0;
+            for (int j = 0; j < x.rows(); j++)
+                value += pow(y(j, i) - mean(i), 2);
+            y(i) = sqrt(value / (x.rows() - 1));
+        }
+        return y;
+    } else if (dim == 2) {
+        Eigen::MatrixBase<T> y(x.rows(),1);
+        for (int i = 0; i < x.rows(); i++) {
+            T value = 0;
+            for (int j = 0; j < x.cols(); j++)
+                value += pow(y(i, j) - mean(j), 2);
+            y(i) = sqrt(value / (x.cols() - 1));
+        }
+        return y;
+    }
+    qFatal("A matrix can only have two dimensions");
+}
 #endif // EIGENUTILS_H
@@ -572,6 +572,7 @@ float EvalLandmarking(const QString &amp;predictedGallery, const QString &amp;truthGalle
     const QStringList predictedNames = File::get<QString>(predicted, "name");
     const QStringList truthNames = File::get<QString>(truth, "name");
+    int skipped = 0;
     QList< QList<float> > pointErrors;
     for (int i=0; i<predicted.size(); i++) {
         const QString &predictedName = predictedNames[i];
@@ -579,7 +580,10 @@ float EvalLandmarking(const QString &amp;predictedGallery, const QString &amp;truthGalle
         if (truthIndex == -1) qFatal("Could not identify ground truth for file: %s", qPrintable(predictedName));
         const QList<QPointF> predictedPoints = predicted[i].file.points();
         const QList<QPointF> truthPoints = truth[truthIndex].file.points();
-        if (predictedPoints.size() != truthPoints.size()) qFatal("Points size mismatch for file: %s", qPrintable(predictedName));
+        if (predictedPoints.size() != truthPoints.size()) {
+            skipped++;
+            continue;
+        }
         while (pointErrors.size() < predictedPoints.size())
             pointErrors.append(QList<float>());
         if (normalizationIndexA >= truthPoints.size()) qFatal("Normalization index A is out of range.");
@@ -588,6 +592,7 @@ float EvalLandmarking(const QString &amp;predictedGallery, const QString &amp;truthGalle
         for (int j=0; j<predictedPoints.size(); j++)
             pointErrors[j].append(QtUtils::euclideanLength(predictedPoints[j] - truthPoints[j])/normalizedLength);
     }
+    qDebug() << "Skipped " << skipped << " files do to point size mismatch.";
     QList<float> averagePointErrors; averagePointErrors.reserve(pointErrors.size());
     for (int i=0; i<pointErrors.size(); i++) {
@@ -605,6 +610,8 @@ float EvalLandmarking(const QString &amp;predictedGallery, const QString &amp;truthGalle
             lines.append(QString("Box,%1,%2").arg(QString::number(i), QString::number(pointError[j*(pointError.size()-1)/(keep-1)])));
     }
+    lines.append(QString("AvgError,0,%1").arg(averagePointError));
+
     QtUtils::writeFile(csv, lines);
     qDebug("Average Error: %.3f", averagePointError);
     return averagePointError;
@@ -24,6 +24,7 @@
 #include <QProcess>
 #include <QProcessEnvironment>
 #include <QRegExp>
+#include <QRegularExpression>
 #include <QStack>
 #include <QUrl>
 #include <QMap>
@@ -81,7 +82,7 @@ void readFile(const QString &amp;file, QStringList &amp;lines)
 {
     QByteArray data;
     readFile(file, data);
-    lines = QString(data).split('\n', QString::SkipEmptyParts);
+    lines = QString(data).split(QRegularExpression("[\n|\r\n|\r]"), QString::SkipEmptyParts);
     for (int i=0; i<lines.size(); i++)
         lines[i] = lines[i].simplified();
 }
@@ -109,9 +109,9 @@ void br_eval_classification(const char *predicted_gallery, const char *truth_gal
     EvalClassification(predicted_gallery, truth_gallery, predicted_property, truth_property);
 }
-void br_eval_clustering(const char *csv, const char *gallery)
+void br_eval_clustering(const char *csv, const char *gallery, const char * truth_property)
 {
-    EvalClustering(csv, gallery);
+    EvalClustering(csv, gallery, truth_property);
 }
 float br_eval_detection(const char *predicted_gallery, const char *truth_gallery, const char *csv)
@@ -435,7 +435,14 @@ br_template_list br_load_from_gallery(br_gallery gallery)
     return (br_template_list)tl;
 }
-void br_add_to_gallery(br_gallery gallery, br_template_list tl)
+void br_add_template_to_gallery(br_gallery gallery, br_template tmpl)
+{
+    Gallery *gal = reinterpret_cast<Gallery*>(gallery);
+    Template *t = reinterpret_cast<Template*>(tmpl);
+    gal->write(*t);
+}
+
+void br_add_template_list_to_gallery(br_gallery gallery, br_template_list tl)
 {
     Gallery *gal = reinterpret_cast<Gallery*>(gallery);
     TemplateList *realTL = reinterpret_cast<TemplateList*>(tl);
@@ -167,9 +167,10 @@ BR_EXPORT void br_eval_classification(const char *predicted_gallery, const char 
  * \brief Evaluates and prints clustering accuracy to the terminal.
  * \param csv The cluster results file.
  * \param gallery The br::Gallery used to generate the \ref simmat that was clustered.
+ * \param truth_property (Optional) which metadata key to use from <i>gallery</i/>, defaults to Label
  * \see br_cluster
  */
-BR_EXPORT void br_eval_clustering(const char *csv, const char *gallery);
+BR_EXPORT void br_eval_clustering(const char *csv, const char *gallery, const char * truth_property);
 /*!
  * \brief Evaluates and prints detection accuracy to terminal.
@@ -562,9 +563,13 @@ BR_EXPORT br_gallery br_make_gallery(const char *gallery);
   */
 BR_EXPORT br_template_list br_load_from_gallery(br_gallery gallery);
 /*!
+  * \brief Write a br::Template to the br::Gallery on disk.
+  */
+BR_EXPORT void br_add_template_to_gallery(br_gallery gallery, br_template tmpl);
+/*!
   * \brief Write a br::TemplateList to the br::Gallery on disk.
   */
-BR_EXPORT void br_add_to_gallery(br_gallery gallery, br_template_list tl);
+BR_EXPORT void br_add_template_list_to_gallery(br_gallery gallery, br_template_list tl);
 /*!
   * \brief Close the br::Gallery.
   */
@@ -137,6 +137,8 @@ QVariant File::parse(const QString &amp;value)
     if (ok) return point;
     const QRectF rect = QtUtils::toRect(value, &ok);
     if (ok) return rect;
+    const int i = value.toInt(&ok);
+    if (ok) return i;
     const float f = value.toFloat(&ok);
     if (ok) return f;
     return value;
@@ -44,7 +44,7 @@ class AlgorithmsInitializer : public Initializer
         Globals->abbreviations.insert("AgeEstimation", "AgeRegression");
         Globals->abbreviations.insert("FaceRecognition2", "{PP5Register+Affine(128,128,0.25,0.35)+Cvt(Gray)}+(Gradient+Bin(0,360,9,true))/(Blur(1)+Gamma(0.2)+DoG(1,2)+ContrastEq(0.1,10)+LBP(1,2,true)+Bin(0,10,10,true))+Merge+Integral+RecursiveIntegralSampler(4,2,8,LDA(.98)+Normalize(L1))+Cat+PCA(768)+Normalize(L1)+Quantize:UCharL1");
         Globals->abbreviations.insert("CropFace", "Open+Cvt(Gray)+Cascade(FrontalFace)+ASEFEyes+Affine(128,128,0.25,0.35)");
-        Globals->abbreviations.insert("4SF", "Open+Cvt(Gray)+Cascade(FrontalFace)+ASEFEyes+Affine(128,128,0.33,0.45)+(Grid(10,10)+SIFTDescriptor(12)+ByRow)/(Blur(1.1)+Gamma(0.2)+DoG(1,2)+ContrastEq(0.1,10)+LBP(1,2)+RectRegions(8,8,6,6)+Hist(59))+PCA(0.95)+Normalize(L2)+Dup(12)+RndSubspace(0.05,1)+LDA(0.98)+Cat+PCA(0.95)+Normalize(L1)+Quantize:NegativeLogPlusOne(ByteL1)");
+        Globals->abbreviations.insert("4SF", "Open+Cvt(Gray)+Cascade(FrontalFace)+ASEFEyes+Affine(128,128,0.33,0.45)+(Grid(10,10)+SIFTDescriptor(12)+ByRow)/(Blur(1.1)+Gamma(0.2)+DoG(1,2)+ContrastEq(0.1,10)+LBP(1,2)+RectRegions(8,8,6,6)+Hist(59))+PCA(0.95)+Cat+Normalize(L2)+Dup(12)+RndSubspace(0.05,1)+LDA(0.98)+Cat+PCA(0.95)+Normalize(L1)+Quantize:NegativeLogPlusOne(ByteL1)");
         // Video
         Globals->abbreviations.insert("DisplayVideo", "Stream(FPSLimit(30)+Show(false,[FrameNumber])+Discard)");
@@ -64,6 +64,7 @@ class AlgorithmsInitializer : public Initializer
         Globals->abbreviations.insert("SmallSIFT", "Open+LimitSize(512)+KeyPointDetector(SIFT)+KeyPointDescriptor(SIFT):KeyPointMatcher(BruteForce)");
         Globals->abbreviations.insert("SmallSURF", "Open+LimitSize(512)+KeyPointDetector(SURF)+KeyPointDescriptor(SURF):KeyPointMatcher(BruteForce)");
         Globals->abbreviations.insert("ColorHist", "Open+LimitSize(512)+Expand+EnsureChannels(3)+SplitChannels+Hist(256,0,8)+Cat+Normalize(L1):L2");
+        Globals->abbreviations.insert("ImageSimilarity", "Open+EnsureChannels(3)+Resize(256,256)+SplitChannels+RectRegions(64,64,64,64)+Hist(256,0,8)+Cat:NegativeLogPlusOne(L2)");
         Globals->abbreviations.insert("ImageClassification", "Open+CropSquare+LimitSize(256)+Cvt(Gray)+Gradient+Bin(0,360,9,true)+Merge+Integral+RecursiveIntegralSampler(4,2,8,Singleton(KMeans(256)))+Cat+CvtFloat+Hist(256)+KNN(5,Dist(L1),false,5)+Rename(KNN,Subject)");
         Globals->abbreviations.insert("TanTriggs", "Blur(1.1)+Gamma(0.2)+DoG(1,2)+ContrastEq(0.1,10)");
@@ -15,15 +15,35 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 #include <Eigen/Dense>
+
 #include "openbr_internal.h"
 #include "openbr/core/common.h"
 #include "openbr/core/eigenutils.h"
+#include "openbr/core/opencvutils.h"
 namespace br
 {
 /*!
+ * \ingroup initializers
+ * \brief Initialize Eigen
+ * http://eigen.tuxfamily.org/dox/TopicMultiThreading.html
+ * \author Scott Klum \cite sklum
+ */
+class EigenInitializer : public Initializer
+{
+    Q_OBJECT
+
+    void initialize() const
+    {
+        Eigen::initParallel();
+    }
+};
+
+BR_REGISTER(Initializer, EigenInitializer)
+
+/*!
  * \ingroup transforms
  * \brief Projects input into learned Principal Component Analysis subspace.
  * \author Brendan Klare \cite bklare
@@ -296,6 +316,8 @@ BR_REGISTER(Transform, DFFSTransform)
  */
 class LDATransform : public Transform
 {
+    friend class SparseLDATransform;
+
     Q_OBJECT
     Q_PROPERTY(float pcaKeep READ get_pcaKeep WRITE set_pcaKeep RESET reset_pcaKeep STORED false)
     Q_PROPERTY(bool pcaWhiten READ get_pcaWhiten WRITE set_pcaWhiten RESET reset_pcaWhiten STORED false)
@@ -499,21 +521,30 @@ class LDATransform : public Transform
         // Do projection
         outMap = projection.transpose() * (inMap - mean);
-
         if (normalize && isBinary)
             dst.m().at<float>(0,0) = dst.m().at<float>(0,0) / stdDev;
     }
     void store(QDataStream &stream) const
     {
-        stream << pcaKeep << directLDA << directDrop << dimsOut << mean << projection;
+        stream << pcaKeep;
+        stream << directLDA;
+        stream << directDrop;
+        stream << dimsOut;
+        stream << mean;
+        stream << projection;
         if (normalize && isBinary)
             stream << stdDev;
     }
     void load(QDataStream &stream)
     {
-        stream >> pcaKeep >> directLDA >> directDrop >> dimsOut >> mean >> projection;
+        stream >> pcaKeep;
+        stream >> directLDA;
+        stream >> directDrop;
+        stream >> dimsOut;
+        stream >> mean;
+        stream >> projection;
         if (normalize && isBinary)
             stream >> stdDev;
     }
@@ -522,6 +553,104 @@ class LDATransform : public Transform
 BR_REGISTER(Transform, LDATransform)
 /*!
+ * \ingroup transforms
+ * \brief Projects input into learned Linear Discriminant Analysis subspace
+ *          learned on a sparse subset of features with the highest weight
+ *          in the original LDA algorithm.
+ * \author Brendan Klare \cite bklare
+ */
+class SparseLDATransform : public Transform
+{
+    Q_OBJECT
+    Q_PROPERTY(float varThreshold READ get_varThreshold WRITE set_varThreshold RESET reset_varThreshold STORED false)
+    Q_PROPERTY(float pcaKeep READ get_pcaKeep WRITE set_pcaKeep RESET reset_pcaKeep STORED false)
+    Q_PROPERTY(bool normalize READ get_normalize WRITE set_normalize RESET reset_normalize STORED false)
+    BR_PROPERTY(float, varThreshold, 1.5)
+    BR_PROPERTY(float, pcaKeep, 0.98)
+    BR_PROPERTY(bool, normalize, true)
+
+    LDATransform ldaSparse;
+    int dimsOut;
+    QList<int> selections;
+
+    Eigen::VectorXf mean;
+
+    void init()
+    {
+        ldaSparse.init();
+        ldaSparse.pcaKeep = pcaKeep;
+        ldaSparse.inputVariable = "Label";
+        ldaSparse.isBinary = true;
+        ldaSparse.normalize = true;
+    }
+
+    void train(const TemplateList &_trainingSet)
+    {
+
+        LDATransform ldaOrig;
+        ldaOrig.init();
+        ldaOrig.inputVariable = "Label";
+        ldaOrig.pcaKeep = pcaKeep;
+        ldaOrig.isBinary = true;
+        ldaOrig.normalize = true;
+
+        ldaOrig.train(_trainingSet);
+
+        //Only works on binary class problems for now
+        assert(ldaOrig.projection.cols() == 1);
+        float ldaStd = eigStd(ldaOrig.projection);
+        for (int i = 0; i < ldaOrig.projection.rows(); i++)
+            if (abs(ldaOrig.projection(i)) > varThreshold * ldaStd)
+                selections.append(i);
+
+        TemplateList newSet;
+        for (int i = 0; i < _trainingSet.size(); i++) {
+            cv::Mat x(_trainingSet[i]);
+            cv::Mat y = cv::Mat(selections.size(), 1, CV_32FC1);
+            int idx = 0;
+            int cnt = 0;
+            for (int j = 0; j < x.rows; j++)
+                for (int k = 0; k < x.cols; k++, cnt++)
+                    if (selections.contains(cnt))
+                        y.at<float>(idx++,0) = x.at<float>(j, k);
+            newSet.append(Template(_trainingSet[i].file, y));
+        }
+        ldaSparse.train(newSet);
+        dimsOut = ldaSparse.dimsOut;
+    }
+
+    void project(const Template &src, Template &dst) const
+    {
+        Eigen::Map<Eigen::MatrixXf> inMap((float*)src.m().ptr<float>(), src.m().rows*src.m().cols, 1);
+        Eigen::Map<Eigen::MatrixXf> outMap(dst.m().ptr<float>(), dimsOut, 1);
+
+        int d = selections.size();
+        cv::Mat inSelect(d,1,CV_32F);
+        for (int i = 0; i < d; i++)
+            inSelect.at<float>(i) = src.m().at<float>(selections[i]);
+        ldaSparse.project(Template(src.file, inSelect), dst);
+    }
+
+    void store(QDataStream &stream) const
+    {
+        stream << pcaKeep;
+        stream << ldaSparse;
+        stream << dimsOut;
+        stream << selections;
+    }
+
+    void load(QDataStream &stream)
+    {
+        stream >> pcaKeep;
+        stream >> ldaSparse;
+        stream >> dimsOut;
+        stream >> selections;
+    }
+};
+
+BR_REGISTER(Transform, SparseLDATransform)
+
+/*!
  * \ingroup distances
  * \brief L1 distance computed using eigen.
  * \author Josh Klontz \cite jklontz
@@ -151,7 +151,7 @@ class csvFormat : public Format
     {
         QFile f(file.name);
         f.open(QFile::ReadOnly);
-        QStringList lines(QString(f.readAll()).split('\n'));
+        QStringList lines(QString(f.readAll()).split(QRegularExpression("[\n|\r\n|\r]"), QString::SkipEmptyParts));
         f.close();
         bool isUChar = true;
@@ -506,29 +506,78 @@ BR_REGISTER(Gallery, csvGallery)
  * \brief Treats each line as a file.
  * \author Josh Klontz \cite jklontz
  *
- * The entire line is treated as the file path.
+ * The entire line is treated as the file path. An optional label may be specified using a space ' ' separator:
  *
+\verbatim
+<FILE>
+<FILE>
+...
+<FILE>
+\endverbatim
+ * or
+\verbatim
+<FILE> <LABEL>
+<FILE> <LABEL>
+...
+<FILE> <LABEL>
+\endverbatim
  * \see csvGallery
  */
 class txtGallery : public Gallery
 {
     Q_OBJECT
-    Q_PROPERTY(QString metadataKey READ get_metadataKey WRITE set_metadataKey RESET reset_metadataKey STORED false)
-    BR_PROPERTY(QString, metadataKey, "")
+    Q_PROPERTY(QString label READ get_label WRITE set_label RESET reset_label STORED false)
+    BR_PROPERTY(QString, label, "")
     QStringList lines;
     ~txtGallery()
     {
-        if (!lines.isEmpty()) QtUtils::writeFile(file.name, lines);
+        if (!lines.isEmpty())
+            QtUtils::writeFile(file.name, lines);
     }
     TemplateList readBlock(bool *done)
     {
-        *done = true;
         TemplateList templates;
-        if (!file.exists()) return templates;
+        foreach (const QString &line, QtUtils::readLines(file)) {
+            int splitIndex = line.lastIndexOf(' ');
+            if (splitIndex == -1) templates.append(File(line));
+            else                  templates.append(File(line.mid(0, splitIndex), line.mid(splitIndex+1)));
+        }
+        *done = true;
+        return templates;
+    }
+
+    void write(const Template &t)
+    {
+        QString line = t.file.name;
+        if (!label.isEmpty())
+            line += " " + t.file.get<QString>(label);
+        lines.append(line);
+    }
+};
+BR_REGISTER(Gallery, txtGallery)
+/*!
+ * \ingroup galleries
+ * \brief Treats each line as a call to File::flat()
+ * \author Josh Klontz \cite jklontz
+ */
+class flatGallery : public Gallery
+{
+    Q_OBJECT
+    QStringList lines;
+
+    ~flatGallery()
+    {
+        if (!lines.isEmpty())
+            QtUtils::writeFile(file.name, lines);
+    }
+
+    TemplateList readBlock(bool *done)
+    {
+        TemplateList templates;
         foreach (const QString &line, QtUtils::readLines(file))
             templates.append(File(line));
         *done = true;
@@ -537,11 +586,11 @@ class txtGallery : public Gallery
     void write(const Template &t)
     {
-        lines.append(metadataKey.isEmpty() ? t.file.flat() : t.file.get<QString>(metadataKey));
+        lines.append(t.file.flat());
     }
 };
-BR_REGISTER(Gallery, txtGallery)
+BR_REGISTER(Gallery, flatGallery)
 /*!
  * \ingroup galleries
@@ -687,7 +736,9 @@ class dbGallery : public Gallery
         if (!subset.isEmpty()) {
             const QStringList &words = subset.split(":");
             QtUtils::checkArgsSize("Input", words, 2, 4);
-            seed = QtUtils::toInt(words[0]);
+            if      (words[0] == "train") seed = 0;
+            else if (words[0] == "test" ) seed = 1;
+            else                          seed = QtUtils::toInt(words[0]);
             if (words[1].startsWith('{') && words[1].endsWith('}')) {
                 foreach (const QString &regexp, words[1].mid(1, words[1].size()-2).split(","))
                     metadataFields.append(QRegExp(regexp));
@@ -813,16 +864,10 @@ class googleGallery : public Gallery
         return templates;
     }
-    void write(const Template &t)
+    void write(const Template &)
     {
-        (void) t;
         qFatal("Not supported.");
     }
-
-    void init()
-    {
-        //
-    }
 };
 BR_REGISTER(Gallery, googleGallery)
@@ -413,13 +413,13 @@ private:
 };
-class DisplayGUI : public QMainWindow
+class GUIWindow : public QMainWindow
 {
     Q_OBJECT
 public:
-    DisplayGUI(QWidget * parent = NULL) : QMainWindow(parent)
+    GUIWindow(QWidget * parent = NULL) : QMainWindow(parent)
     {
         centralWidget = new QWidget();
         layout = new QHBoxLayout();
@@ -592,8 +592,10 @@ public:
     template<typename WindowType>
     void initActual()
     {
-        if (!Globals->useGui)
+        if (!Globals->useGui) {
+            qWarning("GUI transform %s created without enabling GUI support.\nRun \"br -gui ...\" to enable GUI support from the command line, or set\nGlobals->useGui to true.", this->metaObject()->className());
             return;
+        }
         if (displayBuffer)
             delete displayBuffer;
@@ -795,7 +797,7 @@ class ElicitTransform : public ShowTransform
     Q_OBJECT
-    DisplayGUI *gui;
+    GUIWindow *gui;
 public:
     ElicitTransform() : ShowTransform()
@@ -835,14 +837,16 @@ public:
     void init()
     {
-        initActual<DisplayGUI>();
+        initActual<GUIWindow>();
     }
     template<typename GUIType>
     void initActual()
     {
-        if (!Globals->useGui)
+        if (!Globals->useGui) {
+            qWarning("GUI transform %s created without enabling GUI support.\nRun \"br -gui ...\" to enable GUI support from the command line, or set\nGlobals->useGui to true.", this->metaObject()->className());
             return;
+        }
         TimeVaryingTransform::init();
@@ -9,13 +9,14 @@ using namespace cv;
 namespace br
 {
-static TemplateList Downsample(const TemplateList &templates, int classes, int instances, float fraction, const QString & inputVariable, const QStringList &gallery)
+static TemplateList Downsample(const TemplateList &templates, int classes, int instances, float fraction, const QString & inputVariable, const QStringList &gallery, const QStringList &subjects)
 {
     // Return early when no downsampling is required
     if ((classes == std::numeric_limits<int>::max()) &&
             (instances == std::numeric_limits<int>::max()) &&
             (fraction >= 1) &&
-            (gallery.isEmpty()))
+            (gallery.isEmpty()) &&
+            (subjects.isEmpty()))
         return templates;
     const bool atLeast = instances < 0;
@@ -67,6 +68,11 @@ static TemplateList Downsample(const TemplateList &amp;templates, int classes, int i
             if (!gallery.contains(downsample[i].file.get<QString>("Gallery")))
                 downsample.removeAt(i);
+    if (!subjects.isEmpty())
+        for (int i=downsample.size()-1; i>=0; i--)
+            if (subjects.contains(downsample[i].file.get<QString>(inputVariable)))
+                downsample.removeAt(i);
+
     return downsample;
 }
@@ -79,12 +85,15 @@ class DownsampleTrainingTransform : public Transform
     Q_PROPERTY(float fraction READ get_fraction WRITE set_fraction RESET reset_fraction STORED false)
     Q_PROPERTY(QString inputVariable READ get_inputVariable WRITE set_inputVariable RESET reset_inputVariable STORED false)
     Q_PROPERTY(QStringList gallery READ get_gallery WRITE set_gallery RESET reset_gallery STORED false)
+    Q_PROPERTY(QStringList subjects READ get_subjects WRITE set_subjects RESET reset_subjects STORED false)
     BR_PROPERTY(br::Transform*, transform, NULL)
     BR_PROPERTY(int, classes, std::numeric_limits<int>::max())
     BR_PROPERTY(int, instances, std::numeric_limits<int>::max())
     BR_PROPERTY(float, fraction, 1)
     BR_PROPERTY(QString, inputVariable, "Label")
     BR_PROPERTY(QStringList, gallery, QStringList())
+    BR_PROPERTY(QStringList, subjects, QStringList())
+
     void project(const Template & src, Template & dst) const
     {
@@ -97,7 +106,7 @@ class DownsampleTrainingTransform : public Transform
         if (!transform || !transform->trainable)
             return;
-        TemplateList downsampled = Downsample(data, classes, instances, fraction, inputVariable, gallery);
+        TemplateList downsampled = Downsample(data, classes, instances, fraction, inputVariable, gallery, subjects);
         transform->train(downsampled);
     }
@@ -1285,11 +1285,18 @@ public:
             qWarning("Attempted to train untrainable transform, nothing will happen.");
             return;
         }
+        QList<TemplateList> separated;
+        foreach (const TemplateList & list, data) {
+            foreach(const Template & t, list) {
+                separated.append(TemplateList());
+                separated.last().append(t);
+            }
+        }
         for (int i=0; i < transforms.size(); i++) {
             // OK we have a trainable transform, we need to get input data for it.
             if (transforms[i]->trainable) {
-                QList<TemplateList> copy = data;
+                QList<TemplateList> copy = separated;
                 // Project from the start to the trainable stage.
                 subProject(copy,i);
@@ -1308,7 +1315,7 @@ public:
         in.append(src);
         TemplateList out;
         CompositeTransform::project(in,out);
-        dst = out.first();
+        if (!out.isEmpty()) dst = out.first();
         if (out.size() > 1)
             qDebug("Returning first output template only");
     }
@@ -1319,7 +1326,7 @@ public:
         in.append(src);
         TemplateList out;
         projectUpdate(in,out);
-        dst = out.first();
+        if (!out.isEmpty()) dst = out.first();
         if (out.size() > 1)
             qDebug("Returning first output template only");
     }
@@ -58,7 +58,7 @@ def init_brpy(br_loc=&#39;/usr/local/lib&#39;):
     br.br_eval.argtypes = _string_args(3)
     br.br_eval.restype = c_float
     br.br_eval_classification.argtypes = _string_args(4)
-    br.br_eval_clustering.argtypes = _string_args(2)
+    br.br_eval_clustering.argtypes = _string_args(3)
     br.br_eval_detection.argtypes = _string_args(3)
     br.br_eval_detection.restype = c_float
     br.br_eval_landmarking.argtypes = _string_args(3) + [c_int, c_int]
@@ -143,7 +143,8 @@ def init_brpy(br_loc=&#39;/usr/local/lib&#39;):
     br.br_make_gallery.restype = c_void_p
     br.br_load_from_gallery.argtypes = [c_void_p]
     br.br_load_from_gallery.restype = c_void_p
-    br.br_add_to_gallery.argtypes = [c_void_p, c_void_p]
+    br.br_add_template_to_gallery.argtypes = [c_void_p, c_void_p]
+    br.br_add_template_list_to_gallery.argtypes = [c_void_p, c_void_p]
     br.br_close_gallery.argtypes = [c_void_p]
     return br