doc/mediavision_doc.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_MEDIAVISION_DOC_H__
  18 #define __TIZEN_MEDIAVISION_DOC_H__
  19
  20 /**
  21  * @ingroup CAPI_MEDIA_FRAMEWORK
  22  * @defgroup    CAPI_MEDIA_VISION_MODULE Media Vision
  23  * @brief Media Vision library providing following functionality:\n
  24  * * Face detection, recognition, and tracking;\n
  25  * * Barcode detection and generation;\n
  26  * * Flat Image detection, recognition and tracking;\n
  27  * * Flat Image features extraction;\n
  28  * * Surveillance: movement detection, person appearance/disappearance,
  29  *   person recognition.
  30  *
  31  * @defgroup    CAPI_MEDIA_VISION_COMMON_MODULE Media Vision Common
  32  * @ingroup     CAPI_MEDIA_VISION_MODULE
  33  * @brief  Common functions and enumerations used in
  34  *         @ref CAPI_MEDIA_VISION_FACE_MODULE,
  35  *         @ref CAPI_MEDIA_VISION_IMAGE_MODULE,
  36  *         @ref CAPI_MEDIA_VISION_SURVEILLANCE_MODULE and
  37  *         @ref CAPI_MEDIA_VISION_BARCODE_MODULE submodules.
  38  * @section CAPI_MEDIA_VISION_COMMON_MODULE_HEADER Required Header
  39  *      \#include <mv_common.h>
  40  *
  41  * @section CAPI_MEDIA_VISION_COMMON_MODULE_OVERVIEW Overview
  42  * @ref CAPI_MEDIA_VISION_COMMON_MODULE provides a set of functions that
  43  * are used in Media Vision API to correctly prepare and use included modules.
  44  * @ref mv_source_h is the handler that has to be created to keep information
  45  * on image or video frame data as row buffer. It can be created based on
  46  * the media data stored in memory or using the @ref media_packet_h handler.
  47  * @ref mv_source_h supported by the set of getters which allow to retrieve
  48  * such image parameters as its size or colorspace (see @ref mv_colorspace_e
  49  * enumeration). The handler is usually used as parameter for functions
  50  * performing computer vision tasks on the image data.\n
  51  * @ref mv_engine_config_h is the handler which provides dictionary
  52  * functionality. It means that it is possible to set (key, value) pairs to
  53  * the @ref mv_engine_config_h handlers and use them to transfer these values
  54  * to the engine part underlying Media Vision API. Information on which
  55  * attributes can be set is provided together with particular engines.
  56  *
  57  * @section CAPI_MEDIA_VISION_COMMON_MODULE_FEATURE Related Features
  58  * This API is related with the following features:\n
  59  *  - http://tizen.org/feature/vision.barcode_detection\n
  60  *  - http://tizen.org/feature/vision.barcode_generation\n
  61  *  - http://tizen.org/feature/vision.face_recognition\n
  62  *  - http://tizen.org/feature/vision.image_recognition\n
  63  *
  64  * It is recommended to design feature related codes in your application for
  65  * reliability.\n
  66  * You can check if a device supports the related features for this API by using
  67  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
  68  * your application.\n
  69  * To ensure your application is only running on the device with specific
  70  * features, please define the features in your manifest file using the manifest
  71  * editor in the SDK.\n
  72  * More details on featuring your application can be found from
  73  * <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature">
  74  *    <b>Feature Element</b>.
  75  * </a>
  76  *
  77  * @defgroup    CAPI_MEDIA_VISION_FACE_MODULE Media Vision Face
  78  * @ingroup     CAPI_MEDIA_VISION_MODULE
  79  * @brief Face detection, recognition, and tracking.
  80  * @section CAPI_MEDIA_VISION_FACE_MODULE_HEADER Required Header
  81  *      \#include <mv_face.h>
  82  *
  83  * @section CAPI_MEDIA_VISION_FACE_MODULE_FEATURE Related Features
  84  * This API is related with the following features:\n
  85  *  - http://tizen.org/feature/vision.face_recognition\n
  86  *
  87  * It is recommended to design feature related codes in your application for
  88  * reliability.\n
  89  * You can check if a device supports the related features for this API by using
  90  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
  91  * your application.\n
  92  * To ensure your application is only running on the device with specific
  93  * features, please define the features in your manifest file using the manifest
  94  * editor in the SDK.\n
  95  * More details on featuring your application can be found from
  96  * <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature">
  97  *   <b>Feature Element</b>.
  98  * </a>
  99  *
 100  * @section CAPI_MEDIA_VISION_FACE_MODULE_OVERVIEW Overview
 101  * @ref CAPI_MEDIA_VISION_FACE_MODULE contains @ref mv_face_detect() function
 102  * to detect faces on @ref mv_source_h, and @ref mv_face_detected_cb callback
 103  * to process detected faces. Also it contains @ref mv_face_recognize() function
 104  * which performs face recognition on @ref mv_source_h for recognition model
 105  * @ref mv_face_recognition_model_h handle. Results of the recognition will be
 106  * passed to the @ref mv_face_recognized_cb. Results of the recognition consist
 107  * of unique face label and confidence of the recognition model that face was
 108  * recognized correctly. Unique face label is the integer identifier should be
 109  * introduced to the model before starting recognition, when learning examples
 110  * are added (see @ref mv_face_recognition_model_add() function
 111  * documentation for details about unique face labels).\n
 112  * Recognition model should be created with
 113  * @ref mv_face_recognition_model_create() and destroyed with
 114  * @ref mv_face_recognition_model_destroy(). Model can be cloned with
 115  * @ref mv_face_recognition_model_clone(), saved to the file with
 116  * @ref mv_face_recognition_model_save(), loaded with
 117  * @ref mv_face_recognition_model_load(). Model learning can be provided with
 118  * @ref mv_face_recognition_model_add(), and
 119  * @ref mv_face_recognition_model_learn() functions. These two methods has to be
 120  * called in the direct order: first, labeled face examples should be added to
 121  * the model using @ref mv_face_recognition_model_add(). It is
 122  * expected that images of the same face will be added specifying the same face
 123  * label. When examples were added, model has to be learned based on the collected
 124  * set of labeled face images. @ref mv_face_recognition_model_learn() function
 125  * will perform learning. If it is required to get the list of unique face
 126  * labels learned by the model, @ref mv_face_recognition_model_query_labels()
 127  * function can be used.\n
 128  * Module contains function
 129  * @ref mv_face_track() which performs tracking on @ref mv_source_h for
 130  * @ref mv_face_tracking_model_h and  @ref mv_face_tracked_cb which process
 131  * tracked face. Tracking model should be created with
 132  * @ref mv_face_tracking_model_create() and destroyed with
 133  * @ref mv_face_tracking_model_destroy(). Tracking model should be prepared
 134  * with @ref mv_face_tracking_model_prepare() before each session of tracking.
 135  * Model can be cloned with @ref mv_face_tracking_model_clone(), saved to the
 136  * file with @ref mv_face_tracking_model_save(), loaded with
 137  * @ref mv_face_tracking_model_load().\n
 138  * Module provides function for detecting eye-blink status -
 139  * @ref mv_face_eye_condition_recognize(), which provides detection on
 140  * @ref mv_source_h and face location - @ref mv_rectangle_s. Callback
 141  * @ref mv_face_eye_condition_recognized_cb handles result.\n
 142  * Also module contains @ref mv_face_facial_expression_recognize() function which
 143  * detects face expression on @ref mv_source_h, face location is determined by
 144  * @ref mv_rectangle_s. Result is handled with
 145  * @ref mv_face_facial_expression_recognized_cb.
 146  *
 147  * @defgroup    CAPI_MEDIA_VISION_IMAGE_MODULE Media Vision Image
 148  * @ingroup     CAPI_MEDIA_VISION_MODULE
 149  * @brief Flat Image recognition and tracking;\n
 150  * Flat image features extraction.
 151  * @section CCAPI_MEDIA_VISION_IMAGE_MODULE_HEADER Required Header
 152  *      \#include <mv_image.h>
 153  *
 154  * @section CAPI_MEDIA_VISION_IMAGE_MODULE_FEATURE Related Features
 155  * This API is related with the following features:\n
 156  *  - http://tizen.org/feature/vision.image_recognition\n
 157  *
 158  * It is recommended to design feature related codes in your application for
 159  * reliability.\n
 160  * You can check if a device supports the related features for this API by using
 161  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 162  * your application.\n
 163  * To ensure your application is only running on the device with specific
 164  * features, please define the features in your manifest file using the manifest
 165  * editor in the SDK.\n
 166  * More details on featuring your application can be found from
 167  * <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature">
 168  *   <b>Feature Element</b>.
 169  * </a>
 170  *
 171  * @section CAPI_MEDIA_VISION_IMAGE_MODULE_OVERVIEW Overview
 172  * @ref CAPI_MEDIA_VISION_IMAGE_MODULE contains @ref mv_image_recognize()
 173  * function to recognize images on @ref mv_source_h, and @ref
 174  * mv_image_recognized_cb callback to process recognition result. Module
 175  * also contains @ref mv_image_track() which performs tracking of image on
 176  * sequence of @ref mv_source_h handles (by using method for each @ref
 177  * mv_source_h) and callback @ref mv_image_tracked_cb to process tracking result.
 178  * In order to perform general functionality, module contains @ref
 179  * mv_image_object_h and @ref mv_image_tracking_model_h handles.
 180  * Image object should be created with @ref mv_image_object_create() and
 181  * destroyed with @ref mv_image_object_destroy(). @ref mv_image_object_h can be
 182  * constructed by calling @ref mv_image_object_fill() using image wrapped with
 183  * @ref mv_source_h. Object can be cloned with @ref mv_image_object_clone(),
 184  * saved to the file with @ref mv_image_object_save() and loaded from file with
 185  * @ref mv_image_object_load(). Image object can be evaluated with
 186  * @ref mv_image_object_get_recognition_rate().
 187  * Tracking model should be created with @ref mv_image_tracking_model_create()
 188  * and destroyed with @ref mv_image_tracking_model_destroy(). Tracking model
 189  * should be based on image object which will be tracked. Use
 190  * @ref mv_image_tracking_model_set_target() to assign @ref mv_image_object_h
 191  * to the corresponding @ref mv_image_tracking_model_h. It can be cloned with
 192  * @ref mv_image_tracking_model_clone(), saved to the file with @ref
 193  * mv_image_tracking_model_save() and loaded from file with @ref
 194  * mv_image_tracking_model_load().
 195  *
 196  * @defgroup    CAPI_MEDIA_VISION_BARCODE_MODULE Media Vision BarCode
 197  * @ingroup     CAPI_MEDIA_VISION_MODULE
 198  * @brief  Barcode module consists of barcode detection and barcode generation
 199  *         submodules.
 200  * @section CAPI_MEDIA_VISION_BARCODE_MODULE_HEADER Required Header
 201  *      \#include <mv_barcode.h>
 202  *
 203  * @section CAPI_MEDIA_VISION_BARCODE_MODULE_FEATURE Related Features
 204  * This API is related with the following features:\n
 205  *  - http://tizen.org/feature/vision.barcode_detection\n
 206  *  - http://tizen.org/feature/vision.barcode_generation\n
 207  *
 208  * It is recommended to design feature related codes in your application for
 209  * reliability.\n
 210  * You can check if a device supports the related features for this API by using
 211  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 212  * your application.\n
 213  * To ensure your application is only running on the device with specific
 214  * features, please define the features in your manifest file using the manifest
 215  * editor in the SDK.\n
 216  * More details on featuring your application can be found from
 217  * <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature">
 218  *   <b>Feature Element</b>.
 219  * </a>
 220  *
 221  * @section CAPI_MEDIA_VISION_BARCODE_MODULE_OVERVIEW Overview
 222  * @ref CAPI_MEDIA_VISION_BARCODE_MODULE contains two submodules:\n
 223  * * Detection submodule,
 224  * * Generation submodule.\n
 225  *
 226  * Detection submodule can be used for detecting barcodes on image sources,
 227  * reading encoded messages, getting barcode types.\n
 228  * This module contains
 229  * @ref mv_barcode_detect() function and @ref mv_barcode_detected_cb
 230  * callback. @ref mv_barcode_detect() function can be called for the image
 231  * determined by @ref mv_source_h handler to detect barcodes. If barcodes
 232  * were detected, then @ref mv_barcode_detected_cb callback is called.
 233  * Each detected barcode type, message and location can be processed by
 234  * this callback. @ref mv_barcode_detect() supports ROI (rectangular region of
 235  * interest) specification to allow barcode detection only for the region on
 236  * the image.
 237  *
 238  * Generation submodule can be used for generating the barcodes and QR codes.
 239  * Different encoding types (see @ref mv_barcode_qr_mode_e), error correction
 240  * codes (see @ref mv_barcode_qr_ecc_e) and code versions are supported for
 241  * QRCodes.\n This submodule contains @ref mv_barcode_generate_source() function
 242  * to generate handler to the buffer with row image of barcode, and
 243  * @ref mv_barcode_generate_image() function to generate image file with
 244  * barcode. Both functions support the set of parameters which allow API user to
 245  * configure output barcode. QR codes as well as Barcodes are supported
 246  * (see @ref mv_barcode_type_e enumeration for full list of supported barcodes).
 247  * For QR codes it is possible to specify error correction code and encoding
 248  * mode (see @ref mv_barcode_qr_mode_e). Generation to file supports several
 249  * formats (see @ref mv_barcode_image_format_e).
 250  *
 251  * @defgroup    CAPI_MEDIA_VISION_SURVEILLANCE_MODULE Media Vision Surveillance
 252  * @ingroup     CAPI_MEDIA_VISION_MODULE
 253  * @brief Video surveillance module.
 254  * @section CAPI_MEDIA_VISION_SURVEILLANCE_MODULE_HEADER Required Header
 255  *      \#include <mv_surveillance.h>
 256  *
 257  * @section CAPI_MEDIA_VISION_SURVEILLANCE_MODULE_FEATURE Related Features
 258  * This API is related with the following features:\n
 259  *  - http://tizen.org/feature/vision.image_recognition\n
 260  *  - http://tizen.org/feature/vision.face_recognition\n
 261  *
 262  * It is recommended to design feature related codes in your application for
 263  * reliability.\n
 264  * You can check if a device supports the related features for this API by using
 265  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 266  * your application.\n
 267  * To ensure your application is only running on the device with specific
 268  * features, please define the features in your manifest file using the manifest
 269  * editor in the SDK.\n
 270  * More details on featuring your application can be found from
 271  * <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature">
 272  *   <b>Feature Element</b>.
 273  * </a>
 274  *
 275  * @section CAPI_MEDIA_VISION_SURVEILLANCE_MODULE_OVERVIEW Overview
 276  * @ref CAPI_MEDIA_VISION_SURVEILLANCE_MODULE provides functionality can be
 277  * utilized for creation of video surveillance systems. The main idea underlying
 278  * surveillance is event subscription model. By default, supported event types
 279  * are described in @ref CAPI_MEDIA_VISION_SURVEILLANCE_EVENT_TYPES section.
 280  * @ref mv_surveillance_subscribe_event_trigger() function has to be used to
 281  * create subscription to the particular event trigger. Triggers are handled by
 282  * @ref mv_surveillance_event_trigger_h type. Such type handlers can be created
 283  * with @ref mv_surveillance_event_trigger_create() function and destroyed with
 284  * @ref mv_surveillance_event_trigger_destroy() function. Once event trigger
 285  * subscription is created, corresponding @ref mv_surveillance_event_occurred_cb
 286  * callback will be invoked each time when event is detected, i.e. trigger is
 287  * activated. @ref mv_surveillance_result_h event detection result handler will
 288  * be passed to the callback together with identifier of the video stream where
 289  * event was detected and @ref mv_source_h handler containing frame in which
 290  * detection was performed. It is possible to retrieve specific to event type
 291  * result values using @ref mv_surveillance_result_h handler. In the
 292  * @ref mv_surveillance_get_result_value() function documentation can be found
 293  * detailed description of result values retrieving. Following table contains
 294  * general events and corresponding event detection results can be obtained by
 295  * this approach:
 296  * <table>
 297  * <tr>
 298  *     <td><b>Event</b></td>
 299  *     <td><b>Event result values</b></td>
 300  * </tr>
 301  * <tr>
 302  *     <td>@ref MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED</td>
 303  *     <td>
 304  *         @ref MV_SURVEILLANCE_MOVEMENT_NUMBER_OF_REGIONS;<br>
 305  *         @ref MV_SURVEILLANCE_MOVEMENT_REGIONS
 306  *     </td>
 307  * </tr>
 308  * <tr>
 309  *     <td>@ref MV_SURVEILLANCE_EVENT_TYPE_PERSON_APPEARED_DISAPPEARED</td>
 310  *     <td>
 311  *         @ref MV_SURVEILLANCE_PERSONS_APPEARED_NUMBER;<br>
 312  *         @ref MV_SURVEILLANCE_PERSONS_DISAPPEARED_NUMBER;<br>
 313  *         @ref MV_SURVEILLANCE_PERSONS_TRACKED_NUMBER;<br>
 314  *         @ref MV_SURVEILLANCE_PERSONS_APPEARED_LOCATIONS;<br>
 315  *         @ref MV_SURVEILLANCE_PERSONS_DISAPPEARED_LOCATIONS;<br>
 316  *         @ref MV_SURVEILLANCE_PERSONS_TRACKED_LOCATIONS
 317  *     </td>
 318  * </tr>
 319  * <tr>
 320  *     <td>@ref MV_SURVEILLANCE_EVENT_TYPE_PERSON_RECOGNIZED</td>
 321  *     <td>
 322  *         @ref MV_SURVEILLANCE_PERSONS_RECOGNIZED_NUMBER;<br>
 323  *         @ref MV_SURVEILLANCE_PERSONS_RECOGNIZED_LOCATIONS;<br>
 324  *         @ref MV_SURVEILLANCE_PERSONS_RECOGNIZED_LABELS;<br>
 325  *         @ref MV_SURVEILLANCE_PERSONS_RECOGNIZED_CONFIDENCES
 326  *     </td>
 327  * </tr>
 328  * </table>
 329  * Before subscription of the event trigger with
 330  * @ref mv_surveillance_subscribe_event_trigger() call it is possible to create
 331  * @ref mv_engine_config_h handle and configurate following attributes:
 332  * - @ref MV_SURVEILLANCE_SKIP_FRAMES_COUNT to setup number of frames will be
 333      ignored by event trigger;
 334  * - @ref MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD to specify sensitivity of
 335  *   the @ref MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED event detection;
 336  * - @ref MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH to specify the file
 337  *   where face recognition model to be used for recognition is stored.
 338  *
 339  * Created engine config has to be used as a parameter of
 340  * @ref mv_surveillance_subscribe_event_trigger() to apply the configuration. If
 341  * NULL will be passed instead of valid @ref mv_engine_config_h handle, then
 342  * default attribute values will be used for subsriptions.
 343  * To make surveillance system work with video sequences
 344  * @ref mv_surveillance_push_source() function has to
 345  * be used for each frame in the sequence in the correct order. Multiple video
 346  * sources can be supported by the system. To distinguish different video
 347  * sources unique stream identifier has to be assigned to each subscription.
 348  * Then, particular identifier can be passed as a parameter to the
 349  * @ref mv_surveillance_push_source() function. After pushing the source to the
 350  * surveillance system, it will notify all triggers which were subscribed to
 351  * process frames coming from video stream which source has been pushed.
 352  * If trigger(s) is(are) activated on the source, then corresponding callback(s)
 353  * of @ref mv_surveillance_event_occurred_cb type will be called.
 354  * Additionally, region where event detection will be performed by the triggers
 355  * can be set with @ref mv_surveillance_set_event_trigger_roi() function and
 356  * gotten with @ref mv_surveillance_get_event_trigger_roi(). ROI is specified
 357  * independently for the each event trigger, so it is possible to detect events
 358  * of different types in the different parts of the incoming frames.
 359  * Event trigger subscription can be stopped any time using
 360  * @ref mv_surveillance_unsubscribe_event_trigger() function. Additionally,
 361  * @ref mv_surveillance_foreach_supported_event_type() and
 362  * @ref mv_surveillance_foreach_event_result_name() functions can be found
 363  * useful if it is required to obtain supported event types list or result
 364  * value names list dynamically.
 365  *
 366  * @defgroup    CAPI_MEDIA_VISION_SURVEILLANCE_EVENT_TYPES Media Vision Surveillance Event Types
 367  * @ingroup     CAPI_MEDIA_VISION_SURVEILLANCE_MODULE
 368  * @brief Event types supported by the Surveillance module.
 369  */
 370
 371 #endif  /* __TIZEN_MEDIAVISION_DOC_H__ */