From be52f394d63a69894e498994b2241551bdedc84b Mon Sep 17 00:00:00 2001 From: Josh Klontz Date: Sat, 11 May 2013 12:41:51 -0400 Subject: [PATCH] improved File documentation --- openbr/openbr_plugin.h | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/openbr/openbr_plugin.h b/openbr/openbr_plugin.h index b88f168..d7632ae 100644 --- a/openbr/openbr_plugin.h +++ b/openbr/openbr_plugin.h @@ -107,19 +107,28 @@ void reset_##NAME() { NAME = DEFAULT; } /*! * \brief A file path with associated metadata. * - * The br::File is one of the workhorse classes in OpenBR. + * 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 metadata map with the file helps keep the API simple and stable while providing customizable behavior when appropriate. + * 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 using the file's private metadata. - * If the key does not exist in the local map then it will be resolved using the properities in the global br::Context. - * This has the desirable effect that file metadata may optionally be set globally using br::Context::set to operate on all files. + * 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 properities 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 \c ] or \c ) then the text within the final \c [] or \c () are parsed as comma sperated metadata fields. - * Fields within \c [] are expected to have the format [key1=value1, key2=value2, ..., keyN=valueN]. - * Fields within \c () are expected to have the format (value1, value2, ..., valueN) with the keys determined from the order of \c Q_PROPERTY. - * The rest of the string is assigned to #name. + * By convention, fields within \c [] are expected to have the format [key1=value1, key2=value2, ..., keyN=valueN] where order is irrelevant. + * Fields within \c () 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 \c [ and ends with \c ] then it is treated as a comma separated list and represented with \c QVariantList. Each value in the list is parsed recursively. + * -# If the value starts with \c ( and ends with \c ) and contains four comma separated elements, each convertable to a floating point number, then it is represented with \c QRectF. + * -# If the value starts with \c ( and ends with \c ) and contains two comma separated elements, each convertable to a floating point number, then it is represented with \c QPointF. + * -# If the value is convertable to a floating point number then it is represented with \c float. + * -# Otherwise, it is represented with \c QString. * * The metadata keys \c Subject and \c Label have special significance in the system. * \c Subject is a string specifying a unique identifier used to determine ground truth match/non-match. @@ -298,7 +307,7 @@ struct BR_EXPORT FileList : public QList /*! * \brief A list of matrices associated with a file. * - * The br::Template is one of the workhorse classes in OpenBR. + * The Template is one of two important data structures in OpenBR (the File is the other). * A template represents a biometric at various stages of enrollment and can be modified br::Transform and compared to other templates with br::Distance. * * While there exist many cases (ex. video enrollment, multiple face detects, per-patch subspace learning, ...) where the template will contain more than one matrix, -- libgit2 0.21.4