add base code

1 files changed, 512 insertions, 0 deletions

diff --git a/include/face.h b/include/face.h
new file mode 100755
index 0000000..2ad6bdd
--- /dev/null
+++ b/include/face.h
@@ -0,0 +1,512 @@
+/*
+ * Copyright (c) 2011 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_UIX_FACE_H__
+#define __TIZEN_UIX_FACE_H__
+
+#include <tizen.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup CAPI_UIX_FACE_MODULE
+ * @{
+ */
+
+/**
+ * @brief Facial engine handle.
+ */
+typedef struct face_s *face_h;
+
+/**
+ * @brief Face image handle containing the input image data.
+ */
+typedef struct face_image_s *face_image_h;
+
+/**
+ * @brief Facial component handle.
+ */
+typedef struct face_component_s *face_component_h;
+
+/**
+ * @brief Facial feature handle.
+ */
+typedef struct face_feature_s *face_feature_h;
+
+/**
+ * @brief Enumerations of error codes for the Facial Engine API.
+ */
+typedef enum {
+	FACE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
+	FACE_ERROR_INVALID_PARAMTER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
+	FACE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
+	FACE_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_UIX_CLASS | 0x41, /**< Facial engine not found */
+	FACE_ERROR_OPERATION_FAILED = TIZEN_ERROR_UIX_CLASS | 0x42, /**< Operation failed */
+	FACE_ERROR_COMPONENT_NOT_FOUND = TIZEN_ERROR_UIX_CLASS | 0x43, /**< Component not found */
+} face_error_e;
+
+/**
+ * @brief Enumerations of color spaces
+ * @see face_image_create()
+ * @see face_attr_get_prefered_colorspace()
+ */
+typedef enum {
+	FACE_IMAGE_COLORSPACE_YUV420,			/**< Y:U:V = 4:2:0 */
+	FACE_IMAGE_COLORSPACE_RGB565,			/**< Red:Green:Blue = 5:6:5 */
+	FACE_IMAGE_COLORSPACE_RGBA8888,			/**< Red:Green:Blue:Alpha = 8:8:8:8 */
+	FACE_IMAGE_COLORSPACE_LUMINANCE_ONLY,		/**< luminance only image */
+} face_image_colorspace_e;
+
+/**
+ * @brief Enumerations of facial expressions
+ * @see face_recognize_expression()
+ */
+typedef enum {
+	FACE_EXPRESSION_UNKNOWN,		/**< Unknown expression */
+	FACE_EXPRESSION_NUETRAL,		/**< Normal expression */
+	FACE_EXPRESSION_ANGRY,		/**< Angry expression */
+	FACE_EXPRESSION_SMILE,			/**< Cheerful expression */
+	FACE_EXPRESSION_SURPRISE,		/**< Suprised expression */
+} face_expression_e;
+
+/**
+ * @brief Enumerations of eye states
+ * @see face_recognize_blink()
+ */
+typedef enum {
+	FACE_EYE_STATE_UNKNOWN,		/**< The no eye state, when the eye detect fails */
+	FACE_EYE_STATE_OPENED,		/**< The state when eye is opened */
+	FACE_EYE_STATE_CLOSED,		/**< The state when eye is closed */
+} face_eye_state_e;
+
+/**
+ * @brief Enumerations of image types
+ * @see face_detect_faces()
+ */
+typedef enum {
+	FACE_IMAGE_TYPE_SINGLE,	/**< still image */
+	FACE_IMAGE_TYPE_CONTINIOUS,	/**< video frame */
+} face_image_type_e;
+
+
+/**
+ * @brief Represents a rectangular region in a coordinate space
+ */
+typedef struct {
+	int x;		/**< The x coordinate of the top-left corner of the rectangle  */
+	int y;		/**< The y coordinate of the top-left corner of the rectangle  */
+	int w;		/**< The width of the rectangle  */
+	int h;		/**< The height of the rectangle  */
+} face_rect_s;
+
+
+/**
+ * @brief Represents a location in a two-dimensional coordinate space
+ */
+typedef struct {
+	int x;		/**< The x-coordinate */
+	int y;		/**< The y-coordinate */
+} face_point_s;
+
+/**
+ * @brief Creates a facial feature handle.
+ * @details Creates a facial feature handle to represent a recognized face
+ * @remarks The @a face_feature must be released with face_feature_destroy() by you.
+ * @param[out] face_feature A facial feature handle to be newly created on success
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OUT_OF_MEMORY	Out of memory
+ * @see face_feature_destroy()
+ */
+int face_feature_create(face_feature_h *face_feature);
+
+/**
+ * @brief Destroys the facial feature handle.
+ * @param[in] face_feature The facial feature handle
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @see face_feature_create()
+ */
+int face_feature_destroy(face_feature_h face_feature);
+
+/**
+ * @brief Sets the raw data to initialize the facial feature
+ * @remarks The @a data must be from face_feature_get_data()
+ * @param[in] face_feature The facial feature handle
+ * @param[in] data The data of facial feature
+ * @param[in] length The length of facial feature data
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OUT_OF_MEMORY	Out of memory
+ * @see face_feature_get_data()
+ */
+int face_feature_set_data(face_feature_h face_feature, const unsigned char *data, int length);
+
+/**
+ * @brief Gets the raw data of the facial feature
+ * @remarks The @a data must be released with free() by you.
+ * @param[in] face_feature The facial feature handle
+ * @param[out] data The data of facial feature
+ * @param[out] length The length of facial feature data
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @see face_feature_set_data()
+ */
+int face_feature_get_data(face_feature_h face_feature, unsigned char **data, int *length);
+
+/**
+ * @brief Creates a face image handle containing the input image data
+ * @remarks The @a face_image must be released with face_image_destroy() by you.
+ * @remarks The @a buffer must not be released until @a face_image is released with face_image_destroy()
+ * @param[in] colorspace The colorspace of the image
+ * @param[in] buffer The buffer containing the image
+ * @param[in] width The width of the image
+ * @param[in] height The height of the image
+ * @param[in] size The size of the buffer
+ * @param[out] face_image The face image handle to be newly created on success
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OUT_OF_MEMORY	Out of memory
+ *
+ * @see face_image_destroy()
+ */
+int face_image_create(face_image_colorspace_e colorspace, unsigned char *buffer, int width, int height, int size, face_image_h *face_image);
+
+/**
+ * @brief Destroys the face image handle
+ * @param[in] face_image The face image handle
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @see face_image_create()
+ */
+int face_image_destroy(face_image_h face_image);
+
+/**
+ * @brief Destroys the facial component handle
+ * @param[in] face_component The facial component handle
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @see face_extract_component()
+ */
+int face_component_destroy(face_component_h face_component);
+
+/**
+ * @brief Gets the position of the face.
+ * @param[in] face_component The facial component handle
+ * @param[out] face The position of the face
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_COMPONENT_NOT_FOUND Component not found
+ */
+int face_component_get_face_rect(face_component_h face_component, face_rect_s *face);
+
+/**
+ * @brief Gets the position of the left eye.
+ * @param[in] face_component The facial component handle
+ * @param[out] leye The position of the left eye
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_COMPONENT_NOT_FOUND Component not found
+ * @see face_component_get_right_eye_point()
+ */
+int face_component_get_left_eye_point(face_component_h face_component, face_point_s *leye);
+
+/**
+ * @brief Gets the position of the right eye.
+ * @param[in] face_component The facial component handle
+ * @param[out] reye The position of the right eye
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_COMPONENT_NOT_FOUND Component not found
+ * @see face_component_get_left_eye_point()
+ */
+int face_component_get_right_eye_point(face_component_h face_component, face_point_s *reye);
+
+/**
+ * @brief Gets the position of the mouse.
+ * @param[in] face_component The facial component handle
+ * @param[out] mouse The position of the mouse
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_COMPONENT_NOT_FOUND Component not found
+ */
+int face_component_get_mouse_rect(face_component_h face_component, face_rect_s *mouse);
+
+
+/**
+ * @brief Creates a handle to the facial engine.
+ * @remarks The @a face must be released with face_destroy() by you.
+ * @param[out] face A facial engine handle to be newly created on success
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OUT_OF_MEMORY	Out of memory
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_destroy()
+ */
+int face_create(face_h *face);
+
+/**
+ * @brief Destroys the handle to the facial engine and releases all its resources.
+ * @param[in] face The facial engine handle
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_create()
+ */
+int face_destroy(face_h face);
+
+
+/**
+ * @brief Gets the preferred color space of the facial engine.
+ * @remarks The preferred color space depends on the facial engine.
+ * @param[in] face The facial engine handle
+ * @param[out] colorspace The preferred color space
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @see face_image_create()
+ */
+int face_attr_get_prefered_colorspace(face_h face, face_image_colorspace_e *colorspace);
+
+
+/**
+ * @brief Sets the maximum number of faces to detect from the image.
+ * @remarks The maximum number must be a positive number
+ * @param[in] face The facial engine handle
+ * @param[in] max_faces The maximum number of faces
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_attr_get_max_number_faces()
+ */
+int face_attr_set_max_number_faces(face_h face, int max_faces);
+
+/**
+ * @brief Gets the maximum number of faces to detect from the image
+ * @param[in] face The facial engine handle
+ * @param[out] max_faces The maximum number of faces
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_attr_set_max_number_faces()
+ */
+int face_attr_get_max_number_faces(face_h face, int *max_faces);
+
+/**
+ * @brief Sets the minimum ratio of detectable faces relative to the input image
+ * @remarks The range is from values 1 to 3, where the value 1 has the longest execution time and 3 has the shortest execution time.
+ * @param[in] face The facial engine handle
+ * @param[in] scale_factor The minimum ratio of detectable faces
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_attr_get_scale_factor()
+ */
+int face_attr_set_scale_factor(face_h face, int scale_factor);
+
+/**
+ * @brief Gets The minimum ratio of detectable faces relative to the input image
+ * @param[in] face The facial engine handle
+ * @param[out] scale_factor The minimum ratio of detectable faces
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_attr_set_scale_factor()
+ */
+int face_attr_get_scale_factor(face_h face, int *scale_factor);
+
+/**
+ * @brief Sets interval to detect faces at streaming data
+ * @details Sets interval to detect faces at streaming data
+ * @remarks Interval has to positive number
+ * @param[in] face The facial engine handle
+ * @param[in] detect_interval Detect interval
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_attr_get_detect_inteval()
+ */
+int face_attr_set_detect_inteval(face_h face, int detect_interval);
+
+/**
+ * @brief Gets interval to detect faces at streaming data
+ * @details Gets interval to detect faces at streaming data
+ * @param[in] face The facial engine handle
+ * @param[out] detect_interval Detect interval
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE	Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_attr_set_detect_inteval()
+ */
+int face_attr_get_detect_inteval(face_h face, int *detect_interval);
+
+
+/**
+ * @brief Detects faces from the image data.
+ * @param[in] face The facial engine handle
+ * @param[in] image_type The type of the image
+ * @param[in] image The image handle to detect faces
+ * @param[out] face_rect The array of the detected face positions
+ * @param[out] count The number of the detected face positions
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OUT_OF_MEMORY	Out of memory
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ */
+int face_detect_faces(face_h face, face_image_type_e image_type, const face_image_h image,  face_rect_s *face_rect[], int *count);
+
+
+/**
+ * @brief Gets a current position of the specific face detected from the previous image data
+ * @details This function can be used for tracking the face from a sequential image data
+ * @param[in] face The facial engine handle
+ * @param[in] prev_image The handle to previous image data
+ * @param[in] cur_image The handle to current image data
+ * @param[in] prev_rect The position of the detected face from face_detect_faces() with the previous image data
+ * @param[out] cur_rect The position of the detected face from face_detect_faces() with the current image data
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @retval #FACE_ERROR_OPERATION_FAILED Operation failed
+ */
+int face_get_movement(face_h face, const face_image_h prev_image, const face_image_h cur_image, const face_rect_s *prev_rect, face_rect_s *cur_rect);
+
+
+/**
+ * @brief Extracts a facial component from the detected face
+ * @remarks The @a component must be released with face_component_destroy() by you.
+ * @param[in] face The facial engine handle
+ * @param[in] image The face image handle
+ * @param[in] rect The face position to extract component from the image data
+ * @param[out] component The facial component handle to be created on success
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @see face_component_destroy()
+ * @see face_component_get_face_rect()
+ * @see face_component_get_left_eye_point()
+ * @see face_component_get_right_eye_point()
+ * @see face_component_get_mouse_rect()
+ */
+int face_extract_component(face_h face, const face_image_h image, const face_rect_s *rect, face_component_h *component);
+
+
+/**
+ * @brief Extracts a facial feature to represent a recognized face
+ * @remarks The @a feature must be released with face_feature_destroy() by you.
+ * @param[in] face The facial engine handle
+ * @param[in] image The face image handle
+ * @param[in] component The facial component handle from face_extract_component() with the given image data
+ * @param[out] feature The facial feature handle to be created on success
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OUT_OF_MEMORY	Out of memory
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @retval #FACE_ERROR_OPERATION_FAILED Operation failed
+ * @see face_compare_feature()
+ */
+int face_extract_feature(face_h face, const face_image_h image, const face_component_h component, face_feature_h *feature);
+
+/**
+ * @brief Compares two faces using the facial features.
+ * @details This function compares two faces using the facial features and gets the similarity of two specified faces.
+ * @param[in] A The first facial feature handle to compare from face_extract_feature()
+ * @param[in] B The second facial feature handle to compare from face_extract_feature()
+ * @param[out] similarity The degree of similarity in percentage.\n
+ * The range is from 0 to 1.0. 1.0 means the face are the same, and 0 means there is no similarity at between the two faces.
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @retval #FACE_ERROR_OPERATION_FAILED Operation failed
+ * @see face_extract_feature()
+ */
+int face_compare_feature(const face_feature_h A, const face_feature_h B, float *similarity);
+
+/**
+ * @brief Recognizes the facial expression
+ * @param[in] face The facial engine handle
+ * @param[in] image The face image handle
+ * @param[in] component The facial component handle from face_extract_component() with the given image data
+ * @param[out] expression The recognized facial expression
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OPERATION_FAILED Failed to recognize the facial expression
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @retval #FACE_ERROR_OPERATION_FAILED Operation failed
+ * @see face_extract_component()
+ * @see face_expression_e
+ */
+int face_recognize_expression(face_h face, const face_image_h image , const face_component_h component, face_expression_e *expression);
+
+
+/**
+ * @brief Recognizes the eye states
+ * @param[in] face The facial engine handle
+ * @param[in] image The face image handle
+ * @param[in] component The facial component handle from face_extract_component() with the given image data
+ * @param[out] lefteye The state of left eye
+ * @param[out] righteye The state of right eye
+ * @return 0 on success, otherwise a negative error value.
+ * @retval #FACE_ERROR_NONE Successful
+ * @retval #FACE_ERROR_INVALID_PARAMTER Invalid parameter
+ * @retval #FACE_ERROR_OPERATION_FAILED Failed to recognize the eye states
+ * @retval #FACE_ERROR_ENGINE_NOT_FOUND Facial engine not found
+ * @retval #FACE_ERROR_OPERATION_FAILED Operation failed
+ * @see face_extract_component()
+ * @see face_eye_state_e
+ */
+int face_recognize_blink(face_h face,  const face_image_h image, const face_component_h component, face_eye_state_e *lefteye,  face_eye_state_e *righteye);
+
+
+/**
+ * @}
+ */
+
+
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif		// __TIZEN_UIX_FACE_H__
+