OpenVX Classifier Extension  9249ea0
vx_khr_class.h
1 /*
2  * Copyright (c) 2012-2017 The Khronos Group Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and/or associated documentation files (the
6  * "Materials"), to deal in the Materials without restriction, including
7  * without limitation the rights to use, copy, modify, merge, publish,
8  * distribute, sublicense, and/or sell copies of the Materials, and to
9  * permit persons to whom the Materials are furnished to do so, subject to
10  * the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included
13  * in all copies or substantial portions of the Materials.
14  *
15  * MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
16  * KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
17  * SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
18  * https://www.khronos.org/registry/
19  *
20  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
22  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
23  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
24  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
25  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
26  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
27  */
28 
29 #ifndef _VX_KHR_CLASSIFIER_H_
30 #define _VX_KHR_CLASSIFIER_H_
31 
32 /*!
33  * \file
34  * \brief The Khronos Extension for general classification.
35  *
36  */
37 
38 #define OPENVX_KHR_CLASS "vx_khr_class"
39 
40 #include <VX/vx.h>
41 
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 /*! \brief The Classifier Extension Library Set
47  * \ingroup group_classifier
48  */
49 #define VX_LIBRARY_KHR_CLASS_EXTENSION (0x2)
50 /*! \brief The list of Classifier Extension Kernels.
51  * \ingroup group_classifier
52  */
53 enum vx_kernel_nn_ext_e {
54  /*! \brief The Classifier Extension scan kernel.
55  * \see group_classifier
56  */
57  VX_KERNEL_CONVOLUTION_LAYER = VX_KERNEL_BASE(VX_ID_KHRONOS, VX_LIBRARY_KHR_NN_EXTENSION) + 0x0,
58 };
59 
60 /*! \brief Classifier Extension type enums.
61  * \ingroup group_classifier
62  */
63 enum vx_class_enum_e
64 {
65  VX_ENUM_CLASSIFIER_MODEL= 0x1E, /*!< \brief Classifier model */
66 };
67 
68 /*!
69  * \brief classification model to be used in <tt>\ref vxScanClassifierNode</tt>.
70  * The classification models are loadable by undefined binary format see <tt>\ref vxImportClassifierModel</tt>.
71  * Extensions will be added to the specification, to support a defined binary format.
72  * \ingroup group_object_classifier_model
73  */
74 typedef struct _vx_classifier_model* vx_classifier_model;
75 
76 /*! \brief Classifier model format enums.
77  * In the main specification only undefined binary format is supported. Extensions to the specification will be added in order to support specific binary format.
78  * \ingroup group_object_classifier_model
79  */
81 {
82  /*! \brief Undefined binary format.
83  * Using this enumeration will result in an implementation defined behaviour.
84  */
85  VX_CLASSIFIER_MODEL_UNDEFINED = VX_ENUM_BASE( VX_ID_KHRONOS, VX_ENUM_CLASSIFIER_MODEL ) + 0x0,
86 };
87 
88 /*==============================================================================
89  CLASSIFIER MODEL
90  =============================================================================*/
91 /*!
92  * \brief Creates an opaque reference classifier model
93  * This function creates a classifier model to be used in <tt>\ref vxScanClassifierNode</tt>. The object classifier object is a read-only constant object. It cannot be changed during graph execution.
94  * \param [in] context Reference to the context where to create the ClassifierModel.
95  * \param [in] format The binary format which contain the classifier model. See <tt>\ref vx_classifier_model_format_e</tt>. Currently only undefined binary format is supported.
96  * Extensions will be added to the specification, to support a classification model defined binary format.
97  * \param [in] ptr A memory pointer to the binary format.
98  * \param [in] length size in bytes of binary format data.
99  * \returns A ClassifierModel reference <tt>\ref vx_classifier_model</tt>. Any possible errors preventing a
100  * successful creation should be checked using <tt>\ref vxGetStatus</tt>.
101  * \ingroup group_object_classifier_model
102  */
103 VX_API_ENTRY vx_classifier_model vxImportClassifierModel(vx_context context, vx_enum format, const vx_uint8* ptr, vx_size length);
104 
105 /*!
106  * \brief Releases a reference of an ClassifierModel object.
107  * The object may not be garbage collected until its total reference and its contained objects
108  * count is zero. After returning from this function the reference is zeroed/cleared.
109  * \param [in] model The pointer to the ClassifierModel to release.
110  * \return A <tt>\ref vx_status_e</tt> enumeration.
111  * \retval <tt>\ref VX_SUCCESS</tt> No errors; all other values indicate failure
112  * \retval * An error occurred. See <tt\ref >vx_status_e</tt>.
113  * \ingroup group_object_classifier_model
114  */
115 VX_API_ENTRY vx_status vxReleaseClassifierModel(vx_classifier_model* model);
116 
117 /*! \brief [Graph] Scans a feature-map (input_feature_map) and detect the classification for each scan-window.
118  * \param [in] graph The reference to the graph
119  * \param [in] input_feature_map The Feature-map, example is the output of <tt>\ref vxHOGFeaturesNode</tt>.
120  * \param [in] model The pre-trained model loaded. Loaded using <tt>\ref vxImportClassifierModel</tt>
121  * \param [in] scan_window_width Width of the scan window
122  * \param [in] scan_window_height Height of the scan window
123  * \param [in] step_x Horizontal step-size (along x-axis)
124  * \param [in] step_y Vertical step-size (along y-axis)
125  * \param [out] object_confidences [Optional] An array of confidences measure, the measure is of type <tt>\ref VX_TYPE_UINT16</tt>. The confidence measure is defined by the extensions which define classification model with defined binary format.
126  * This output can be used as class index as well. In case we detect several different classes in single execution. The output will be an array of indexes of the classes.
127  * \param [out] object_rectangles An array of object positions, in <tt>\ref VX_TYPE_RECTANGLE</tt>
128  * \param [out] num_objects [optional] The number of object detected in a <tt>\ref VX_SIZE</tt> scalar
129  * \note The border mode <tt>\ref VX_NODE_BORDER</tt> value <tt>\ref VX_BORDER_UNDEFINED</tt> is supported.
130  * \ingroup group_vision_function_classifier
131  * \return <tt>\ref vx_node</tt>.
132  * \retval vx_node A node reference. Any possible errors preventing a successful creation should be checked using <tt>\ref vxGetStatus</tt>
133  */
134 
135 VX_API_ENTRY vx_node vxScanClassifierNode(vx_graph graph,vx_tensor input_feature_map, vx_classifier_model model, vx_int32 scanwindow_width, vx_int32 scanwindow_height, vx_int32 step_x, vx_int32 step_y,
136  vx_array object_confidences, vx_array object_rectangles, vx_scalar num_objects);
137 
138 
139 #ifdef __cplusplus
140 }
141 #endif
142 
143 
144 #endif
vx_classifier_model vxImportClassifierModel(vx_context context, vx_enum format, vx_uint8 *ptr, vx_size length)
Creates an opaque reference classifier model This function creates a classifier model to be used in v...
vx_status vxReleaseClassifierModel(vx_classifier_model *model)
Releases a reference of an ClassifierModel object. The object may not be garbage collected until its ...
vx_classifier_model_format_e
Classifier model format enums. In the main specification only undefined binary format is supported...
Definition: vx_khr_class.h:80
vx_node vxScanClassifierNode(vx_graph graph, vx_tensor input_feature_map, vx_classifier_model model, vx_int32 scanwindow_width, vx_int32 scanwindow_height, vx_int32 step_x, vx_int32 step_y, vx_array object_confidences, vx_array object_rectangles, vx_scalar num_objects)
[Graph] Scans a feature-map (input_feature_map) and detect the classification for each scan-window...
Undefined binary format. Using this enumeration will result in an implementation defined behaviour...
Definition: vx_khr_class.h:85
struct _vx_classifier_model * vx_classifier_model
classification model to be used in vxScanClassifierNode. The classification models are loadable by un...
Definition: vx_khr_class.h:74