diff --git a/CMakeLists.txt b/CMakeLists.txt index 14df738..2ea1395 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -169,16 +169,6 @@ foreach(DIR ${BR_THIRDPARTY_APPS_DIR}) add_subdirectory(${DIR} 3rdparty_apps/${FNAME}) endforeach() -# Build the documentation? -option(BR_BUILD_DOCUMENTATION "Build Documentation (Requires doxygen and latex)") -if(${BR_BUILD_DOCUMENTATION}) - find_package(Doxygen REQUIRED) - configure_file(${BR_SHARE_DIR}/Doxyfile.in Doxyfile) - add_custom_target(doc ALL ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) - configure_file(${CMAKE_CURRENT_SOURCE_DIR}/share/openbr/MBGC_file_overview.pdf ${CMAKE_CURRENT_BINARY_DIR}/html/MBGC_file_overview.pdf COPYONLY) - install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION .) -endif() - # Install install(FILES CHANGELOG.md LICENSE.txt README.md DESTINATION share/openbr) install(DIRECTORY share DESTINATION .) diff --git a/app/br/br.cpp b/app/br/br.cpp index 75dc390..a130813 100644 --- a/app/br/br.cpp +++ b/app/br/br.cpp @@ -257,19 +257,22 @@ private: "-train ... [{model}]\n" "-enroll ... {output_gallery}\n" "-compare [{output}]\n" + "-pairwiseCompare [{output}]\n" "-eval [] [{csv}] [{matches}]\n" + "-inplaceEval [{csv}]\n" "-plot ... {destination}\n" "\n" "==== Other Commands ====\n" "-fuse ... (None|MinMax|ZScore|WScore) (Min|Max|Sum[W1:W2:...:Wn]|Replace|Difference|None) {simmat}\n" "-cluster ... {csv}\n" "-makeMask {mask}\n" + "-makePairwiseMask {mask}\n" "-combineMasks ... {mask} (And|Or)\n" "-cat ... {gallery}\n" "-convert (Format|Gallery|Output) {output_file}\n" "-evalClassification \n" "-evalClustering \n" - "-evalDetection [{csv}] [{normalize}] [{minSize}]\n" + "-evalDetection [{csv}] [{normalize}] [{minSize}] [{maxSize}]\n" "-evalLandmarking [{csv} [ ] [sample_index] [total_examples]]\n" "-evalRegression \n" "-assertEval \n" @@ -277,6 +280,7 @@ private: "-plotLandmarking ... {destination}\n" "-plotMetadata ... \n" "-project {output_gallery}\n" + "-deduplicate " "-getHeader \n" "-setHeader {} \n" "- \n" @@ -288,6 +292,7 @@ private: "-about\n" "-version\n" "-daemon\n" + "-slave\n" "-exit\n"); } }; diff --git a/docs/DOCS.md b/docs/DOCS.md new file mode 100644 index 0000000..a52a946 --- /dev/null +++ b/docs/DOCS.md @@ -0,0 +1,13 @@ +# OpenBR Documentation Guide + +This is a quick guide for generating the OpenBR documentation on your local machine. The documentation is available online at www.openbiometrics.org. + +OpenBR's documentation is built with MkDocs. Please see their website for additional information at www.mkdocs.org. Installing mkdocs with pip is super easy- + + $ pip install mkdocs + +Please note that you need Python 2.7 and above already installed. Once mkdocs is installed you can run build_docs.sh to build static html pages at openbr/docs/site. However, for viewing we recommend serving the docs to your browser using a simple http server. Run + + $ mkdocs serve + +from openbr/docs and then go to http://127.0.0.1:8000 in your internet browser of choice to view the docs locally. diff --git a/docs/build_docs.sh b/docs/build_docs.sh new file mode 100644 index 0000000..4bdf83a --- /dev/null +++ b/docs/build_docs.sh @@ -0,0 +1,6 @@ +# Build the OpenBR documentation as static html +# +# NOTE: This requires mkdocs to be installed. Please see DOCS.md file for +# instructions + +mkdocs build --clean diff --git a/docs/docs/api_docs.md b/docs/docs/api_docs.md new file mode 100644 index 0000000..f96cb2f --- /dev/null +++ b/docs/docs/api_docs.md @@ -0,0 +1,10 @@ +# API Documentation + +OpenBR offers four APIs for your convenience: + +* [C API](api_docs/c_api.md) +* [Command Line API](api_docs/cl_api.md) +* [Python API](api_docs/python_api.md) +* [C++ Plugin API](api_docs/cpp_api.md) + +Please see the detailed documentation for each to learn more. diff --git a/docs/docs/api_docs/c_api.md b/docs/docs/api_docs/c_api.md new file mode 100644 index 0000000..799f38e --- /dev/null +++ b/docs/docs/api_docs/c_api.md @@ -0,0 +1,28 @@ +# C API + +The C API is a high-level API for running algorithms and evaluating results. + +In order to provide a high-level interface that is usable from the command line and callable from other programming languages, the API is designed to operate at the "file system" level. +In other words, arguments to many functions are file paths that specify either a source of input or a desired output. +File extensions are relied upon to determine *how* files should be interpreted in the context of the function being called. +The [C++ Plugin API](cpp_api.md) should be used if more fine-grained control is required. + +## Important API Considerations + +Name | Consideration +--- | --- +Memory | Memory for const char* return values is managed internally and guaranteed until the next call to the function +Input String Buffers | Users should input a char * buffer and the size of that buffer. String data will be copied into the buffer, if the buffer is too small, only part of the string will be copied. Returns the buffer size required to contain the complete string. + + +## Using the API + +To use the API in your project include the following file: + + #include + +[CMake](http://www.cmake.org/) developers may wish to the cmake configuration file found at: + + share/openbr/cmake/OpenBRConfig.cmake + +Please see the [tutorials](../tutorials.md) section for examples. diff --git a/docs/docs/api_docs/c_api/functions.md b/docs/docs/api_docs/c_api/functions.md new file mode 100644 index 0000000..4c54895 --- /dev/null +++ b/docs/docs/api_docs/c_api/functions.md @@ -0,0 +1,1397 @@ +## br_about + +Calls [Context](../cpp_api/context/context.md)::[about](../cpp_api/context/statics.md#about). + +* **function definition:** + + const char *br_about() + +* **parameters:** None +* **output:** (const char *) Returns a string describing OpenBR +* **see:** [br_version](#br_version) + +--- + +## br_cat + +Concatenates a list of galleries into 1 gallery. + +* **function definition:** + + void br_cat(int num_input_galleries, const char *input_galleries[], const char *output_gallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_input_galleries | int | Size of input_galleries + input_galleries[] | const char * | List of galleries + output_gallery | const char * | Pointer to store concatenated gallery + +* **output:** void +* **see:** [Cat](../cpp_api/apifunctions.md#cat) + +--- + +## br_deduplicate + +Removes duplicate [templates](../cpp_api/template/template.md) in a [gallery](../cpp_api/gallery/gallery.md). If a galley contains n duplicates, the first n-1 duplicates in the gallery will be removed and the nth will be kept. Users are encouraged to use binary gallery formats as the entire gallery is read into memory in one call to [Gallery](../cpp_api/gallery/gallery.md)::[read](../cpp_api/gallery/functions.md#read). + +* **function definition:** + + void br_deduplicate(const char *input_gallery, const char *output_gallery, const char *threshold) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input_gallery | const char * | Gallery to be deduplicated + output_gallery | const char * | Deduplicated gallery + threshold | const char * | Comparisons with a match score >= this value are designated to be duplicates. + +* **output:** (void) + +--- + +## br_cluster + +Clusters one or more similarity matrices into a list of subjects. A [similarity matrix](../../tutorials.md#the-evaluation-harness) is a type of [Output](../cpp_api/output/output.md). The current clustering algorithm is a simplified implementation of the algorithm proposed by Zhu et al[^1]. + +* **function definition:** + + void br_cluster(int num_simmats, const char *simmats[], float aggressiveness, const char *csv) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_simmats | int | Size of **simmats** + simmats[] | const char * | Array of [simmat](../../tutorials.md#the-evaluation-harness) composing one large self-similarity matrix arranged in row major order. + aggressiveness | float | The higher the aggressiveness the larger the clusters. Suggested range is [0,10] + csv | const char * | The cluster results file to generate. Results are stored one row per cluster and use gallery indices. + +* **output:** (void) + +--- + +## br_combine_masks + +Combines several equal-sized mask matrices. A comparison may not be simultaneously indentified as both a genuine and an imposter by different input masks. + +* **function definition:** + + void br_combine_masks(int num_input_masks, const char *input_masks[], const char *output_mask, const char *method) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_input_masks | int | Size of **input_masks** + input_masks[] | const char * | Array of [mask matrices](../../tutorials.md#the-evaluation-harness) to combine. All matrices must have the same dimensions. + output_mask | const char * | The file to contain the resulting [mask matrix](../../tutorials.md#the-evaluation-harness) + method | const char * | Possible values are:
  • And - Ignore comparison if *any* input masks ignore.
  • Or - Ignore comparison if *all* input masks ignore.
