A file path with associated metadata.
The File is one of two important data structures in OpenBR (the Template is the other). It is typically used to store the path to a file on disk with associated metadata. The ability to associate a key/value metadata table with the file helps keep the API simple while providing customizable behavior.
When querying the value of a metadata key, the value will first try to be resolved against the file's private metadata table. If the key does not exist in its local table then it will be resolved against the properties in the global Context. By design file metadata may be set globally using Context::setProperty to operate on all files.
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.
Values are not necessarily stored as strings in the metadata table. The system will attempt to infer and convert them to their "native" type. The conversion logic is as follows:
- If the value starts with [ and ends with ] then it is treated as a comma separated list and represented with QVariantList. Each value in the list is parsed recursively.
- If the value starts with ( and ends with ) and contains four comma separated elements, each convertable to a floating point number, then it is represented with QRectF.
- If the value starts with ( and ends with ) and contains two comma separated elements, each convertable to a floating point number, then it is represented with QPointF.
- If the value is convertable to a floating point number then it is represented with float.
- Otherwise, it is represented with QString.
Metadata keys fall into one of two categories: camelCaseKeys are inputs that specify how to process the file. Capitalized_Underscored_Keys are outputs computed from processing the file.
Below are some of the most commonly occurring standardized keys:
|name||QString||Contents of name|
|separator||QString||Separate name into multiple files|
|Index||int||Index of a template in a template list|
|FTE||bool||Failure to enroll|
|FTO||bool||Failure to open|
|Points||QList<QPointF>||List of unnamed points|
|Rects||QList<Rect>||List of unnamed rects|
|Age||float||Age used for demographic filtering|
|Train||bool||The data is for training, as opposed to enrollment|
|_*||*||Reserved for internal use|