index.html
16.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../docs/img/openbr.ico">
<title>Tutorials - OpenBR</title>
<link href="../css/bootstrap-custom.min.css" rel="stylesheet">
<link href="../css/font-awesome-4.0.3.css" rel="stylesheet">
<link rel="stylesheet" href="../css/highlight.css">
<link href="../css/base.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
</head>
<body data-spy="scroll" data-target="#bs-sidebar">
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<!-- Main title -->
<a class="navbar-brand" href="..">OpenBR</a>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li >
<a href="..">Home</a>
</li>
<li >
<a href="../install/">Install</a>
</li>
<li class="active">
<a href="./">Tutorials</a>
</li>
<li >
<a href="../technical/">Technical Overviews</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">More <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../contribute/">Contribute</a>
</li>
<li >
<a href="../papers/">Publications</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Docs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../docs/c_api/">C API</a>
</li>
<li >
<a href="../docs/cpp_api/">C++ Plugin API</a>
</li>
<li >
<a href="../docs/cl_api/">Command Line API</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Plugin Docs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../docs/plugins/classification/">Classification</a>
</li>
<li >
<a href="../docs/plugins/cluster/">Cluster</a>
</li>
<li >
<a href="../docs/plugins/core/">Core</a>
</li>
<li >
<a href="../docs/plugins/distance/">Distance</a>
</li>
<li >
<a href="../docs/plugins/format/">Format</a>
</li>
<li >
<a href="../docs/plugins/gallery/">Gallery</a>
</li>
<li >
<a href="../docs/plugins/gui/">GUI</a>
</li>
<li >
<a href="../docs/plugins/imgproc/">Image Processing</a>
</li>
<li >
<a href="../docs/plugins/io/">I/O</a>
</li>
<li >
<a href="../docs/plugins/metadata/">Metadata</a>
</li>
<li >
<a href="../docs/plugins/output/">Output</a>
</li>
<li >
<a href="../docs/plugins/video/">Video</a>
</li>
</ul>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
<li >
<a rel="next" href="../install/">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li >
<a rel="prev" href="../technical/">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li>
<a href="https://github.com/biometrics/openbr">
<i class="fa fa-github"></i>
GitHub
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="col-md-3"><div class="bs-sidebar hidden-print affix" role="complementary">
<ul class="nav bs-sidenav">
<li class="main active"><a href="#quick-start">Quick Start</a></li>
<li class="main "><a href="#training-algorithms">Training Algorithms</a></li>
<li class="main "><a href="#face-recognition">Face Recognition</a></li>
<li class="main "><a href="#age-estimation">Age Estimation</a></li>
<li class="main "><a href="#gender-estimation">Gender Estimation</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<p>Welcome to OpenBR! Here we have a series of tutorials designed to get you up to speed on what OpenBR is, how it works, its command line interface, and the C API. These tutorials aren't meant to be completed in a specific order so feel free to hop around. If you need help, feel free to <a href="..#help">contact us</a>.</p>
<hr />
<h1 id="quick-start">Quick Start</h1>
<p>This tutorial is meant to familiarize you with the ideas, objects and motivations behind OpenBR using some fun examples. <strong>Note:</strong> parts of this tutorial require a webcam.</p>
<p>OpenBR is a C++ library built on top of QT and OpenCV. It can either be used from the command line using the <strong>br</strong> application, or from interfacing with the <a href="../docs/c_api/">C API</a>. The command line is the easiest and fastest way to get started and this tutorial will use it for all of the examples.</p>
<p>First, make sure that OpenBR has been installed on your system using the steps described in the <a href="../install/">installation section</a>. Then open up your terminal or command prompt and enter:</p>
<pre><code>$ br -gui -algorithm "Show(false)" -enroll 0.webcam
</code></pre>
<p>If everything goes well your webcam should have opened up and is streaming. Look you are using OpenBR! Let's talk about what's happening in this command. OpenBR expects flags to be prepended by a <em>-</em> and arguments to follow the flags and be separated by spaces. Flags normally require a specific number of flags. All of the possible flags and their values are <a href="../docs/cl_api/">documented here</a>. Let's step through the individual arguments and values. <strong>-gui</strong> is the flag that tells OpenBR to open up a GUI window. Take a look at the <a href="../docs/plugins/gui/">GUI plugins</a> for other plugins that require the <strong>-gui</strong> flag. <strong>-algorithm</strong> is one of the most important flags in OpenBR. It expects one argument called the <em>algorithm string</em>. This string determines the pipeline that images and metadata propagate through. Finally, <strong>-enroll</strong> reads files from disk and <em>enrolls</em> them into the image pipeline. It takes one input argument (0.webcam in our example) and an optional output argument. OpenBR has a range of formats that can be enrolled into algorithms, some examples include .jpg, .png, .csv, and .xml. .webcam tells OpenBR to enroll frames from the computers webcam.</p>
<p>Let's try a slightly more complicated example, after all OpenBR can do way more then just open webcams! Fire up the terminal again and enter:</p>
<pre><code>$ br -gui -algorithm "Cvt(Gray)+Show(false)" -enroll 0.webcam
</code></pre>
<p>Hey what happened? We took our normal BGR (OpenCV's alternative to RGB) image and converted it to a grayscale image. How did we do that? Simple, by adding "Cvt(Gray)" to the algorithm string. <a href="../docs/plugins/imgproc/#cvttransform">Cvt</a>, short for convert, is an example of an OpenBR <em>plugin</em>. <a href="../docs/plugins/gui/#showtransform">Show</a> is a plugin as well. Every algorithm string in OpenBR is just a series of plugins joined together into a pipeline. In fact the <strong>+</strong> symbol is shorthand for a <a href="../docs/plugins/core/#pipetransform">Pipe</a>, another kind of OpenBR plugin. We specify <strong>Gray</strong> to <a href="../docs/plugins/imgproc/#cvttransform">Cvt</a> as a runtime parameter to tell the plugin which color space to convert the image to. We also could have written <strong>Cvt(HSV)</strong> if we wanted to convert to the HSV color space or <strong>Cvt(Luv)</strong> if we wanted to convert to Luv. The arguments inside of the plugins are runtime parameters that can adjust the functionality. They can be provided as key-value pairs, <strong>Cvt(Gray)</strong> is equivalent to <strong>Cvt(ColorSpace=Gray)</strong>, or as keyless values. Make sure you are supplying parameters in the proper order if you are not using keys! Try and run the code with <strong>Show(true)</strong> and see how changing the parameters effect the output of the command (<strong>Hint:</strong> hit a key to cycle through the images).</p>
<p>Let's make this example a little bit more exciting and relevant to OpenBR's biometric roots. Face detection is normally the first step in a <a href="#face-recognition">face recognition</a> algorithm. Let's do face detection in OpenBR. Back in the terminal enter:</p>
<pre><code>$ br -gui -algorithm "Cvt(Gray)+Cascade(FrontalFace)+Draw(lineThickness=3)+Show(false)" -enroll 0.webcam
</code></pre>
<p>You're webcam should be open again but this time a box should have appeared around your face! We added two new plugins to our string, <a href="../docs/plugins/metadata/#cascadetransform">Cascade</a> and <a href="../docs/plugins/gui/#drawtransform">Draw</a>. Let's walk through this plugin by plugin and see how it works:</p>
<ol>
<li><a href="../docs/plugins/imgproc/#cvttransform">Cvt(Gray)</a>: Convert the image from BGR to grayscale. Grayscale is required for <a href="../docs/plugins/metadata/#cascadetransform">Cascade</a> to work properly.</li>
<li><a href="../docs/plugins/metadata/#cascadetransform">Cascade(FrontalFace)</a>: This is a wrapper on the OpenCV <a href="http://docs.opencv.org/modules/objdetect/doc/cascade_classification.html">Cascade Classification</a> framework. It detects frontal faces using the <strong>FrontalFace</strong> model.</li>
<li><a href="../docs/plugins/gui/#drawtransform">Draw(lineThickness=3)</a>: Take the rects detected by <a href="../docs/plugins/metadata/#cascadetransform">Cascade</a> and draw them onto the frame from the webcam. <strong>lineThickness</strong> determines the thickness of the drawn rect.</li>
<li><a href="../docs/plugins/gui/#showtransform">Show(false)</a>: Show the image in a GUI window. <strong>false</strong> indicates the images should be shown in succession without waiting for a key press.</li>
</ol>
<p>Pretty straightforward right? Each plugin completes one task and the passes the output on to the next plugin. You can pipe together as many plugins as you like as long as the output data from one can be the input data to the next. But wait! Output data? Input data? we haven't talked about data at all yet! How does OpenBR handle data? There are two objects that handle data is OpenBR; <a href="../docs/cpp_api/#file">Files</a>, which handle metadata, and <a href="../docs/cpp_api/#template">Templates</a> which are containers for images and <a href="../docs/cpp_api/#file">Files</a>. Let's talk about <a href="../docs/cpp_api/#file">Files</a> first. A file consists of file name, which is a path to a file on disk, and metadata which is a map of key-value pairs. The metadata can contain any textual information about the file. In the example above we use it to store the rectangles detected by <a href="../docs/plugins/metadata/#cascadetransform">Cascade</a> and pass them along to <a href="../docs/plugins/metadata/#drawtransform">Draw</a> for drawing. <a href="../docs/cpp_api/#template">Templates</a> are containers for images, given as OpenCV <a href="http://docs.opencv.org/modules/core/doc/basic_structures.html#mat">Mats</a>, and <a href="../docs/cpp_api/#file">Files</a>. They can contain one image or a list of images. Plugins are either <a href="../docs/cpp_api/#template">Template</a> in, <a href="../docs/cpp_api/#template">Template</a> out or <a href="../docs/cpp_api/#templatelist">TemplateList</a> in, <a href="../docs/cpp_api/#templatelist">TemplateList</a> out. <a href="../docs/cpp_api/#templatelist">TemplateLists</a> are, of course, just a list of <a href="../docs/cpp_api/#template">Templates</a> which a few functions added for your convenience.</p>
<p>And there you go! You have gotten your quick start in OpenBR. We covered the <a href="../docs/cl_api/">command line</a>, plugins, and the key <a href="../docs/cpp_api/">data structures</a> in OpenBR. If you want to learn more the next few tutorials will cover these fields with more depth. For even more information check out the <a href="../technical/">technical overviews</a> and class documentation!</p>
<hr />
<h1 id="training-algorithms">Training Algorithms</h1>
<hr />
<h1 id="face-recognition">Face Recognition</h1>
<hr />
<h1 id="age-estimation">Age Estimation</h1>
<hr />
<h1 id="gender-estimation">Gender Estimation</h1></div>
</div>
<!-- Search modal. Not yet supported. -->
<div class="modal fade" id="searchModal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
<h4 class="modal-title" id="searchModalLabel">Documentation search</h4>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<script src="../js/jquery-1.10.2.min.js"></script>
<script src="../js/bootstrap-3.0.3.min.js"></script>
<script src="../js/highlight.pack.js"></script>
<script src="../js/base.js"></script>
</body>
</html>