Openbr docs app

app/CMakeLists.txt

@@ -8,5 +8,7 @@ if(NOT BR_PACKAGE_THIRDPARTY)
 
     # Build additional OpenBR utilities
     add_subdirectory(br-gui)
+
+    add_subdirectory(br-docs)
   endif()
 endif()

app/br-docs/CMakeLists.txt

@@ -0,0 +1,9 @@
+include_directories(${CMAKE_CURRENT_BINARY_DIR})
+add_executable(br-docs br-docs.cpp ${BR_RESOURCES})
+
+foreach(QT_DEPENDENCY IN LISTS QT_DEPENDENCIES)
+  target_link_libraries(br-docs "Qt6::${QT_DEPENDENCY}")
+endforeach()
+
+target_link_libraries(br-docs openbr ${BR_THIRDPARTY_LIBS} opencv_core)
+install(TARGETS br-docs RUNTIME DESTINATION bin)

app/br-docs/br-docs.cpp

@@ -0,0 +1,27 @@
+
+#include <QRegularExpression>
+#include <stdio.h>
+
+#include <openbr/openbr_plugin.h>
+
+int main(int argc, char *argv[])
+{
+    QRegularExpression regex;
+
+    for (int i = 1; i < argc; i++) {
+        QString arg = QString::fromLocal8Bit(argv[i]);
+        if (arg == "--help" || arg == "-h") {
+            printf("Usage: br-docs\n");
+            printf("  --regex <pattern>   Only generate docs for transforms matching <pattern>\n");
+            return 0;
+        } else if (arg == "--regex") {
+          regex = QRegularExpression(QString::fromLocal8Bit(argv[++i]));
+        }
+    }
+
+    br::Context::initialize(argc, argv);
+
+    br::AllDocs(regex);
+
+    br::Context::finalize();
+}

app/br/br.cpp

