path: root/doc/mediavision_doc.h

/*
 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
 *
 * Licensed under the Apache License, Version 2.0 (the License);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __TIZEN_MEDIAVISION_DOC_H__
#define __TIZEN_MEDIAVISION_DOC_H__

/**
 * @ingroup CAPI_MEDIA_FRAMEWORK
 * @defgroup    CAPI_MEDIA_VISION_MODULE Media Vision
 * @brief Media Vision library providing following functionality:\n
 * * Face detection, recognition, and tracking;\n
 * * Barcode detection and generation;\n
 * * Flat Image detection, recognition and tracking;\n
 * * Flat Image feature extraction;\n
 * * Surveillance: movement detection, person appearance/disappearance,
 *   person recognition.
 * * Inference: Image classification, object detection,
 *   face detection and facial landmark detection;\n
 *
 *
 * @defgroup    CAPI_MEDIA_VISION_COMMON_MODULE Media Vision Common
 * @ingroup     CAPI_MEDIA_VISION_MODULE
 * @brief  Common functions and enumerations used in
 *         @ref CAPI_MEDIA_VISION_FACE_MODULE,
 *         @ref CAPI_MEDIA_VISION_IMAGE_MODULE,
 *         @ref CAPI_MEDIA_VISION_SURVEILLANCE_MODULE and
 *         @ref CAPI_MEDIA_VISION_BARCODE_MODULE submodules.
 * @section CAPI_MEDIA_VISION_COMMON_MODULE_HEADER Required Header
 *      \#include <mv_common.h>
 *
 * @section CAPI_MEDIA_VISION_COMMON_MODULE_OVERVIEW Overview
 * @ref CAPI_MEDIA_VISION_COMMON_MODULE provides a set of functions that
 * are used in Media Vision API to correctly prepare and use included modules.
 * #mv_source_h is the handler that has to be created to keep information
 * on image or video frame data as row buffer. It can be created based on
 * the media data stored in memory or using the #media_packet_h handler.
 * #mv_source_h supported by the set of getters which allow to retrieve
 * such image parameters as its size or colorspace (see #mv_colorspace_e
 * enumeration). The handler is usually used as parameter for functions
 * performing computer vision tasks on the image data.\n
 * #mv_engine_config_h is the handler which provides dictionary
 * functionality. It means that it is possible to set (key, value) pairs to
 * the #mv_engine_config_h handlers and use them to transfer these values
 * to the engine part underlying Media Vision API. Information on which
 * attributes can be set is provided together with particular engines.
 *
 * @section CAPI_MEDIA_VISION_COMMON_MODULE_FEATURE Related Features
 * This API is related with the following features:\n
 *  - http://tizen.org/feature/vision.barcode_detection\n
 *  - http://tizen.org/feature/vision.barcode_generation\n
 *  - http://tizen.org/feature/vision.face_recognition\n
 *  - http://tizen.org/feature/vision.image_recognition\n
 *  - http://tizen.org/feature/vision.inference\n
 *  - http://tizen.org/feature/vision.inference.image\n
 *  - http://tizen.org/feature/vision.inference.face\n
 *
 * It is recommended to design feature related codes in your application for
 * reliability.\n
 * You can check if a device supports the related features for this API by using
 * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 * your application.\n
 * To ensure your application is only running on the device with specific
 * features, please define the features in your manifest file using the manifest
 * editor in the SDK.\n
 * More details on featuring your application can be found from
 * <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature">
 *    <b>Feature Element</b>.
 * </a>
 *
 * @defgroup    CAPI_MEDIA_VISION_FACE_MODULE Media Vision Face
 * @ingroup     CAPI_MEDIA_VISION_MODULE
 * @brief Face detection, recognition, and tracking.
 * @section CAPI_MEDIA_VISION_FACE_MODULE_HEADER Required Header
 *      \#include <mv_face.h>
 *
 * @section CAPI_MEDIA_VISION_FACE_MODULE_FEATURE Related Features
 * This API is related with the following features:\n
 *  - http://tizen.org/feature/vision.face_recognition\n
 *
 * It is recommended to design feature related codes in your application for
 * reliability.\n
 * You can check if a device supports the related features for this API by using
 * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 * your application.\n
 * To ensure your application is only running on the device with specific
 * features, please define the features in your manifest file using the manifest
 * editor in the SDK.\n
 * More details on featuring your application can be found from
 * <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature">
 *   <b>Feature Element</b>.
 * </a>
 *
 * @section CAPI_MEDIA_VISION_FACE_MODULE_OVERVIEW Overview
 * @ref CAPI_MEDIA_VISION_FACE_MODULE contains mv_face_detect() function
 * to detect faces on #mv_source_h, and mv_face_detected_cb() callback
 * to process detected faces. Also it contains mv_face_recognize() function
 * which performs face recognition on #mv_source_h for recognition model
 * #mv_face_recognition_model_h handle. Results of the recognition will be
 * passed to the mv_face_recognized_cb(). Results of the recognition consist
 * of unique face label and confidence of the recognition model that face was
 * recognized correctly. Unique face label is the integer identifier should be
 * introduced to the model before starting recognition, when learning examples
 * are added (see mv_face_recognition_model_add() function
 * documentation for details about unique face labels).\n
 * Recognition model should be created with
 * mv_face_recognition_model_create() and destroyed with
 * mv_face_recognition_model_destroy(). Model can be cloned with
 * mv_face_recognition_model_clone(), saved to the file with
 * mv_face_recognition_model_save(), loaded with
 * mv_face_recognition_model_load(). Model learning can be provided with
 * mv_face_recognition_model_add(), and
 * mv_face_recognition_model_learn() functions. These two methods has to be
 * called in the direct order: first, labeled face examples should be added to
 * the model using mv_face_recognition_model_add(). It is
 * expected that images of the same face will be added specifying the same face
 * label. When examples were added, model has to be learned based on the collected
 * set of labeled face images. mv_face_recognition_model_learn() function
 * will perform learning. If it is required to get the list of unique face
 * labels learned by the model, mv_face_recognition_model_query_labels()
 * function can be used.\n
 * Module contains function
 * mv_face_track() which performs tracking on #mv_source_h for
 * #mv_face_tracking_model_h and mv_face_tracked_cb() which process
 * tracked face. Tracking model should be created with
 * mv_face_tracking_model_create() and destroyed with
 * mv_face_tracking_model_destroy(). Tracking model should be prepared
 * with mv_face_tracking_model_prepare() before each session of tracking.
 * Model can be cloned with mv_face_tracking_model_clone(), saved to the
 * file with mv_face_tracking_model_save(), loaded with
 * mv_face_tracking_model_load().\n
 * Module provides function for detecting eye-blink status -
 * mv_face_eye_condition_recognize(), which provides detection on
 * #mv_source_h and face location - #mv_rectangle_s. Callback
 * mv_face_eye_condition_recognized_cb() handles result.\n
 * Also module contains mv_face_facial_expression_recognize() function which
 * detects face expression on #mv_source_h, face location is determined by
 * #mv_rectangle_s. Result is handled with
 * mv_face_facial_expression_recognized_cb().
 *
 * @defgroup    CAPI_MEDIA_VISION_IMAGE_MODULE Media Vision Image
 * @ingroup     CAPI_MEDIA_VISION_MODULE
 * @brief Flat Image recognition and tracking;\n
 * Flat image feature extraction.
 * @section CAPI_MEDIA_VISION_IMAGE_MODULE_HEADER Required Header
 *      \#include <mv_image.h>
 *
 * @section CAPI_MEDIA_VISION_IMAGE_MODULE_FEATURE Related Features
 * This API is related with the following features:\n
 *  - http://tizen.org/feature/vision.image_recognition\n
 *
 * It is recommended to design feature related codes in your application for
 * reliability.\n
 * You can check if a device supports the related features for this API by using
 * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 * your application.\n
 * To ensure your application is only running on the device with specific
 * features, please define the features in your manifest file using the manifest
 * editor in the SDK.\n
 * More details on featuring your application can be found from
 * <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature">
 *   <b>Feature Element</b>.
 * </a>
 *
 * @section CAPI_MEDIA_VISION_IMAGE_MODULE_OVERVIEW Overview
 * @ref CAPI_MEDIA_VISION_IMAGE_MODULE contains mv_image_recognize()
 * function to recognize images on #mv_source_h, and
 * mv_image_recognized_cb() callback to process recognition result. Module
 * also contains mv_image_track() which performs tracking of image on
 * sequence of #mv_source_h handles (by using method for each
 * #mv_source_h) and callback #mv_image_tracked_cb to process tracking result.
 * In order to perform general functionality, module contains
 * #mv_image_object_h and #mv_image_tracking_model_h handles.
 * Image object should be created with mv_image_object_create() and
 * destroyed with mv_image_object_destroy(). #mv_image_object_h can be
 * constructed by calling mv_image_object_fill() using image wrapped with
 * #mv_source_h. Object can be cloned with mv_image_object_clone(),
 * saved to the file with mv_image_object_save() and loaded from file with
 * mv_image_object_load(). Image object can be evaluated with
 * mv_image_object_get_recognition_rate().
 * Tracking model should be created with mv_image_tracking_model_create()
 * and destroyed with mv_image_tracking_model_destroy(). Tracking model
 * should be based on image object which will be tracked. Use
 * mv_image_tracking_model_set_target() to assign #mv_image_object_h
 * to the corresponding #mv_image_tracking_model_h. It can be cloned with
 * mv_image_tracking_model_clone(), saved to the file with
 * mv_image_tracking_model_save() and loaded from file with
 * mv_image_tracking_model_load().
 *
 * @defgroup    CAPI_MEDIA_VISION_BARCODE_MODULE Media Vision BarCode
 * @ingroup     CAPI_MEDIA_VISION_MODULE
 * @brief  Barcode module consists of barcode detection and barcode generation
 *         submodules.
 * @section CAPI_MEDIA_VISION_BARCODE_MODULE_HEADER Required Header
 *      \#include <mv_barcode.h>
 *
 * @section CAPI_MEDIA_VISION_BARCODE_MODULE_FEATURE Related Features
 * This API is related with the following features:\n
 *  - http://tizen.org/feature/vision.barcode_detection\n
 *  - http://tizen.org/feature/vision.barcode_generation\n
 *
 * It is recommended to design feature related codes in your application for
 * reliability.\n
 * You can check if a device supports the related features for this API by using
 * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 * your application.\n
 * To ensure your application is only running on the device with specific
 * features, please define the features in your manifest file using the manifest
 * editor in the SDK.\n
 * More details on featuring your application can be found from
 * <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature">
 *   <b>Feature Element</b>.
 * </a>
 *
 * @section CAPI_MEDIA_VISION_BARCODE_MODULE_OVERVIEW Overview
 * @ref CAPI_MEDIA_VISION_BARCODE_MODULE contains two submodules:\n
 * * Detection submodule,
 * * Generation submodule.\n
 *
 * Detection submodule can be used for detecting barcodes on image sources,
 * reading encoded messages, getting barcode types.\n
 * This module contains
 * mv_barcode_detect() function and mv_barcode_detected_cb()
 * callback. mv_barcode_detect() function can be called for the image
 * determined by #mv_source_h handler to detect barcodes. If barcodes
 * were detected, then mv_barcode_detected_cb() callback is called.
 * Each detected barcode type, message and location can be processed by
 * this callback. mv_barcode_detect() supports ROI (rectangular region of
 * interest) specification to allow barcode detection only for the region on
 * the image.
 *
 * Generation submodule can be used for generating the barcodes and QR codes.
 * Different encoding types (see #mv_barcode_qr_mode_e), error correction
 * codes (see #mv_barcode_qr_ecc_e) and code versions are supported for
 * QRCodes.\n This submodule contains mv_barcode_generate_source() function
 * to generate handler to the buffer with row image of barcode, and
 * mv_barcode_generate_image() function to generate image file with
 * barcode. Both functions support the set of parameters which allow API user to
 * configure output barcode. QR codes as well as Barcodes are supported
 * (see #mv_barcode_type_e enumeration for full list of supported barcodes).
 * For QR codes it is possible to specify error correction code and encoding
 * mode (see #mv_barcode_qr_mode_e). Generation to file supports several
 * formats (see #mv_barcode_image_format_e).
 *
 * @defgroup    CAPI_MEDIA_VISION_SURVEILLANCE_MODULE Media Vision Surveillance
 * @ingroup     CAPI_MEDIA_VISION_MODULE
 * @brief Video surveillance module.
 * @section CAPI_MEDIA_VISION_SURVEILLANCE_MODULE_HEADER Required Header
 *      \#include <mv_surveillance.h>
 *
 * @section CAPI_MEDIA_VISION_SURVEILLANCE_MODULE_FEATURE Related Features
 * This API is related with the following features:\n
 *  - http://tizen.org/feature/vision.image_recognition\n
 *  - http://tizen.org/feature/vision.face_recognition\n
 *
 * It is recommended to design feature related codes in your application for
 * reliability.\n
 * You can check if a device supports the related features for this API by using
 * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
 * your application.\n
 * To ensure your application is only running on the device with specific
 * features, please define the features in your manifest file using the manifest
 * editor in the SDK.\n
 * More details on featuring your application can be found from
 * <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature">
 *   <b>Feature Element</b>.
 * </a>
 *
 * @section CAPI_MEDIA_VISION_SURVEILLANCE_MODULE_OVERVIEW Overview
 * @ref CAPI_MEDIA_VISION_SURVEILLANCE_MODULE provides functionality can be
 * utilized for creation of video surveillance systems. The main idea underlying
 * surveillance is event subscription model. By default, supported event types
 * are described in @ref CAPI_MEDIA_VISION_SURVEILLANCE_EVENT_TYPES section.
 * mv_surveillance_subscribe_event_trigger() function has to be used to
 * create subscription to the particular event trigger. Triggers are handled by
 * #mv_surveillance_event_trigger_h type. Such type handlers can be created
 * with mv_surveillance_event_trigger_create() function and destroyed with
 * mv_surveillance_event_trigger_destroy() function. Once event trigger
 * subscription is created, corresponding mv_surveillance_event_occurred_cb()
 * callback will be invoked each time when event is detected, i.e. trigger is
 * activated. #mv_surveillance_result_h event detection result handler will
 * be passed to the callback together with identifier of the video stream where
 * event was detected and #mv_source_h handler containing frame in which
 * detection was performed. It is possible to retrieve specific to event type
 * result values using #mv_surveillance_result_h handler. In the
 * mv_surveillance_get_result_value() function documentation can be found
 * detailed description of result values retrieving. Following table contains
 * general events and corresponding event detection results can be obtained by
 * this approach:
 * <table>
 * <tr>
 *     <td><b>Event</b></td>
 *     <td><b>Event result values</b></td>
 * </tr>
 * <tr>
 *     <td>#MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED</td>
 *     <td>
 *         #MV_SURVEILLANCE_MOVEMENT_NUMBER_OF_REGIONS;<br>
 *         #MV_SURVEILLANCE_MOVEMENT_REGIONS
 *     </td>
 * </tr>
 * <tr>
 *     <td>#MV_SURVEILLANCE_EVENT_TYPE_PERSON_APPEARED_DISAPPEARED</td>
 *     <td>
 *         #MV_SURVEILLANCE_PERSONS_APPEARED_NUMBER;<br>
 *         #MV_SURVEILLANCE_PERSONS_DISAPPEARED_NUMBER;<br>
 *         #MV_SURVEILLANCE_PERSONS_TRACKED_NUMBER;<br>
 *         #MV_SURVEILLANCE_PERSONS_APPEARED_LOCATIONS;<br>
 *         #MV_SURVEILLANCE_PERSONS_DISAPPEARED_LOCATIONS;<br>
 *         #MV_SURVEILLANCE_PERSONS_TRACKED_LOCATIONS
 *     </td>
 * </tr>
 * <tr>
 *     <td>#MV_SURVEILLANCE_EVENT_TYPE_PERSON_RECOGNIZED</td>
 *     <td>
 *         #MV_SURVEILLANCE_PERSONS_RECOGNIZED_NUMBER;<br>
 *         #MV_SURVEILLANCE_PERSONS_RECOGNIZED_LOCATIONS;<br>
 *         #MV_SURVEILLANCE_PERSONS_RECOGNIZED_LABELS;<br>
 *         #MV_SURVEILLANCE_PERSONS_RECOGNIZED_CONFIDENCES
 *     </td>
 * </tr>
 * </table>
 * Before subscription of the event trigger with
 * mv_surveillance_subscribe_event_trigger() call it is possible to create
 * mv_engine_config_h handle and configure following attributes:
 * - #MV_SURVEILLANCE_SKIP_FRAMES_COUNT to setup number of frames will be
     ignored by event trigger;
 * - #MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD to specify sensitivity of
 *   the #MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED event detection;
 * - #MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH to specify the file
 *   where face recognition model to be used for recognition is stored.
 *
 * Created engine config has to be used as a parameter of
 * mv_surveillance_subscribe_event_trigger() to apply the configuration. If
 * NULL will be passed instead of valid #mv_engine_config_h handle, then
 * default attribute values will be used for subscriptions.
 * To make surveillance system work with video sequences
 * mv_surveillance_push_source() function has to
 * be used for each frame in the sequence in the correct order. Multiple video
 * sources can be supported by the system. To distinguish different video
 * sources unique stream identifier has to be assigned to each subscription.
 * Then, particular identifier can be passed as a parameter to the
 * mv_surveillance_push_source() function. After pushing the source to the
 * surveillance system, it will notify all triggers which were subscribed to
 * process frames coming from video stream which source has been pushed.
 * If trigger(s) is(are) activated on the source, then corresponding callback(s)
 * of mv_surveillance_event_occurred_cb() type will be called.
 * Additionally, region where event detection will be performed by the triggers
 * can be set with mv_surveillance_set_event_trigger_roi() function and
 * gotten with mv_surveillance_get_event_trigger_roi(). ROI is specified
 * independently for the each event trigger, so it is possible to detect events
 * of different types in the different parts of the incoming frames.
 * Event trigger subscription can be stopped any time using
 * mv_surveillance_unsubscribe_event_trigger() function. Additionally,
 * mv_surveillance_foreach_supported_event_type() and
 * mv_surveillance_foreach_event_result_name() functions can be found
 * useful if it is required to obtain supported event types list or result
 * value names list dynamically.
 *
 * @defgroup    CAPI_MEDIA_VISION_SURVEILLANCE_EVENT_TYPES Media Vision Surveillance Event Types
 * @ingroup     CAPI_MEDIA_VISION_SURVEILLANCE_MODULE
 * @brief Event types supported by the Surveillance module.
 *
 * @defgroup    CAPI_MEDIA_VISION_INFERENCE_MODULE Media Vision Inference
 * @ingroup     CAPI_MEDIA_VISION_MODULE
 * @brief Image Classification, Object Detection, Face and Facial landmark detection.
 * @section CAPI_MEDIA_VISION_INFERENCE_MODULE_HEADER Required Header
 *      \#include <mv_inference.h>
 *
 * @section CAPI_MEDIA_VISION_INFERECNE_MODULE_FEATURE Related Features
 * This API is related with the following features:\n
 *  - http://tizen.org/feature/vision.inference\n
 *  - http://tizen.org/feature/vision.inference.image\n
 *  - http://tizen.org/feature/vision.inference.face\n
 *
 * It is recommended to use features in your application for reliability.\n
 * You can check if the device supports the related features for this API by using
 * System Information, and control your application's actions accordingly.\n
 * To ensure your application is only running on devices with specific
 * features, please define the features in your manifest file using the manifest
 * editor in the SDK.\n
 * More details on using features in your application can be found in
 * <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature">
 *   <b>Feature Element</b>.
 * </a>
 *
 * @section CAPI_MEDIA_VISION_INFERENCE_MODULE_OVERVIEW Overview
 * @ref CAPI_MEDIA_VISION_INFERENCE_MODULE contains #mv_inference_h handle to perform
 * Image Classification, Object Detection, Face and Facial Landmark detection.
 * Inference handle should be created with mv_inference_create() and destoryed with
 * mv_inference_destroy(). #mv_inference_h should be configured by calling
 * mv_inference_configure(). After configuration, #mv_inference_h should be prepared by
 * calling mv_inference_prepare() which loads models and set required parameters.
 * After preparation, mv_inference_image_classify() has to be called to classify images on #mv_source_h,
 * and callback mv_inference_image_classified_cb() will be invoked to process results.
 * Module contains mv_inference_object_detect() function to detect object on #mv_source_h, and
 * mv_inference_object_detected_cb() to process object detection results.
 * Module also contains mv_inference_face_detect() and
 * mv_inference_facial_landmark_detect() functionalities to detect faces and their landmark
 * on #mv_source_h, and callbacks mv_inference_face_detected_cb() and
 * mv_inference_facial_landmark_detected_cb() to process detection results.
 */

#endif  /* __TIZEN_MEDIAVISION_DOC_H__ */