Peter M. Groen / openbr

Commit b6e5735cd06241c72a3345f5a2ff751d71e53fa9

Authored by Scott Klum
1 parent 3d38dee7

Done with tutorials

Inline Side-by-side
Showing 1 changed file with 28 additions and 19 deletions
docs/docs/tutorials.md
  View file @b6e5735
... ... @@ -66,28 +66,28 @@ As previously noted, an algorithm is defined in OpenBR through an algorithm stri
66 66 3. It allows for algorithm parameter tuning without recompiling.
67 67 4. It is completely unambiguous, both the OpenBR interpreter and anyone familiar with the project can understand exactly what your algorithm does just from this description.
68 68  
69   -OpenBR provides a syntax for creating concise algorithm strings. The relevant symbols are:
  69 +OpenBR provides a syntax for setting plugin property values and creating concise algorithm strings. The relevant symbols are:
70 70  
71 71 Symbol | Meaning
72 72 --- | ---
73 73 PluginName(property1=value1,...propertyN=valueN) | A plugin is described by its name (without the abstraction) and a list of properties and values. Properties of a plugin that are not specified are set to their default values.
74   -: | Seperates *templatelate enrollment* from *template comparison*. Enrollment is on the left and comparison is on the right. Defining an algorithm with a template comparison step is optional.
75   -\+ | Abbreviation for a Pipe. Joins Transforms together and projects input through them in series. The output of a Transform to the left of \+ become the input of the Transform to the right.
76   - / | Abbreviation for a Fork. Joins Transforms together and projects input through them in parallel. All Transforms receive the same input, the output of which is concatenated together.
77   - \{\} | Abbreviation for Cache. Cache the output of a plugin in memory for quick lookups later on.
78   - <\> | Abbreviation for LoadStore. Parameters for Transforms inside the brackets are stored on disk after training and loaded from disk before projection.
  74 +: | Seperates *template enrollment* from *template comparison*. Enrollment is on the left of the colon in the algorithm string, while comparison is on the right. Defining an algorithm with a template comparison step is optional.
  75 +\+ | Abbreviation for a [Pipe](api_docs/plugins/core.md#pipetransform). Joins [Transform](api_docs/cpp_api/transform/transform.md)s together and projects input through them in series. The output of a [Transform](api_docs/cpp_api/transform/transform.md) to the left of \+ become the input of the Transform to the right.
  76 + / | Abbreviation for a [Fork](api_docs/plugins/core.md#forktransform). Joins [Transform](api_docs/cpp_api/transform/transform.md)s together and projects input through them in parallel. All [Transform](api_docs/cpp_api/transform/transform.md)s receive the same input, the output of which is concatenated together.
  77 + \{\} | Abbreviation for [Cache](api_docs/plugins/core.md#cachetransform). Cache the output of a plugin in memory for quick lookups later on.
  78 + <\> | Abbreviation for [LoadStore](api_docs/plugins/core.md#loadstoretransform). Parameters for [Transform](api_docs/cpp_api/transform/transform.md)s inside the brackets are stored on disk after training and loaded from disk before projection.
79 79 () | Order of operations. Change the order of operations using parantheses.
80 80  
81   -Let's look at some of the important parts of the code base that make this possible:
  81 +Let's look at some of the important parts of the codebase that make this possible:
82 82  
83 83 In ```AlgorithmCore::init()``` in ```openbr/core/core.cpp``` you can see the code for splitting the algorithm description at the colon.
84   -Shortly thereafter in this function we *make* the template generation and comparison objects.
85   -These make calls are defined in the public [C++ plugin API](api_docs/cpp_api.md) and can also be called from end user code.
  84 +Shortly thereafter in this function we `make` the template generation and comparison objects.
  85 +These `make` calls are defined in the public [C++ plugin API](api_docs/cpp_api.md) and can also be called from end user code.
86 86  
87 87 Below we discuss some of the source code for `Transform::make` in `openbr/openbr_plugin.cpp`.
88   -Note, the make functions for other plugin types are similar in spirit and will not be covered.
  88 +Note, the `make` functions for other plugin types are similar in spirit and will not be covered.
89 89  
90   -One of the first steps when converting the template enrollment description into a [Transform](api_docs/cpp_api/transform/transform.md) is to replace the operators, like '', with their full form:
  90 +One of the first steps when converting the template generation description into [Transform](api_docs/cpp_api/transform/transform.md)s is to replace the operators, like '', with their full form:
91 91  
92 92 { // Check for use of '+' as shorthand for Pipe(...)
93 93 QStringList words = parse(str, '+');
... ... @@ -95,7 +95,7 @@ One of the first steps when converting the template enrollment description into
95 95 return make("Pipe([" + words.join(",") + "])", parent);
96 96 }
97 97  
98   -After operator expansion, the template enrollment description forms a tree, and the transform is constructed from this description starting recursively starting at the root of the tree:
  98 +After operator expansion, the template enrollment description forms a tree, and the [Transform](api_docs/cpp_api/transform/transform.md) is constructed from this description recursively, starting at the root of the tree:
99 99  
100 100 Transform *transform = Factory<Transform>::make("." + str);
101 101  
... ... @@ -103,24 +103,33 @@ Let&#39;s use the algorithm in ```scripts/helloWorld.sh``` as an example. The algori
103 103  
104 104 Open+Cvt(Gray)+Cascade(FrontalFace)+ASEFEyes+Affine(128,128,0.33,0.45)+CvtFloat+PCA(0.95):Dist(L2)
105 105  
106   -So what is happening here? Let's expand this using our new knowledge of OpenBR's algorithm syntax. First, the algorithm will be split into enrollment and comparison portions at the **:**. So enrollment becomes-
  106 +Let's expand this using our new knowledge of OpenBR's algorithm syntax. First, the algorithm will be split into enrollment and comparison portions at the `:`. So enrollment becomes:
107 107  
108 108 Open+Cvt(Gray)+Cascade(FrontalFace)+ASEFEyes+Affine(128,128,0.33,0.45)+CvtFloat+PCA(0.95)
109 109  
110   -and comparison is-
  110 +and comparison is:
111 111  
112 112 Dist(L2)
113 113  
114   -On the enrollment side the **+'s** are converted into a [PipeTransform](api_docs/plugins/core.md#pipetransform) with the other plugins as children. Enrollment is transformed to
  114 +On the enrollment side, [Transform](api_docs/cpp_api/transform/transform.md)s joined by the `+` operators are converted into children of a [Pipe](api_docs/plugins/core.md#pipetransform). Thus, the enrollment algorithm is constructed as:
115 115  
116 116 Pipe(transforms=[Open,Cvt(Gray),Cascade(FrontalFace),ASEFEyes,Affine(128,128,0.33,0.45,CvtFloat,PCA(0.95)])
117 117  
118   -If you want all the details about what exactly this algorithm does, then you should read the [project](api_docs/cpp_api/transform/functions.md#project-1) function implemented by each of these plugins.
119   -The brief explanation is that it *reads the image from disk, converts it to grayscale, runs the face detector, runs the eye detector on any detected faces, uses the eye locations to normalize the face for rotation and scale, converts to floating point format, and then embeds it in a PCA subspaced trained on face images*.
  118 +Low-level detail of the operations involved in this algorithm can be found in the [project](api_docs/cpp_api/transform/functions.md#project-1) function implemented by each of these [Transform](api_docs/cpp_api/transform/transform.md)s.
  119 +To briefly summarize:
  120 +
  121 + 1. Reads the image from disk
  122 + 2. Converts the image to grayscale
  123 + 3. Detects faces
  124 + 4. Detects eyes in detected faces
  125 + 5. Normalize the face with respect to rotation and scale using the eye locations
  126 + 6. Converts the image to floating point format
  127 + 7. Embeds the image in a PCA subspace trained on face images
  128 +
120 129 If you are familiar with face recognition, you will likely recognize this as the Eigenfaces[^1] algorithm.
121 130  
122 131 As a final note, the Eigenfaces algorithms uses the Euclidean distance (or L2-norm) to compare templates.
123   -Since OpenBR expects similarity values when comparing templates and not dissimilarity values, the [DistDistance](api_docs/plugins/distance.md#distdistance) will return *-log(distance+1)* by default so that larger values indicate more similarity.
  132 +Since OpenBR expects similarity values when comparing templates and not dissimilarity values, the [DistDistance](api_docs/plugins/distance.md#distdistance) will return *-log(distance+1)* by default so that smaller distances (in the Euclidean sense) indicate higher similarity.
124 133 Note that [NegativeLogPlusOne](api_docs/plugins/distance.md#negativelogplusone) distance also exists such that you can convert the output of any distance using the above function.
125 134  
126 135 ---
... ... @@ -153,7 +162,7 @@ Easy enough? You should see results printed to terminal that look like
153 162 $ 100.00% ELAPSED=00:00:00 REMAINING=00:00:00 COUNT=1
154 163 $ 0.571219
155 164  
156   -So what is 'FaceRecognition'? It's an abbrieviation to make running the algorithm easier. All of the algorithm abbreviations are located in ```openbr/plugins/core/algorithms.cpp```.
  165 +So, what is `FaceRecognition`? It's an abbrieviation to simplify execution of the algorithm. All of the algorithm abbreviations are located in ```openbr/plugins/core/algorithms.cpp```.
157 166  
158 167 It is also possible to:
159 168  
... ...