@@ -210,6 +210,9 @@ class FakeMain : public QRunnable
             else if (!strcmp(fun, "help")) {
                 check(parc == 0, "No parameters expected for 'help'.");
                 help();
+            } else if (!strcmp(fun, "docs")) {
+                check(parc == 0, "No parameters expected for 'docs'.");
+                br_docs();
             } else if (!strcmp(fun, "gui")) {
                 // Do nothing because we checked for this flag prior to initialization
             } else if (!strcmp(fun, "objects")) {

openbr/core/core.cpp

@@ -45,12 +45,11 @@ struct AlgorithmCore
 
     AlgorithmCore(const QString &name)
     {
-        if (name == "algorithm") {
-            this->name = Globals->algorithm;
-            init(Globals->algorithm);
-        } else {
-            this->name = name;
-            init(name);
+        this->name = name == "algorithm" ? Globals->algorithm : name;
+        try {
+            init(this->name);
+        } catch (...) {
+            qFatal("Failed to initialize%s: %s", qPrintable(name == "algorithm" ? " algorithm" : ""), qPrintable(this->name));
         }
 
         progressCounter = QSharedPointer<Transform>(Transform::make("ProgressCounter", NULL));
@@ -653,6 +652,28 @@ void br::Train(const File &input, const File &model)
     AlgorithmManager::getAlgorithm(model.get<QString>("algorithm"))->train(input, model);
 }
 
+void br::Docs()
+{
+    AlgorithmManager::getAlgorithm("algorithm")->transform->docs(0);
+}
+
+void br::AllDocs(QRegularExpression regex)
+{
+    QStringList names = Factory<Transform>::names();
+    printf("Registered Transforms: %d\n", names.size());
+
+    foreach (const QString &name, names) {
+        if (!regex.pattern().isEmpty() && !regex.match(name).hasMatch())
+            continue;
+        try {
+            br::Transform* transform = br::Factory<br::Transform>::make("." + name);
+            transform->docs(4);
+        } catch (...) {
+            printf("    %s(???)\n", name.toStdString().c_str());
+        }
+    }
+}
+
 void br::Enroll(const File &input, const File &gallery)
 {
     AlgorithmManager::getAlgorithm(gallery.get<QString>("algorithm"))->enroll(input, gallery);

openbr/openbr.cpp

@@ -151,6 +151,11 @@ void br_eval_eer(const char *predicted_xml, const char *gt_property, const char
     EvalEER(predicted_xml, gt_property, distribution_property, pdf);
 }
 
+void br_docs()
+{
+    Docs();
+}
+
 void br_finalize()
 {
     Context::finalize();
@@ -293,7 +298,11 @@ void br_set_header(const char *matrix, const char *target_gallery, const char *q
 
 void br_set_property(const char *key, const char *value)
 {
-    Globals->setProperty(key, value);
+    try {
+        Globals->setProperty(key, value);
+    } catch (...) {
+        qFatal("Failed to set property %s to %s", key, value);
+    }
 }
 
 int br_time_remaining()

openbr/openbr.h

@@ -26,6 +26,8 @@ extern "C" {
 
 BR_EXPORT const char *br_about();
 
+BR_EXPORT void br_docs();
+
 BR_EXPORT void br_cat(int num_input_galleries, const char *input_galleries[], const char *output_gallery);
 
 BR_EXPORT void br_deduplicate(const char *input_gallery, const char *output_gallery, const char *threshold);

openbr/openbr_plugin.cpp

@@ -681,7 +681,7 @@ QString Object::argument(int index, bool expanded) const
 
         return "[" + strings.join(",") + "]";
     } else if (type == "br::Transform*") {
-        return variant.value<Transform*>()->description(expanded);
+        return variant.isNull() ? "" : variant.value<Transform*>()->description(expanded);
     } else if (type == "br::Distance*") {
         return variant.value<Distance*>()->description(expanded);
     } else if (type == "br::Representation*") {
@@ -886,7 +886,10 @@ void Object::setProperty(const QString &name, QVariant value)
 {
     QString type;
     int index = metaObject()->indexOfProperty(qPrintable(name));
-    if (index != -1) type = metaObject()->property(index).typeName();
+    if (index != -1)
+        type = metaObject()->property(index).typeName();
+    else
+        printf("Object %s does not have property %s! Can not set its value to %s!\n", metaObject()->className(), qPrintable(name), qPrintable(value.toString()));
 
     if (metaObject()->property(index).isEnumType()) {
         // This is necessary because setProperty can only set enums
@@ -995,8 +998,7 @@ void Object::setProperty(const QString &name, QVariant value)
     }
 
     if (!QObject::setProperty(qPrintable(name), value) && !type.isEmpty())
-        qFatal("Failed to set %s %s::%s to: %s",
-               qPrintable(type), metaObject()->className(), qPrintable(name), qPrintable(value.toString()));
+        throw QString("Failed to set %1 %2::%3 to: %4").arg(type).arg(metaObject()->className()).arg(name).arg(value.toString()).toStdString();
 }
 
 QStringList Object::parse(const QString &string, char split)
@@ -1271,8 +1273,13 @@ QStringList br::Context::objects(const char *abstractions, const char *implement
     }
     if (abstractionsRegExp.match("Transform").hasMatch()) {
         foreach (const QString &name, Factory<Transform>::names())
-            if (implementationsRegExp.match(name).hasMatch())
-                objectList.append(name + (parameters ? "\t" + Factory<Transform>::parameters(name) : ""));
+            if (implementationsRegExp.match(name).hasMatch()) {
+                try {
+                    objectList.append(name + (parameters ? "\t" + Factory<Transform>::parameters(name) : ""));
+                } catch (...) {
+                    // Exclude transforms that fail to initialize
+                }
+            }
     }
     if (abstractionsRegExp.match("Representation").hasMatch()) {
         foreach (const QString &name, Factory<Representation>::names())

openbr/openbr_plugin.h

@@ -31,6 +31,7 @@
 #include <QPoint>
 #include <QPointF>
 #include <QRectF>
+#include <QRegularExpression>
 #include <QScopedPointer>
 #include <QSharedPointer>
 #include <QString>
@@ -752,6 +753,29 @@ class BR_EXPORT Transform : public Object
     virtual void train(const TemplateList &data);
     virtual void train(const QList<TemplateList> &data);
 
+    void print_doc_header(QString doc, int indent) const {
+        QString name = this->file.suffix();
+        QString params;
+        try {
+            params = Factory<Transform>::parameters("."+description(false));
+        } catch (...) {
+            params = "???";
+        }
+        printf("%*s%s(%s): %s\n", indent, "", name.toStdString().c_str(), params.toStdString().c_str(), doc.toStdString().c_str());
+    }
+
+    void print_doc(QString doc, int indent) const {
+        printf("%*s%s\n", indent, "", doc.toStdString().c_str());
+    }
+
+    virtual void docs(int indent) const {
+        print_doc_header(docs(), indent);
+    }
+
+    virtual const QString docs() const
+    {
+        return "";
+    }
 
     virtual void project(const Template &src, Template &dst) const = 0;
     virtual void project(const TemplateList &src, TemplateList &dst) const;
@@ -918,6 +942,10 @@ BR_EXPORT bool IsClassifier(const QString &algorithm);
 
 BR_EXPORT void Train(const File &input, const File &model);
 
+BR_EXPORT void Docs();
+
+BR_EXPORT void AllDocs(QRegularExpression regex);
+
 BR_EXPORT void Enroll(const File &input, const File &gallery = File());
 
 BR_EXPORT void Enroll(TemplateList &tmpl);

openbr/plugins/core/discard.cpp

@@ -33,6 +33,11 @@ class DiscardTransform : public UntrainableMetaTransform
     {
         dst.file = src.file;
     }
+
+    const QString docs() const
+    {
+        return "Removes all matrices from a template.";
+    }
 };
 
 BR_REGISTER(Transform, DiscardTransform)

openbr/plugins/core/fork.cpp

@@ -105,6 +105,17 @@ class ForkTransform : public CompositeTransform
         }
     }
 
+    void docs(int indent) const
+    {
+        print_doc_header("Project the input template(s) through each transform and concatenate the results", indent);
+        foreach (const Transform *f, transforms) {
+            // We need to create a new instance of the transform for any independent transforms
+            // because they are wrapped by MetaTransform until project() is called.
+            QString description = "." + f->description(false); // Needs to start with a .
+            Factory<Transform>::make(description)->docs(indent + 4);
+        }
+    }
+
 protected:
 
     // Apply each transform to src, concatenate the results

openbr/plugins/core/identity.cpp

@@ -33,6 +33,11 @@ class IdentityTransform : public UntrainableMetaTransform
     {
         dst = src;
     }
+
+    const QString docs() const
+    {
+        return "Noop transform";
+    }
 };
 
 BR_REGISTER(Transform, IdentityTransform)

openbr/plugins/core/independent.cpp

@@ -41,7 +41,7 @@ class IndependentTransform : public MetaTransform
 
     QString description(bool expanded) const
     {
-        return transform->description(expanded);
+        return transform != NULL ? transform->description(expanded) : "Identity";
     }
 
     // can't use general setPropertyRecursive because of transforms oddness

openbr/plugins/core/pipe.cpp

@@ -196,6 +196,16 @@ class PipeTransform : public CompositeTransform
         return result;
     }
 
+    void docs(int indent) const
+    {
+        print_doc_header("Project the output of each Transform into the next", indent);
+        foreach (const Transform *f, transforms) {
+            // We need to create a new instance of the transform for any independent transforms
+            // because they are wrapped by MetaTransform until project() is called.
+            QString description = "." + f->description(false); // Needs to start with a .
+            Factory<Transform>::make(description)->docs(indent + 4);
+        }
+    }
 protected:
     // Template list project -- process templates in parallel through Transform::project
     // or if parallelism is disabled, handle them sequentially

openbr/plugins/distance/dist.cpp

@@ -44,7 +44,8 @@ class DistDistance : public UntrainableDistance
                   L1,
                   L2,
                   Cosine,
-                  Dot};
+                  Dot,
+                  Default = L2};
 
 private:
     BR_PROPERTY(Metric, metric, L2)

