Some additional comments about train/project overloads

Charles Otto
1 parent d0aa1fd8
Showing 1 changed file with 27 additions and 6 deletions
openbr/openbr_plugin.h
@@ -1058,7 +1058,15 @@ public:
     static QSharedPointer<Transform> fromAlgorithm(const QString &algorithm); /*!< \brief Retrieve an algorithm's transform. */
     virtual Transform *clone() const; /*!< \brief Copy the transform. */
-    /*!< \brief Train the transform, separate list items represent the way calls to project would be broken up*/
+
+    /*!< \brief Train the transform, separate list items represent the way calls to project would be broken up
+     * Transforms that have to call train on another transform should implement train(QList), the strucutre of the
+     * list should mirror the calls that would be made to project by the parent transform. For example, DistributeTemplates
+     * would make a separate project call for each template it receives, and therefore sets the QList to contain single item
+     * template lists before passing it on.
+     * This version of train(QList) is appropriate for transforms that perform training on themselves, and don't call train
+     * on other transforms. It combines everything in data into a single TemplateList, then calls train(TemplateList)
+     */
     virtual void train(const QList<TemplateList> &data)
     {
         TemplateList combined;
@@ -1071,16 +1079,27 @@ public:
     // Terminal train, call with a complete training set when no further structure is needed
     virtual void train(const TemplateList &data) = 0; /*!< \brief Train the transform. */
-    virtual void project(const Template &src, Template &dst) const = 0; /*!< \brief Apply the transform. */
-    virtual void project(const TemplateList &src, TemplateList &dst) const; /*!< \brief Apply the transform. */
+    /*!< \brief Apply the transform to a single template. Typically used by independent transforms */
+    virtual void project(const Template &src, Template &dst) const = 0;
+    /*!< \brief Apply the transform, taking the full template list as input.
+     * A TemplateList is what is typically passed from transform to transform. Transforms that just
+     * need to operatoe on a single template at a time (and want to output exactly 1 template) can implement
+     * project(template), but transforms that want to change the structure of the TemplateList (such as flatten), or
+     * or output more or less than one template (e.g. detection methods) should implement project(TemplateList) directly
+     */
+    virtual void project(const TemplateList &src, TemplateList &dst) const;
-    /*!< \brief Apply the transform, may update the transform's internal state */
+    /*!< \brief Apply the transform to a single template, may update the transform's internal state
+     * By default, just call project, we can always call a const function from a non-const function.
+     * If a transform implements projectUpdate, it should report true to timeVarying so that it can be
+     * handled correctly by e.g. Stream.
+     */
     virtual void projectUpdate(const Template &src, Template &dst)
     {
         project(src, dst);
     }
-    /*!< \brief Apply the transform, may update the transform's internal state */
+    /*!< \brief Apply the transform, may update the transform's internal state. */
     virtual void projectUpdate(const TemplateList &src, TemplateList &dst)
     {
         project(src,dst);
@@ -1142,7 +1161,9 @@ public:
      * \brief Perform the minimum amount of work necessary to make a
      * transform that can be used safely from a different thread than this
      * transform. For transforms that aren't time-varying, nothing needs to be
-     * done, returning this is sufficient.
+     * done, returning this is sufficient. Time varying transforms should implement this method
+     * and copy enough of their state that projectUpdate can safely be called on the original
+     * instance, and the copy concurrently.
      */
     virtual Transform * smartCopy() { return this;}