+ +* **see:** [br_make_mask](#br_make_mask) + +--- + +## br_compare + +Compares each [Template](../cpp_api/template/template.md) in the query [Gallery](../cpp_api/gallery/gallery.md) to each [Template](../cpp_api/template/template.md) in the target [Gallery](../cpp_api/gallery/gallery.md). + +* **function definition:** + + void br_compare(const char *target_gallery, const char *query_gallery, const char *output = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + target_gallery | const char * | target_gallery The [Gallery](../cpp_api/gallery/gallery.md) file whose templates make up the columns of the output. + query_gallery | const char * | The [Gallery](../cpp_api/gallery/gallery.md) file whose templates make up the rows of the output. A value of '.' reuses the target gallery as the query gallery. + output | const char * | (Optional) The [Output](../cpp_api/output/output.md) file to contain the results of comparing the templates. The default behavior is to print scores to the terminal. + +* **output:** (void) +* **see:** br_enroll + +--- + +## br_compare_n + +Convenience function for comparing to multiple targets. + +* **function definition:** + + void br_compare_n(int num_targets, const char *target_galleries[], const char *query_gallery, const char *output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_targets | int | Size of **target_galleries** + target_galleries[] | const char * | Target galleries to compare against + query_gallery | const char * | query gallery for comparison. + output | const char * | (Optional) [Output](../cpp_api/output/output.md) file to contain the results of comparing the templates. The default behavior is to print scores to the terminal. + +* **output:** (void) +* **see:** br_compare + +--- + +## br_pairwise_compare + +DOCUMENT ME! + +* **function definition:** + + void br_pairwise_compare(const char *target_gallery, const char *query_gallery, const char *output = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + target_gallery | const char * | DOCUMENT ME + query_gallery | const char * | DOCUMENT ME + output | const char * | DOCUMENT ME + +* **output:** (void) + +--- + +## br_convert + +Convert a file to a different type. Files can only be converted to types within the same group. For example [formats](../cpp_api/format/format.md) can only be converted to other [formats](../cpp_api/format/format.md). + +* **function definition:** + + void br_convert(const char *file_type, const char *input_file, const char *output_file) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + file_type | const char * | Type of file to convert. Options are [Format](../cpp_api/format/format.md), [Gallery](../cpp_api/gallery/gallery.md) or [Output](../cpp_api/output/output.md). + input_file | const char * | File to convert. + output_file | const char * | Output file. Type is determined by the file extension. + +* **output:** (void) + +--- + +## br_enroll + +Constructs [Template(s)](../cpp_api/template/template.md) from an input. + +* **function definition:** + + void br_enroll(const char *input, const char *gallery = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const char * | The [format](../cpp_api/format/format.md) or [gallery](../cpp_api/gallery/gallery.md) to enroll. + gallery | const char * | (Optional) The [Gallery](../cpp_api/gallery/gallery.md) file to contain the enrolled templates. By default the gallery will be held in memory and *input* can used as a gallery in [br_compare](#br_compare) + +* **output:** (void) +* **see:** [br_enroll_n](#br_enroll_n) + +--- + +## br_enroll_n + +Convenience function for enrolling multiple inputs. + +* **function definition:** + + void br_enroll_n(int num_inputs, const char *inputs[], const char *gallery = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_inputs | int | Size of **inputs**. + inputs[] | const char * | Array of inputs to enroll. + gallery | const char * | (Optional) The [Gallery](../cpp_api/gallery/gallery.md) file to contain the enroll templates. + +* **output:** (void) +* **see:** [br_enroll](#br_enroll) + +--- + +## br_project + +A naive alternative to [br_enroll](#br_enroll). + +* **function definition:** + + void br_project(const char *input, const char *output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const char * | The [format](../cpp_api/format/format.md) or [gallery](../cpp_api/gallery/gallery.md) to enroll. + output | const char * | The [Gallery](../cpp_api/gallery/gallery.md) file to contain the enrolled templates. By default the gallery will be held in memory and *input* can used as a gallery in [br_compare](#br_compare) + +* **output:** (void) +* **see:** [br_enroll](#br_enroll) + +--- + +## br_eval + +Creates a **.csv** file containing performance metrics from evaluating the similarity matrix using the mask matrix. + +* **function defintion:** + + float br_eval(const char *simmat, const char *mask, const char *csv = "", int matches = 0) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + simmat | const char * | The [simmat](../../tutorials.md#the-evaluation-harness) to use + mask | const char * | The [mask](../../tutorials.md#the-evaluation-harness) to use. + csv | const char * | (Optional) The **.csv** file to contain performance metrics. + matches | int | (Optional) An integer number of matches to output around the EER. Default is 0. + +* **output:** (float) Returns the true accept rate (TAR) at a false accept rate (FAR) of one in one thousand +* **see:** [br_plot](#br_plot) + +--- + +## br_assert_eval + +Evaluates the similarity matrix using the mask matrix. Function aborts if TAR @ FAR = 0.001 does not meet an expected performance value. + +* **function definition:** + + void br_assert_eval(const char *simmat, const char *mask, const float accuracy) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + simmat | const char * | The [simmat](../../tutorials.md#the-evaluation-harness) to use + mask | const char * | The [mask](../../tutorials.md#the-evaluation-harness) + accuracy | const float | Desired true accept rate at false accept rate of one in one thousand. + +* **output:** (void) + +--- + +## br_inplace_eval + +Creates a **.csv** file containing performance metrics from evaluating the similarity matrix using galleries containing ground truth labels. + +* **function definition:** + + float br_inplace_eval(const char * simmat, const char *target, const char *query, const char *csv = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + simmat | const char * | The [simmat](../../tutorials.md#the-evaluation-harness) + target | const char * | The name of a gallery containing metadata for the target set. + query | const char * | The name of a gallery containing metadata for the query set. + csv | const char * | (Optional) The **.csv** file to contain performance metrics. + +* **output:** (float) Returns the true accept rate (TAR) at a false accept rate (FAR) of one in one thousand +* **see:** [br_plot](#br_plot) + +--- + +## br_eval_classification + +Evaluates and prints classification accuracy to terminal. + +* **function definition:** + + void br_eval_classification(const char *predicted_gallery, const char *truth_gallery, const char *predicted_property = "", const char *truth_property = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + predicted_gallery | const char * | The predicted [Gallery](../cpp_api/gallery/gallery.md). + truth_gallery | const char * | The ground truth [Gallery](../cpp_api/gallery/gallery.md). + predicted_property | const char * | (Optional) Which metadata key to use from the **predicted_gallery**. + truth_property | const char * | (Optional) Which metadata key to use from the **truth_gallery**. + +* **output:** (void) + +--- + +## br_eval_clustering + +Evaluates and prints clustering accuracy to the terminal. + +* **function definition:** + + void br_eval_clustering(const char *csv, const char *gallery, const char * truth_property) + +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +csv | const char * | The cluster results file. +gallery | const char * | The [Gallery](../cpp_api/gallery/gallery.md) used to generate the [simmat](../../tutorials.md#the-evaluation-harness) that was clustered. +truth_property | const char * | (Optional) which metadata key to use from **gallery**, defaults to Label + +* **output:** (void) + +--- + +## br_eval_detection + +Evaluates and prints detection accuracy to terminal. + +* **function definition:** + + float br_eval_detection(const char *predicted_gallery, const char *truth_gallery, const char *csv = "", bool normalize = false, int minSize = 0, int maxSize = 0) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + predicted_gallery | const char * | The predicted [Gallery](../cpp_api/gallery/gallery.md). + truth_gallery | const char * | The ground truth [Gallery](../cpp_api/gallery/gallery.md). + csv | const char * | (Optional) The **.csv** file to contain performance metrics. + normalize | bool | (Optional) Flag to normalize predicted bounding boxes for improved detection. Defaults to false. + minSize | int | (Optional) Minimum size of faces to be considered in the evaluation. Size is applied to predicted and ground truth galleries. Defaults to -1 (no minimum size). + maxSize | int | (Optional) Maximum size if faces to be considered in the evaluation. Size is applied to predicted and ground truth galleries. Defaults to -1 (no maximum size). + +* **output:** (float) Returns the true accept rate (TAR) at a false accept rate (FAR) of one in one thousand + +--- + +## br_eval_landmarking + +Evaluates and prints landmarking accuracy to terminal. + +* **function definition:** + + float br_eval_landmarking(const char *predicted_gallery, const char *truth_gallery, const char *csv = "", int normalization_index_a = 0, int normalization_index_b = 1, int sample_index = 0, int total_examples = 5) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + predicted_gallery | const char * | The predicted [Gallery](../cpp_api/gallery/gallery.md). + truth_gallery | const char * | The ground truth [Gallery](../cpp_api/gallery/gallery.md). + csv | const char * | (Optional) The **.csv** file to contain performance metrics. + normalization_index_a | int | (Optional) The first index in the list of points to use for normalization. Default is 0. + normalization_index_b | int | (Optional) The second index in the list of points to use for normalization. Default is 1. + sample_index | int | (Optional) The index for sample landmark image in ground truth gallery. Default = 0. + total_examples | int | (Optional) The number of accurate and inaccurate examples to display. Default is 5. + +* **output:** (float) Returns the true accept rate (TAR) at a false accept rate (FAR) of one in one thousand + +--- + +## br_eval_regression + +Evaluates regression accuracy to disk. + +* **function definition:** + + void br_eval_regression(const char *predicted_gallery, const char *truth_gallery, const char *predicted_property = "", const char *truth_property = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + predicted_gallery | const char * | The predicted [Gallery](../cpp_api/gallery/gallery.md) + truth_gallery | const char * | The ground truth [Gallery](../cpp_api/gallery/gallery.md) + predicted_property | const char * | (Optional) Which metadata key to use from **predicted_gallery**. + truth_property | const char * | (Optional) Which metadata key to use from **truth_gallery**. + +* **output:** (void) + +--- + +## br_fuse + +Perform score level fusion on similarity matrices. + +* **function definition:** + + void br_fuse(int num_input_simmats, const char *input_simmats[], const char *normalization, const char *fusion, const char *output_simmat) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_input_simmats | int | Size of **input_simmats**. + input_simmats[] | const char * | Array of [simmats](../../tutorials.md#the-evaluation-harness). All simmats must have the same dimensions. + normalization | const char * | Valid options are:
  • None - No score normalization.
  • MinMax - Scores normalized to [0,1].
  • ZScore - Scores normalized to a standard normal curve.
+ fusion | const char * | Valid options are:
  • Min - Uses the minimum score.
  • Max - Uses the maximum score.
  • Sum - Sums the scores. Sums can also be weighted: SumW1:W2:...:Wn.
  • Replace - Replaces scores in the first matrix with scores in the second matrix when the mask is set.
+ output_simmat | const char * | [Simmat](../../tutorials.md#the-evaluation-harness) to contain the fused scores. + +* **output:** (void) + +--- + +## br_initialize + +Initializes the [Context](../cpp_api/context/context.md). Required at the beginning of any OpenBR program. + +* **function definition:** + + void br_initialize(int &argc, char *argv[], const char *sdk_path = "", bool use_gui = false) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + argc | int | Number of command line arguments. + argv[] | char * | Array of command line arguments. + sdk_path | const char * | (Optional) Path to the OpenBR sdk. If no path is provided OpenBR will try and find the sdk automatically. + use_gui | bool | (Optional) Enable OpenBR to use make GUI windows. Default is false. + +* **output:** (void) +* **see:** [br_finalize](#br_finalize) + +--- + +## br_initialize_default + +Initializes the [Context](../cpp_api/context/context.md) with default arguments. + +* **function definition:** + + void br_initialize_default() + +* **parameters:** None +* **output:** (void) +* **see:** [br_finalize](#br_finalize) + +--- + +## br_finalize + +Finalizes the context. Required at the end of any OpenBR program. + +* **function definition:** + + void br_finalize() + +* **parameters:** None +* **output:** (void) +* **see:** [br_initialize](#br_initialize) + +--- + +## br_is_classifier + +Checks if the provided algorithm is a classifier. Wrapper of [IsClassifier](../cpp_api/apifunctions.md#isclassifier). + +* **function definition:** + + bool br_is_classifier(const char *algorithm) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + algorithm | const char * | Algorithm to check. + +* **output:** (bool) Returns true if the algorithm is a classifier (does not have an associated distance) +* **see:** [IsClassifier](../cpp_api/apifunctions.md#isclassifier) + +--- + +## br_make_mask + +Constructs a [mask](../../tutorials.md#the-evaluation-harness) from target and query inputs. + +* **function definition:** + + void br_make_mask(const char *target_input, const char *query_input, const char *mask) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + target_input | const char * | The target [Gallery](../cpp_api/gallery/gallery.md) + query_input | const char * | The query [Gallery](../cpp_api/gallery/gallery.md) + mask | const char * | The file to contain the resulting [mask](../../tutorials.md#the-evaluation-harness). + +* **output:** (void) +* **see:** [br_combine_masks](#br_combine_masks) + +--- + +## br_make_pairwise_mask + +Constructs a [mask](../../tutorials.md#the-evaluation-harness) from target and query inputs considering the target and input sets to be definite pairwise comparisons. + +* **function definition:** + + void br_make_pairwise_mask(const char *target_input, const char *query_input, const char *mask) + +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +target_input | const char * | The target [Gallery](../cpp_api/gallery/gallery.md) +query_input | const char * | The query [Gallery](../cpp_api/gallery/gallery.md) +mask | const char * | The file to contain the resulting [mask](../../tutorials.md#the-evaluation-harness). + +* **output:** (void) +* **see:** [br_combine_masks](#br_combine_masks) + +--- + +## br_most_recent_message + +Returns the most recent line sent to stderr. For information on input string buffers please look [here](../c_api.md#input-string-buffers) + +* **function definition:** + + int br_most_recent_message(char * buffer, int buffer_length) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + buffer | char * | Buffer to store the last line in. + buffer_length | int | Length of the buffer. + +* **output:** (int) Returns the required size of the input buffer for the most recent message to fit completely +* **see:** [br_progress](#br_progress), [br_time_remaining](#br_time_remaining) + +--- + +## br_objects + +Returns names and parameters for the requested objects. Each object is newline seperated. Arguments are seperated from the object name with a tab. This function uses [QRegExp][QRegExp] syntax. + +* **function definition:** + + int br_objects(char * buffer, int buffer_length, const char *abstractions = ".*", const char *implementations = ".*", bool parameters = true) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + buffer | char * | Output buffer for results. + buffer_length | int | Length of output buffer. + abstractions | const char * | (Optional) Regular expression of the abstractions to search. Default is ".\*". + implementations | const char * | (Optional) Regular expression of the implementations to search. Default is ".\*". + parameters | bool | (Optional) Include parameters after object name. Default is true. + +* **output:** (int) Returns the required size of the input buffer for the returned objects to fit completely + +--- + +## br_plot + +Renders recognition performance figures for a set of **.csv** files created by [br_eval](#br_eval). + +In order of their output, the figures are: +1. Metadata table +2. Receiver Operating Characteristic (ROC) +3. Detection Error Tradeoff (DET) +4. Score Distribution (SD) histogram +5. True Accept Rate Bar Chart (BC) +6. Cumulative Match Characteristic (CMC) +7. Error Rate (ERR) curve + +Two files will be created: + * **destination.R** which is the auto-generated R script used to render the figures. + * **destination.pdf** which has all of the figures in one file multi-page file. + +OpenBR uses file and folder names to automatically determine the plot legend. +For example, let's consider the case where three algorithms (A, B, & C) were each evaluated on two datasets (Y & Z). +The suggested way to plot these experiments on the same graph is to create a folder named Algorithm_Dataset that contains the six .csv files produced by br_eval A_Y.csv, A_Z.csv, B_Y.csv, B_Z.csv, C_Y.csv, & C_Z.csv. +The '_' character plays a special role in determining the legend title(s) and value(s). +In this case, A, B, & C will be identified as different values of type Algorithm, and each will be assigned its own color; Y & Z will be identified as different values of type Dataset, and each will be assigned its own line style. +Matches around the EER will be displayed if the matches parameter is set in [br_eval](#br_eval). + +This function requires a current [R][R] installation with the following packages: + + install.packages(c("ggplot2", "gplots", "reshape", "scales", "jpg", "png")) + +* **function definiton:** + + bool br_plot(int num_files, const char *files[], const char *destination, bool show = false) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_files | int | Number of **.csv** files. + files[] | const char * | **.csv** files created using [br_eval](#br_eval). + destination | const char * | Basename for the resulting figures. + show | bool | Open **destination.pdf** using the system's default PDF viewer. Default is false. + +* **output:** (bool) Returns true on success. Returns false on a failure to compile the figures due to a missing, out of date, or incomplete R installation. +* **see:** [br_eval](#br_eval) + +--- + +## br_plot_detection + +Renders detection performance figures for a set of **.csv** files created by [br_eval_detection](#br_eval_detection). + +In order of their output, the figures are: +1. Discrete Receiver Operating Characteristic (DiscreteROC) +2. Continuous Receiver Operating Characteristic (ContinuousROC) +3. Discrete Precision Recall (DiscretePR) +4. Continuous Precision Recall (ContinuousPR) +5. Bounding Box Overlap Histogram (Overlap) +6. Average Overlap Table (AverageOverlap) +7. Average Overlap Heatmap (AverageOverlap) + +Detection accuracy is measured with *overlap fraction = bounding box intersection / union*. +When computing *discrete* curves, an overlap >= 0.5 is considered a true positive, otherwise it is considered a false negative. +When computing *continuous* curves, true positives and false negatives are measured fractionally as *overlap* and *1-overlap* respectively. + +This function requires a current [R](http://www.r-project.org/) installation with the following packages: + + install.packages(c("ggplot2", "gplots", "reshape", "scales", "jpg", "png")) + +* **function definition:** + + bool br_plot_detection(int num_files, const char *files[], const char *destination, bool show = false) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_files | int | Number of **.csv** files. + files[] | const char * | **.csv** files created using [br_eval_detection](#br_eval_detection). + destination | const char * | Basename for the resulting figures. + show | bool | Open **destination.pdf** using the system's default PDF viewer. Default is false. + +* **output:** (bool) Returns true on success. Returns false on a failure to compile the figures due to a missing, out of date, or incomplete R installation. +* **see:** [br_eval_detection](#br_eval_detection), [br_plot](#br_plot) + +--- + +## br_plot_landmarking + +Renders landmarking performance figures for a set of **.csv** files created by [br_eval_landmarking](#br_eval_landmarking). + +In order of their output, the figures are: +1. Cumulative landmarks less than normalized error (CD) +2. Normalized error box and whisker plots (Box) +3. Normalized error violin plots (Violin) + +Landmarking error is normalized against the distance between two predifined points, usually inter-ocular distance (IOD). + +* **function definition:** + + bool br_plot_landmarking(int num_files, const char *files[], const char *destination, bool show = false) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_files | int | Number of **.csv** files. + files[] | const char * | **.csv** files created using [br_eval_landmarking](#br_eval_landmarking). + destination | const char * | Basename for the resulting figures. + show | bool | Open **destination.pdf** using the system's default PDF viewer. Default is false. + +* **output:** (bool) Returns true on success. Returns false on a failure to compile the figures due to a missing, out of date, or incomplete R installation. +* **see:** [br_eval_landmarking](#br_eval_landmarking), [br_plot](#br_plot) + +--- + +## br_plot_metadata + +Renders metadata figures for a set of **.csv** files with specified columns. + +* **function definition:** + + bool br_plot_metadata(int num_files, const char *files[], const char *columns, bool show = false) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_files | int | Number of **.csv** files. + files[] | const char * | **.csv** files created by enrolling templates to **.csv** metadata files. + columns | const char * | ';' seperated list of columns to plot. + show | bool | Open **PlotMetadata.pdf** using the system's default PDF viewer. + +* **output:** (bool) Returns true on success. Returns false on a failure to compile the figures due to a missing, out of date, or incomplete R installation. +* **see:** [br_plot](#br_plot) + +--- + +## br_progress + +Returns current progress from [Context](../cpp_api/context/context.md)::[progress](../cpp_api/context/functions.md#progress). + +* **function definition:** + + float br_progress() + +* **parameters:** None + +* **output:** (float) Returns the completion percentage of the running process +* **see:** [br_most_recent_message](#br_most_recent_message), [br_time_remaining](#br_time_remaining) + +--- + +## br_read_pipe + +Read and parse arguments from a named pipe. Used by the [command line api](../cl_api.md) to implement **-daemon**, generally not useful otherwise. Guaranteed to return at least one argument. For information on managed returned values see [here](../c_api.md#memory) + +* **function defintion:** + + void br_read_pipe(const char *pipe, int *argc, char ***argv) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + pipe | const char * | Pipe name + argc | int * | Argument count + argv | char *** | Argument list + +* **output:** (void) + +--- + +## br_scratch_path + +Fills the buffer with the value of [Context](../cpp_api/context/context.md)::[scratchPath](../cpp_api/context/statics.md#scratchpath). For information on input string buffers see [here](../c_api.md#input-string-buffers). + +* **function defintion:** + + int br_scratch_path(char * buffer, int buffer_length) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + buffer | char * | Buffer for scratch path + buffer_length | int | Length of buffer. + +* **output:** (int) Returns the required size of the input buffer for the most recent message to fit completely +* **see:** [br_version](#br_version) + +--- + +## br_sdk_path + +Returns the full path to the root of the SDK. + +* **function definition:** + + const char *br_sdk_path() + +* **parameters:** None +* **output:** (const char *) Returns the full path to the root of the SDK +* **see:** [br_initialize](#br_initialize) + +--- + +## br_get_header + +Retrieve the target and query inputs in the [BEE matrix](../../tutorials.md#the-evaluation-harness) header. For information on managed return values see [here](../c_api.md#memory). + +* **function definition:** + + void br_get_header(const char *matrix, const char **target_gallery, const char **query_gallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + matrix | const char * | The [BEE matrix](../../tutorials.md#the-evaluation-harness) file to modify + target_gallery | const char ** | The matrix target + query_gallery | const char ** | The matrix query + +* **output:** (void) +* **set:** [br_set_header](#br_set_header) + +--- + +## br_set_header + +Update the target and query inputs in the [BEE matrix](../../tutorials.md#the-evaluation-harness) header. + +* **function definition:** + + void br_set_header(const char *matrix, const char *target_gallery, const char *query_gallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + matrix | const char * | The [BEE matrix](../../tutorials.md#the-evaluation-harness) file to modify + target_gallery | const char ** | The matrix target + query_gallery | const char ** | The matrix query + +* **output:** (void) +* **see:** [br_get_header](#br_get_header) + +--- + +## br_set_property + +Appends a provided value to the [global metadata](../cpp_api/context/context.md) using a provided key. + +* **function definition:** + + void br_set_property(const char *key, const char *value) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + key | const char * | Key to append + value | const char * | Value to append + +* **output:** (void) + +--- + +## br_time_remaining + +Returns estimate of time remaining in the current process. + +* **function definition:** + + int br_time_remaining() + +* **parameters:** None +* **output:** (int) Returns an estimate of the time remaining +* **see:** [br_most_recent_message](#br_most_recent_message), [br_progress](#br_progress) + +--- + +## br_train + +Trains a provided model's [Transform](../cpp_api/transform/transform.md) and [Distance](../cpp_api/distance/distance.md) on the provided input. + +* **function definiton:** + + void br_train(const char *input, const char *model = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const char * | The [Gallery](../cpp_api/gallery/gallery.md) to train on. + model | const char * | (Optional) String specifying the binary file to serialize training results to. The trained algorithm can be recovered by using this file as the algorithm. By default the trained algorithm will not be serialized to disk. + +* **output:** (void) +* **see:** [br_train_n](#br_train_n) + +--- + +## br_train_n + +Convenience function for training on multiple inputs + +* **function definition:** + + void br_train_n(int num_inputs, const char *inputs[], const char *model = "") + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + num_inputs | int | Size of **inputs** + inputs[] | const char * | An array of [galleries](../cpp_api/gallery/gallery.md) to train on. + model | const char * | (Optional) String specifying the binary file to serialize training results to. The trained algorithm can be recovered by using this file as the algorithm. By default the trained algorithm will not be serialized to disk. + +* **output:** (void) +* **see:** [br_train](#br_train) + +--- + +## br_version + +Get the current OpenBR version. + +* **function definition:** + + const char *br_version() + +* **parameters:** None +* **output:** (const char *) Returns the current OpenBR version +* **see:** [br_about](#br_about), [br_scratch_path](#br_scratch_path) + +--- + +## br_slave_process + +For internal use via [ProcessWrapperTransform](../../plugin_docs/core.md#processwrappertransform) + +* **function definition:** + + void br_slave_process(const char * baseKey) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + baseKey | const char * | base key for the slave process + +* **output:** (void) + +--- + +## br_load_img + +Load an image from a string buffer. This is an easy way to pass an image in memory from another programming language to openbr. + +* **function definition:** + + br_template br_load_img(const char *data, int len) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + data | const char * | The image buffer. + len | int | The length of the buffer. + +* **output:** ([br_template](typedefs.md#br_template) Returns a [br_template](typedefs.md#br_template) loaded with the provided image +* **see:** [br_unload_img](#br_unload_img) + +--- + +## br_unload_img + +Unload an image to a string buffer. This is an easy way to pass an image from openbr to another programming language. + +* **function definition:** + + unsigned char* br_unload_img(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md) + +* **output:** (unsigned char*) Returns a buffer loaded with the image data from tmpl +* **see:** [br_load_img](#br_load_img) + +--- + +## br_template_list_from_buffer + +Deserialize a [TemplateList](../cpp_api/templatelist/templatelist.md) from a buffer. Can be the buffer for a .gal file, since they are just a [TemplateList](../cpp_api/templatelist/templatelist.md) serialized to disk. + +* **function definition:** + + br_template_list br_template_list_from_buffer(const char *buf, int len) + +* **return type:** br_template_list +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +buf | const char * | The buffer. +len | int | The length of the buffer. + +* **output:** ([br_template_list](typedefs.md#br_template_list)) Returns a pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) created from the buffer. + +--- + +## br_free_template + +Free a [Template's](../cpp_api/template/template.md) memory. + +* **function definition:** + + void br_free_template(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | br_template | Pointer to the [Template](../cpp_api/template/template.md) to free. + +* **output:** (void) + +--- + +## br_free_template_list + +Free a [TemplateList's](../cpp_api/templatelist/templatelist.md) memory. + +* **function definition:** + + void br_free_template_list(br_template_list tl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tl | [br_template_list](typedefs.md#br_template_list) | Pointer to the [TemplateList](../cpp_api/templatelist/templatelist.md) to free. + +* **output:** (void) + +--- + +## br_free_output + +Free a [Output's](../cpp_api/output/output.md) memory. + +* **function definition:** + + void br_free_output(br_matrix_output output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + output | [br_matrix_output](typedefs.md#br_matrix_output) | Pointer to the[Output](../cpp_api/output/output.md) to free. + +* **output:** (void) + +--- + +## br_img_rows + +Returns the number of rows in an image. + +* **function definition:** + + int br_img_rows(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + +* **output:** (int) Returns the number of rows in an image + +--- + +## br_img_cols + +Returns the number of cols in an image. + +* **function definition:** + + int br_img_cols(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + +* **output:** (int) Returns the number of columns in an image + +--- + +## br_img_channels + +Returns the number of channels in an image. + +* **function definition:** + + int br_img_channels(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + +* **output:** (int) Returns the number of channels in an image + +--- + +## br_img_is_empty + +Checks if the image is empty. + +* **function definition:** + + bool br_img_is_empty(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + +* **output:** (bool) Returns true if the image is empty, false otherwise. + +--- + +## br_get_filename + +Get the name of the [file](../cpp_api/template/members.md#file) of a provided [Template](../cpp_api/template/template.md). For information on input string buffers please see [here](../c_api.md#input-string-buffers) + +* **function definition:** + + int br_get_filename(char * buffer, int buffer_length, br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + buffer | char * | Buffer to hold the filename + buffer_length | int | Length of the buffer + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + +* **output:** (int) Returns the size of the buffer required to hold the entire file name. + +--- + +## br_set_filename + +Set the name of the [file](../cpp_api/template/members.md#file) for a provided [Template](../cpp_api/template/template.md). + +* **function definition:** + + void br_set_filename(br_template tmpl, const char *filename) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + filename | const char * | New filename for the template. + +* **output:** (void) + +--- + +## br_get_metadata_string + +Get the [metadata](../cpp_api/file/members.md#m_metadata) value as a string for a provided key in a provided [Template](../cpp_api/template/template.md). + +* **function definition:** + + int br_get_metadata_string(char * buffer, int buffer_length, br_template tmpl, const char *key) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + buffer | char * | Buffer to hold the metadata string. + buffer_length | int | length of the buffer. + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md). + key | const char * | Key for the metadata lookup + +* **output:** (int) Returns the size of the buffer required to hold the entire metadata string + +--- + +## br_enroll_template + +Enroll a [Template](../cpp_api/template/template.md) from the C API! + +* **function definition:** + + br_template_list br_enroll_template(br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | br_template | Pointer to a [Template](../cpp_api/template/template.md). + +* **output:** ([br_template_list](typedefs.md#br_template_list)) Returns a pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + +--- + +## br_enroll_template_list + +Enroll a [TemplateList](../cpp_api/templatelist/templatelist.md) from the C API! + +* **function definition:** + + void br_enroll_template_list(br_template_list tl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tl | [br_template_list](typedefs.md#br_template_list) | Pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + +* **output:** (void) + +--- + +## br_compare_template_lists + +Compare [TemplateLists](../cpp_api/templatelist/templatelist.md) from the C API! + +* **function definition:** + + br_matrix_output br_compare_template_lists(br_template_list target, br_template_list query) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + target | br_template_list | Pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + query | br_template_list | Pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + + +* **output:** ([br_matrix_output](typedefs.md#br_matrix_output)) Returns a pointer to a [MatrixOutput](../cpp_api/matrixoutput/matrixoutput.md) + +--- + +## br_get_matrix_output_at + +Get a value in a provided [MatrixOutput](../cpp_api/matrixoutput/matrixoutput.md). + +* **function definition:** + + float br_get_matrix_output_at(br_matrix_output output, int row, int col) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + output | br_matrix_output | Pointer to [MatrixOutput](../cpp_api/matrixoutput/matrixoutput.md) + row | int | Row index for lookup + col | int | Column index for lookup + +* **output:** (float) Returns the value of the [MatrixOutput](../cpp_api/matrixoutput/matrixoutput.md) at the provided indexes. + +--- + +## br_get_template + +Get a [Template](../cpp_api/template/template.md) from a [TemplateList](../cpp_api/templatelist/templatelist.md) at a specified index. + +* **function definition:** + + br_template br_get_template(br_template_list tl, int index) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tl | [br_template_list](typedefs.md#br_template_list) | Pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + index | int | Index into the template list. Should be in the range [0,len(tl) - 1]. + +* **output:** ([br_template](typedefs.md#br_template)) Returns a pointer to a [Template](../cpp_api/template/template.md) + +--- + +## br_num_templates + +Get the number of [Templates](../cpp_api/template/template.md) in a [TemplateList](../cpp_api/templatelist/templatelist.md). + +* **function definition:** + + int br_num_templates(br_template_list tl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tl | [br_template_list](typedefs.md#br_template_list) | Pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + +* **output:** (int) Returns the size of the provided [TemplateList](../cpp_api/templatelist/templatelist.md) + +--- + +## br_make_gallery + +Initialize a [Gallery](../cpp_api/gallery/gallery.md) from a file. + +* **function definition:** + + br_gallery br_make_gallery(const char *gallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + gallery | const char * | String location of gallery on disk. + +* **output:** ([br_gallery](typedefs.md#br_gallery)) Returns a pointer to a [Gallery](../cpp_api/gallery/gallery.md) that has been created from the provided file + +--- + +## br_load_from_gallery + +Read a [TemplateList](../cpp_api/templatelist/templatelist.md) from a [Gallery](../cpp_api/gallery/gallery.md). + +* **function definition:** + + br_template_list br_load_from_gallery(br_gallery gallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + gallery | [br_gallery](typedefs.md#br_gallery) | Pointer to a [Gallery](../cpp_api/gallery/gallery.md) + +* **output:** ([br_template_list](typedefs.md#br_template_list)) Returns a pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) containing the data from the provided [Gallery](../cpp_api/gallery/gallery.md) + +--- + +## br_add_template_to_gallery + +Write a [Template](../cpp_api/template/template.md) to a [Gallery](../cpp_api/gallery/gallery.md) + +* **function definition:** + + void br_add_template_to_gallery(br_gallery gallery, br_template tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + gallery | [br_gallery](typedefs.md#br_gallery) | Pointer to a [Gallery](../cpp_api/gallery/gallery.md) + tmpl | [br_template](typedefs.md#br_template) | Pointer to a [Template](../cpp_api/template/template.md) + +* **output:** (void) + +--- + +## br_add_template_list_to_gallery + +Write a [TemplateList](../cpp_api/templatelist/templatelist.md) to the [Gallery](../cpp_api/gallery/gallery.md) on disk. + +* **function definition:** + + void br_add_template_list_to_gallery(br_gallery gallery, br_template_list tl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + gallery | [br_gallery](typedefs.md#br_gallery) | Pointer to a [Gallery](../cpp_api/gallery/gallery.md) + tl | [br_template_list](typedefs.md#br_template_list) | Pointer to a [TemplateList](../cpp_api/templatelist/templatelist.md) + +* **output:** (void) + +--- + +## br_close_gallery + +Close a provided [Gallery](../cpp_api/gallery/gallery.md). + +* **function definition:** + + void br_close_gallery(br_gallery gallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + gallery | [br_gallery](typedefs.md#br_gallery) | Pointer to a [Gallery](../cpp_api/gallery/gallery.md) + +* **output:** (void) + +[^1]: *Zhu et al.* + **A Rank-Order Distance based Clustering Algorithm for Face Tagging**, + CVPR 2011 + + +[R]: http://www.r-project.org/ "R" +[QRegExp]: http://doc.qt.io/qt-5/QRegExp.html "QRegExp" diff --git a/docs/docs/api_docs/c_api/typedefs.md b/docs/docs/api_docs/c_api/typedefs.md new file mode 100644 index 0000000..0fffe52 --- /dev/null +++ b/docs/docs/api_docs/c_api/typedefs.md @@ -0,0 +1,7 @@ +## void *br_template {: #br_template } + +## void *br_template_list {: #br_template_list } + +## void *br_gallery {: #br_gallery } + +## void *br_matrix_output {: #br_matrix_output } diff --git a/docs/docs/api_docs/cl_api.md b/docs/docs/api_docs/cl_api.md new file mode 100644 index 0000000..9245eaa --- /dev/null +++ b/docs/docs/api_docs/cl_api.md @@ -0,0 +1,380 @@ +The command line API is a tool to run OpenBR from the command line. The command line is the easiest and fastest way to run OpenBR! + +The following is a detailed description of the command line API. The command line API is really just a set of wrappers to call the [C API](c_api.md). All of the flags in this API have a corresponding C API call. To help display the examples the following shorthand definitions will be used: + +Shortcut | Definition +--- | --- +<arg> | <> Represent an input argument +\{arg\} | \{\} Represent an output argument +[arg] | [] Represent an optional argument +(arg0 | ... | argN) | (... | ...) Represent a choice. + +## Algorithms + +Almost every command line process needs to specify an algorithm to work properly. Algorithms in OpenBR are described in detail [here](../tutorials.md#algorithms-in-openbr). To specify algorithms to the command line use the -algorithm flag like so: + + -algorithm "AlgorithmString" + +Make sure you use the quotes if your algorithm is longer than one plugin because special characters in OpenBR are also special characters (with very different meanings!) in Bash. + +## Core Commands + +### -train {: #train } + +Train a model + +* **arguments:** + + -train ... [{model}] + +* **wraps:** [br_train_n](c_api/functions.md#br_train_n) + +### -enroll {: #enroll } + +Enroll a [Gallery](cpp_api/gallery/gallery.md) through an algorithm + +* **arguments:** + + -enroll ... {output_gallery} + +* **wraps:** [br_enroll](c_api/functions.md#br_enroll) or [br_enroll_n](c_api/functions.md#br_enroll_n) depending on the input size + +### -compare {: #compare } + +Compare query [Templates](cpp_api/template/template.md) against a target [Gallery](cpp_api/gallery/gallery.md) + +* **arguments:** + + -compare [{output}] + +* **wraps:** [br_compare](c_api/functions.md#br_compare) + +### -pairwiseCompare {: #pairwisecompare } + +DOCUMENT ME + +* **arguments:** + + -pairwiseCompare [{output}] + +* **wraps:** [br_pairwise_compare](c_api/functions.md#br_pairwise_compare) + +### -eval {: #eval } + +Evaluate a similarity matrix + +* **arguments:** + + -eval [] [{csv}] [{matches}] + +* **wraps:** [br_eval](c_api/functions.md#br_eval) + +### -inplaceEval {: #inplaceeval } + +DOCUMENT ME + +* **arguments:** + + -inplaceEval [{output}] + +* **wraps:** [br_inplace_eval](c_api/functions.md#br_inplace_eval) + +### -plot {: #inplaceeval} + +Plot the results of an evaluation + +* **arguments:** + + -plot ... {destination} + +* **wraps:** [br_plot](c_api/functions.md#br_plot) + + +## Other Commands + +### -fuse {: #fuse } + +Perform score level fusion on similarity matrices. + +* **arguments:** + + -fuse ... (None|MinMax|ZScore|WScore) (Min|Max|Sum[W1:W2:...:Wn]|Replace|Difference|None) {simmat} + +* **wraps:** [br_fuse](c_api/functions.md#br_fuse) + +### -cluster {: #cluster } + +Clusters one or more similarity matrices into a list of subjects + +* **arguments:** + + -cluster ... {csv} + +* **wraps:** [br_cluster](c_api/functions.md#br_cluster) + +### -makeMask {: #makemask } + +Constructs a mask from target and query inputs + +* **arguments:** + + -makeMask {mask} + +* **wraps:** [br_make_mask](c_api/functions.md#br_make_mask) + +### -makePairwiseMask {: #makepairwisemask } + +Constructs a mask from target and query inputs considering the target and input sets to be definite pairwise comparisons. + +* **arguments:** + + -makePairwiseMask {mask} + +* **wraps:** [br_make_pairwise_mask](c_api/functions.md#br_make_pairwise_mask) + +### -combineMasks {: #combinemask } + +Combines several equal-sized mask matrices. A comparison may not be simultaneously indentified as both a genuine and an imposter by different input masks. + +* **arguments:** + + -combineMasks ... {mask} (And|Or) + +* **wraps:** [br_combine_masks](c_api/functions.md#br_combine_masks) + +### -cat {: #cat } + +Concatenates a list of galleries into 1 gallery + +* **arguments:** + + -cat ... {gallery} + +* **wraps:** [br_cat](c_api/functions.md#br_cat) + +### -convert {: #convert } + +Convert a file to a different type. Files can only be converted to types within the same group. For example formats can only be converted to other formats. + +* **arguments:** + + -convert (Format|Gallery|Output) {output_file} + +* **wraps:** [br_convert](c_api/functions.md#br_convert) + +### -evalClassification {: #evalclassification } + +Evaluates and prints classification accuracy to terminal + +* **arguments:** + + -evalClassification + +* **wraps:** [br_eval_classification](c_api/functions.md#br_eval_classification) + +### -evalClustering {: #evalclustering } + +Evaluates and prints clustering accuracy to the terminal + +* **arguments:** + + -evalClustering + +* **wraps:** [br_eval_clustering](c_api/functions.md#br_eval_clustering) + +### -evalDetection {: #evaldetection } + +Evaluates and prints detection accuracy to terminal + +* **arguments:** + + -evalDetection [{csv}] [{normalize}] [{minSize}] [{maxSize}] + +* **wraps:** [br_eval_detection](c_api/functions.md#br_eval_detection) + +### -evalLandmarking {: #evallandmarking } + +Evaluates and prints landmarking accuracy to terminal + +* **arguments:** + + -evalLandmarking [{csv} [ ] [sample_index] [total_examples]] + +* **wraps:** [br_eval_landmarking](c_api/functions.md#br_eval_landmarking) + + +### -evalRegression {: #evalregression } + +Evaluates regression accuracy to disk + +* **arguments:** + + -evalRegression + +* **wraps:** [br_eval_regression](c_api/functions.md#br_eval_regression) + +### -assertEval {: #asserteval } + +Evaluates the similarity matrix using the mask matrix. Function aborts if TAR @ FAR = 0.001 does not meet an expected performance value. + +* **arguments:** + + -assertEval + +* **wraps:** [br_assert_eval](c_api/functions.md#br_assert_eval) + +### -plotDetection {: #plotdetection } + +Renders detection performance figures for a set of .csv files created by [-evalDetection](#evaldetection). + +* **arguments:** + + -plotDetection ... {destination} + +* **wraps:** [br_plot_detection](c_api/functions.md#br_plot_detection) + +### -plotLandmarking {: #plotlandmarking } + +Renders landmarking performance figures for a set of .csv files created by [-evalLandmarking](#evallandmarking) + +* **arguments:** + + -plotLandmarking ... {destination} + +* **wraps:** [br_plot_landmarking](c_api/functions.md#br_plot_landmarking) + +### -plotMetadata {: #plotmetadata } + +Renders metadata figures for a set of .csv files with specified columns + +* **arguments:** + + -plotMetadata ... + +* **wraps:** [br_plot_metadata](c_api/functions.md#br_plot_metadata) + +### -project {: #project } + +A naive alternative to [-enroll](#enroll) + +* **arguments:** + + -project {output_gallery} + +* **wraps:** [br_project](c_api/functions.md#br_project) + +### -getHeader {: #getheader } + +Retrieve the target and query inputs in the [BEE matrix](../tutorials.md#the-evaluation-harness) header + +* **arguments:** + + -getHeader + +* **wraps:** [br_get_header](c_api/functions.md#br_get_header) + +### -setHeader {: #setheader } + +Update the target and query inputs in the [BEE matrix](../tutorials.md#the-evaluation-harness) header + +* **arguments:** + + -setHeader {} + +* **wraps:** [br_set_header](c_api/functions.md#br_set_header) + +### -<key> <value> {: #setproperty } + +Appends a provided value to the [global metadata](cpp_api/context/context.md) using a provided key + +* **arguments:** + + - + +* **wraps:** [br_set_property](c_api/functions.md#br_set_property) + + +## Miscellaneous + +### -help {: #help } + +Print command line API documentation to the terminal + +* **arguments:** + + -help + +* **wraps:** N/A + +### -gui {: #gui } + +If this flag is set OpenBR will enable GUI windows to be launched. It must be the first flag set. + +* **arguments:** + + br -gui + +* **wraps:** N/A + +### -objects {: #objects } + +Returns names and parameters for the requested objects. Each object is newline separated. Arguments are separated from the object name with a tab. This function uses [QRegExp][QRegExp] syntax + +* **arguments:** + + -objects [abstraction [implementation]] + +* **wraps:** [br_objects](c_api/functions.md#br_objects) + +### -about {: #about } + +Get a string with the name, version, and copyright of the project. This string is suitable for printing or terminal + +* **arguments:** + + -about + +* **wraps:** [br_about](c_api/functions.md#br_about) + +### -version {: #version } + +Get the current OpenBR version + +* **arguments:** + + -version + +* **wraps:** [br_version](c_api/functions.md#br_version) + +### -slave {: #slave } + +For internal use via [ProcessWrapperTransform](../plugin_docs/core.md#processwrappertransform) + +* **arguments:** + + -slave + +* **wraps:** [br_slave_process](c_api/functions.md#br_slave_process) + +### -daemon {: #daemon } + +DOCUMENT ME + +* **arguments:** + + -daemon + +* **wraps:** N/A + +### -exit + +Exit the application + +* **arguments:** + + -exit + +* **wraps:** N/A + + +[QRegExp]: http://doc.qt.io/qt-5/QRegExp.html "QRegExp" diff --git a/docs/docs/api_docs/cpp_api.md b/docs/docs/api_docs/cpp_api.md new file mode 100644 index 0000000..3e7460f --- /dev/null +++ b/docs/docs/api_docs/cpp_api.md @@ -0,0 +1,41 @@ +# C++ Plugin API + +The C++ Plugin API is a pluggable API designed to allow the succinct expression of biometrics algorithms as a series of independent plugins. The API exposes a number of data structures and plugin abstractions to use as simple building blocks for complex algorithms. + +## Data Structures + +The API defines two data structures: + +* [File](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](../plugin_docs/metadata.md#cascadetransform) as metadata which are then used by [Draw](../plugin_docs/gui.md#drawtransform) for visualization. +* [Template](cpp_api/template/template.md)s are containers for images and [File](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. + +## Plugin Abstractions + +A plugin in OpenBR is defined as *classes which modify, interpret, or assist with the modification of OpenBR compatible images and/or metadata*. All OpenBR plugins have a common ancestor, [Object](cpp_api/object/object.md), and they all are constructed from string descriptions given by [Files](cpp_api/file/file.md). There are eight base abstractions that derive from [Object](cpp_api/object/object.md), one of which should be the parent for all production plugins. They are: + +Plugin | Function +--- | --- +[Initializer](cpp_api/initializer/initializer.md) | Initializes shared contexts and variables at the launch of OpenBR. Typically used with third-party plugins. +[Transform](cpp_api/transform/transform.md) | The most common plugin type in OpenBR. Provides the basis for algorithms by transforming images or metadata. +[Distance](cpp_api/distance/distance.md) | Used to compute a distance metric between [Template](cpp_api/template/template.md)s. +[Format](cpp_api/format/format.md) | Used for I/O. Formats handle file types that correspond to single objects (e.g. .jpg, .png, etc.). +[Gallery](cpp_api/gallery/gallery.md) | Used for I/O. Galleries handle file types that correspond to many objects (e.g. .csv., .xml, etc.). +[Output](cpp_api/output/output.md) | Used for I/O. Outputs handle the results of [Distance](cpp_api/distance/distance.md) comparisons. +[Representation](cpp_api/representation/representation.md) | Converts images into feature vectors. Slightly different then [Transform](cpp_api/transform/transform.md)s in implementation and available API calls. +[Classifier](cpp_api/classifier/classifier.md) | Classifies feature vectors as members of specific classes or performs regression on them. + + Additionally, there are several child-abstractions for specific use cases. A few examples are: + + Plugin | Parent | Function + --- | --- | --- + [UntrainableTransform](cpp_api/untrainabletransform/untrainabletransform.md) | [Transform](cpp_api/transform/transform.md) | A [Transform](cpp_api/transform/transform.md) that cannot be trained. + [MetaTransform](cpp_api/metatransform/metatransform.md) | [Transform](cpp_api/transform/transform.md) | A [Transform](cpp_api/transform/transform.md) that is *not* [independent](cpp_api/transform/members.md#independent). + [UntrainableMetaTransform](cpp_api/untrainablemetatransform/untrainablemetatransform.md) | [UntrainableTransform](cpp_api/untrainabletransform/untrainabletransform.md) | A [Transform](cpp_api/transform/transform.md) that is *not* [independent](cpp_api/transform/members.md#independent) and cannot be trained. + [MetadataTransform](cpp_api/metadatatransform/metadatatransform.md) | [Transform](cpp_api/transform/transform.md) | A [Transform](cpp_api/transform/transform.md) that operates only on [Template](cpp_api/template/template.md) [metadata](cpp_api/template/members.md#file). + [TimeVaryingTransform](cpp_api/timevaryingtransform/timevaryingtransform.md) | [Transform](cpp_api/transform/transform.md) | A [Transform](cpp_api/transform/transform.md) that changes at runtime as a result of the input. + [UntrainableDistance](cpp_api/untrainabledistance/untrainabledistance.md) | [Distance](cpp_api/distance/distance.md) | A [Distance](cpp_api/distance/distance.md) that cannot be trained. + [MatrixOutput](cpp_api/matrixoutput/matrixoutput.md) | [Output](cpp_api/output/output.md) | A [Output](cpp_api/output/output.md) that outputs data as a matrix. + + As previously mentioned, all plugins in OpenBR are constructed using strings stored as [Files](cpp_api/file/file.md). The construction is done at runtime by a [Factory](cpp_api/factory/factory.md) class[^1]. The [Factory](cpp_api/factory/factory.md) expects strings of the form `PluginName(property1=value1,property2=value2...propertyN=valueN)` (value lists are also permitted). It looks up the `PluginName` in a static registry and builds the plugin if found. The registry is populated using a special macro [BR_REGISTER](cpp_api/factory/macros.md#br_register); each plugin needs to register itself and its base abstraction in the factory to enable construction. The purpose of this is to allow algorithms to be described completely by strings. For more information on algorithms in OpenBR please see the [tutorial](../tutorials.md#algorithms-in-openbr) + +[^1]: [Industrial Strength Pluggable Factories](https://adtmag.com/articles/2000/09/25/industrial-strength-pluggable-factories.aspx) diff --git a/docs/docs/api_docs/cpp_api/apifunctions.md b/docs/docs/api_docs/cpp_api/apifunctions.md new file mode 100644 index 0000000..8a75670 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/apifunctions.md @@ -0,0 +1,289 @@ + + +## IsClassifier {: #isclassifier } + +Determines if the given algorithm is a classifier. A classifier is defined as a [Transform](transform/transform.md) with no associated [Distance](distance/distance.md). Instead metadata fields with the predicted output classes are populated in [Template](template/template.md) [files](template/members.md#file). + +* **function definition:** + + bool IsClassifier(const QString &algorithm) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + algorithm | const [QString][QString] & | Algorithm to evaluate + +* **output:** (bool) True if the algorithm is a classifier and false otherwise +* **see:** [br_is_classifier](../c_api/functions.md#br_is_classifier) +* **example:** + + IsClassifier("Identity"); // returns true + IsClassifier("Identity:Dist"); // returns false + +--- + +## Train {: #train } + +High level function for creating models. + +* **function definition:** + + void Train(const File &input, const File &model) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const [File](file/file.md) & | Training data + model | const [File](file/file.md) & | Model file + +* **output:** (void) +* **see:** The [training tutorial](../../tutorials.md#training-algorithms) for an example of training. +* **example:** + + File file("/path/to/images/or/gallery.gal"); + File model("/path/to/model/file"); + Train(file, model); + +--- + +## Enroll {: #enroll-1 } + +High level function for creating [galleries](gallery/gallery.md). + +* **function definition:** + + void Enroll(const File &input, const File &gallery = File()) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const [File](file/file.md) & | Path to enrollment file + gallery | const [File](file/file.md) & | (Optional) Path to gallery file. + +* **output:** (void) +* **see:** [br_enroll](../c_api/functions.md#br_enroll) +* **example:** + + File file("/path/to/images/or/gallery.gal"); + Enroll(file); // Don't need to specify a gallery file + File gallery("/path/to/gallery/file"); + Enroll(file, gallery); // Will write to the specified gallery file + +--- + +## Enroll {: #enroll-2 } + +High level function for enrolling templates. Templates are modified in place as they are projected through the algorithm. + +* **function definition:** + + void Enroll(TemplateList &tmpl) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + tmpl | [TemplateList](templatelist/templatelist.md) & | Data to enroll + +* **output:** (void) +* **example:** + + TemplateList tList = TemplateList() << Template("picture1.jpg") + << Template("picture2.jpg") + << Template("picture3.jpg"); + Enroll(tList); + +--- + +## Project {: #project} + +A naive alternative to [Enroll](#enroll-1). + +* **function definition:** + + void Project(const File &input, const File &output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const [File](file/file.md) & | Path to enrollment file + gallery | const [File](file/file.md) & | Path to gallery file. + +* **output:** (void) +* **see:** [Enroll](#enroll-1) +* **example:** + + File file("/path/to/images/or/gallery.gal"); + File output("/path/to/gallery/file"); + Project(file, gallery); // Will write to the specified gallery file + +--- + +## Compare {: #compare } + +High level function for comparing galleries. Each template in the **queryGallery** is compared against every template in the **targetGallery**. + +* **function definition:** + + void Compare(const File &targetGallery, const File &queryGallery, const File &output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + targetGallery | const [File](file/file.md) & | Gallery of target templates + queryGallery | const [File](file/file.md) & | Gallery of query templates + output | const [File](file/file.md) & | Output file for results + +* **returns:** (output) +* **see:** [br_compare](../c_api/functions.md#br_compare) +* **example:** + + File target("/path/to/target/images/"); + File query("/path/to/query/images/"); + File output("/path/to/output/file"); + Compare(target, query, output); + +--- + +## CompareTemplateList {: #comparetemplatelists} + +High level function for comparing templates. + +* **function definition:** + + void CompareTemplateLists(const TemplateList &target, const TemplateList &query, Output *output); + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + target | const [TemplateList](templatelist/templatelist.md) & | Target templates + query | const [TemplateList](templatelist/templatelist.md) & | Query templates + output | [Output](output/output.md) \* | Output file for results + +* **output:** (void) +* **example:** + + TemplateList targets = TemplateList() << Template("target_img1.jpg") + << Template("target_img2.jpg") + << Template("target_img3.jpg"); + + TemplateList query = TemplateList() << Template("query_img.jpg"); + Output *output = Factory::make("/path/to/output/file"); + + CompareTemplateLists(targets, query, output); + +--- + +## PairwiseCompare {: #pairwisecompare } + +High level function for doing a series of pairwise comparisons. + +* **function definition:** + + void PairwiseCompare(const File &targetGallery, const File &queryGallery, const File &output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + targetGallery | const [File](file/file.md) & | Gallery of target templates + queryGallery | const [File](file/file.md) & | Gallery of query templates + output | const [File](file/file.md) & | Output file for results + +* **output:** (void) +* **see:** [br_pairwise_comparison](../c_api/functions.md#br_pairwise_compare) +* **example:** + + File target("/path/to/target/images/"); + File query("/path/to/query/images/"); + File output("/path/to/output/file"); + PairwiseCompare(target, query, output); + +--- + +## Convert {: #convert } + +Change the format of the **inputFile** to the format of the **outputFile**. Both the **inputFile** format and the **outputFile** format must be of the same format group, which is specified by the **fileType**. + +* **function definition:** + + void Convert(const File &fileType, const File &inputFile, const File &outputFile) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + fileType | const [File](file/file.md) & | Can be either:
  • [Format](format/format.md)
  • [Gallery](gallery/gallery.md)
  • [Output](output/output.md)
+ inputFile | const [File](file/file.md) & | File to be converted. Format is inferred from the extension. + outputFile | const [File](file/file.md) & | File to store converted input. Format is inferred from the extension. + +* **output:** (void) +* **example:** + + File input("input.csv"); + File output("output.xml"); + Convert("Format", input, output); + +--- + +## Cat {: #cat } + +Concatenate several galleries into one. + +* **function definition:** + + void Cat(const QStringList &inputGalleries, const QString &outputGallery) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + inputGalleries | const [QStringList][QStringList] & | List of galleries to concatenate + outputGallery | const [QString][QString] & | Gallery to store the concatenated result. This gallery cannot be in the inputGalleries + +* **output:** (void) +* **see:** [br_cat](../c_api/functions.md#br_cat) +* **example:** + + QStringList inputGalleries = QStringList() << "/path/to/gallery1" + << "/path/to/gallery2" + << "/path/to/gallery3"; + + QString outputGallery = "/path/to/outputGallery"; + Cat(inputGalleries, outputGallery); + +--- + +## Deduplicate {: #deduplicate } + +Deduplicate a gallery. A duplicate is defined as an image with a match score above a given threshold to another image in the gallery. + +* **function definition:** + + void Deduplicate(const File &inputGallery, const File &outputGallery, const QString &threshold) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + inputGallery | const [File](file/file.md) & | Gallery to deduplicate + outputGallery | const [File](file/file.md) & | Gallery to store the deduplicated result + threshold | const [QString][QString] & | Match score threshold to determine duplicates + +* **output:** (void) +* **see:** [br_deduplicate](../c_api/functions.md#br_deduplicate) +* **example:** + + File input("/path/to/input/galley/with/dups"); + File output("/path/to/output/gallery"); + Deduplicate(input, output, "0.7"); // Remove duplicates with match scores above 0.7 + + +[QString]: http://doc.qt.io/qt-5/QString.html "QString" +[QStringList]: http://doc.qt.io/qt-5/qstringlist.html "QStringList" diff --git a/docs/docs/api_docs/cpp_api/classifier/classifier.md b/docs/docs/api_docs/cpp_api/classifier/classifier.md new file mode 100644 index 0000000..315fd61 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/classifier/classifier.md @@ -0,0 +1,11 @@ + + +Inherits [Object](../object/object.md) + +See: + +* [Constructors](constructors.md) +* [Static Functions](statics.md) +* [Functions](functions.md) + +Classifiers are used to assign images to a specific class, or to a particular value along a regression line. Although [Transforms](../transform/transform.md) can also be used for this purpose, [Classifiers](classifier.md) provide a simpler and more consistent API. diff --git a/docs/docs/api_docs/cpp_api/classifier/constructors.md b/docs/docs/api_docs/cpp_api/classifier/constructors.md new file mode 100644 index 0000000..b098412 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/classifier/constructors.md @@ -0,0 +1,3 @@ +Constructor / Destructor | Description +--- | --- +virtual ~Classifier() | Default destructor. It doesn' do anything. diff --git a/docs/docs/api_docs/cpp_api/classifier/functions.md b/docs/docs/api_docs/cpp_api/classifier/functions.md new file mode 100644 index 0000000..595fcbd --- /dev/null +++ b/docs/docs/api_docs/cpp_api/classifier/functions.md @@ -0,0 +1,56 @@ +## void train(const [QList][QList]<[Mat][Mat]> &images, const [QList][QList]<float> &labels) {: #train } + +This is a pure, virtual function. Train the classifier using the provided images and labels. + +* **function definition:** + + virtual void train(const QList &images, const QList &labels) = 0 + +* **parameters:** + + Parameter | Type | Descriptions + --- | --- | --- + images | const [QList][QList]<[Mat][Mat]> & | Training images + labels | const [QList][QList]<float> & | Training labels + +* **output:** (void) +* **example:** + + // Create data for a 2-class classification problem + QList images = QList() << Template("training_pic1.jpg").m() + << Template("training_pic2.jpg").m() + << Template("training_pic3.jpg").m() + << Template("training_pic4.jpg").m(); + + QList labels = QList() << 0 << 0 << 1 << 1; + + Classifier *classifier = Classifier::make("Classifier"); + rep->train(images, labels); + +## float classify(const [Mat][Mat] &image) const {: #classify } + +This is a pure virtual function. Classify a provided input image. + +* **function description:** + + virtual float classify(const Mat &image) const = 0 + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + image | const [Mat][Mat] & | Input image to be classified + +* **output:** (float) Returns the classification value of the image. The value can be a confidence, a regression, or a class. In 2-class classification is it often a confidence which has been normalized such that 0 is the inflection point. Values below zero represent a negative classification and values above represent a positive classification. +* **example:** + Classifier *classifier = Classifier::make("2ClassClassifier"); // assume classifier is already trained + + Template p1("pos_image1.jpg"); // positive sample + Template n1("neg_image1.jpg"); // negative sample + + classifier->classify(p1); // returns confidence > 0 + classifier->classify(n1); // returns confidence < 0 + + +[QList]: http://doc.qt.io/qt-5/QList.html "QList" +[Mat]: http://docs.opencv.org/modules/core/doc/basic_structures.html#mat "Mat" diff --git a/docs/docs/api_docs/cpp_api/classifier/statics.md b/docs/docs/api_docs/cpp_api/classifier/statics.md new file mode 100644 index 0000000..df5b778 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/classifier/statics.md @@ -0,0 +1,25 @@ +## [Classifier](classifier.md) \*make([QString][QString] str, [QObject][QObject] \*parent) {: #make } + +Make a [Classifier](classifier.md) from a string. The string is passed to [Factory](../factory/factory.md)::[make](../factory/statics.md#make) to be turned into a classifier. + +* **function definition:** + + static Classifier *make(QString str, QObject *parent) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + str | [QString][QString] | String describing the classifier + parent | [QObject][QObject] \* | Parent of the object to be created + +* **output:** ([Classifier](classifier.md) \*) Returns a pointer to the [Classifier](classifier.md) described by the string +* **see:** [Factory::make](../factory/statics.md#make) +* **example:** + + Classifier *classifier = Classifier::make("Classifier(representation=Representation(property1=value1)"); + classifier->description(); // Returns "Classifier(representation=Representation(property1=value1))" + + +[QString]: http://doc.qt.io/qt-5/QString.html "QString" +[QObject]: http://doc.qt.io/qt-5/QObject.html "QObject" diff --git a/docs/docs/api_docs/cpp_api/compositetransform/compositetransform.md b/docs/docs/api_docs/cpp_api/compositetransform/compositetransform.md new file mode 100644 index 0000000..0fc1ae6 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/compositetransform/compositetransform.md @@ -0,0 +1,14 @@ + + +Inherits [TimeVaryingTransform](../timevaryingtransform/timevaryingtransform.md) + +Base class for [Transforms](../transform/transform.md) that aggregate subtransforms. + +See: + +* [Properties](properties.md) +* [Members](members.md) +* [Constructors](constructors.md) +* [Functions](functions.md) + +CompositeTransforms are the base class for [Transforms](../transform/transform.md) that have a list of child transforms. It is used internally for plugins like pipes and forks. It inherits from [TimeVaryingTransform](../timevaryingtransform/timevaryingtransform.md) so that it can properly handle having children (one or many) that are time varying. diff --git a/docs/docs/api_docs/cpp_api/compositetransform/constructors.md b/docs/docs/api_docs/cpp_api/compositetransform/constructors.md new file mode 100644 index 0000000..a610b8d --- /dev/null +++ b/docs/docs/api_docs/cpp_api/compositetransform/constructors.md @@ -0,0 +1,3 @@ +Constructor | Description +--- | --- +CompositeTransform() | Default constructor. Calls the [TimeVaryingTransform](../timevaryingtransform/timevaryingtransform.md) [constructor](../timevaryingtransform/constructors.md) with [independent](../transform/members.md#independent) set to false. diff --git a/docs/docs/api_docs/cpp_api/compositetransform/functions.md b/docs/docs/api_docs/cpp_api/compositetransform/functions.md new file mode 100644 index 0000000..844d88e --- /dev/null +++ b/docs/docs/api_docs/cpp_api/compositetransform/functions.md @@ -0,0 +1,121 @@ +## bool timeVarying() {: #timevarying } + +Check if the transform is time varying. The transform is time varying if any of its children are time varying. + +* **function definition:** + + bool timeVarying() const + +* **parameters:** NONE +* **output:** (bool) Returns [isTimeVarying](members.md#istimevarying) + +## void init() {: #init } + +Initialize the transform. If any of the child transform are time varying, [isTimeVarying](members.md#istimevarying) is set to true. Similarly if any of the child transforms are trainable, [trainable](../transform/members.md#trainable) is set to true. + +* **function definition:** + + void init() + +* **parameters:** NONE +* **output:** (void) + +## void project(const [Template](../template/template.md) &src, [Template](../template/template.md) &dst) {: #project-1 } + +If the transform is time varying call [timeInvariantAlias](../timevaryingtransform/members.md#timeinvariantalias) project, which ensures thread safety. If the transform is not time varying call [_project](#_project-1). + +* **function definition:** + + virtual void project(const Template &src, Template &dst) const + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + src | const [Template](../template/template.md) & | The input template + dst | [Template](../template/template.md) & | The output template + +* **output:** (void) + +## void project(const [TemplateList](../templatelist/templatelist.md) &src, [TemplateList](../templatelist/templatelist.md) &dst) {: #project-2 } + +If the transform is time varying call [timeInvariantAlias](../timevaryingtransform/members.md#timeinvariantalias) project, which ensures thread safety. If the transform is not time varying call [_project](#_project-2). + +* **function definition:** + + virtual void project(const TemplateList &src, TemplateList &dst) const + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + src | const [TemplateList](../templatelist/templatelist.md) & | The input template list + dst | [TemplateList ](../templatelist/templatelist.md) & | The output template list + +* **output:** (void) + +## void \_project(const [Template](../template/template.md) &src, [Template](../template/template.md) &dst) {: #\_project-1 } + +This is a pure virtual function. It should handle standard projection through the child transforms + +* **function definition:** + + virtual void _project(const Template &src, Template &dst) const = 0 + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + src | const [Template](../template/template.md) & | The input template + dst | [Template](../template/template.md) & | The output template + +* **output:** (void) + +## void \_project(const [TemplateList](../templatelist/templatelist.md) &src, [TemplateList](../templatelist/templatelist.md) &dst) {: #\_project-2 } + +This is a pure virtual function. It should handle standard projection through the child transforms + +* **function definition:** + + virtual void _project(const TemplateList &src, TemplateList &dst) const = 0 + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + src | const [TemplateList](../templatelist/templatelist.md) & | The input template list + dst | [TemplateList](../templatelist/templatelist.md) & | The output template list + +* **output:** (void) + +## [Transform](../transform/transform.md) \*simplify(bool &newTransform) {: #simplify } + +This is a virtual function. Calls [simplify](../transform/functions.md#simplify) on each child transform. + +* **function definition:** + + virtual Transform *simplify(bool &newTransform) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + newTransform | bool & | True if a new, simplified, transform was allocated inside this call, false otherwise + +* **output:** ([Transform](../transform/transform.md) \*) Returns itself if none of the children can be simplified. newTransform is false in this case. If any child can be simplified a new [CompositeTransform](compositetransform.md) is allocated and its children are set as the result of calling simplify on each of the old children. newTransform is true in this case + +## [Transform](../transform/transform.md) \*smartCopy(bool &newTransform) {: #smartcopy } + +Get a smart copy, meaning a copy only if one is required, of this transform + +* **function definition:** + + Transform *smartCopy(bool &newTransform) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + newTransform | bool & | True if a new, simplified, transform was allocated inside this call, false otherwise + +* **output:** ([Transform](../transform/transform.md) \*) Returns itself if [isTimeVarying](members.md#istimevarying) is false (no copy needed). newTransform is set to false in this case. If [isTimeVarying](members.md#istimevarying) is true, a new [CompositeTransform](compositetransform.md) is allocated and its children are set to the result of calling smartCopy on each of the old children. newTransform is true in this case. diff --git a/docs/docs/api_docs/cpp_api/compositetransform/members.md b/docs/docs/api_docs/cpp_api/compositetransform/members.md new file mode 100644 index 0000000..ae23870 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/compositetransform/members.md @@ -0,0 +1,3 @@ +Member | Type | Description +--- | --- | --- +isTimeVarying | bool | True if any child transform is time varying, false otherwise diff --git a/docs/docs/api_docs/cpp_api/compositetransform/properties.md b/docs/docs/api_docs/cpp_api/compositetransform/properties.md new file mode 100644 index 0000000..94e7aea --- /dev/null +++ b/docs/docs/api_docs/cpp_api/compositetransform/properties.md @@ -0,0 +1,6 @@ +Property | Type | Description +--- | --- | --- +transforms | [QList][QList]<[Transform](../transform/transform.md)\*> | List of child transforms + + +[QList]: http://doc.qt.io/qt-5/QList.html "QList" diff --git a/docs/docs/api_docs/cpp_api/context/context.md b/docs/docs/api_docs/cpp_api/context/context.md new file mode 100644 index 0000000..9302586 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/context/context.md @@ -0,0 +1,11 @@ + + +The singleton class of global settings. + +See: + +* [Members](members.md) +* [Static Functions](statics.md) +* [Functions](functions.md) + +Before including and using OpenBR in a project the user must call [initialize](statics.md#initialize). Before the program terminates the user must call [finalize](statics.md#finalize). The settings are accessible as Context \*Globals. diff --git a/docs/docs/api_docs/cpp_api/context/functions.md b/docs/docs/api_docs/cpp_api/context/functions.md new file mode 100644 index 0000000..322a6e7 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/context/functions.md @@ -0,0 +1,87 @@ +## bool contains(const [QString][QString] &name) {: #contains } + +Check if a property exists in the [global metadata](context.md). + +* **function definition:** + + bool contains(const QString &name); + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + name | const [QString][QString] & | [Metadata](context.md) key. It must be queryable using [QObject::property][QObject::property]. + +* **output:** (bool) Returns true if the provided key is a global property. +* **see:** [setProperty](#setproperty) +* **example:** + + Globals->contains("path"); // returns true + Globals->contains("key"); // returns false + + +## void setProperty(const [QString][QString] &key, const [QString][QString] &value) {: #setproperty } + +Set a global property. + +* **function definition:** + + void setProperty(const QString &key, const QString &value) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | [Metadata](context.md) key + value | const [QString][QString] & | Value to be added to the [Metadata](context.md) + +* **output:** (void) +* **see:** [contains](#contains) +* **example:** + + Globals->contains("key"); // returns false + Globals->setProperty("key", "value"); + Globals->contains("key"); // returns true + + +## void printStatus() {: #printstatus } + +Prints the current progress statistics to **stdout**. + +* **function definition:** + +void printStatus(); + +* **parameters:** NONE +* **output:** (void) +* **see:** [progress](#progress) +* **example:** + + Globals->printStatus(); // returns 00.00% ELAPSED=00:00:00 REMAINING=99:99:99 COUNT=0 + + +## int timeRemaining() const {: #timeremaining } + +Get the time remaining in seconds of a call to [Train](../apifunctions.md#train), [Enroll](../apifunctions.md#enroll-1) or [Compare](../apifunctions.md#compare). + +* **function defintion:** + + int timeRemaining() const; + +* **parameters:** NONE +* **output:** (int) Returns the estimated time remaining in the currently running process. If not process is running returns -1. + +## float progress() {: #progress } + +Get the completion percentage of a call to [Train](../apifunctions.md#train), [Enroll](../apifunctions.md#enroll-1) or [Compare](../apifunctions.md#compare). + +* **function definition:** + + float progress() const; + +* **parameters:** NONE +* **output:** (float) Returns the fraction of the currently running job that has been completed. + + +[QString]: http://doc.qt.io/qt-5/QString.html "QString" +[QObject::property]: http://doc.qt.io/qt-5/qobject.html#property "QObject::property" diff --git a/docs/docs/api_docs/cpp_api/context/members.md b/docs/docs/api_docs/cpp_api/context/members.md new file mode 100644 index 0000000..f9dcaf1 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/context/members.md @@ -0,0 +1,33 @@ +Member | Type | Description +--- | --- | --- +sdkPath | [QString][QString] | Path to the sdk. Path + **share/openbr/openbr.bib** must exist. +algorithm | [QString][QString] | The default algorithm to use when enrolling and comparing templates. +log | [QString][QString] | Optional log file to copy **stderr** to. +path | [QString][QString] | Path to use when resolving images specified with relative paths. Multiple paths can be specified using a semicolon separator. +parallelism | int | The number of threads to use. The default is the maximum of 1 and the value returned by ([QThread][QThread]::idealThreadCount() + 1). +useGui | bool | Whether or not to use GUI functions. The default is true. +blockSize | int | The maximum number of templates to process in parallel. The default is: ```parallelism * ((sizeof(void*) == 4) ? 128 : 1024)``` +quiet | bool | If true, no messages will be sent to the terminal. The default is false. +verbose | bool | If true, extra messages will be sent to the terminal. The default is false. +mostRecentMessage | [QString][QString] | The most recent message sent to the terminal. +currentStep | double | Used internally to compute [progress](functions.md#progress) and [timeRemaining](functions.md#timeremaining). +totalSteps | double | Used internally to compute [progress](functions.md#progress) and [timeRemaining](functions.md#timeremaining). +enrollAll | bool | If true, enroll 0 or more templates per image. Otherwise, enroll exactly one. The default is false. +filters | Filters | Filters is a ```typedef QHash Filters```. Filters that automatically determine imposter matches based on target ([gallery](../gallery/gallery.md)) template metadata. See [FilterDistance](../../../plugin_docs/distance.md#filterdistance). +buffer | [QByteArray][QByteArray] | File output is redirected here if the file's basename is "buffer". This clears previous contents. +scoreNormalization | bool | If true, enable score normalization. Otherwise disable it. The default is true. +crossValidate | int | Perform k-fold cross validation where k is the value of **crossValidate**. The default value is 0. +modelSearch | [QList][QList]<[QString][QString]> | List of paths to search for sub-models on. +abbreviations | [QHash][QHash]<[QString][QString], [QString][QString]> | Used by [Transform](../transform/transform.md)::[make](../transform/statics.md#make) to expand abbreviated algorithms into their complete definitions. +startTime | [QTime][QTime] | Used to estimate [timeRemaining](functions.md#timeremaining). +logFile | [QFile][QFile] | Log file to write to. + + + +[QString]: http://doc.qt.io/qt-5/QString.html "QString" +[QList]: http://doc.qt.io/qt-5/QList.html "QList" +[QHash]: http://doc.qt.io/qt-5/qhash.html "QHash" +[QThread]: http://doc.qt.io/qt-5/qthread.html "QThread" +[QByteArray]: http://doc.qt.io/qt-5/qbytearray.html "QByteArray" +[QTime]: http://doc.qt.io/qt-5/QTime.html "QTime" +[QFile]: http://doc.qt.io/qt-5/qfile.html "QFile" diff --git a/docs/docs/api_docs/cpp_api/context/statics.md b/docs/docs/api_docs/cpp_api/context/statics.md new file mode 100644 index 0000000..cd6a2fd --- /dev/null +++ b/docs/docs/api_docs/cpp_api/context/statics.md @@ -0,0 +1,146 @@ +## void initialize(int &argc, char \*argv[], [QString][QString] sdkPath = "", bool useGui = true) {: #initialize } + +Call *once* at the start of the application to allocate global variables. If the project is a [Qt][Qt] project this call should occur after initializing QApplication. + +* **function definition:** + + static void initialize(int &argc, char *argv[], QString sdkPath = "", bool useGui = true); + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + argc | int & | Number of command line arguments as provided by main() + argv | char * [] | Command line arguments as provided by main() + sdkPath | [QString][QString] | (Optional) The path to the folder containing **share/openbr/openbr.bib**. If no path is provided (default) OpenBR automatically searches:
  • The working directory
  • The executable's location
+ useGui | bool | (Optional) Make OpenBR as a [QApplication][QApplication] instead of a [QCoreApplication][QCoreApplication]. Default is true. + +* **output:** (void) +* **see:** [finalize](#finalize) +* **example:** + + int main(int argc, char \*argv[]) + { + QApplication(argc, argv); // ONLY FOR QT PROJECTS + br::Context::initialize(argc, argv); + + // ... + + br::Context::finalize(); + return 0; + } + +## void finalize() {: #finalize } + +Call *once* at the end of the application to deallocate global variables. + +* **function definition:** + + static void finalize(); + +* **parameters:** NONE +* **output:** (void) +* **see:** [initialize](#initialize) + + +## bool checkSDKPath(const [QString][QString] &sdkPath) {: #checksdkpath } + +Check if a given SDK path is valid. A valid SDK satisfies + + exists(sdkPath + "share/openbr/openbr.bib") + +* **function definition:** + + static bool checkSDKPath(const QString &sdkPath); + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + sdkPath | const [QString][QString] & | Possible sdk path to examine + +* **output:** (bool) Returns true if the sdkPath + "share/openbr/openbr.bib" exists, otherwise returns false. +* **example:** + + // OpenBR is at /libs/openbr + + checkSDKPath("/libs/openbr/"); // returns true + checkSDKPath("/libs/"); // returns false + +## [QString][QString] about() {: #about } + +Get a string with the name, version, and copyright of the project. This string is suitable for printing or terminal. + +* **function definition:** + + static QString about(); + +* **parameters:** NONE +* **output:** ([QString][QString]) Returns a string containing the name, version and copyright of the project +* **example:** + + // Using OpenBR version 0.6.0 + Context::about(); // returns "OpenBR 0.6.0 Copyright (c) 2013 OpenBiometrics. All rights reserved." + +## [QString][QString] version() {: #version } + +Get the version of the SDK. + +* **function definition:** + + static QString version(); + +* **parameters:** NONE +* **output:** ([QString][QString]) Returns a string containing the version of the OpenBR SDK. The string has the format **\.**\.** +* **example:** + + // Using OpenBR version 0.6.0 + Context::version(); // returns "0.6.0" + +## [QString][QString] scratchPath() {: #scratchpath } + +Get the scratch directory used by OpenBR. This directory should be used as the root directory for managing temporary files and providing process persistence. + +* **function definition:** + + static QString scratchPath(); + +* **parameters:** NONE +* **output:** ([QString][QString]) Returns a string pointing to the OpenBR scratch directory. The string has the format **\.**. +* **see:** [version](#version) +* **example:** + + // Using OpenBR version 0.6.0 + Context::scratchPath(); // returns "/path/to/user/home/OpenBR-0.6" + +## [QStringList][QStringList] objects(const char \*abstractions = ".\*", const char \*implementations = ".\*", bool parameters = true) {: #objects } + +Get a collection of objects in OpenBR that match provided regular expressions. This function uses [QRegExp][QRegExp] syntax. + +* **function definition:** + + static QStringList objects(const char *abstractions = ".*", const char *implementations = ".*", bool parameters = true) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + abstractions | const char \* | (Optional) Regular expression of the abstractions to search. Default is ".\*" + implementations | const char \* | (Optional) Regular expression of the implementations to search. Default is ".\*". + parameters | bool | (Optional) If true include parameters after object name. Default is true. + +* **output:** ([QStringList][QStringList]) Return names and parameters for the requested objects. Each object is newline separated. Arguments are separated from the object name with tabs. +* **example:** + + // Find all 'Rnd' Transforms + Context::objects("Transform", "Rnd.*", false); // returns ["RndPoint", "RndRegion", "RndRotate", "RndSample", "RndSubspace"] + + +[Qt]: http://qt-project.org/ "Qt" +[QApplication]: http://doc.qt.io/qt-5/qapplication.html "QApplication" +[QCoreApplication]: http://doc.qt.io/qt-5/qcoreapplication.html "QCoreApplication" + +[QRegExp]: http://doc.qt.io/qt-5/QRegExp.html "QRegExp" + +[QString]: http://doc.qt.io/qt-5/QString.html "QString" +[QStringList]: http://doc.qt.io/qt-5/qstringlist.html "QStringList" diff --git a/docs/docs/api_docs/cpp_api/distance/constructors.md b/docs/docs/api_docs/cpp_api/distance/constructors.md new file mode 100644 index 0000000..ae1271c --- /dev/null +++ b/docs/docs/api_docs/cpp_api/distance/constructors.md @@ -0,0 +1,3 @@ +Constructor / Destructor | Description +--- | --- +virtual ~Distance() | The default destructor. It doesn't do anything. diff --git a/docs/docs/api_docs/cpp_api/distance/distance.md b/docs/docs/api_docs/cpp_api/distance/distance.md new file mode 100644 index 0000000..82201d5 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/distance/distance.md @@ -0,0 +1,11 @@ +Inherits [Object](../object/object.md) + +Plugin base class for comparing two [Templates](../template/template.md) + +See: + +* [Constructors](constructors.md) +* [Static Functions](statics.md) +* [Functions](functions.md) + +Distances are used to find the *distance* or *similarity* between two feature vectors. A *distance* is defined such that a higher value indicates a larger difference between templates. A *similarity* is the opposite, higher values indicate a smaller difference between templates (they are more similar). diff --git a/docs/docs/api_docs/cpp_api/distance/functions.md b/docs/docs/api_docs/cpp_api/distance/functions.md new file mode 100644 index 0000000..9b5c582 --- /dev/null +++ b/docs/docs/api_docs/cpp_api/distance/functions.md @@ -0,0 +1,218 @@ + +## bool trainable() {: #trainable } + +This is a virtual function. Check if the distance is trainable. The default version returns true. Distances that are not trainable should derive from [UntrainableDistance](../untrainabledistance/untrainabledistance.md) instead. + +* **function defintion:** + + virtual bool trainable() + +* **parameters:** NONE +* **output:** (bool) Returns true if the distance is trainable, false otherwise. + +## void train(const [TemplateList](../templatelist/templatelist.md) &src) {: #train } + +This is a pure virtual function. Train the distance on a provided [TemplateList](../templatelist/templatelist.md) of data. The structure of the data is dependent on the distance to be trained. Distances that are not trainable should derive from [UntrainableDistance](../untrainabledistance/untrainabledistance.md) so they do not have to overload this function. + +* **function definition:** + + virtual void train(const TemplateList &src) = 0 + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + src | const [TemplateList](../templatelist/templatelist.md) & | Training data for the distance. + +* **output:** (void) +* **example:** + + // Create data for a 2-class classification problem + Template t1("training_pic1.jpg"); + t1.file.set("Label", 0); + Template t2("training_pic2.jpg"); + t2.file.set("Label", 0); + Template t3("training_pic3.jpg"); + t3.file.set("Label", 1); + Template t4("training_pic4.jpg"); + t4.file.set("Label", 1); + + TemplateList training_data(QList