README

   1 CONTENT
   2
   3 1. GENERAL DESCRIPTION OF THE MEDIA VISION PACKAGE
   4 2. USAGE OF PORTING LAYER FOR CHANGING MEDIA VISION ENGINE MODULES
   5 3. OPEN PORT REQUIRED PACKAGES
   6 4. TEST SUITE
   7
   8
   9
  10
  11 1. GENERAL DESCRIPTION OF THE MEDIA VISION PACKAGE
  12
  13 Media Vision package includes following modules: Common, Media Vision Barcode,
  14 Media Vision Face and Media Vision Image. Common module provides two handles
  15 (mv_source_h and mv_engine_config_h) and related functionality. It used by
  16 barcode detector and generator submodules. mv_source_h is used for wrapping raw
  17 image data buffers. mv_engine_config_h is optional. It can be used for fine
  18 tuning of internal libraries which are used by API. mv_engine_config_h handle
  19 usually can be used by barcode detector and/or generator modules (these modules
  20 provide mv_barcode_detector and mv_barcode_generator internal libraries) in the
  21 case when Native API doesn't cover all features supported by internal libraries.
  22 Using NULL instead of real mv_engine_h handle as functions parameter has to be
  23 taken into account. In most cases API user prefer to ignore detailed
  24 configuration of the modules.
  25
  26 Barcode detector submodule API provides tools to analyze the image buffers using
  27 mv_barcode_detect() function. This analysis strives to detect barcodes at the
  28 image, determine the type and extract the message. Results can be processed
  29 using mv_barcode_detected_cb callback.
  30
  31 Barcode generator submodule API provides tools to generate image buffer (or
  32 image file) with barcode. Barcodes generation can be configured by type,
  33 message, size, encoding mode, ECC (error correction level), version (three last
  34 setting are allowed only for QR Codes). One of two functions can be used:
  35 mv_barcode_generate_source() to generate the mv_source_h handle and
  36 mv_barcode_generate_image() to generate the file with barcode image.
  37
  38 Media Vision Face module aggregates functionality for detecting, recognition and
  39 tracking the faces on images. More detailed description can be found in doxygen
  40 documentation.
  41
  42 Media Vision Image module aggregates functionality for recognition and
  43 tracking the Flat Image objects. More detailed description can be found in
  44 doxygen documentation.
  45
  46
  47 2. USAGE OF PORTING LAYER FOR CHANGING MEDIA VISION ENGINE MODULES
  48
  49 By default open source engine libraries are used to provide modules
  50 functionality. But it is possible to substitute them by licensed or other custom
  51 libraries. To enable building of custom library for the Media Vision package,
  52 follow these steps:
  53
  54 a. Find CMakeLists.txt in the root of the package directory and change
  55    MEDIA_VISION_BARCODE_DETECTOR_LICENSE_PORT (for enabling build of a custom
  56    barcode detector library) and/or
  57    MEDIA_VISION_BARCODE_GENERATOR_LICENSE_PORT (for enabling build of a custom
  58    barcode generator library) and/or
  59    MEDIA_VISION_FACE_LICENSE_PORT (for enabling build of a custom Media Vision
  60    Face library) and/or MEDIA_VISION_IMAGE_LICENSE_PORT (for enabling build of
  61    a custom Media Vision Image library) options to ON. Example:
  62
  63    # only barcode detector module will be customized
  64    option(MEDIA_VISION_BARCODE_DETECTOR_LICENSE_PORT "..." ON)
  65    # barcode generator module will be default
  66    option(MEDIA_VISION_BARCODE_GENERATOR_LICENSE_PORT "..." OFF)
  67    # face module will be default
  68    option(MEDIA_VISION_FACE_LICENSE_PORT "..." OFF)
  69    # image module will be default
  70    option(MEDIA_VISION_IMAGE_LICENSE_PORT "..." OFF)
  71
  72 b. Options change will cause CMake to build from different subdirectories of
  73    mv_barcode/mv_face/mv_image directories. mv_barcode/barcode_detector,
  74    mv_barcode/barcode_generator, mv_face/face, mv_image/image subdirectories are
  75    used by default. mv_barcode/barcode_detector_lic,
  76    mv_barcode/mv_barcode_generator_lic, mv_face/face_lic, mv_image/image_lic
  77    subdirectories will be used during build if the corresponding option in ON.
  78    *_lic subdirectories already include base structure of the porting layer
  79    projects, and files will be used by main capi-media-vision library. Use this
  80    files to call functions from custom libraries. For example, you can change
  81    mv_barcode_detect_lic.c file in such a way:
  82
  83    #include "mv_barcode_detect_lic.h"
  84    #include "custom_library_header.h"
  85
  86    int mv_barcode_detect_lic(
  87        mv_source_h source,
  88        mv_engine_config_h engine_cfg,
  89        mv_rectangle_s roi,
  90        mv_barcode_on_detected_cb detect_cb,
  91        void *user_data)
  92    {
  93        mv_quadrangle_s *locations = NULL;
  94        const char *messages = NULL;
  95        mv_barcode_type_e *types = NULL;
  96
  97        // Here the call of the custom barcode detection function from
  98        // custom_library_header.h:
  99        int barcodes_number = custom_library_function(
 100                                  source, roi, &locations, &messages, &types);
 101
 102        if (barcodes_number > 0)
 103        {
 104            detect_cb(
 105                source, engine_cfg, locations, messages, types, barcodes_number,
 106                user_data);
 107            delete[] locations;
 108            delete[] messages;
 109            delete[] types;
 110        }
 111
 112        return MEDIA_VISION_ERROR_NONE;
 113    }
 114
 115 c. Change the packaging/capi-media-vision.spec to support any packages required
 116    to be found into the system for success build of the custom libraries.
 117    You also can remove requirements on open packages that are required by
 118    disabled barcode generator/detector, face, image ports. See list of the
 119    dependencies in the section 3 of this README file.
 120
 121 d. Modify mv_barcode/<name_of_the_(sub)module>_lic/CMakeLists.txt file for
 122    linking required libraries and/or including additional headers. Don't modify
 123    the project name or reset ${MV_BARCODE_DETECTOR_LIB_NAME},
 124    ${MV_BARCODE_GENERATOR_LIB_NAME}, ${MV_FACE_LIB_NAME}, ${MV_IMAGE_LIB_NAME}
 125    variables, because porting layer use these ones during the build. If it is
 126    required to change projects/libraries names, best solution is to change
 127    MV_BARCODE_DETECTOR_LIB_NAME, MV_BARCODE_GENERATOR_LIB_NAME,
 128    MV_FACE_LIB_NAME, MV_IMAGE_LIB_NAME options in the CMakeLists.txt file that
 129    is located in the root of the package sources.
 130
 131
 132
 133 3. OPEN PORT REQUIRED PACKAGES
 134
 135 Building default barcode detector and generator libraries requires following
 136 dependencies:
 137
 138 Barcode detector: zbar
 139 Barcode generator: zint
 140 Media Vision Face: opencv_core, opencv_objdetect, opencv_contrib
 141 Media Vision Image: opencv_core, opencv_highgui, opencv_imgproc,
 142                     opencv_objdetect, opencv_features2d, opencv_nonfree,
 143                     opencv_calib3d
 144
 145 You can remove BuildRequires sections for these libraries from
 146 packaging/capi-media-vision.spec file if corresponding module/modules is/are
 147 disabled with options mentioned in 2.a.
 148
 149
 150
 151 3. TEST SUITE
 152
 153 capi-media-vision package includes test suites which allow to check API
 154 functionality. The test suite applications provide console interface that allows
 155 to select options for barcode generation and detection, face detection,
 156 recognition and tracking, image recognition and tracking. Source codes of the
 157 testsuites are located in corresponding subdirectories of the test directory in
 158 the capi-media-vision project root:
 159 test/testsuites/barcode
 160 test/testsuites/face
 161 test/testsuites/image