More edits

Scott Klum
1 parent e1413198
Showing 1 changed file with 44 additions and 41 deletions
docs/docs/tutorials.md
@@ -7,7 +7,7 @@ Welcome to OpenBR! Here we have a series of tutorials designed to get you up to 
  
 This tutorial is meant to familiarize you with the ideas, objects and motivations behind OpenBR using some fun examples. **Note that parts of this tutorial require a webcam.**
  
-OpenBR is a C++ library built on top of [Qt](http://www.qt.io/) and [OpenCV](http://opencv.org/). It can either be used from the command line using the `br` application, or from interfacing with the [C++](api_docs/cpp_api.md) or [C](api_docs/c_api.md) APIs. Using the command line application `br` is the easiest and fastest way to get started and this tutorial will use it for all of the examples.
+OpenBR is a C++ library built on top of [Qt](http://www.qt.io/), [OpenCV](http://opencv.org/), and [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page). It can either be used from the command line using the `br` application, or from interfacing with the [C++](api_docs/cpp_api.md) or [C](api_docs/c_api.md) APIs. Using the `br` application is the easiest and fastest way to get started and this tutorial will use it for all of the examples.
  
 First, make sure that OpenBR has been installed on your system using the steps described in the [installation section](install.md).
  
@@ -19,37 +19,37 @@ If everything has gone according to plan, your webcam should be on and capturing
  
 Let's talk about what's happening in the above command. `-gui`, `-algorithm`, and `-enroll` are examples of OpenBR's flags and are used to specify instructions to `br`. OpenBR expects flags to be prepended by a `-` and arguments that follow the flags to be separated by spaces. Flags normally require a specific number of arguments. All of the possible flags and their values are [documented here](api_docs/cl_api.md). Let's step through the individual arguments and values:
  
-* `-gui` is the flag that tells OpenBR to open up a GUI window. Note that when `-gui` is used, it must be the first flag passed to `br`. Take a look at the [GUI](api_docs/plugins/gui.md) plugins for other plugins that require the `-gui` flag. 
-* `-algorithm` is one of the most important flags in OpenBR. It expects one argument, referred to as the *algorithm string*. This string determines the pipeline that images and metadata propagate through.
-* `-enroll` reads files from a [Gallery](api_docs/cpp_api/gallery/gallery.md) and *enrolls* them through the algorithm pipeline and serializes them to another [Gallery](api_docs/cpp_api/gallery/gallery.md). `-enroll` takes one input argument (`0.webcam` in this example) and an optional output argument. OpenBR supports multiple formats including `.jpg`, `.png`, `.csv`, and `.xml`. `.webcam` tells OpenBR to enroll frames from the computer's webcam.
+* `-gui` is the flag that tells OpenBR to open up a GUI window. Note that when `-gui` is used, it must be the first flag passed to `br`. 
+* `-algorithm` is one of the most important flags in OpenBR. It expects one argument, referred to as the *algorithm string*. This string determines the pipeline through which images and metadata propagate. It is composed of [Transform](api_docs/cpp_api/transform/transform.md)s, which are described in detail later in this tutorial. 
+* `-enroll` reads files from a [Gallery](api_docs/cpp_api/gallery/gallery.md) or a [Format](api_docs/cpp_api/format/format.md) and *enrolls* them through the algorithm pipeline and serializes them to another [Gallery](api_docs/cpp_api/gallery/gallery.md) or [Format](api_docs/cpp_api/format/format.md). `-enroll` takes one input argument (`0.webcam` in this example) and an optional output argument. OpenBR supports multiple formats including `.jpg`, `.png`, `.csv`, and `.xml`. The `.webcam` [Format](api_docs/cpp_api/format/format.md) tells OpenBR to enroll frames from the computer's webcam.
  
 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:
  
     $ br -gui -algorithm "Cvt(Gray)+Show(false)" -enroll 0.webcam
  
-Here, we took our normal BGR (OpenCV's alternative to RGB) image and converted it to a grayscale image simply by adding `Cvt(Gray)` to the algorithm string. [Cvt](api_docs/plugins/imgproc.md#cvttransform), short for convert, is an example of an OpenBR *Transform*. [Show](api_docs/plugins/gui.md#showtransform) is a Transform as well. Every algorithm string in OpenBR is just a series of Transforms joined to form a pipeline. In fact, the `+` symbol is shorthand for a [Pipe](api_docs/plugins/core.md#pipetransform), another kind of OpenBR Transform. 
+Here, we took our normal BGR (OpenCV's alternative to RGB) image and converted it to a grayscale image simply by adding `Cvt(Gray)` to the algorithm string. [Cvt](api_docs/plugins/imgproc.md#cvttransform), short for convert, is an example of an OpenBR *[Transform](api_docs/cpp_api/transform/transform.md)*. [Show](api_docs/plugins/gui.md#showtransform) is a [Transform](api_docs/cpp_api/transform/transform.md) as well. In fact, every algorithm string in OpenBR is just a series of [Transform](api_docs/cpp_api/transform/transform.md)s joined to form a pipeline; even the `+` symbol is shorthand for a [Pipe](api_docs/plugins/core.md#pipetransform), another kind of OpenBR [Transform](api_docs/cpp_api/transform/transform.md). 
  
-Typically, Transforms accept parameters.  We specify `Gray` to [Cvt](api_docs/plugins/imgproc.md#cvttransform) as a runtime parameter to tell the plugin which color space to convert the image to. We also could have written `Cvt(HSV)` if we wanted to convert to the HSV color space or `Cvt(Luv)` if we wanted to convert to LUV. They can be provided as key-value pairs or as keyless values (`Cvt(Gray)` is equivalent to `Cvt(colorSpace=Gray)`) . Note that if you are supplying values only, the parameters are expected to be supplied in the order they are defined. Try running changing the algorithm string above to include `Show(true)` to see how changing the parameters affect the output of the command (Hint: hit a key to cycle through the images).
+Typically, [Transform](api_docs/cpp_api/transform/transform.md)s accept parameters.  We specify `Gray` to [Cvt](api_docs/plugins/imgproc.md#cvttransform) as a runtime parameter to tell the [Transform](api_docs/cpp_api/transform/transform.md) which color space to convert the image to. We also could have written `Cvt(HSV)` if we wanted to convert to the HSV color space or `Cvt(Luv)` if we wanted to convert to LUV. Parameters can be provided as key-value pairs or as keyless values (`Cvt(Gray)` is equivalent to `Cvt(colorSpace=Gray)`) . Note that if you are supplying values only, the parameters are expected to be supplied in the order they are defined. Try changing the algorithm string above to include `Show(true)` to see how modifying the parameters affects the output of the command (Hint: hit a key to cycle through the images).
  
 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 [face recognition](#face-recognition) algorithm. Let's perform face detection in OpenBR. Back in the terminal enter:
  
     $ br -gui -algorithm "Cvt(Gray)+Cascade(FrontalFace)+Draw(lineThickness=3)+Show(false)" -enroll 0.webcam
  
-You're webcam should be open again but this time a bounding-box should have appeared around your face! We added two new Transforms to our string, [Cascade](api_docs/plugins/metadata.md#cascadetransform) and [Draw](api_docs/plugins/gui.md#drawtransform). Let's walk through this Transform by Transform and see how it works:
+You're webcam should be open again but this time a bounding-box should have appeared around your face! We added two new [Transform](api_docs/cpp_api/transform/transform.md)s to our string: [Cascade](api_docs/plugins/metadata.md#cascadetransform) and [Draw](api_docs/plugins/gui.md#drawtransform). Let's walk through this [Transform](api_docs/cpp_api/transform/transform.md) by [Transform](api_docs/cpp_api/transform/transform.md) and see how it works:
  
 1. [Cvt(Gray)](api_docs/plugins/imgproc.md#cvttransform): Convert the image from BGR to grayscale. Grayscale is required for [Cascade](api_docs/plugins/metadata.md#cascadetransform) to work properly.
 2. [Cascade(FrontalFace)](api_docs/plugins/metadata.md#cascadetransform): This is a wrapper on the OpenCV [Cascade Classification](http://docs.opencv.org/modules/objdetect/doc/cascade_classification.html) framework. It detects frontal faces using the `FrontalFace` model.
 3. [Draw(lineThickness=3)](api_docs/plugins/gui.md#drawtransform): Take the rectangles detected by [Cascade](api_docs/plugins/metadata.md#cascadetransform) and draw them onto the frame from the webcam. `lineThickness` determines the thickness of the drawn rectangle.
 4. [Show(false)](api_docs/plugins/gui.md#showtransform): Show the image in a GUI window. `false` indicates the images should be shown in succession without waiting for a key press.
  
-Each Transform completes one task and the passes the output on to the next Transform. You can pipe together as many Transforms as you like, but note that certain Transforms have specific expectations for their input. 
+Each [Transform](api_docs/cpp_api/transform/transform.md) completes one task and the passes the output on to the next [Transform](api_docs/cpp_api/transform/transform.md). You can pipe together as many [Transform](api_docs/cpp_api/transform/transform.md)s as you like, but note that certain [Transform](api_docs/cpp_api/transform/transform.md)s have specific expectations for their input. 
  
 You may be wondering what objects are actually being propagated through the algorithm pipeline. There are two objects that handle data in OpenBR:
  
 * [File](api_docs/cpp_api/file/file.md)s are typically used to store the path to a file on disk with associated metadata (in the form of key-value pairs). In the example above, we store the rectangles detected by [Cascade](api_docs/plugins/metadata.md#cascadetransform) as metadata which are then used by [Draw](api_docs/plugins/gui.md#drawtransform) for visualization.
 * [Template](api_docs/cpp_api/template/template.md)s are containers for images and [File](api_docs/cpp_api/file/file.md)s. Images in OpenBR are OpenCV Mats and are member variables of Templates. Templates can contain one or more images.
  
-If you want to learn more about the [command line](api_docs/cl_api.md) or the [plugins, and the key data structures](api_docs/cpp_api.md), the next few tutorials will cover these fields with more depth.
+If you want to learn more about the [command line](api_docs/cl_api.md) or [all of the plugins and the key data structures](api_docs/cpp_api.md), please refer to the linked documentation.  The next few tutorials will explore algorithms and their use in more depth.
  
 ---
  
@@ -142,7 +142,7 @@ Easy enough? You should see results printed to terminal that look like
     $ Loading /usr/local/share/openbr/models/transforms//FaceRecognitionExtraction
     $ Loading /usr/local/share/openbr/models/transforms//FaceRecognitionEmbedding
     $ Loading /usr/local/share/openbr/models/transforms//FaceRecognitionQuantization
-    $Comparing ../data/MEDS/img/S354-01-t10_01.jpg and ../data/MEDS/img/S354-02-t10_01.jpg
+    $ Comparing ../data/MEDS/img/S354-01-t10_01.jpg and ../data/MEDS/img/S354-02-t10_01.jpg
     $ Enrolling ../data/MEDS/img/S354-01-t10_01.jpg to S354-01-t10_01r7Rv4W.mem
     $ 100.00%  ELAPSED=00:00:00  REMAINING=00:00:00  COUNT=1
     $ 100.00%  ELAPSED=00:00:00  REMAINING=00:00:00  COUNT=1
@@ -155,24 +155,27 @@ Easy enough? You should see results printed to terminal that look like
  
 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```.
  
-It is also possible to evaluate face recognition performance (Note that this requires [R](http://www.r-project.org/) to be installed):
+It is also possible to:
  
-    $ br -algorithm FaceRecognition -path ../data/MEDS/img/ \
-         -enroll ../data/MEDS/sigset/MEDS_frontal_target.xml target.gal \
-         -enroll ../data/MEDS/sigset/MEDS_frontal_query.xml query.gal \
-         -compare target.gal query.gal scores.mtx \
-         -makeMask ../data/MEDS/sigset/MEDS_frontal_target.xml ../data/MEDS/sigset/MEDS_frontal_query.xml MEDS.mask \
-         -eval scores.mtx MEDS.mask Algorithm_Dataset/FaceRecognition_MEDS.csv \
-         -plot Algorithm_Dataset/FaceRecognition_MEDS.csv MEDS
+* Evaluate face recognition performance (Note that this requires [R](http://www.r-project.org/) to be installed):
  
-Perform a 1:N face recognition search:
+            $ br -algorithm FaceRecognition -path ../data/MEDS/img/ \
+            -enroll ../data/MEDS/sigset/MEDS_frontal_target.xml target.gal \
+            -enroll ../data/MEDS/sigset/MEDS_frontal_query.xml query.gal \
+            -compare target.gal query.gal scores.mtx \
+            -makeMask ../data/MEDS/sigset/MEDS_frontal_target.xml ../data/MEDS/sigset/MEDS_frontal_query.xml MEDS.mask \
+            -eval scores.mtx MEDS.mask Algorithm_Dataset/FaceRecognition_MEDS.csv \
+            -plot Algorithm_Dataset/FaceRecognition_MEDS.csv MEDS
+         
  
-    $ br -algorithm FaceRecognition -enrollAll -enroll ../data/MEDS/img 'meds.gal;meds.csv[separator=;]'
-    $ br -algorithm FaceRecognition -compare meds.gal ../data/MEDS/img/S001-01-t10_01.jpg match_scores.csv
+* Perform a 1:N face recognition search:
  
-Or, train a new face recognition algorithm (on a different dataset):
+    	$ br -algorithm FaceRecognition -enrollAll -enroll ../data/MEDS/img 'meds.gal'
+    	$ br -algorithm FaceRecognition -compare meds.gal ../data/MEDS/img/S001-01-t10_01.jpg match_scores.csv
  
-    $ br -algorithm '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)' -train ../data/ATT/img FaceRecognitionATT
+* Train a new face recognition algorithm (on a different dataset):
+
+    	$ br -algorithm '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)' -train ../data/ATT/img FaceRecognitionATT
  
 The entire command line API is documented [here](api_docs/cl_api.md).
  
@@ -180,14 +183,14 @@ The entire command line API is documented [here](api_docs/cl_api.md).
  
 # Age Estimation
  
-Age Estimation is very similar in spirit to [Face Recognition](#face-recognition) and will be covered in far less detail.
+Age estimation is very similar in spirit to [Face Recognition](#face-recognition) and will be covered in far less detail.
  
-To implement Age Estimation from the command line you can run
+To perform age estimation from the command line you can run:
  
     $ br -algorithm AgeEstimation \
         -enroll ../data/MEDS/img/S354-01-t10_01.jpg ../data/MEDS/img/S001-01-t10_01.jpg metadata.csv
  
-The results will be stored in metadata.csv under the key 'Age'. Remember from the [Face Recognition](#face-recognition) 'AgeEstimation' is just an abbreviation for the full algorithm description. The expanded version is stored in ```openbr/plugins/core/algorithms.cpp```.
+The results will be stored in metadata.csv under the key 'Age'. Remember from the [Face Recognition](#face-recognition) tutorial that `AgeEstimation` is just an abbreviation for the full algorithm description.
  
 The source code to run age estimation as an application is in ```app/examples/age_estimation.cpp```
  
@@ -195,14 +198,14 @@ The source code to run age estimation as an application is in ```app/examples/ag
  
 # Gender Estimation
  
-Gender Estimation is very similar in spirit to [Face Recognition](#face-recognition) and will be covered in far less detail.
+As with age estimation, gender estimation is very similar in spirit to [Face Recognition](#face-recognition) and will be covered in far less detail.
  
-To implement Gender Estimation from the command line you can run
+To perform gender estimation from the command line you can run:
  
     $ br -algorithm GenderEstimation \
         -enroll ../data/MEDS/img/S354-01-t10_01.jpg ../data/MEDS/img/S001-01-t10_01.jpg metadata.csv
  
-The results will be stored in metadata.csv under the key 'Gender'. Remember from the [Face Recognition](#face-recognition) 'GenderEstimation' is just an abbreviation for the full algorithm description. The expanded version is stored in ```openbr/plugins/core/algorithms.cpp```.
+The results will be stored in metadata.csv under the key 'Gender'. Remember from the [Face Recognition](#face-recognition) tutorial that `GenderEstimation` is just an abbreviation for the full algorithm description.
  
 The source code to run gender estimation as an application is in ```app/examples/gender_estimation.cpp```
  
@@ -212,11 +215,11 @@ The source code to run gender estimation as an application is in ```app/examples
  
 OpenBR exposes a [C++ API](api_docs/cpp_api.md) that can be embedded into your own applications. Let's step through the example code at ```app/example/face_recognition.cpp``` and learn about using OpenBR as a library.
  
-Our main function starts with-
+Our main function starts with:
  
     br::Context::initialize(argc, argv)
  
-This is the first step in any OpenBR application, it initializes the global context.
+This is the first step in any OpenBR-based application, it initializes the global context.
  
     QSharedPointer<br::Transform> transform = br::Transform::fromAlgorithm("FaceRecognition");
     QSharedPointer<br::Distance> distance = br::Distance::fromAlgorithm("FaceRecognition");
@@ -227,29 +230,29 @@ Here, we split our algorithm into *enrollment* ([Transform](api_docs/cpp_api/tra
     br::Template queryB("../data/MEDS/img/S382-08-t10_01.jpg");
     br::Template target("../data/MEDS/img/S354-02-t10_01.jpg");
  
-These lines create our [Templates](api_docs/cpp_api/template/template.md) for enrollment. They are just images loaded from disk. For this example queryA is the same person (different picture) as target and queryB is a different person.
+These lines create our [Template](api_docs/cpp_api/template/template.md)s for enrollment. At this point, the Templates simply store the file path to the specified image on disk. In this example, `queryA` depicts the same person as `target` (often referred to as a *genuine match*) and `queryB` depicts a different person from `target` (often referred to as an *impostor match*).
  
     queryA >> *transform;
     queryB >> *transform;
     target >> *transform;
  
-And now we enroll them! **>>** is a convienience operator for enrolling [Templates](api_docs/cpp_api/template/template.md) in [Transforms](api_docs/cpp_api/transform/transform.md). The enrollment is done in-place, which means the output overwrites the input. Our [Templates](api_docs/cpp_api/template/template.md) now store the results of enrollment.
+`>>` is a convienience operator for enrolling [Template](api_docs/cpp_api/template/template.md)s in [Transform](api_docs/cpp_api/transform/transform.md)s. Thus, at this stage, our [Template](api_docs/cpp_api/template/template.md)s now store the images enrolled via the `FaceRecognition` algorithm.
  
     float comparisonA = distance->compare(target, queryA);
     float comparisonB = distance->compare(target, queryB);
  
-Compare our query [Templates](api_docs/cpp_api/template/template.md) against the target [Template](api_docs/cpp_api/template/template.md). The result is a float.
+We then compare our query [Template](api_docs/cpp_api/template/template.md)s against the target [Template](api_docs/cpp_api/template/template.md). The result is a floating point value indicating similarity.
  
     printf("Genuine match score: %.3f\n", comparisonA);
     printf("Impostor match score: %.3f\n", comparisonB);
  
-Print out our results. You can see that comparisonA (between queryA and target) has a higher score then comparisonB, which is exactly what we expect!
+After printing the results, you can see that `comparisonA` (between `queryA` and `target`) has a higher similarity score then `comparisonB`, which is exactly what we expect!
  
     br::Context::finalize();
  
-The last line in any OpenBR application has to be call to finalize. This shuts down OpenBR.
+The last line in any OpenBR application has to be call to `finalize`. This functions performs the clean up of OpenBR.
  
-And that's it! Now you can embed face recognition into all of your applications.
+That's it! You can now embed face recognition into all of your applications.
  
 ---
  
@@ -257,13 +260,13 @@ And that&#39;s it! Now you can embed face recognition into all of your applications.
  
 OpenBR implements a complete, [NIST](http://www.nist.gov/index.html) compliant, evaluation harness for evaluating face recognition, face detection, and facial landmarking. The goal is to provide a consistent environment for the repeatable evaluation of algorithms to the academic and open source communities. To accompish this OpenBR defines the following portions of the biometrics evaluation environment (BEE) standard-
  
-* Signature Set- A signature set (or *sigset*) is a [Gallery](api_docs/cpp_api/gallery/gallery.md) compliant **XML** file-list specified on page 9 of the [MBGC File Overview](misc/MBGC_file_overview.pdf) and implemented in [xmlGallery](api_docs/plugins/gallery.md#xmlgallery). Sigsets are identified with a **.xml** extension.
+* Signature set - A signature set (or *sigset*) is an XML file-list specified on page 9 of the [MBGC File Overview](misc/MBGC_file_overview.pdf) and is implemented in [xmlGallery](api_docs/plugins/gallery.md#xmlgallery). Sigsets are identified with an `.xml` extension.
  
-* Similarity Matrix- A similarity matrix (or *simmat*) is an [Output](api_docs/cpp_api/output/output.md) compliant binary score matrix specified on page 12 of the [MBGC File Overview](misc/MBGC_file_overview.pdf) and implemented in [mtxOutput](api_docs/plugins/output.md#mtxoutput). Simmats are identified with a **.mtx** extension. See [br_eval](api_docs/c_api/functions.md#br_eval) for more information.
+* Similarity matrix - A similarity matrix (or *simmat*) is a binary score matrix specified on page 12 of the [MBGC File Overview](misc/MBGC_file_overview.pdf) and is implemented in [mtxOutput](api_docs/plugins/output.md#mtxoutput). Simmats are identified with a `.mtx` extension. See [br_eval](api_docs/c_api/functions.md#br_eval) for more information.
  
-* Mask Matrix- A mask matrix (or *mask*) is a binary matrix specified on page 14 of the [MBGC File Overview](misc/MBGC_file_overview.pdf) identifying the ground truth genuines and impostors of a corresponding *simmat*. Masks are identified with a **.mask** extension. See [br_make_mask](api_docs/c_api/functions.md#br_make_mask) and [br_combine_masks](api_docs/c_api/functions.md#br_combine_masks) for more information.
+* Mask matrix - A mask matrix (or *mask*) is a binary matrix specified on page 14 of the [MBGC File Overview](misc/MBGC_file_overview.pdf) identifying the genuine and impostor matches within a corresponding *simmat*. Masks are identified with a `.mask` extension. See [br_make_mask](api_docs/c_api/functions.md#br_make_mask) and [br_combine_masks](api_docs/c_api/functions.md#br_combine_masks) for more information.
  
-The evaluation harness is also accessible from the command line! Please see [-eval](api_docs/cl_api.md#eval), [-evalDetection](api_docs/cl_api.md#evaldetection), [-evalLandmarking](api_docs/cl_api.md#evallandmarking), [-evalClassification](api_docs/cl_api.md#evalclassification), [-evalClustering](api_docs/cl_api.md#evalclustering), or [-evalRegression](api_docs/cl_api.md#evalregression) for relevant information.
+The evaluation harness is also accessible from the command line. See [-eval](api_docs/cl_api.md#eval), [-evalDetection](api_docs/cl_api.md#evaldetection), [-evalLandmarking](api_docs/cl_api.md#evallandmarking), [-evalClassification](api_docs/cl_api.md#evalclassification), [-evalClustering](api_docs/cl_api.md#evalclustering), or [-evalRegression](api_docs/cl_api.md#evalregression) for relevant information.
  
 [^1]: *Matthew Turk and Alex Pentland.*
     **Eigenfaces for recognition.**