diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 196 |
1 files changed, 196 insertions, 0 deletions
@@ -0,0 +1,196 @@ +CONTENT + +1. GENERAL DESCRIPTION OF THE MEDIA VISION PACKAGE +2. USAGE OF PORTING LAYER FOR CHANGING MEDIA VISION ENGINE MODULES +3. OPEN PORT REQUIRED PACKAGES +4. TEST SUITE + + + + +1. GENERAL DESCRIPTION OF THE MEDIA VISION PACKAGE + +Currently Media Vision package includes three modules: Common, Barcode +detector and Barcode generator. Common module provides two handles (mv_source_h +and mv_engine_config_h) and related fuctionality. It used by barcode detector +and generator modules. mv_source_h is used for wrapping raw image data buffers. +mv_engine_config_h is optional. It can be used for fine tuning of internal +libraries which are used by API. mv_engine_config_h handle usually can be used +by barcode detector and/or generator modules (these modules provide +mv_barcode_detector and mv_barcode_generator internal libraries) in the case +when Native API doesn't cover all features supported by internal libraries. +Using NULL instead of real mv_engine_h handle as functions parameter has to be +taken into account. In most cases API user prefer to ignore detailed +configuration of the modules. + +Barcode detector module API provides tools to analyze the image buffers using +mv_barcode_detect() function. This analysis strives to detect barcodes at the +image, determine the type and extract the message. Results can be processed +using mv_barcode_detected_cb callback. + +Barcode generator module API provides tools to generate image buffer (or image +file) with barcode. Barcodes generation can be configured by type, message, +size, encoding mode, ECC (error correction level), version (three last setting +are allowed only for QR Codes). One of two functions can be used: +mv_barcode_generate_source() to generate the mv_source_h handle and +mv_barcode_generate_image() to generate the file with barcode image. + + + +2. USAGE OF PORTING LAYER FOR CHANGING MEDIA VISION ENGINE MODULES + +By default open source engine libraries are used to provide modules +functionality. But it is possible to substitute them by licensed or other custom +libraries. To enable building of custom library for the Media Vision package, +follow these steps: + +a. Find CMakeLists.txt in the root of the package directory and change + MEDIA_VISION_BARCODE_DETECTOR_LICENSE_PORT (for enabling build of a custom + barcode detector library) and/or + MEDIA_VISION_BARCODE_GENERATOR_LICENSE_PORT (for enabling build of a custom + barcode generator library) options to ON. Example: + + # only barcode detector module will be customized + option(MEDIA_VISION_BARCODE_DETECTOR_LICENSE_PORT "..." ON) + # barcode generator module will be default + option(MEDIA_VISION_BARCODE_GENERATOR_LICENSE_PORT "..." OFF) + +b. Options change will cause CMake to build from different subdirectories of + mv_barcode directory. mv_barcode/barcode_detector and + mv_barcode/barcode_generator subdirectories are used by default. + mv_barcode/barcode_detector_lic and mv_barcode/mv_barcode_generator_lic + subdirectories will be used during build if the corresponding option is ON. + Last two subdirectories already include base structure of the porting layer + projects, and files will be used by main capi-media-vision library. Use this + files to call functions from custom libraries. For example, you can change + mv_barcode_detect_lic.c file in such a way: + + #include "mv_barcode_detect_lic.h" + #include "custom_library_header.h" + + int mv_barcode_detect_lic( + mv_source_h source, + mv_engine_config_h engine_cfg, + mv_rectangle_s roi, + mv_barcode_detected_cb detect_cb, + void *user_data) + { + mv_quadrangle_s *locations = NULL; + const char *messages = NULL; + mv_barcode_type_e *types = NULL; + + // Here the call of the custom barcode detection function from + // custom_library_header.h: + int barcodes_number = custom_library_function( + source, roi, &locations, &messages, &types); + + if (barcodes_number > 0) + { + detect_cb( + source, engine_cfg, locations, messages, types, barcodes_number, + user_data); + delete[] locations; + delete[] messages; + delete[] types; + } + + return MEDIA_VISION_ERROR_NONE; + } + +c. Change the packaging/capi-media-vision.spec to support any packages required + to be found into the system for success build of the custom libraries + (mv_barcode_detector and/or mv_barcode_generator). You also can remove + requirements on open packages that are required by disabled barcode + generator/detector ports. See list of the dependencies in the section 3 of + this README file. + +d. Modify mv_barcode/barcode_{detector/generator}_lic/CMakeLists.txt file for + linking required libraries and/or including additional headers. Don't modify + the project name or reset ${MV_BARCODE_DETECTOR_LIB_NAME} variable, because + porting layer use these ones during the build. If it is required to change + projects/libraries names, best solution is to change + MV_BARCODE_DETECTOR_LIB_NAME and/or MV_BARCODE_GENERATOR_LIB_NAME options in + the CMakeLists.txt file that is located in the root of the package sources. + +e. If custom libraries support mv_engine_config_h handle attributes, then + default values of these attributes has to be specified into + media-vision-config.json file. This file can be found into the root directory + of the sources. For each attribute three parameters has to be specified: + attribute name, attribute value type and attribute value. For example, + in the following example four attributes are specified: + + { + "attributes": + [ + { "name" : "custom_detect_threshold", + "type" : "double", + "value" : 0.82, + }, + { "name" : "custom_detect_cascades_num", + "type" : "integer", + "value" : 50, + }, + { "name" : "custom_detect_use_haar", + "type" : "boolean", + "value" : true, + }, + { "name" : "custom_detect_haar_file_name", + "type" : "string", + "value" : "/usr/share/capi-media-vision/custom_haar.xml", + }, + ] + } + + In above example for each newly created mv_engine_config_h handle four + attributes will be automatically added. These values can be accessed + into the custom modules using Media Vision Common library interface + functions: + mv_engine_config_get_double_attribute(), + mv_engine_config_get_int_attribute(), + mv_engine_config_get_bool_attribute(), + mv_engine_config_get_string_attribute(). + For example, following code can be used to get value of the + "custom_detect_threshold" attribute: + + mv_engine_conf_h engine_cfg = NULL; + // When configuration is creating, default attributes from + // media-vision-config.json file will be set: + int err = mv_create_engine_config(&engine_cfg); + if (MEDIA_VISION_ERROR_NONE == err) + { + double attribute_value = 0.0; + err = mv_engine_config_get_double_attribute( + engine_cfg, "custom_detect_threshold", &attribute_value); + + if (MEDIA_VISION_ERROR_NONE == err) + { + // now attribute_value = 0.82 ("value" : 0.82 in json configuration) + } + } + + + +3. OPEN PORT REQUIRED PACKAGES + +Building default barcode detector and generator libraries requires following +dependencies: + +Barcode detector: zbar +Barcode generator: zint + +You can remove BuildRequires sections for these libraries from +packaging/capi-media-vision.spec file if corresponding module/modules is/are +disabled with options mentioned in 2.a. + + + +4. TEST SUITE + +capi-media-vision package includes test suite that allows to check API +functionality. The test suite application provides console interface that allows +to select options for barcode generation and detection. +Generation feature allows to generate barcodes images configured according to +the specified settings (type, message, size, encoding mode, ECC (error +correction level), version). Detection feature detects barcodes at the input +image files, decodes messages and generates output file (in jpeg format) where +locations of detected bercodes can be checked. |