diff --git a/docs/docs/docs/c_api.md b/docs/docs/docs/c_api.md index e69de29..dafcd06 100644 --- a/docs/docs/docs/c_api.md +++ b/docs/docs/docs/c_api.md @@ -0,0 +1,1208 @@ +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. + +Import API considerations include- + +* Memory for const char* return values is managed internally and guaranteed until the next call to the function +* 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. + +To use the API in your project use- + + #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. + +--- + +# Typedefs + +## void *br_template + +## void *br_template_list + +## void *br_gallery + +## void *br_matrix_output + +--- + +# Functions + +## br_about + +Wraps [Context](cpp_api.md#context) + +* **return type:** const char * +* **parameters:** None +* **example call:** ```const char *br_about()``` +* **see:** [br_version](#br_version) + +--- + +## br_cat + +Concatenates a list of galleries into 1 gallery. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- + num_input_galleries | int | Parameter description +input_galleries[] | const char * | Parameter description +output_gallery | const char * | Parameter description + +* **example call:** ```void br_cat(int num_input_galleries, const char *input_galleries[], const char *output_gallery)``` + +--- + +## br_deduplicate + +Removes duplicate [templates](cpp_api.md#template) in a [gallery](cpp_api.md#gallery). 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.md#gallery)::read. + +* **return type:** void +* **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. + +* **example call:** ```void br_deduplicate(const char *input_gallery, const char *output_gallery, const char *threshold)``` + +--- + +## br_cluster + +\brief Clusters one or more similarity matrices into a list of subjects. A [similarity matrix](../technical.md#the-evaluation-harness) is a type of [Output](cpp_api.md#output). The current clustering algorithm is a simplified implementation of \cite zhu11. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +num_simmats | int | Size of **simmats** +simmats[] | const char * | Array of [simmat](../technical.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. + +* **example call:** ```void br_cluster(int num_simmats, const char *simmats[], float aggressiveness, const char *csv)``` + +--- + +## 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. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +num_input_masks | int | Size of **input_masks** +input_masks[] | const char * | Array of [mask matrices](../technical.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](../technical.md#the-evaluation-harness) +method | const char * | Possible values are: + +* **example call:** ```void br_combine_masks(int num_input_masks, const char *input_masks[], const char *output_mask, const char *method)``` +* **see:** [br_make_mask](#br_make_mask) + +--- + +## br_compare + +Compares each template in the query gallery to each template in the target gallery. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +target_gallery | const char * | target_gallery The br::Gallery file whose templates make up the columns of the output. +query_gallery | const char * | The br::Gallery 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) [Output](cpp_api.md#output) file to contain the results of comparing the templates. The default behavior is to print scores to the terminal. + +* **example call:** ```void br_compare(const char *target_gallery, const char *query_gallery, const char *output = "")``` +* **see:** br_enroll + +--- + +## br_compare_n + +Convenience function for comparing to multiple targets. + +* **return type:** void +* **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.md#output) file to contain the results of comparing the templates. The default behavior is to print scores to the terminal. + +* **example call:** ```void br_compare_n(int num_targets, const char *target_galleries[], const char *query_gallery, const char *output)``` +* **see:** br_compare + +--- + +## br_pairwise_compare + +DOCUMENT ME! + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +target_gallery | const char * | DOCUMENT ME +query_gallery | const char * | DOCUMENT ME +output | const char * | DOCUMENT ME + +* **example call:** ```void br_pairwise_compare(const char *target_gallery, const char *query_gallery, const char *output = "")``` + +--- + +## 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.md#format) can only be converted to other [formats](cpp_api.md#format). + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +file_type | const char * | Type of file to convert. Options are Format, Gallery or Output. +input_file | const char * | File to convert. +output_file | const char * | Output file. Type is determined by the file extension. + +* **example call:** ```void br_convert(const char *file_type, const char *input_file, const char *output_file)``` + +--- + +## br_enroll + +Constructs template(s) from an input. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +input | const char * | The [format](cpp_api.md#format) or [gallery](cpp_api.md#gallery) to enroll. +gallery | const char * | (Optional) The [Gallery](cpp_api.md#gallery) 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) + +* **example call:** ```void br_enroll(const char *input, const char *gallery = "")``` +* **see:** [br_enroll_n](#br_enroll_n) + +--- + +## br_enroll_n + +Convenience function for enrolling multiple inputs. + +* **return type:** void +* **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.md#gallery) file to contain the enroll templates. + +* **example call:** ```void br_enroll_n(int num_inputs, const char *inputs[], const char *gallery = "")``` +* **see:** [br_enroll](#br_enroll) + +--- + +## br_project + +A naive alternative to [br_enroll](#br_enroll). + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +input | const char * | DOCUMENT ME! +output | const char * | DOCUMENT ME! + +* **example call:** ```void br_project(const char *input, const char *output)``` +* **see:** [br_enroll](#br_enroll) + +--- + +## br_eval + +Creates a **.csv** file containing performance metrics from evaluating the similarity matrix using the mask matrix. The return value is the true accept rate at a false accept rate of one in one thousand. + +* **return type:** float +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +simmat | const char * | The [simmat](../technical.md#the-evaluation-harness) to use +mask | const char * | The [mask](../technical.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. + +* **example call:** ```float br_eval(const char *simmat, const char *mask, const char *csv = "", int matches = 0)``` +* **see:** [br_plot](#br_plot) + +--- + +## br_assert_eval + +Evaluates the similarity matrix using the mask matrix. Function aborts ff TAR @ FAR = 0.001 does not meet an expected performance value. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +simmat | const char * | The [simmat](../technical.md#the-evaluation-harness) to use +mask | const char * | The [mask](../technical.md#the-evaluation-harness) +accuracy | const float | Desired true accept rate at false accept rate of one in one thousand. + +* **example call:** ```void br_assert_eval(const char *simmat, const char *mask, const float accuracy)``` + +--- + +## br_inplace_eval + +Creates a **.csv** file containing performance metrics from evaluating the similarity matrix using galleries containing ground truth labels. + +* **return type:** float +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +simmat | const char * | The [simmat](../technical.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. + +* **example call:** ```float br_inplace_eval(const char * simmat, const char *target, const char *query, const char *csv = "")``` +* **see:** [br_plot](#br_plot) + +--- + +## br_eval_classification + +Evaluates and prints classification accuracy to terminal. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +predicted_gallery | const char * | The predicted [Gallery](cpp_api.md#gallery). +truth_gallery | const char * | The ground truth [Gallery](cpp_api.md#gallery). +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**. + +* **example call:** ```void br_eval_classification(const char *predicted_gallery, const char *truth_gallery, const char *predicted_property = "", const char *truth_property = "")``` + +--- + +## br_eval_clustering + +Evaluates and prints clustering accuracy to the terminal. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +csv | const char * | The cluster results file. +gallery | const char * | The [Gallery](cpp_api.md#gallery) used to generate the [simmat](../technical.md#the-evaluation-harness) that was clustered. +truth_property | const char * | (Optional) which metadata key to use from **gallery**, defaults to Label + +* **example call:** ```void br_eval_clustering(const char *csv, const char *gallery, const char * truth_property)``` + +--- + +## br_eval_detection + +Evaluates and prints detection accuracy to terminal. + +* **return type:** float +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +predicted_gallery | const char * | The predicted [Gallery](cpp_api.md#gallery). +truth_gallery | const char * | The ground truth [Gallery](cpp_api.md#gallery). +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). + +* **example call:** ```float br_eval_detection(const char *predicted_gallery, const char *truth_gallery, const char *csv = "", bool normalize = false, int minSize = 0, int maxSize = 0)``` + +--- + +## br_eval_landmarking + +Evaluates and prints landmarking accuracy to terminal. + +* **return type:** float +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +predicted_gallery | const char * | The predicted [Gallery](cpp_api.md#gallery). +truth_gallery | const char * | The ground truth [Gallery](cpp_api.md#gallery). +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. + +* **example call:** ```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)``` + +--- + +## br_eval_regression + +Evaluates regression accuracy to disk. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +predicted_gallery | const char * | The predicted [Gallery](cpp_api.md#gallery) +truth_gallery | const char * | The ground truth [Gallery](cpp_api.md#gallery) +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**. + +* **example call:** ```void br_eval_regression(const char *predicted_gallery, const char *truth_gallery, const char *predicted_property = "", const char *truth_property = "")``` + +--- + +## br_fuse + +Perform score level fusion on similarity matrices. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +num_input_simmats | int | Size of **input_simmats**. +input_simmats[] | const char * | Array of [simmats](../technical.md#the-evaluation-harness). All simmats must have the same dimensions. +normalization | const char * | Valid options are: +fusion | const char * | Valid options are: +output_simmat | const char * | [Simmat](../technical.md#the-evaluation-harness) to contain the fused scores. + +* **example call:** ```void br_fuse(int num_input_simmats, const char *input_simmats[], + const char *normalization, const char *fusion, const char *output_simmat)``` + +--- + +## br_initialize + +Initializes the [Context](cpp_api.md#context). Required at the beginning of any OpenBR program. + +* **return type:** void +* **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 | Enable OpenBR to use make GUI windows. Default is false. + +* **example call:** ```void br_initialize(int &argc, char *argv[], const char *sdk_path = "", bool use_gui = false)``` +* **see:** [br_finalize](#br_finalize) + +--- + +## br_initialize_default + +Initializes the [Context](cpp_api.md#context) with default arguments. + +* **return type:** void +* **parameters:** None +* **example call:** ```void br_initialize_default()``` +* **see:** [br_finalize](#br_finalize) + +--- + +## br_finalize + +Finalizes the context. Required at the end of any OpenBR program. + +* **return type:** void +* **parameters:** None +* **example call:** ```void br_finalize()``` +* **see:** [br_initialize](#br_initialize) + +--- + +## br_is_classifier + +Checks if the provided algorithm is a classifier. Wrapper of [cpp_api.md#bool-isclassifierconst-qstring-algorithm]. + +* **return type:** bool +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +algorithm | const char * | Algorithm to check. + +* **example call:** ```bool br_is_classifier(const char *algorithm)``` + +--- + +## br_make_mask + +Constructs a [mask](../technical.md#the-evaluation-harness) from target and query inputs. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +target_input | const char * | The target [Gallery](cpp_api.md#gallery) +query_input | const char * | The query [Gallery](cpp_api.md#gallery) +mask | const char * | The file to contain the resulting [mask](../technical.md#the-evaluation-harness). + +* **example call:** ```void br_make_mask(const char *target_input, const char *query_input, const char *mask)``` +* **see:** [br_combine_masks](#br_combine_masks) + +--- + +## br_make_pairwise_mask + +Constructs a [mask](../technical.md#the-evaluation-harness) from target and query inputs considering the target and input sets to be definite pairwise comparisons. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +target_input | const char * | The target [Gallery](cpp_api.md#gallery) +query_input | const char * | The query [Gallery](cpp_api.md#gallery) +mask | const char * | The file to contain the resulting [mask](../technical.md#the-evaluation-harness). + +* **example call:** ```void br_make_pairwise_mask(const char *target_input, const char *query_input, const char *mask)``` +* **see:** [br_combine_masks](#br_combine_masks) + +--- + +## br_most_recent_message + +Returns the most recent line sent to stderr. Please see the bullet about input string buffers at the top of this page. + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +buffer | char * | Buffer to store the last line in. +buffer_length | int | Length of the buffer. + +* **example call:** ```int br_most_recent_message(char * buffer, int buffer_length)``` +* **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](http://doc.qt.io/qt-5/QRegExp.html) syntax. + +* **return type:** int +* **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. + +* **example call:** ```int br_objects(char * buffer, int buffer_length, const char *abstractions = ".*", const char *implementations = ".*", bool parameters = true)``` + +--- + +## 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). + +Returns **true** on success. Returns **false** on a failure to compile the figures due to a missing, out of date, or incomplete R installation. + +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")) + +* **return type:** bool +* **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. + +* **example call:** ```bool br_plot(int num_files, const char *files[], const char *destination, bool show = false)``` +* **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. + +Returns **true** on success. Returns **false** on a failure to compile the figures due to a missing, out of date, or incomplete R installation. + +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")) + +* **return type:** bool +* **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. + +* **example call:** ```bool br_plot_detection(int num_files, const char *files[], const char *destination, bool show = false)``` +* **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). + +* **return type:** bool +* **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. + +* **example call:** ```bool br_plot_landmarking(int num_files, const char *files[], const char *destination, bool show = false)``` +* **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. + +* **return type:** bool +* **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. + +* **example call:** ```bool br_plot_metadata(int num_files, const char *files[], const char *columns, bool show = false)``` +* **see:** [br_plot](#br_plot) + +--- + +## br_progress + +Returns current progress from [Context](cpp_api.md#context)::progress(). + +* **return type:** float +* **parameters:** None +* **example call:** ```float br_progress()``` +* **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. See the bullets at the top of this page on managed return values. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +pipe | const char * | Pipe name +argc | int * | Argument count +argv | char *** | Argument list + +* **example call:** ```void br_read_pipe(const char *pipe, int *argc, char ***argv)``` + +--- + +## br_scratch_path + +Fills the buffer with the value of [Context](cpp_api.md#context)::scratchPath(). See the bullets at the top of this page on input string buffers. + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +buffer | char * | Buffer for scratch path +buffer_length | int | Length of buffer. + +* **example call:** ```int br_scratch_path(char * buffer, int buffer_length)``` +* **see:** [br_version](#br_version) + +--- + +## br_sdk_path + +Returns the full path to the root of the SDK. + +* **return type:** const char * +* **parameters:** None +* **example call:** ```const char *br_sdk_path()``` +* **see:** [br_initialize](#br_initialize) + +--- + +## br_get_header + +Retrieve the target and query inputs in the [BEE matrix](../technical.md#the-evaluation-harness) header. See the bullets at the top of this page on managed return values. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +matrix | const char * | The [BEE matrix](../technical.md#the-evaluation-harness) file to modify +target_gallery | const char ** | The matrix target +query_gallery | const char ** | The matrix query + +* **example call:** ```void br_get_header(const char *matrix, const char **target_gallery, const char **query_gallery)``` +* **set:** [br_set_header](#br_set_header) + +--- + +## br_set_header + +Update the target and query inputs in the [BEE matrix](../technical.md#the-evaluation-harness) header. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +matrix | const char * | The [BEE matrix](../technical.md#the-evaluation-harness) file to modify +target_gallery | const char ** | The matrix target +query_gallery | const char ** | The matrix query + +* **example call:** ```void br_set_header(const char *matrix, const char *target_gallery, const char *query_gallery)``` +* **see:** [br_get_header](#br_get_header) + +--- + +## br_set_property + +Appends the given value to the global [metadata](cpp_api.md#context) using the given key. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +key | const char * | Key to append +value | const char * | Value to append + +* **example call:** ```void br_set_property(const char *key, const char *value)``` + +--- + +## br_time_remaining + +Returns estimate of time remaining in the current process. + +* **return type:** int +* **parameters:** None +* **example call:** ```int br_time_remaining()``` +* **see:** [br_most_recent_message](#br_most_recent_message), [br_progress](#br_progress) + +--- + +## br_train + +Trains the [Transform](cpp_api.md#transform) and [Distance](cpp_api.md#distance) on the input. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +input | const char * | The [Gallery](cpp_api.md#gallery) 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. + +* **example call:** ```void br_train(const char *input, const char *model = "")``` +* **see:** [br_train_n](#br_train_n) + +--- + +## br_train_n + +Convenience function for training on multiple inputs + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +num_inputs | int | Size of **inputs** +inputs[] | const char * | An array of [galleries](cpp_api.md#gallery) to train on. +modell | const char *model = | (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. + +* **example call:** ```void br_train_n(int num_inputs, const char *inputs[], const char *model = "")``` +* **see:** [br_train](#br_train) + +--- + +## br_version + +Returns the current OpenBR version. + +* **return type:** const char * +* **parameters:** None +* **example call:** ```const char *br_version()``` +* **see:** [br_about](#br_about), [br_scratch_path](#br_scratch_path) + +--- + +## 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. + +* **return type:** br_template +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +data | const char * | The image buffer. +len | int | The length of the buffer. + +* **example call:** ```br_template br_load_img(const char *data, int len)``` +* **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. + +* **return type:** unsigned char* +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template) + +* **example call:** ```unsigned char* br_unload_img(br_template tmpl)``` +* **see:** [br_load_img](#br_load_img) + +--- + +## br_template_list_from_buffer + +Deserialize a br::TemplateList from a buffer. Can be the buffer for a .gal file, since they are just a TemplateList serialized to disk. + +* **return type:** br_template_list +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +buf | const char * | The buffer. +len | int | The length of the buffer. + +* **example call:** ```br_template_list br_template_list_from_buffer(const char *buf, int len)``` + +--- + +## br_free_template + +Free a [Template's](cpp_api.md#template) memory. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to the [Template](cpp_api.md#template) to free. + +* **example call:** ```void br_free_template(br_template tmpl)``` + +--- + +## br_free_template_list + +Free a [TemplateList's](cpp_api.md#templatelist) memory. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tl | br_template_list | Pointer to the [TemplateList](cpp_api.md#templatelist) to free. + +* **example call:** ```void br_free_template_list(br_template_list tl)``` + +--- + +## br_free_output + +Free a [Output's](cpp_api.md#output) memory. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +output | br_matrix_output | Pointer to the[Output](cpp_api.md#output) to free. + +* **example call:** ```void br_free_output(br_matrix_output output)``` + +--- + +## br_img_rows + +Returns the number of rows in an image. + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). + +* **example call:** ```int br_img_rows(br_template tmpl)``` + +--- + +## br_img_cols + +Returns the number of cols in an image. + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). + +* **example call:** ```int br_img_cols(br_template tmpl)``` + +--- + +## br_img_channels + +Returns the number of channels in an image. + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). + +* **example call:** ```int br_img_channels(br_template tmpl)``` + +--- + +## br_img_is_empty + +Checks if the image is empty. + +* **return type:** bool +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). + +* **example call:** ```bool br_img_is_empty(br_template tmpl)``` + +--- + +## br_get_filename + +Get the filename for a [Template](cpp_api.md#template). Please see the bullets at the top of the page on input string buffers. + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +buffer | char * | Buffer to hold the filename +buffer_length | int | Length of the buffer +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). + +* **example call:** ```int br_get_filename(char * buffer, int buffer_length, br_template tmpl)``` + +--- + +## br_set_filename + +Set the filename for a [Template](cpp_api.md#template). + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). +filename | const char * | New filename for the template. + +* **example call:** ```void br_set_filename(br_template tmpl, const char *filename)``` + +--- + +## br_get_metadata_string + +Get metadata as a string for the given key in the given [Template](cpp_api.md#template). + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +buffer | char * | Buffer to hold the metadata string. +buffer_length | int | length of the buffer. +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). +key | const char * | Key for the metadata lookup + +* **example call:** ```int br_get_metadata_string(char * buffer, int buffer_length, br_template tmpl, const char *key)``` + +--- + +## br_enroll_template + +Enroll a [Template](cpp_api.md#template) from the C API! Returns a pointer to a [TemplateList](cpp_api.md#templatelist) + +* **return type:** br_template_list +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tmpl | br_template | Pointer to a [Template](cpp_api.md#template). + +* **example call:** ```br_template_list br_enroll_template(br_template tmpl)``` + +--- + +## br_enroll_template_list + +Enroll a [TemplateList](cpp_api.md#templatelist) from the C API! + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tl | br_template_list | Pointer to a [TemplateList](cpp_api.md#templatelist) + +* **example call:** ```void br_enroll_template_list(br_template_list tl)``` + +--- + +## br_compare_template_lists + +Compare [TemplateLists](cpp_api.md#templatelist) from the C API! + +* **return type:** br_matrix_output +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +target | br_template_list | Pointer to a [TemplateList](cpp_api.md#templatelist) +query | br_template_list | Pointer to a [TemplateList](cpp_api.md#templatelist) + +* **example call:** ```br_matrix_output br_compare_template_lists(br_template_list target, br_template_list query)``` + +--- + +## br_get_matrix_output_at + +Get a value in the [MatrixOutput](cpp_api.md#matrixoutput). + +* **return type:** float +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +output | br_matrix_output | Pointer to [MatrixOutput](cpp_api.md#matrixoutput) +row | int | Row for lookup +col | int | Col for lookup + +* **example call:** ```float br_get_matrix_output_at(br_matrix_output output, int row, int col)``` + +--- + +## br_get_template + +Get a pointer to a [Template](cpp_api.md#template) at a specified index. + +* **return type:** br_template +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tl | br_template_list | Pointer to a [TemplateList](cpp_api.md#templatelist) +index | int | Index into the template list. Should be in the range [0,len(tl) - 1]. + +* **example call:** ```br_template br_get_template(br_template_list tl, int index)``` + +--- + +## br_num_templates + +Get the number of [Templates](cpp_api.md#template) in a [TemplateList](cpp_api.md#templatelist). + +* **return type:** int +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +tl | br_template_list | Pointer to a [TemplateList](cpp_api.md#templatelist) + +* **example call:** ```int br_num_templates(br_template_list tl)``` + +--- + +## br_make_gallery + +Initialize a [Gallery](cpp_api.md#gallery). + +* **return type:** br_gallery +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +gallery | const char * | String location of gallery on disk. + +* **example call:** ```br_gallery br_make_gallery(const char *gallery)``` + +--- + +## br_load_from_gallery + +Read [TemplateList](cpp_api.md#templatelist) from [Gallery](cpp_api.md#gallery). + +* **return type:** br_template_list +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +gallery | br_gallery | Pointer to a [Gallery](cpp_api.md#gallery) + +* **example call:** ```br_template_list br_load_from_gallery(br_gallery gallery)``` + +--- + +## br_add_template_to_gallery + +Write a [Template](cpp_api.md#template) to the [Gallery](cpp_api.md#gallery) on disk + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +gallery | br_gallery | Pointer to a [Gallery](cpp_api.md#gallery) +tmpl | br_template | Pointer to a [Template](cpp_api.md#template) + +* **example call:** ```void br_add_template_to_gallery(br_gallery gallery, br_template tmpl)``` + +--- + +## br_add_template_list_to_gallery + +Write a [TemplateList](cpp_api.md#templatelist) to the [Gallery](cpp_api.md#gallery) on disk. + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +gallery | br_gallery | Pointer to a [Gallery](cpp_api.md#gallery) +tl | br_template_list | Pointer to a [TemplateList](cpp_api.md#templatelist) + +* **example call:** ```void br_add_template_list_to_gallery(br_gallery gallery, br_template_list tl)``` + +--- + +## br_close_gallery + +Close the [Gallery](cpp_api.md#gallery). + +* **return type:** void +* **parameters:** + +Parameter | Type | Description +--- | --- | --- +gallery | br_gallery | Pointer to a [Gallery](cpp_api.md#gallery) + +* **example call:** ```void br_close_gallery(br_gallery gallery)``` + +--- diff --git a/docs/docs/docs/cpp_api.md b/docs/docs/docs/cpp_api.md index 931e176..c6e09aa 100644 --- a/docs/docs/docs/cpp_api.md +++ b/docs/docs/docs/cpp_api.md @@ -1,3 +1,272 @@ +# API Functions + +## IsClassifier {: #function-isclassiifer } + +Determines if the given algorithm is a classifier. A classifier is defined as a [Transform](#transform) with no associated [Distance](#distance). Instead metadata fields with the predicted output classes are populated in [Template](#template) [files](#template-members-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.md#br_is_classifier) +* **example:** + + IsClassifier("Identity"); // returns true + IsClassifier("Identity:Dist"); // returns false + +## Train {: #function-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) & | Training data + model | const [File](#file) & | 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 {: #function-enroll } + +High level function for creating [galleries](#gallery). + +* **function definition:** + + void Enroll(const File &input, const File &gallery = File()) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const [File](#file) & | Path to enrollment file + gallery | const [File](#file) & | (Optional) Path to gallery file. + +* **output:** (void) +* **see:** [br_enroll](c_api.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 {: #function-enroll } + +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) & | Data to enroll + +* **output:** (void) +* **example:** + + TemplateList tList = TemplateList() << Template("picture1.jpg") + << Template("picture2.jpg") + << Template("picture3.jpg"); + Enroll(tList); + +## Project {: #function-project} + +A naive alternative to [Enroll](#function-enroll-1). + +* **function definition:** + + void Project(const File &input, const File &output) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + input | const [File](#file) & | Path to enrollment file + gallery | const [File](#file) & | Path to gallery file. + +* **output:** (void) +* **see:** [Enroll](#function-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 {: #function-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) & | Gallery of target templates + queryGallery | const [File](#file) & | Gallery of query templates + output | const [File](#file) & | Output file for results + +* **returns:** (output) +* **see:** [br_compare](c_api.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 {: #function-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) & | Target templates + query | const [TemplateList](#templatelist) & | Query templates + output | [Output](#output) \* | 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 {: #function-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) & | Gallery of target templates + queryGallery | const [File](#file) & | Gallery of query templates + output | const [File](#file) & | Output file for results + +* **output:** (void) +* **see:** [br_pairwise_comparison](c_api.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 {: #function-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) & | Can be either: + inputFile | const [File](#file) & | File to be converted. Format is inferred from the extension. + outputFile | const [File](#file) & | 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 {: #function-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.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 {: #function-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) & | Gallery to deduplicate + outputGallery | const [File](#file) & | Gallery to store the deduplicated result + threshold | const [QString][QString] & | Match score threshold to determine duplicates + +* **output:** (void) +* **see:** [br_deduplicate](c_api.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 + +--- + # File A file path with associated metadata. @@ -14,7 +283,7 @@ Files have a simple grammar that allow them to be converted to and from strings. If a string ends with a **]** or **)** then the text within the final **[]** or **()** are parsed as comma separated metadata fields. By convention, fields within **[]** are expected to have the format [key1=value1, key2=value2, ..., keyN=valueN] where order is irrelevant. Fields within **()** are expected to have the format (value1, value2, ..., valueN) where order matters and the key context dependent. -The left hand side of the string not parsed in a manner described above is assigned to [name](#qstring-name). +The left hand side of the string not parsed in a manner described above is assigned to [name](#file-members-name). Values are not necessarily stored as strings in the metadata table. The system will attempt to infer and convert them to their "native" type. @@ -34,8 +303,8 @@ Below are some of the most commonly occurring standardized keys: Key | Value | Description --- | ---- | ----------- -name | QString | Contents of [name](#name) -separator | QString | Separate [name](#name) into multiple files +name | QString | Contents of [name](#file-members-name) +separator | QString | Separate [name](#file-members-name) into multiple files Index | int | Index of a template in a template list Confidence | float | Classification/Regression quality FTE | bool | Failure to enroll @@ -59,93 +328,134 @@ _* | * | Reserved for internal use --- -## Members +## Members {: #file-members } + +Member | Type | Description +--- | --- | --- +name | [QString][QString] | Path to a file on disk +fte | bool | Failed to enroll. If true this file failed to be processed somewhere in the template enrollment algorithm +m_metadata | [QVariantMap][QVariantMap] | Map for storing metadata. It is a [QString][QString], [QVariant][QVariant] key value pairing. + +--- + +## Constructors {: #file-constructors } -### [QString][QString] name +Constructor | Description +--- | --- +File() | Default constructor. Sets [name](#file-members-fte) to false. +File(const [QString][QString] &file) | Initializes the file by calling the private function init. +File(const [QString][QString] &file, const [QVariant][QVariant] &label) | Initializes the file by calling the private function init. Append label to the [metadata](#file-members-m_metadata) using the key "Label". +File(const char \*file) | Initializes the file with a c-style string. +File(const [QVariantMap][QVariantMap] &metadata) | Sets [name](#file-members-fte) to false and sets the [file metadata](#file-members) to metadata. -Path to a file on disk +--- -### bool fte +## Static Functions {: #file-static-functions } -Failed to enroll. If true this file failed to be processed somewhere in the template enrollment algorithm -### [QVariantMap][QVariantMap] m_metadata +### [QVariant][QVariant] parse(const [QString][QString] &value) {: #function-static-parse } -Map for storing metadata. It is a [QString][QString], [QVariant][QVariant] key value pairing. +Try to convert a given value to a [QPointF][QPointF], [QRectF][QRectF], int or float. ---- +* **function definition:** -## Constructors + static QVariant parse(const QString &value); -### File() +* **parameters:** -Default constructor. Sets [FTE](#bool-fte) to false. + Parameter | Type | Description + --- | --- | --- + value | const [QString][QString] & | String value to be converted. -### File(const [QString][QString] &file) +* **output:** ([QVariant][QVariant]) The converted file if a conversion was possible. Otherwise the unconverted string is returned. +* **example:** -Initializes the file by calling the private function init. + QString point = "(1, 1)"; + QString rect = "(1, 1, 5, 5)"; + QString integer = "1"; + QString fp = "1.0"; + QString string = "Hello World"; -### File(const [QString][QString] &file, const [QVariant][QVariant] &label) + File::parse(point); // returns QVariant(QPointF, QPointF(1, 1)) + File::parse(rect); // returns QVariant(QRectF, QRectF(1, 1, 5x5)) + File::parse(integer); // returns QVariant(int, 1) + File::parse(fp); // returns QVariant(float, 1.0f) + File::parse(string); // returns QVariant(QString, "Hello World") -Initializes the file by calling the private function init. Append label to the [metadata](#qvariantmap-m_metadata) using the key "Label". -### File(const char \*file) +### [QList][QList]<[QVariant][QVariant]> values(const [QList][QList]<U> &fileList, const [QString][QString] &key) {: #file-static-values } -Initializes the file with a c-style string. +Gather a list of [QVariant][QVariant] values associated with a metadata key from a provided list of files. -### File(const [QVariantMap][QVariantMap] &metadata) +* **function definition:** -Sets [FTE](#bool-fte) to false and sets the [file metadata](#qvariantmap-m_metadata) to metadata. + template static [QList values(const QList &fileList, const QString &key) ---- +* **parameters:** -## Static Functions + Parameter | Type | Description + --- | --- | --- + fileList | const [QList][QList]<U> & | A list of files to parse for values. A type is required for U. Valid options are:
  • [File](#file)
  • [QString][QString]
+ key | const [QString][QString] & | A metadata key used to lookup the values. +* **output:** ([QList][QList]<[QVariant][QVariant]>) A list of [QVariant][QVariant] values associated with the given key in each of the provided files. +* **example:** -### static [QVariant][QVariant] parse([QString][QString] &value) const + File f1, f2; + f1.set("Key1", QVariant::fromValue(1)); + f1.set("Key2", QVariant::fromValue(2)); + f2.set("Key1", QVariant::fromValue(3)); -Try to convert value to a [QPointF][QPointF], [QRectF][QRectF], int or float. If a conversion is possible it returns the converted value, otherwise it returns the unconverted string. + File::values(QList() << f1 << f2, "Key1"); // returns [QVariant(float, 1), + // QVariant(float, 3)] - QString point = "(1, 1)"; - QString rect = "(1, 1, 5, 5)"; - QString integer = "1"; - QString fp = "1.0"; - QString string = "Hello World"; - File::parse(point); // returns QVariant(QPointF, QPointF(1, 1)) - File::parse(rect); // returns QVariant(QRectF, QRectF(1, 1, 5x5)) - File::parse(integer); // returns QVariant(int, 1) - File::parse(fp); // returns QVariant(float, 1.0f) - File::parse(string); // returns QVariant(QString, "Hello World") +### [QList][QList]<T> get(const [QList][QList]<U> &fileList, const [QString][QString] &key) {: #file-static-get-1 } -### static [QList][QList]<[QVariant][QVariant]> values(const [QList][QList]<U> &fileList, const [QString][QString] &key) +Gather a list of T values associated with a metadata key from a provided list of files. T is a user provided type. If the key does not exist in the metadata of *any* file an error is thrown. -This function requires a type specification in place of U. Valid types are [File](#file) and [QString][QString]. Returns a list of the values of the key in each of the given files. +* **function definition:** - File f1, f2; - f1.set("Key1", QVariant::fromValue(1)); - f1.set("Key2", QVariant::fromValue(2)); - f2.set("Key1", QVariant::fromValue(3)); + template static QList get(const QList &fileList, const QString &key) - File::values(QList() << f1 << f2, "Key1"); // returns [QVariant(float, 1), - // QVariant(float, 3)] +* **parameters:** -### static [QList][QList]<T> get(const [QList][QList]<U> &fileList, const [QString][QString] &key) + Parameter | Type | Description + --- | --- | --- + fileList | const [QList][QList]<U> & | A list of files to parse for values. A type is required for U. Valid options are:
  • [File](#file)
  • [QString][QString]
+ key | const [QString][QString] & | A metadata key used to lookup the values. -This function requires a type specification in place of T and U. Valid types for U are [File](#file) and [QString][QString]. T can be any type. Returns a list of the values of the key in each of the given files. If the key doesn't exist in any of the files or the value cannot be converted to type T an error is thrown. +* **output:** ([QList][QList]<T>) A list of the values of type T associated with the given key. A type is required for T. +* **example:** + + File f1, f2; + f1.set("Key1", QVariant::fromValue(1)); + f1.set("Key2", QVariant::fromValue(2)); + f2.set("Key1", QVariant::fromValue(3)); + + File::get(QList() << f1 << f2, "Key1"); // returns [1., 3.] + File::get(QList() << f1 << f2, "Key2"); // Error: Key doesn't exist in f2 + File::get(QList() << f1 << f2, "Key1"); // Error: float is not convertable to QRectF - File f1, f2; - f1.set("Key1", QVariant::fromValue(1)); - f1.set("Key2", QVariant::fromValue(2)); - f2.set("Key1", QVariant::fromValue(3)); - File::get(QList() << f1 << f2, "Key1"); // returns [1., 3.] - File::get(QList() << f1 << f2, "Key2"); // Error: Key doesn't exist in f2 - File::get(QList() << f1 << f2, "Key1"); // Error: float is not convertable to QRectF +### [QList][QList]<T> get(const [QList][QList]<U> &fileList, const [QString][QString] &key, const T &defaultValue) {: #file-static-get-2 } -### static [QList][QList]<T> get(const [QList][QList]<U> &fileList, const [QString][QString] &key, const T &defaultValue) +Gather a list of T values associated with a metadata key from a provided list of files. T is a user provided type. If the key does not exist in the metadata of *any* file the provided **defaultValue** is used. -This function requires a type specification in place of T and U. Valid types for U are [File](#file) and [QString][QString]. T can be any type. Returns a list of the values of the key in each of the given files. If the key doesn't exist in any of the files or the value cannot be converted to type T the given defaultValue is returned. +* **function definition:** + + template static QList get(const QList &fileList, const QString &key, const T &defaultValue) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + fileList | const [QList][QList]<U> & | A list of files to parse for values. A type is required for U. Valid options are:
  • [File](#file)
  • [QString][QString]
+ key | const [QString][QString] & | A metadata key used to lookup the values. + defaultValue | const T & | The default value if the key is not in a file's metadata. A type is required for T. All types are valid. + +* **output:** ([QList][QList]<T>) A list of the values of type T associated with the given key. A type is required for T. +* **example:** File f1, f2; f1.set("Key1", QVariant::fromValue(1)); @@ -156,76 +466,155 @@ This function requires a type specification in place of T and U. Valid types for File::get(QList() << f1 << f2, "Key2", QList() << 1); // returns [1.] File::get(QList() << f1 << f2, "Key1, QList()"); // returns [] -### [QDebug][QDebug] operator <<([QDebug][QDebug] dbg, const [File](#file) &file) -Calls [flat](#qstring-flat-const) on the given file and that streams that file to stderr. +### [QDebug][QDebug] operator <<([QDebug][QDebug] dbg, const [File](#file) &file) {: #file-static-dbg-operator-ltlt } - File file("../path/to/pictures/picture.jpg"); - file.set("Key", QString("Value")); +Calls [flat](#file-function-flat) on the given file and then streams that file to stderr. - qDebug() << file; // "../path/to/pictures/picture.jpg[Key=Value]" streams to stderr +* **function definition:** -### [QDataStream][QDataStream] &operator <<([QDataStream][QDataStream] &stream, const [File](#file) &file) + QDebug operator <<(QDebug dbg, const File &file) -Serialize a file to a data stream. +* **parameter:** + + Parameter | Type | Description + --- | --- | --- + dbg | [QDebug][QDebug] | The debug stream + file | const [File](#file) & | File to stream + +* **output:** ([QDebug][QDebug] &) returns a reference to the updated debug stream +* **example:** - void store(QDataStream &stream) - { File file("../path/to/pictures/picture.jpg"); file.set("Key", QString("Value")); - stream << file; // "../path/to/pictures/picture.jpg[Key=Value]" serialized to the stream - } + qDebug() << file; // "../path/to/pictures/picture.jpg[Key=Value]" streams to stderr + + +### [QDataStream][QDataStream] &operator <<([QDataStream][QDatastream] &stream, const [File](#file) &file) {: #file-static-stream-operator-ltlt } + +Serialize a file to a data stream. + +* **function definition:** + + QDataStream &operator <<(QDataStream &stream, const File &file) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + stream | [QDataStream][QDataStream] | The data stream + file | const [File](#file) & | File to stream -### [QDataStream][QDataStream] &operator >>([QDataStream][QDataStream] &stream, [File](#file) &file) +* **output:** ([QDataStream][QDataStream] &) returns a reference to the updated data stream +* **example:** + + void store(QDataStream &stream) + { + File file("../path/to/pictures/picture.jpg"); + file.set("Key", QString("Value")); + + stream << file; // "../path/to/pictures/picture.jpg[Key=Value]" serialized to the stream + } + + +### [QDataStream][QDataStream] &operator >>([QDataStream][QDataStream] &stream, const [File](#file) &file) {: #file-static-stream-operator-gtgt } Deserialize a file from a data stream. - void load(QDataStream &stream) - { - File in("../path/to/pictures/picture.jpg"); - in.set("Key", QString("Value")); +* **function definition:** + + QDataStream &operator >>(QDataStream &stream, const File &file) + +* **parameters:** + + Parameter | Type | Description + --- | --- | --- + stream | [QDataStream][QDataStream] | The data stream + file | const [File](#file) & | File to stream + +* **output:** ([QDataStream][QDataStream] &) returns a reference to the updated data stream +* **example:** - stream << in; // "../path/to/pictures/picture.jpg[Key=Value]" serialized to the stream + void load(QDataStream &stream) + { + File in("../path/to/pictures/picture.jpg"); + in.set("Key", QString("Value")); - File out; - stream >> out; + stream << in; // "../path/to/pictures/picture.jpg[Key=Value]" serialized to the stream - out.name; // returns "../path/to/pictures/picture.jpg" - out.flat(); // returns "../path/to/pictures/picture.jpg[Key=Value]" - } + File out; + stream >> out; + + out.name; // returns "../path/to/pictures/picture.jpg" + out.flat(); // returns "../path/to/pictures/picture.jpg[Key=Value]" + } --- -## Functions +## Functions {: #file-functions } -### Operator [QString][QString]() const -returns [name](#qstring-name). Allows Files to be used as [QString][QString]. +### operator [QString][QString]() const {: #file-function-operator-qstring } -### [QString][QString] flat() const +Convenience function that allows [Files](#file) to be used as [QStrings][QString] -Returns the [name](#qstring-name) and [metadata](#qvariantmap-m_metadata) as string. +* **function definition:** - File file("../path/to/pictures/picture.jpg"); - file.set("Key1", QVariant::fromValue(1)); - file.set("Key2", QVariant::fromValue(2)); + inline operator QString() const - file.flat(); // returns "../path/to/pictures/picture.jpg[Key1=1,Key2=2]" +* **parameters:** NONE +* **output:** ([QString][QString]) returns [name](#file-members-name). -### [QString][QString] hash() const +### [QString][QString] flat() const {: #file-function-flat } -Returns a hash of the file. +Function to output files in string formats. - File file("../path/to/pictures/picture.jpg"); - file.set("Key1", QVariant::fromValue(1)); - file.set("Key2", QVariant::fromValue(2)); +* **function definition:** + + QString flat() const - file.hash(); // returns "kElVwY" +* **parameters:** NONE +* **output:** ([QString][QString]) returns the [file name](#file-members) and [metadata](#file-members-m_metadata) as a formated string. The format is *filename*[*key1=value1,key2=value2,...keyN=valueN*]. +* **example:** -### [QStringList][QStringList] localKeys() const + File file("picture.jpg"); + file.set("Key1", QVariant::fromValue(1)); + file.set("Key2", QVariant::fromValue(2)); -Returns an immutable version of the local metadata keys gotten by calling [metadata](#metadata).keys(). + file.flat(); // returns "picture.jpg[Key1=1,Key2=2]" + + +### [QString][QString] hash() const {: #file-function-hash } + +Function to output a hash of the file. + +* **function definition:** + + QString hash() const + +* **parameters:** NONE +* **output:** ([QString][QString]) Returns a hash of the file. +* **example:** + + File file("../path/to/pictures/picture.jpg"); + file.set("Key1", QVariant::fromValue(1)); + file.set("Key2", QVariant::fromValue(2)); + + file.hash(); // returns "kElVwY" + + +### [QStringList][QStringList] localKeys() const {: #file-function-localkeys } + +Function to get the private [metadata](#file-members-m_metadata) keys. + +* **function definition:** + + inline QStringList localKeys() const + +* **parameters:** NONE +* **output:** ([QStringList][QStringList]) Returns a list of the local [metadata](#file-members-m_metadata) keys. They are called local because they do not include the keys in the [global metadata](#context). +* **example:** File file("../path/to/pictures/picture.jpg"); file.set("Key1", QVariant::fromValue(1)); @@ -233,1099 +622,2674 @@ Returns an immutable version of the local metadata keys gotten by calling [metad file.localKeys(); // returns [Key1, Key2] -### [QVariantMap][QVariantMap] localMetadata() const -returns an immutable version of the local [metadata](#qvariantmap-m_metadata). +### [QVariantMap][QVariantMap] localMetadata() const {: #file-function-localmetadata } - File file("../path/to/pictures/picture.jpg"); - file.set("Key1", QVariant::fromValue(1)); - file.set("Key2", QVariant::fromValue(2)); +Function to get the private [metadata](#file-members-m_metadata). - file.localMetadata(); // return QMap(("Key1", QVariant(float, 1)) ("Key2", QVariant(float, 2))) +* **function definition:** -### void append([QVariantMap][QVariantMap] &localMetadata) + inline QVariantMap localMetadata() const -Add new metadata fields to [metadata](#qvariantmap-m_metadata). +* **parameters:** NONE +* **output:** ([QVariantMap][QVariantMap]) Returns the local [metadata](#file-members-m_metadata). +* **example:** - File f(); - f.set("Key1", QVariant::fromValue(1)); + File file("../path/to/pictures/picture.jpg"); + file.set("Key1", QVariant::fromValue(1)); + file.set("Key2", QVariant::fromValue(2)); - QVariantMap map; - map.insert("Key2", QVariant::fromValue(2)); - map.insert("Key3", QVariant::fromValue(3)); + file.localMetadata(); // return QMap(("Key1", QVariant(float, 1)) ("Key2", QVariant(float, 2))) - f.append(map); - f.flat(); // returns "[Key1=1, Key2=2, Key3=3]" -### void append(const [File](#file) &other) +### void append(const [QVariantMap][QVariantMap] &localMetadata) {: #file-function-append-1 } -Append another file using the **;** separator. The file names are combined with the separator in between them. The metadata fields are combined. An additional field describing the separator is appended to the metadata. +Add new metadata fields to [metadata](#file-members-m_metadata). - File f1("../path/to/pictures/picture1.jpg"); - f1.set("Key1", QVariant::fromValue(1)); +* **function definition:** - File f2("../path/to/pictures/picture2.jpg"); - f2.set("Key2", QVariant::fromValue(2)); - f2.set("Key3", QVariant::fromValue(3)); + void append(const QVariantMap &localMetadata) - f1.append(f2); - f1.name; // return "../path/to/pictures/picture1.jpg;../path/to/pictures/picture2.jpg" - f1.localKeys(); // returns "[Key1, Key2, Key3, separator]" +* **parameters:** + Parameter | Type | Description + --- | --- | --- + localMetadata | const [QVariantMap][QVariantMap] & | metadata to append to the local [metadata](#file-members-m_metadata) -### [File](#file) &operator +=(const [QMap][QMap]<[QString][QString], [QVariant][QVariant]> &other) +* **output:** (void) +* **example:** -Shortcut operator to call [append](#void-appendqvariantmap-localmetadata). + File f(); + f.set("Key1", QVariant::fromValue(1)); -### [File](#file) &operator +=(const [File](#file) &other) + QVariantMap map; + map.insert("Key2", QVariant::fromValue(2)); + map.insert("Key3", QVariant::fromValue(3)); -Shortcut operator to call [append](#void-appendconst-file-other). + f.append(map); + f.flat(); // returns "[Key1=1, Key2=2, Key3=3]" -### [QList][QList]<[File](#file)> split() const -Parse [name](#qstring-name) and split on the **;** separator. Each split file has the same [metadata](#qvariantmap-m_metadata) as the joined file. +### void append(const [File](#file) &other) {: #file-function-append-2 } - File f1("../path/to/pictures/picture1.jpg"); - f1.set("Key1", QVariant::fromValue(1)); +Append another file using the **;** separator. The [File](#file) [names](#file-members-name) are combined with the separator in between them. The [metadata](#file-members-m_metadata) fields are combined. An additional field describing the separator is appended to the [metadata](#file-members-m_metadata). - f1.split(); // returns [../path/to/pictures/picture1.jpg[Key1=1]] +* **function definition:** - File f2("../path/to/pictures/picture2.jpg"); - f2.set("Key2", QVariant::fromValue(2)); - f2.set("Key3", QVariant::fromValue(3)); + void append(const File &other) - f1.append(f2); - f1.split(); // returns [../path/to/pictures/picture1.jpg[Key1=1, Key2=2, Key3=3, separator=;], - // ../path/to/pictures/picture2.jpg[Key1=1, Key2=2, Key3=3, separator=;]] +* **parameters:** -### [QList][QList]<[File](#file)> split(const [QString][QString] &separator) const + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to append -Split the file on the given separator. Each split file has the same [metadata](#qvariantmap-m_metadata) as the joined file. +* **output:** (void) +* **example:** - File f("../path/to/pictures/picture1.jpg,../path/to/pictures/picture2.jpg"); - f.set("Key1", QVariant::fromValue(1)); - f.set("Key2", QVariant::fromValue(2)); + File f1("../path/to/pictures/picture1.jpg"); + f1.set("Key1", QVariant::fromValue(1)); - f.split(","); // returns [../path/to/pictures/picture1.jpg[Key1=1, Key2=2], - ../path/to/pictures/picture2.jpg[Key1=1, Key2=2]] + File f2("../path/to/pictures/picture2.jpg"); + f2.set("Key2", QVariant::fromValue(2)); + f2.set("Key3", QVariant::fromValue(3)); -### void setParameter(int index, const [QVariant][QVariant]&value) + f1.append(f2); + f1.name; // return "../path/to/pictures/picture1.jpg;../path/to/pictures/picture2.jpg" + f1.localKeys(); // returns "[Key1, Key2, Key3, separator]" -Insert a keyless value into the [metadata](#qvariantmap-m_metadata). - File f; - f.set("Key1", QVariant::fromValue(1)); - f.set("Key2", QVariant::fromValue(2)); +### [File](#file) &operator+=(const [QMap][QMap]<[QString][QString], [QVariant][QVariant]> &other) {: #file-function-operator-pe-1 } - f.setParameter(1, QVariant::fromValue(3)); - f.setParameter(5, QVariant::fromValue(4)); +Shortcut operator to call [append](#file-function-append-1). - f.flat(); // returns "[Key1=1, Key2=2, Arg1=3, Arg5=4]" +* **function definition:** -### bool operator ==(const char \*other) const + inline File &operator+=(const QMap &other) -Compare [name](#qstring-name) to c-style string other. +* **parameters:** - File f("picture.jpg"); + Parameter | Type | Description + other | const [QMap][QMap]<[QString][QString], [QVariant][QVariant]> & | Metadata map to append to the local [metadata](#file-members-m_metadata) - f == "picture.jpg"; // returns true - f == "other_picture.jpg"; // returns false +* **output:** ([File](#file) &) Returns a reference to this file after the append occurs. +* **example:** -### bool operator ==(const [File](#file) &other) const + File f(); + f.set("Key1", QVariant::fromValue(1)); -Compare [name](#qstring-name) and [metadata](#qvariantmap-m_metadata) to another file name and metadata for equality. + QMap map; + map.insert("Key2", QVariant::fromValue(2)); + map.insert("Key3", QVariant::fromValue(3)); - File f1("picture1.jpg"); - File f2("picture1.jpg"); + f += map; + f.flat(); // returns "[Key1=1, Key2=2, Key3=3]" - f1 == f2; // returns true - f1.set("Key1", QVariant::fromValue(1)); - f2.set("Key2", QVariant::fromValue(2)); +### [File](#file) &operator+=(const [File](#file) &other) {: #file-function-operator-pe-2 } - f1 == f2; // returns false (metadata doesn't match) +Shortcut operator to call [append](#file-function-append-2). -### bool operator !=(const [File](#file) &other) const +* **function definition:** -Compare [name](#qstring-name) and [metadata](#qvariantmap-m_metadata) to another file name and metadata for inequality. + inline File &operator+=(const File &other) - File f1("picture1.jpg"); - File f2("picture1.jpg"); +* **parameters:** - f1 != f2; // returns false + Parameter | Type | Description + other | const [File](#file) & | File to append - f1.set("Key1", QVariant::fromValue(1)); - f2.set("Key2", QVariant::fromValue(2)); +* **output:** ([File](#file) &) Returns a reference to this file after the append occurs. +* **example:** - f1 != f2; // returns true (metadata doesn't match) + File f1("../path/to/pictures/picture1.jpg"); + f1.set("Key1", QVariant::fromValue(1)); -### bool operator <(const [File](#file) &other) const + File f2("../path/to/pictures/picture2.jpg"); + f2.set("Key2", QVariant::fromValue(2)); + f2.set("Key3", QVariant::fromValue(3)); -Compare [name](#qstring-name) to a different file name. + f1 += f2; + f1.name; // return "../path/to/pictures/picture1.jpg;../path/to/pictures/picture2.jpg" + f1.localKeys(); // returns "[Key1, Key2, Key3, separator]" -### bool operator <=(const [File](#file) &other) const -Compare [name](#qstring-name) to a different file name. +### [QList][QList]<[File](#file)> split() const {: #file-function-split-1 } -### bool operator >(const [File](#file) &other) const +This function splits the [File](#file) into multiple files and returns them as a list. This is done by parsing the file [name](#file-members-name) and splitting on the separator located at [metadata](#file-members-m_metadata)["separator"]. If "separator" is not a [metadata](#file-members-m_metadata) key, the returned list has the original file as the only entry. Each new file has the same [metadata](#file-members-m_metadata) as the original, pre-split, file. -Compare [name](#qstring-name) to a different file name. +* **function definition:** -### bool operator >=(const [File](#file) &other) const + QList split() const -Compare [name](#qstring-name) to a different file name. +* **parameters:** None +* **output:** ([QList][QList]<[File](#file)>) List of split files +* **example:** -### bool isNull() const + File f1("../path/to/pictures/picture1.jpg"); + f1.set("Key1", QVariant::fromValue(1)); -Returns true if [name](#qstring-name) and [metadata](#qvariantmap-m_metadata) are empty and false otherwise. + f1.split(); // returns [../path/to/pictures/picture1.jpg[Key1=1]] - File f; - f.isNull(); // returns true + File f2("../path/to/pictures/picture2.jpg"); + f2.set("Key2", QVariant::fromValue(2)); + f2.set("Key3", QVariant::fromValue(3)); - f.set("Key1", QVariant::fromValue(1)); - f.isNull(); // returns false + f1.append(f2); + f1.split(); // returns [../path/to/pictures/picture1.jpg[Key1=1, Key2=2, Key3=3, separator=;], + // ../path/to/pictures/picture2.jpg[Key1=1, Key2=2, Key3=3, separator=;]] -### bool isTerminal() const -Returns true if [name](#qstring-name) equals "Terminal". +### [QList][QList]<[File](#file)> split(const [QString][QString] &separator) const {: #file-function-split-2 } -### bool exists() const +This function splits the file into multiple files and returns them as a list. This is done by parsing the file [name](#file-members-name) and splitting on the given separator. Each new file has the same [metadata](#file-members-m_metadata) as the original, pre-split, file. -Returns true if the file at [name](#qstring-name) exists on disk. +* **function definition:** -### [QString][QString] fileName() const + QList split(const QString &separator) const -Returns the file's base name and extension. +* **parameters:** - File file("../path/to/pictures/picture.jpg"); - file.fileName(); // returns "picture.jpg" + Parameter | Type | Description + --- | --- | --- + separator | const [QString][QString] & | Separator to split the file name on -### [QString][QString] baseName() const +* **output:** ([QList][QList]<[File](#file)>) List of split files +* **example:** -Returns the file's base name. + File f("../path/to/pictures/picture1.jpg,../path/to/pictures/picture2.jpg"); + f.set("Key1", QVariant::fromValue(1)); + f.set("Key2", QVariant::fromValue(2)); - File file("../path/to/pictures/picture.jpg"); - file.baseName(); // returns "picture" + f.split(","); // returns [../path/to/pictures/picture1.jpg[Key1=1, Key2=2], + ../path/to/pictures/picture2.jpg[Key1=1, Key2=2]] -### [QString][QString] suffix() const -Returns the file's extension. +### void setParameter(int index, const [QVariant][QVariant] &value) {: #file-function-setparameter } - File file("../path/to/pictures/picture.jpg"); - file.suffix(); // returns "jpg" +Insert a keyless value into the [metadata](#file-members-m_metadata). Generic key of "ArgN" is used, where N is given as a parameter. -### [QString][QString] path() const +* **function definition:** -Return's the path of the file, excluding the name. + inline void setParameter(int index, const QVariant &value) - File file("../path/to/pictures/picture.jpg"); - file.suffix(); // returns "../path/to/pictures" +* **parameters:** -### [QString][QString] resolved() const + Parameter | Type | Description + --- | --- | --- + index | int | Number to append to generic key + value | const [QVariant][QVariant] & | Value to add to the metadata -Returns [name](#qstring-name). If name does not exist it prepends name with the path in Globals->path. +* **output:** (void) +* **see:** [containsParameter](#file-function-containsparameter), [getParameter](#file-function-getparameter) +* **example:** -### bool contains(const [QString][QString] &key) const + File f; + f.set("Key1", QVariant::fromValue(1)); + f.set("Key2", QVariant::fromValue(2)); -Returns True if the key is in the [metadata](#qvariantmap-m_metadata) and False otherwise. + f.setParameter(1, QVariant::fromValue(3)); + f.setParameter(5, QVariant::fromValue(4)); - File file; - file.set("Key1", QVariant::fromValue(1)); + f.flat(); // returns "[Key1=1, Key2=2, Arg1=3, Arg5=4]" - file.contains("Key1"); // returns true - file.contains("Key2"); // returns false -### bool contains(const [QStringList][QStringList] &keys) const +### bool containsParameter(int index) const {: #file-function-containsparameter } -Returns True if all of the keys are in the [metadata](#qvariantmap-m_metadata) and False otherwise. +Check if the local [metadata](#file-members-m_metadata) contains a keyless value. - File file; - file.set("Key1", QVariant::fromValue(1)); - file.set("Key2", QVariant::fromValue(2)); +* **function definition:** - file.contains(QStringList("Key1")); // returns true - file.contains(QStringList() << "Key1" << "Key2") // returns true - file.contains(QStringList() << "Key1" << "Key3"); // returns false + inline bool containsParameter(int index) const -### [QVariant][QVariant] value(const [QString][QString] &key) const +* **parameters:** -Returns the value associated with key in the [metadata](#qvariantmap-m_metadata). + Parameter | Type | Description + --- | --- | --- + index | int | Index of the keyless value to check for - File file; - file.set("Key1", QVariant::fromValue(1)); - file.value("Key1"); // returns QVariant(float, 1) +* **output:** (bool) Returns true if the local [metadata](#file-members-m_metadata) contains the keyless value, otherwise reutrns false. +* **see:** [setParameter](#file-function-setparameter), [getParameter](#file-function-getparameter) +* **example:** -### void set(const [QString][QString] &key, const [QVariant][QVariant] &value) + File f; + f.setParameter(1, QVariant::fromValue(1)); + f.setParameter(2, QVariant::fromValue(2)); -Insert or overwrite the [metadata](#qvariantmap-m_metadata) key with the given value. + f.containsParameter(1); // returns true + f.containsParameter(2); // returns true + f.containsParameter(3); // returns false - File f; - f.flat(); // returns "" - f.set("Key1", QVariant::fromValue(1)); - f.flat(); // returns "[Key1=1]" +### [QVariant][QVariant] getParameter(int index) const {: #file-function-getparameter } -### void set(const [QString][QString] &key, const [QString][QString] &value) +Get a keyless value from the local [metadata](#file-members-m_metadata). If the value does not exist an error is thrown. -Insert or overwrite the [metadata](#qvariantmap-m_metadata) key with the given value. +* **function definition:** - File f; - f.flat(); // returns "" + inline QVariant getParameter(int index) const - f.set("Key1", QString("1")); - f.flat(); // returns "[Key1=1]" +* **parameter:** -### void setList(const [QString][QString] &key, const [QList][QList]<T> &value) + Parameter | Type | Description + --- | --- | --- + index | int | Index of the keyless value to look up. If the index does not exist an error is thrown. -This function requires a type specification in place of T. Insert or overwrite the [metadata](#qvariantmap-m_metadata) key with the value. The value will remain a list and should be queried with the function [getList](#qlistt-getlistconst-qstring-key-const). +* **output:** ([QVariant][QVariant]) Returns the keyless value associated with the given index +* **see:** [setParameter](#file-function-setparameter), [containsParameter](#file-function-containsparameter) +* **example:** - File file; + File f; + f.setParameter(1, QVariant::fromValue(1)); + f.setParameter(2, QVariant::fromValue(2)); - QList list = QList() << 1 << 2 << 3; - file.setList("List", list); - file.getList("List"); // return [1., 2. 3.] + f.getParameter(1); // returns 1 + f.getParameter(2); // returns 2 + f.getParameter(3); // error: index does not exist -### void remove(const [QString][QString] &key) -Remove the key value pair associated with the given key from the [metadata](#metadata) +### bool operator==(const char \*other) const {: #file-function-operator-ee-1 } - File f; - f.set("Key1", QVariant::fromValue(1)); - f.set("Key2", QVariant::fromValue(2)); +Compare [name](#file-members-name) against a c-style string. - f.flat(); // returns "[Key1=1, Key2=2]" +* **function definition:** - f.remove("Key1"); - f.flat(); // returns "[Key2=2]" + inline bool operator==(const char *other) const -### T get(const [QString][QString] &key) +* **parameters:** -This function requires a type specification in place of T. Try and get the value associated with the given key in the [metadata](#qvariantmap-m_metadata). If the key does not exist or cannot be converted to the given type an error is thrown. + Parameter | Type | Description + --- | --- | --- + other | const char \* | C-style string to compare against - File f; - f.set("Key1", QVariant::fromValue(1)); +* **output:** (bool) Returns true if the strings are equal, false otherwise. +* **example:** - f.get("Key1"); // returns 1 - f.get("Key2"); // Error: Key2 is not in the metadata - f.get("Key1"); // Error: A float can't be converted to a QRectF + File f("picture.jpg"); -### T get(const [QString][QString] &key, const T &defaultValue) + f == "picture.jpg"; // returns true + f == "other_picture.jpg"; // returns false -This function requires a type specification in place of T. Try and get the value associated with the given key in the [metadata](#qvariantmap-m_metadata). If the key does not exist or cannot be converted to the given type the defaultValue is returned. - File f; - f.set("Key1", QVariant::fromValue(1)); +### bool operator==(const [File](#file) &other) const {: #file-function-operator-ee-2 } - f.get("Key1", 5); // returns 1 - f.get("Key2", 5); // returns 5 - f.get("Key1", QRectF(0, 0, 10, 10)); // returns QRectF(0, 0, 10x10) +Compare [name](#file-members-name) and [metadata](#file-members-m_metadata) against another file name and metadata. -### bool getBool(const [QString][QString] &key, bool defaultValue = false) +* **function definition:** -This is a specialization of [get](#t-getconst-qstring-key) for the boolean type. If the key is not in the [metadata](#qvariantmap-m_metadata) the defaultValue is returned. If the key is in the metadata but the value cannot be converted to a bool **true** is returned. If the key is found and the value can be converted to a bool the value is returned. + inline bool operator==(const File &other) const - File f; - f.set("Key1", QVariant::fromValue(true)); - f.set("Key2", QVariant::fromValue(10)); +* **parameters:** - f.getBool("Key1"); // returns true - f.getBool("Key2") // returns true (key found) - f.getBool("Key3"); // returns false (default value) - f.getBool("Key3", true); // returns true (default value) + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to compare against -### [QList][QList]<T> getList(const [QString][QString] &key) const +* **output:** (bool) Returns true if the names and metadata are equal, false otherwise. +* **example:** -This function requires a type specification in place of T. Similar to [get](#t-getconst-qstring-key) only this returns a list. If the key is not found or the value cannot be converted into a [QList][QList]<T> an error is thrown. + File f1("picture1.jpg"); + File f2("picture1.jpg"); - File file; + f1 == f2; // returns true - QList list = QList() << 1 << 2 << 3; - file.setList("List", list); + f1.set("Key1", QVariant::fromValue(1)); + f2.set("Key2", QVariant::fromValue(2)); - file.getList("List"); // return [1., 2. 3.] - file.getList("List"); // Error: float cannot be converted to QRectF - file.getList("Key"); // Error: key doesn't exist + f1 == f2; // returns false (metadata doesn't match) -### [QList][QList]<T> getList(const [QString][QString] &key, const [QList][QList]<T> &defaultValue) const -This function requires a type specification in place of T. Similar to [get](#t-getconst-qstring-key-const-t-defaultvalue) only this returns a list. If the key is not found or the value cannot be converted into a [QList][QList]<T> the supplied defaultValue is returned. +### bool operator!=(const [File](#file) &other) const {: #file-function-operator-ne } - File file; +Compare [name](#file-members-name) and [metadata](#file-members-m_metadata) against another file name and metadata. - QList list = QList() << 1 << 2 << 3; - file.setList("List", list); +* **function definition:** - file.getList("List", QList()); // return [1., 2. 3.] - file.getList("List", QList()); // return [] - file.getList("Key", QList() << 1 << 2 << 3); // return [1., 2., 3.] + inline bool operator!=(const File &other) const -### [QList][QList]<[QPointF][QPointF]> namedPoints() const +* **parameters:** -Find all of the points that can be parsed from [metadata](#qvariantmap-m_metadata) keys and return them. Only values that are convertable to [QPointF][QPointF] are found. Values that can be converted to [QList][QList]><[QPointF][QPointF]> are not included. + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to compare against - File file; - file.set("Key1", QVariant::fromValue(QPointF(1, 1))); - file.set("Key2", QVariant::fromValue(QPointF(2, 2))); - file.set("Points", QVariant::fromValue(QPointF(3, 3))) +* **output:** (bool) Returns true if the names and metadata are not equal, false otherwise. +* **example:** - f.namedPoints(); // returns [QPointF(1, 1), QPointF(2, 2), QPointF(3, 3)] + File f1("picture1.jpg"); + File f2("picture1.jpg"); - file.setPoints(QList() << QPointF(3, 3)); // changes metadata["Points"] to QList - f.namedPoints(); // returns [QPointF(1, 1), QPointF(2, 2)] + f1 != f2; // returns false -### [QList][QList]<[QPointf][QPointF]>> points() const + f1.set("Key1", QVariant::fromValue(1)); + f2.set("Key2", QVariant::fromValue(2)); -Returns the list of points stored in [metadata](#qvariantmap-m_metadata)["Points"]. A list is expected and a single point not in a list will not be returned. Convenience functions [appendPoint](#void-appendpointconst-qpointf-point), [appendPoints](#void-appendpointsconst-qlistqpointf-points), [clearPoints](#void-clearpoints) and [setPoints](#void-setpointsconst-qlistqpointf-points) have been provided to manipulate the internal points list. + f1 != f2; // returns true (metadata doesn't match) - File file; - file.set("Points", QVariant::fromValue(QPointF(1, 1))); - file.points(); // returns [] (point is not in a list) - file.setPoints(QList() << QPointF(2, 2)); - file.points(); // returns [QPointF(2, 2)] +### bool operator<(const [File](#file) &other) const {: #file-function-operator-lt } -### void appendPoint(const [QPointF][QPointF] &point) +Compare [name](#file-members-name) against another file name. -Add a point to the file's points list stored in [metadata](#qvariantmap-m_metadata)["Points"] +* **function definition:** - File file; - file.points(); // returns [] + inline bool operator<(const File &other) const - file.appendPoint(QPointF(1, 1)); - file.points(); // returns [QPointF(1, 1)] +* **parameters:** -### void appendPoints(const [QList][QList]<[QPointF][QPointF]> &points) + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to compare against -Add a list of points to the file's points list stored in [metadata](#qvariantmap-m_metadata)["Points"] +* **output:** (bool) Returns true if [name](#file-members-name) < others.name - File file; - file.points(); // returns [] - file.appendPoints(QList() << QPointF(1, 1) << QPointF(2, 2)); - file.points(); // returns [QPointF(1, 1), QPointF(2, 2)] +### bool operator<=(const [File](#file) &other) const {: #file-function-operator-lte } -### void clearPoints() +Compare [name](#file-members-name) against another file name. -Clear the list of points stored in [metadata](#qvariantmap-m_metadata)["Points"]. +* **function definition:** - File file; - file.appendPoints(QList() << QPointF(1, 1) << QPointF(2, 2)); - file.points(); // returns [QPointF(1, 1), QPointF(2, 2)] + inline bool operator<=(const File &other) const - file.clearPoints(); - file.points(); // returns [] +* **parameters:** -### void setPoints(const [QList][QList]<[QPointF][QPointF]> &points) + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to compare against -Clears the points stored in [metadata](#qvariantmap-m_metadata) and replaces them with points. +* **output:** (bool) Returns true if [name](#file-members-name) <= others.name - File file; - file.appendPoints(QList() << QPointF(1, 1) << QPointF(2, 2)); - file.points(); // returns [QPointF(1, 1), QPointF(2, 2)] - file.setPoints(QList() << QPointF(3, 3) << QPointF(4, 4)); - file.points(); // returns [QPointF(3, 3), QPointF(4, 4)] +### bool operator>(const [File](#file) &other) const {: #file-function-operator-gt } -### [QList][QList]<[QRectF][QRectF]> namedRects() const +Compare [name](#file-members-name) against another file name. -Find all of the rects that can be parsed from [metadata](#qvariantmap-m_metadata) keys and return them. Only values that are convertable to [QRectF][QRectF] are found. Values that can be converted to [QList][QList]<[QRectF][QRectF]> are not included. +* **function definition:** - File file; - file.set("Key1", QVariant::fromValue(QRectF(1, 1, 5, 5))); - file.set("Key2", QVariant::fromValue(QRectF(2, 2, 5, 5))); - file.set("Rects", QVariant::fromValue(QRectF(3, 3, 5, 5))); + inline bool operator>(const File &other) const - f.namedRects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5), QRectF(3, 3, 5x5)] +* **parameters:** - file.setRects(QList() << QRectF(3, 3, 5x5)); // changes metadata["Rects"] to QList - f.namedRects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5)] + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to compare against -### [QList][QList]<[QRectF][QRectF]> rects() const +* **output:** (bool) Returns true if [name](#file-members-name) > others.name -Returns the list of points stored in [metadata](#qvariantmap-m_metadata)["Rects"]. A list is expected and a single rect not in a list will not be returned. Convenience functions [appendRect](#void-appendrectconst-qrectf-rect), [appendRects](#void-appendrectsconst-qlistqrectf-rects), [clearRects](#void-clearrects) and [setRects](#void-setrectsconst-qlistqrectf-rects) have been provided to manipulate the internal points list. - File file; - file.set("Rects", QVariant::fromValue(QRectF(1, 1, 5, 5))); - file.rects(); // returns [] (rect is not in a list) +### bool operator>=(const [File](#file) &other) const {: #file-function-operator-gte } - file.setRects(QList() << QRectF(2, 2, 5, 5)); - file.rects(); // returns [QRectF(2, 2, 5x5)] +Compare [name](#file-members-name) against another file name. -### void appendRect(const [QRectF][QRectF] &rect) +* **function definition:** -Add a rect to the file's rects list stored in [metadata](#qvariantmap-m_metadata)["Rects"]. + inline bool operator>=(const File &other) const - File file; - file.rects(); // returns [] +* **parameters:** - file.appendRect(QRectF(1, 1, 5, 5)); - file.rects(); // returns [QRectF(1, 1, 5x5)] + Parameter | Type | Description + --- | --- | --- + other | const [File](#file) & | File to compare against -### void appendRect(const [Rect][Rect] &rect) +* **output:** (bool) Returns true if [name](#file-members-name) >= others.name -Add a OpenCV style rect to the file's rects list stored in [metadata](#qvariantmap-m_metadata)["Rects"]. The rect is automatically converted to a QRectF. - File file; - file.rects(); // returns [] +### bool isNull() const {: #file-function-isnull } - file.appendRect(cv::Rect(1, 1, 5, 5)); // automatically converted to QRectF - file.rects(); // returns [QRectF(1, 1, 5x5)] +Check if the file is null. -### void appendRects(const [QList][QList]<[QRectF][QRectF]> &rects) +* **function definition:** -Add a list of rects to the file's rects list stored in [metadata](#qvariantmap-m_metadata)["Rects"] + inline bool isNull() const - File file; - file.rects(); // returns [] +* **parameters:** NONE +* **output:** (bool) Returns true if [name](#file-members-name) and [metadata](#file-members-m_metadata) are empty, false otherwise. +* **example:** - file.appendRects(QList() << QRectF(1, 1, 5, 5) << QRectF(2, 2, 5, 5)); - file.rects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5)] + File f; + f.isNull(); // returns true -### void appendRects(const [QList][QList]<[Rect][Rect]> &rects) + f.set("Key1", QVariant::fromValue(1)); + f.isNull(); // returns false -Add a list of OpenCV style rects to the file's rects list stored in [metadata](#qvariantmap-m_metadata)["Rects"]. Each rect is automatically converted to a QRectF. - File file; - file.rects(); // returns [] +### bool isTerminal() const {: #file-function-isterminal } - file.appendRects(QList() << cv::Rect(1, 1, 5, 5) << cv::Rect(2, 2, 5, 5)); - file.rects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5)] +Checks if the value of [name](#file-members-name) == "terminal". +* **function definition:** -### void clearRects() + inline bool isTerminal() const -Clear the list of rects stored in [metadata](#qvariantmap-m_metadata)["Rects"]. +* **parameters:** NONE +* **output:** (bool) Returns true if [name](#file-members-name) == "terminal", false otherwise. +* **example:** - File file; - file.appendRects(QList() << QRectF(1, 1, 5, 5) << QRectF(2, 2, 5, 5)); - file.rects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5)] + File f1("terminal"), f2("not_terminal"); - file.clearRects(); - file.rects(); // returns [] + f1.isTerminal(); // returns true + f2.isTerminal(); // returns false -### void setRects(const [QList][QList]<[QRectF][QRectF]> &rects) -Clears the rects stored in [metadata](#qvariantmap-m_metadata)["Rects"] and replaces them with the given rects. +### bool exists() const {: #file-function-exists } - File file; - file.appendRects(QList() << QRectF(1, 1, 5, 5) << QRectF(2, 2, 5, 5)); - file.rects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5)] +Check if the file exists on disk. - file.setRects(QList() << QRectF(3, 3, 5, 5) << QRectF(4, 4, 5, 5)); - file.rects(); // returns [QRectF(3, 3, 5x5), QRectF(4, 4, 5x5)] +* **function definition:** -### void setRects(const [QList][QList]<[Rect][Rect]> &rects) + inline bool exists() const -Clears the rects stored in [metadata](#qvariantmap-m_metadata)["Rects"] and replaces them with the given OpenCV style rects. +* **parameters:** NONE +* **output:** Returns true if [name](#file-members-name) exists on disk, false otherwise. +* **example:** - File file; - file.appendRects(QList() << cv::Rect(1, 1, 5, 5) << cv::Rect(2, 2, 5, 5)); - file.rects(); // returns [QRectF(1, 1, 5x5), QRectF(2, 2, 5x5)] + File f1("/path/to/file/that/exists"), f2("/path/to/non/existant/file"); - file.setRects(QList() << cv::Rect(3, 3, 5, 5) << cv::Rect(4, 4, 5, 5)); - file.rects(); // returns [QRectF(3, 3, 5x5), QRectF(4, 4, 5x5)] + f1.exists(); // returns true + f2.exists(); // returns false ---- -# FileList +### [QString][QString] fileName() const {: #file-function-filename } -Inherits [QList][QList]<[File](#file)>. +Get the file's base name and extension. -A convenience class for dealing with lists of files. +* **function definition:** -## Members + inline QString fileName() const ---- +* **parameters:** NONE +* **output:** ([QString][QString]) Returns the base name + extension of [name](#file-members-name) +* **example:** -## Constructors + File file("../path/to/pictures/picture.jpg"); + file.fileName(); // returns "picture.jpg" -### FileList() -Default constructor. Doesn't do anything +### [QString][QString] baseName() const {: #file-function-basename } -### FileList(int n) +Get the file's base name. -Initialize the [FileList](#filelist) with n empty files +* **function definition:** -### FileList(const [QStringList][QStringList] &files) + inline QString baseName() const -Initialize the [FileList](#filelist) from a list of strings. Each string should have the format "filename[key1=value1, key2=value2, ... keyN=valueN]" +* **parameters:** NONE +* **output:** ([QString][QString]) Returns the base name of [name](#file-members-name) +* **example:** -### FileList(const [QList][QList]<[File](#file)> &files) + File file("../path/to/pictures/picture.jpg"); + file.baseName(); // returns "picture" -Initialize the [FileList](#filelist) from a list of [files](#file). ---- +### [QString][QString] suffix() const {: #file-function-suffix } -## Static Functions +Get the file's extension. -### static FileList fromGallery(const [File](#file) &gallery, bool cache = false) +* **function definition:** -Creates a [FileList](#filelist) from a [Gallery](#gallery). Galleries store one or more [Templates](#template) on disk. Common formats include csv, xml, and gal, which is a unique OpenBR format. Read more about this in the [Gallery](#gallery) section. This function creates a [FileList](#filelist) by parsing the stored gallery based on its format. Cache determines whether the gallery should be stored for faster reading later. + inline QString suffix() const - File gallery("gallery.csv"); +* **parameters:** NONE +* **output:** ([QString][QString]) Returns the extension of [name](#file-members-name) +* **example:** - FileList fList = FileList::fromGallery(gallery); - fList.flat(); // returns all the files that have been loaded from disk. It could - // be 1 or 100 depending on what was stored. + File file("../path/to/pictures/picture.jpg"); + file.suffix(); // returns "jpg" ---- -## Functions +### [QString][QString] path() const {: #file-function-path } -### [QStringList][QStringList] flat() const +Get the path of the file without the name. -Calls [flat](#qstring-flat-const) on every [File](#file) in the list and returns the resulting strings as a [QStringList][QStringList]. +* **function definition:** - File f1("picture1.jpg"), f2("picture2.jpg"); - f1.set("Key", QString("Value")); + inline QString path() const - FileList fList(QList() << f1 << f2); - fList.flat(); // returns ["picture1.jpg[Key=Value]", "picture2.jpg"] +* **parameters:** NONE +* **output:** ([QString][QString]) Returns the path of [name](#file-members-name). +* **example:** -### [QStringList][QStringList] names() const + File file("../path/to/pictures/picture.jpg"); + file.suffix(); // returns "../path/to/pictures" -Stores the name of every [file](#file) in the list and returns the resulting strings as a [QStringList][QStringList]. - File f1("picture1.jpg"), f2("picture2.jpg"); - f1.set("Key", QString("Value")); +### [QString][QString] resolved() const {: #file-function-resolved } - FileList fList(QList() << f1 << f2); - fList.names(); // returns ["picture1.jpg", "picture2.jpg"] +Get the full path for the file. This is done in three steps: -### void sort(const [QString][QString] &key) +1. If [name](#file-members-name) exists, return [name](#file-members-name). +2. Prepend each path stored in [Globals->path](#context-members-path) to [name](#file-members-name). If the combined name exists then it is returned. +3. Prepend each path stored in [Globals->path](#context-members-path) to [fileName](#file-function-filename). If the combined name exists then it is returned. -Sorts the [FileList](#filelist) based on the value associated with the given key in each file. +If none of the attempted names exist, [name](#file-members-name) is returned unmodified. - File f1("1"), f2("2"), f3("3"); - f1.set("Key", QVariant::fromValue(3)); - f2.set("Key", QVariant::fromValue(1)); - f3.set("Key", QVariant::fromValue(2)); +* **function definition:** - FileList fList(QList() << f1 << f2 << f3); - fList.names(); // returns ["1", "2", "3"] + QString resolved() const - fList.sort("Key"); - fList.names(); // returns ["2", "3", "1"] +* **parameters:** NONE +* **output:** ([QString][QString]) Returns the resolved string if it can be created. Otherwise it returns [name](#file-members-name) -### [QList][QList]<int> crossValidationPartitions() const -Returns the cross-validation partition (default=0) for each file in the list. The partition is stored with the [metadata](#qvariantmap-m_metadata) key "Partition". +### bool contains(const [QString][QString] &key) const {: #file-function-contains-1 } - File f1, f2, f3; - f1.set("Partition", QVariant::fromValue(1)); - f3.set("Partition", QVariant::fromValue(3)); +Check if a given key is in the local [metadata](#file-members-m_metadata). - FileList fList(QList() << f1 << f2 << f3); - fList.crossValidationPartitions(); // returns [1, 0, 3] +* **function definition:** -### int failures() const + bool contains(const QString &key) const -Returns the number of files that have [FTE](#bool-fte) = **True**. +* **parameters:** - File f1, f2, f3; - f1.fte = false; - f2.fte = true; - f3.fte = true; + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to check the [metadata](#file-members-m_metadata) for - FileList fList(QList() << f1 << f2 << f3); - fList.failures(); // returns 2 +* **output:** (bool) Returns true if the given key is in the [metadata](#file-members-m_metadata), false otherwise. +* **example:** ---- + File file; + file.set("Key1", QVariant::fromValue(1)); -# Template + file.contains("Key1"); // returns true + file.contains("Key2"); // returns false -Inherits [QList][QList]<[Mat][Mat]>. -A list of matrices associated with a file. +### bool contains(const [QStringList][QStringList] &keys) const {: #file-function-contains-2 } -The Template is one of two important data structures in OpenBR (the [File](#file) is the other). -A template represents a biometric at various stages of enrollment and can be modified by [Transforms](#transform) and compared to other [templates](#template) with [Distance](#distance). +Check if a list of keys is in the local [metadata](#file-members-m_metadata). -While there exist many cases (ex. video enrollment, multiple face detects, per-patch subspace learning, ...) where the template will contain more than one matrix, -in most cases templates have exactly one matrix in their list representing a single image at various stages of enrollment. -In the cases where exactly one image is expected, the template provides the function m() as an idiom for treating it as a single matrix. -Casting operators are also provided to pass the template into image processing functions expecting matrices. +* **function definition:** -Metadata related to the template that is computed during enrollment (ex. bounding boxes, eye locations, quality metrics, ...) should be assigned to the template's [File](#file-file) member. + bool contains(const QStringList &keys) const -## Members +* **parameters:** -### File file + Parameter | Type | Description + --- | --- | --- + keys | const [QStringList][QStringList] & | Keys to check the [metadata](#file-members-m_metadata) for -The [File](#file) that constructs the [template](#template) +* **output:** (bool) Returns true if *all* of the given keys are in the [metadata](#file-members-m_metadata), false otherwise. +* **example:** ---- + File file; + file.set("Key1", QVariant::fromValue(1)); + file.set("Key2", QVariant::fromValue(2)); -## Constructors + file.contains(QStringList("Key1")); // returns true + file.contains(QStringList() << "Key1" << "Key2") // returns true + file.contains(QStringList() << "Key1" << "Key3"); // returns false -### Template() -The default template constructor. It doesn't do anything. +### [QVariant][QVariant] value(const [QString][QString] &key) const {: #file-function-value } -### Template(const [File](#file) &file) +Get the value associated with a given key from the [metadata](#file-members-m_metadata). If the key is not found in the [local metadata](#file-members-m_metadata), the [global metadata](#context) is searched. In a special case, the key can be "name". This returns the file's [name](#file-members-name). -Sets [file](#file-file) to the given file. +* **function description:** -### Template(const [File](#file) &file, const [Mat][Mat] &mat) + QVariant value(const QString &key) const -Sets [file](#file-file) to the given file and appends the given mat to itself. +* **parameters:** -### Template(const [File](#file) &file, const [QList][QList]<[Mat][Mat]> &mats) + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to look up the value in the [local metadata](#file-members-m_metadata) or [global metadata](#context). The key can also be "name". -Sets [file](#file-file) to the given file and appends the given mats to itself. +* **output:** ([QVariant][QVariant]) Returns the key associated with the value from either the [local](#file-members-m_metadata) or [global](#context) metadata. If the key is "name", [name](#file-members-name) is returned. +* **example:** -### Template(const [Mat][Mat] &mat) + File file; + file.set("Key1", QVariant::fromValue(1)); + file.value("Key1"); // returns QVariant(float, 1) -Appends the given mat to itself. +### void set(const [QString][QString] &key, const [QVariant][QVariant] &value) {: #file-function-set-1 } ---- +Insert a value into the [metadata](#file-members-m_metadata) using a provided key. If the key already exists the new value will override the old one. -## Static Functions +* **function description:** -[QDataStream][QDataStream] &operator <<([QDataStream][QDataStream] &stream, const [Template](#template) &t) + inline void set(const QString &key, const QVariant &value) -Serialize a template. +* **parameters:** - void store(QDataStream &stream) - { - Template t("picture.jpg"); - t.append(Mat::ones(1, 1, CV_8U)); + Parameters | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to store the given value in the [metadata](#file-members-m_metadata) + value | const [QVariant][QVariant] & | Value to be stored - stream << t; // "["1"]picture.jpg" serialized to the stream - } +* **output:** (void) +* **example:** -[QDataStream][QDataStream] &operator >>([QDataStream][QDataStream] &stream, const [Template](#template) &t) + File f; + f.flat(); // returns "" -Deserialize a template. + f.set("Key1", QVariant::fromValue(1)); + f.flat(); // returns "[Key1=1]" - void load(QDataStream &stream) - { - Template in("picture.jpg"); - in.append(Mat::ones(1, 1, CV_8U)); - stream << in; // "["1"]picture.jpg" serialized to the stream +### void set(const [QString][QString] &key, const [QString][QString] &value) {: #file-function-set-2 } - Template out; - stream >> out; +Insert a value into the [metadata](#file-members-m_metadata) using a provided key. If the key already exists the new value will override the old one. - out.file; // returns "picture.jpg" - out; // returns ["1"] - } +* **function description:** ---- + void set(const QString &key, const QString &value) -## Functions +* **parameters:** -### operator const [File](#file) &() + Parameters | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to store the given value in the [metadata](#file-members-m_metadata) + value | const [QString][QString] & | Value to be stored -Idiom to treat the template like a [File](#file). Returns [file](#file-file). +* **output:** (void) +* **example:** -### const [Mat][Mat] &m() + File f; + f.flat(); // returns "" -Idiom to treat the template like a [Mat][Mat]. If the template is empty then an empty [Mat][Mat] is returned. If the list has multiple [Mats][Mat] the last is returned. + f.set("Key1", QString("1")); + f.flat(); // returns "[Key1=1]" - Template t; - t.m(); // returns empty mat - Mat m1; - t.append(m1); - t.m(); // returns m1; +### void setList(const [QString][QString] &key, const [QList][QList]<T> &value) {: #file-function-setlist } - Mat m2; - t.append(m2); - t.m(); // returns m2; +Insert a list into the [metadata](#file-members-m_metadata) using a provided key. If the key already exists the new value will override the old one. The value should be queried with [getList](#file-function-getlist-1) instead of [get](#file-function-get-1). -### [Mat][Mat] &m() +* **function description:** -Idiom to treat the template like a [Mat][Mat]. If the template is empty then an empty [Mat][Mat] is returned. If the list has multiple [Mats][Mat] the last is returned. + template void setList(const QString &key, const QList &value) - Template t; - t.m(); // returns empty mat +* **parameters:** - Mat m1; - t.append(m1); - t.m(); // returns m1; + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to store the given value in the [metadata](#file-members-m_metadata) + value | const [QList][QList]<T> | List to be stored - Mat m2; - t.append(m2); - t.m(); // returns m2; +* **output:** (void) +* **see:** [getList](#file-function-getlist-1), [get](#file-function-get-1) +* **example:** -### operator const [Mat][Mat] &() + File file; -Idiom to treat the template like a [Mat][Mat]. Makes a call to [m()](#mat-m). + QList list = QList() << 1 << 2 << 3; + file.setList("List", list); + file.getList("List"); // return [1., 2. 3.] -### operator [Mat][Mat] &() -Idiom to treat the template like a [Mat][Mat]. Makes a call to [m()](#mat-m). +### void remove(const [QString][QString] &key) {: #file-function-remove } -### operator [_InputArray][InputArray] &() +Remove a key-value pair from the [metadata](#file-members-m_metadata) -Idiom to treat the template like a [Mat][Mat]. Makes a call to [m()](#mat-m). +* **function description:** -### operator [_OutputArray][OutputArray] &() + inline void remove(const QString &key) -Idiom to treat the template like a [Mat][Mat]. Makes a call to [m()](#mat-m). +* **parameters:** -### [Mat][Mat] &operator =(const [Mat][Mat] &other) + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to be removed from [metadata](#file-members-m_metadata) along with its associated value. -Idiom to treat the template like a [Mat][Mat]. Sets other equal to [m()](#mat-m). +* **output:** (void) +* **example:** -### bool isNull() const + File f; + f.set("Key1", QVariant::fromValue(1)); + f.set("Key2", QVariant::fromValue(2)); -Returns true if the template is empty or if [m()](#mat-m) has no data. + f.flat(); // returns "[Key1=1, Key2=2]" - Template t; - t.isNull(); // returns true + f.remove("Key1"); + f.flat(); // returns "[Key2=2]" - t.append(Mat()); - t.isNull(); // returns true - t.append(Mat::ones(1, 1, CV_8U)); - t.isNull(); // returns false +### T get(const [QString][QString] &key) const {: #file-function-get-1 } -### void merge(const [Template](#template) &other) +Get a value from the [metadata](#file-members-m_metadata) using a provided key. If the key does not exist or the value cannot be converted to a user specified type an error is thrown. -Append the contents of another template. The [files](#file-file) are appended using [append()](#void-append-const-file-other). +* **function definition:** - Template t1("picture1.jpg"), t2("picture2.jpg"); - Mat m1, m2; + template T get(const QString &key) const - t1.append(m1); - t2.append(m2); +* **parameters:** - t1.merge(t2); + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to retrieve a value from [metadata](#file-members-m_metadata) - t1.file; // returns picture1.jpg;picture2.jpg[seperator=;] - t1; // returns [m1, m2] +* **output:** (T) Returns a value of type T. T is a user specified type. The value associated with the given key must be convertable to T. +* **see:** [get](#file-function-get-2), [getList](#file-function-getlist-1) +* **example:** -### size_t bytes() const + File f; + f.set("Key1", QVariant::fromValue(1)); -Returns the total number of bytes in all of the matrices in the template. + f.get("Key1"); // returns 1 + f.get("Key2"); // Error: Key2 is not in the metadata + f.get("Key1"); // Error: A float can't be converted to a QRectF - Template t; +### T get(const [QString][QString] &key, const T &defaultValue) {: #file-function-get-2 } - Mat m1 = Mat::ones(1, 1, CV_8U); // 1 byte - Mat m2 = Mat::ones(2, 2, CV_8U); // 4 bytes - Mat m3 = Mat::ones(3, 3, CV_8U); // 9 bytes +Get a value from the [metadata](#file-members-m_metadata) using a provided key. If the key does not exist or the value cannot be converted to user specified type a provided default value is returned instead. - t << m1 << m2 << m3; +* **function definition:** - t.bytes(); // returns 14 + template T get(const QString &key, const T &defaultValue) -### Template clone() const +* **parameters:** -Returns a new template with copies of the [file](#file-file) and all of the matrices that were in the original. + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to retrieve a value from the [metadata](#file-members-m_metadata) + defaultValue | const T & | Default value to be returned if the key does not exist or found value cannot be converted to T. T is a user specified type. - Template t1("picture.jpg"); - t1.append(Mat::ones(1, 1, CV_8U)); +* **output:** (T) Returns a value of type T. T is a user specified type. If the value associated with the key is invalid, the provided default value is returned instead. +* **see:** [get](#file-function-get-1), [getList](#file-function-getlist-1) +* **example:** - Template t2 = t1.clone(); + File f; + f.set("Key1", QVariant::fromValue(1)); - t2.file; // returns "picture.jpg" - t2; // returns ["1"] + f.get("Key1", 5); // returns 1 + f.get("Key2", 5); // returns 5 + f.get("Key1", QRectF(0, 0, 10, 10)); // returns QRectF(0, 0, 10x10) ---- -# TemplateList +### bool getBool(const [QString][QString] &key, bool defaultValue = false) const {: #file-function-getbool } -Inherits [QList][QList]<[Template][#template]>. +Get a boolean value from the [metadata](#file-members-m_metadata) using a provided key. If the key is not in the [metadata](#file-members-m_metadata) a provided default value is returned. If the key is in the metadata but the value cannot be converted to a bool true is returned. If the key is found and the value can be converted to a bool the value is returned. -Convenience class for working with a list of templates. +* **function definition:** -## Members + bool getBool(const QString &key, bool defaultValue = false) const ---- +* **parameters:** -## Constructors + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to retrieve a value from the [metadata](#file-members-m_metadata) + defaultValue | bool | (Optional) Default value to be returned if the key is not in the [metadata](#file-members-m_metadata). -### TemplateList() +* **output:** (bool) If the key *is not* in the [metadata](#file-members-m_metadata) the provided default value is returned. If the key *is* in the [metadata](#file-members-m_metadata) but the associated value *cannot* be converted to a bool true is returned. If the key *is* in the [metadata](#file-members-m_metadata) and the associated value *can* be converted to a bool, that value is returned. +* **see:** [get](#file-function-get-2) +* **example:** -Default constructor. + File f; + f.set("Key1", QVariant::fromValue(true)); + f.set("Key2", QVariant::fromValue(10)); -### TemplateList(const [QList][QList]<[Template](#template)> &templates) + f.getBool("Key1"); // returns true + f.getBool("Key2") // returns true (key found) + f.getBool("Key3"); // returns false (default value) + f.getBool("Key3", true); // returns true (default value) -Initialize the [TemplateList](#templatelist) with a list of templates. The given list is appended. -### TemplateList(const [QList][QList]<[File](#file)> &files) +### [QList][QList]<T> getList(const [QString][QString] &key) const {: #file-function-getlist-1 } -Initialize the [TemplateList](#templatelist) with a list of files. The files are each treated like a template and appended. +Get a list from the [metadata](#file-members-m_metadata) using a provided key. If the key does not exist or the elements of the list cannot be converted to a user specified type an error is thrown. ---- +* **function definition:** -## Static Functions + template QList getList(const QString &key) const -### static [TemplateList](#templatelist) fromGallery(const [File](#file) &gallery) +* **parameters:** -Create a [TemplateList](#templatelist) from a [Gallery](#gallery). + Parameter | Type | Description + --- | --- | --- + key | const [QString][QString] & | Key to retrieve a value from the [metadata](#file-members-m_metadata) -### static [TemplateList](#templatelist) fromBuffer(const [QByteArray][QByteArray] &buffer) +* **output:** ([QList][QList]<T>) Returns a list of values of a user specified type. +* **see:** [setList](#file-function-setlist), [get](#file-function-get-1) +* **example:** -Create a template from a memory buffer of individual templates. This is compatible with **.gal** galleries. + File file; -### static [TemplateList](#templatelist) relabel(const [TemplateList](#templatelist) &tl, const [QString][QString] &propName, bool preserveIntegers) + QList list = QList() << 1 << 2 << 3; + file.setList("List", list); -Relabels the metadata value associated with propName in each [Template](#template) to be between [0, numClasses-1]. **numClasses** is equal to the maximum value of the given metadata if the value can be converted to an **int** and **preserveIntegers** is true, or the total number of unique values. The relabeled values are stored in the "Label" field of each template. + file.getList("List"); // return [1., 2. 3.] + file.getList("List"); // Error: float cannot be converted to QRectF + file.getList("Key"); // Error: key doesn't exist - Template t1, t2, t3; - t1.file.set("Class", QString("1")); - t2.file.set("Class", QString("10")); - t3.file.set("Class", QString("100")); - TemplateList tList(QList