openbr/plugins/gui/show.cpp

@@ -611,10 +611,8 @@ class ShowTransform : public TimeVaryingTransform
     template<typename WindowType>
     void initActual()
     {
-        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 (!Globals->useGui)
+            throw QString("GUI transform %1 created without enabling GUI support.\nRun \"br -gui ...\" to enable GUI support from the command line, or set\nGlobals->useGui to true.").arg(this->metaObject()->className()).toStdString();
 
         if (displayBuffer)
             delete displayBuffer;
@@ -863,10 +861,8 @@ class ElicitTransform : public ShowTransform
     template<typename GUIType>
     void initActual()
     {
-        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 (!Globals->useGui)
+            throw QString("GUI transform %1 created without enabling GUI support.\nRun \"br -gui ...\" to enable GUI support from the command line, or set\nGlobals->useGui to true.").arg(this->metaObject()->className()).toStdString();
 
         TimeVaryingTransform::init();
 

openbr/plugins/imgproc/cvtfloat.cpp

@@ -34,6 +34,11 @@ class CvtFloatTransform : public UntrainableTransform
     {
         src.m().convertTo(dst, CV_32F);
     }
+
+    const QString docs() const
+    {
+        return "Convert the matrix to float32";
+    }
 };
 
 BR_REGISTER(Transform, CvtFloatTransform)

openbr/plugins/imgproc/cvtuchar.cpp

@@ -33,6 +33,11 @@ class CvtUCharTransform : public UntrainableTransform
     {
         OpenCVUtils::cvtUChar(src, dst);
     }
+
+    const QString docs() const
+    {
+        return "Convert the matrix to uint8";
+    }
 };
 
 BR_REGISTER(Transform, CvtUCharTransform)

openbr/plugins/imgproc/ensurechannels.cpp

@@ -58,6 +58,11 @@ class EnsureChannelsTransform : public UntrainableTransform
             merge(mv, dst);
         }
     }
+
+    const QString docs() const
+    {
+        return "Ensure the matrix has n channels by adding or removing channels.";
+    }
 };
 
 BR_REGISTER(Transform, EnsureChannelsTransform)

openbr/plugins/imgproc/if.cpp

@@ -89,6 +89,10 @@ class IfTransform : public MetaTransform
         dst.append(ifFalse);
     }
 
+    const QString docs() const
+    {
+        return "For each template that pases the comparison, project it thru the transform";
+    }
 };
 BR_REGISTER(Transform, IfTransform)
 

openbr/plugins/io/print.cpp

@@ -46,6 +46,11 @@ class PrintTransform : public UntrainableMetaTransform
         QString fteString = src.file.fte ? "\n  FTE=true" : QString();
         fprintf(error ? stderr : stdout, "%s%s\n  %s\n%s", qPrintable(nameString), qPrintable(fteString), qPrintable(matricies.join(",")), qPrintable(dataString));
     }
+
+    const QString docs() const
+    {
+        return "Print the specified keys (all if empty)";
+    }
 };
 
 BR_REGISTER(Transform, PrintTransform)