diff --git a/modules/python/src2/cv2.cpp b/modules/python/src2/cv2.cpp index b78004c915..a79bc23c68 100644 --- a/modules/python/src2/cv2.cpp +++ b/modules/python/src2/cv2.cpp @@ -118,9 +118,28 @@ static PyObject* pycvRegisterMatType(PyObject *self, PyObject *value) Py_RETURN_NONE; } +static PyObject* pycvSetAllowNonConventionalDataTypes(PyObject*, PyObject* value) +{ + int allow = PyObject_IsTrue(value); + if (allow < 0) + return NULL; + setAllowNonConventionalDataTypes(allow != 0); + Py_RETURN_NONE; +} + +static PyObject* pycvGetAllowNonConventionalDataTypes(PyObject*, PyObject*) +{ + return PyBool_FromLong(getAllowNonConventionalDataTypes()); +} + static PyMethodDef special_methods[] = { {"_registerMatType", (PyCFunction)(pycvRegisterMatType), METH_O, "_registerMatType(cv.Mat) -> None (Internal)"}, {"redirectError", CV_PY_FN_WITH_KW(pycvRedirectError), "redirectError(onError) -> None"}, + {"setAllowNonConventionalDataTypes", (PyCFunction)(pycvSetAllowNonConventionalDataTypes), METH_O, + "setAllowNonConventionalDataTypes(allow) -> None\n. Keep bfloat16 / float8 arrays at their exact dtype " + "(registered by the ml_dtypes package, which must be imported) instead of widening them to float32. Off by default."}, + {"getAllowNonConventionalDataTypes", (PyCFunction)(pycvGetAllowNonConventionalDataTypes), METH_NOARGS, + "getAllowNonConventionalDataTypes() -> retval"}, #ifdef HAVE_OPENCV_HIGHGUI {"createTrackbar", (PyCFunction)pycvCreateTrackbar, METH_VARARGS, "createTrackbar(trackbarName, windowName, value, count, onChange) -> None"}, {"createButton", CV_PY_FN_WITH_KW(pycvCreateButton), "createButton(buttonName, onChange [, userData, buttonType, initialButtonState]) -> None"}, diff --git a/modules/python/src2/cv2_convert.cpp b/modules/python/src2/cv2_convert.cpp index dbd238234a..3946d18a53 100644 --- a/modules/python/src2/cv2_convert.cpp +++ b/modules/python/src2/cv2_convert.cpp @@ -152,7 +152,7 @@ bool pyopencv_to(PyObject* o, Mat& m, const ArgInfo& info) int typenum = PyArray_TYPE(oarr), new_typenum = typenum; int type = numpyTypeToCvDepth(typenum); if( type < 0 ) - type = mlDtypeToCvDepth(typenum); // bfloat16 / float8, when ml_dtypes is installed + type = nonConventionalTypeToCvDepth(typenum); // bfloat16 / float8, when allowed if( type < 0 ) { @@ -335,7 +335,7 @@ bool pyopencv_to(PyObject* o, Mat& m, const ArgInfo& info) } // Hands a bfloat16 / float8 Mat back with its exact dtype; `descr` is the caller's to check. -static PyObject* pyopencv_from_mldtype(const cv::Mat& m, PyArray_Descr* descr) +static PyObject* pyopencv_from_nonconventional(const cv::Mat& m, PyArray_Descr* descr) { cv::Mat cont; if( m.isContinuous() ) @@ -364,14 +364,15 @@ static PyObject* pyopencv_from_mldtype(const cv::Mat& m, PyArray_Descr* descr) template<> PyObject* pyopencv_from(const cv::Mat& m) { - if( m.depth() == CV_16BF || m.depth() == CV_8F_E4M3FN || m.depth() == CV_8F_E4M3FNUZ ) + if( isNonConventionalDepth(m.depth()) ) { - if( PyArray_Descr* descr = mlDtypeDescrForCvDepth(m.depth()) ) - return pyopencv_from_mldtype(m, descr); - // Without ml_dtypes NumPy cannot name these; widen to float32 (lossless). - CV_LOG_ONCE_WARNING(NULL, "Python bindings: ml_dtypes package is not found, " - "bfloat16 / float8 arrays are returned as float32. " - "Install ml_dtypes to keep the exact dtype."); + if( PyArray_Descr* descr = nonConventionalDescrForCvDepth(m.depth()) ) + return pyopencv_from_nonconventional(m, descr); + if( getAllowNonConventionalDataTypes() ) + CV_LOG_ONCE_WARNING(NULL, "Python bindings: non-conventional data types are allowed, " + "but NumPy does not know bfloat16 / float8 and they are returned as float32. " + "Import ml_dtypes to keep the exact dtype."); + // NumPy alone cannot name these; widen to float32 (lossless). cv::Mat m32f; ERRWRAP2(m.convertTo(m32f, CV_32F)); return pyopencv_from(m32f); diff --git a/modules/python/src2/cv2_numpy.cpp b/modules/python/src2/cv2_numpy.cpp index fafad8c136..a1066a74fb 100644 --- a/modules/python/src2/cv2_numpy.cpp +++ b/modules/python/src2/cv2_numpy.cpp @@ -41,9 +41,9 @@ UMatData* NumpyAllocator::allocate(int dims0, const int* sizes, int type, void* if( cn > 1 ) _sizes[dims++] = cn; - // bfloat16 / float8 need their ml_dtypes descriptor: cvDepthToNumpyType()'s float32 + // bfloat16 / float8 need their exact NumPy descriptor: cvDepthToNumpyType()'s float32 // fallback would pair a narrow element step with wide NumPy strides and corrupt the buffer. - PyArray_Descr* exotic = mlDtypeDescrForCvDepth(depth); + PyArray_Descr* exotic = nonConventionalDescrForCvDepth(depth); if( exotic ) { Py_INCREF(exotic); // PyArray_NewFromDescr steals the reference @@ -53,10 +53,10 @@ UMatData* NumpyAllocator::allocate(int dims0, const int* sizes, int type, void* CV_Error_(Error::StsError, ("The numpy array of depth=%d, ndims=%d can not be created", depth, dims)); return allocate(eo, dims0, sizes, type, step); } - if( depth == CV_16BF || depth == CV_8F_E4M3FN || depth == CV_8F_E4M3FNUZ ) + if( isNonConventionalDepth(depth) ) CV_Error(Error::StsNotImplemented, "bfloat16 / float8 arrays cannot be allocated through the NumPy allocator: " - "NumPy has no such dtype and the ml_dtypes package is not installed"); + "call cv.setAllowNonConventionalDataTypes(True) and import ml_dtypes first"); int typenum = cvDepthToNumpyType(depth); PyObject* o = PyArray_SimpleNew(dims, _sizes.data(), typenum); diff --git a/modules/python/src2/cv2_util.cpp b/modules/python/src2/cv2_util.cpp index 9bdfffd377..ae5722ae5e 100644 --- a/modules/python/src2/cv2_util.cpp +++ b/modules/python/src2/cv2_util.cpp @@ -24,7 +24,8 @@ int cvDepthToNumpyType(int depth) case CV_32F: return NPY_FLOAT; case CV_64F: return NPY_DOUBLE; case CV_16F: return NPY_HALF; - // NumPy alone has no bfloat16; pyopencv_from() uses ml_dtypes when importable, else float32. + // NumPy alone has no bfloat16; pyopencv_from() widens it to float32 unless the + // non-conventional data types are allowed (see setAllowNonConventionalDataTypes()). case CV_16BF: return NPY_FLOAT; case CV_Bool: return NPY_BOOL; default: @@ -35,87 +36,98 @@ int cvDepthToNumpyType(int depth) namespace { -// ml_dtypes registers bfloat16 and the OCP float8 formats as NumPy dtypes. When importable, -// Mats of OpenCV's matching types keep their exact dtype instead of widening to float32. -struct MlDtypeRegistry +// The NumPy dtypes that match OpenCV's bfloat16 / float8 depths. NumPy itself does not define +// them; ml_dtypes registers them under these names when the user imports it. OpenCV never +// imports ml_dtypes: the type numbers are assigned at registration time, so the descriptors +// are looked up by name and only once the user has asked for them. +struct NonConventionalDtype { - PyArray_Descr* bf16 = nullptr; - PyArray_Descr* e4m3fn = nullptr; - PyArray_Descr* e4m3fnuz = nullptr; - - MlDtypeRegistry() - { - PyObject* mod = PyImport_ImportModule("ml_dtypes"); - if (!mod) - { - PyErr_Clear(); - return; - } - bf16 = fetch(mod, "bfloat16"); - e4m3fn = fetch(mod, "float8_e4m3fn"); - e4m3fnuz = fetch(mod, "float8_e4m3fnuz"); - Py_DECREF(mod); - } - - // The descriptors are kept for the life of the process, so they are never released. - static PyArray_Descr* fetch(PyObject* mod, const char* name) - { - PyObject* scalarType = PyObject_GetAttrString(mod, name); - if (!scalarType) - { - PyErr_Clear(); - return nullptr; - } - PyArray_Descr* descr = nullptr; - if (!PyArray_DescrConverter(scalarType, &descr)) - { - PyErr_Clear(); - descr = nullptr; - } - Py_DECREF(scalarType); - return descr; - } + int depth; + const char* name; + int itemsize; }; -// Guarded by the GIL rather than a function-local static: the import inside the constructor -// can release the GIL, and a thread blocked on a static-init lock while holding it deadlocks. -const MlDtypeRegistry* g_mlDtypes = nullptr; +const NonConventionalDtype kNonConventionalDtypes[] = { + { CV_16BF, "bfloat16", 2 }, + { CV_8F_E4M3FN, "float8_e4m3fn", 1 }, + { CV_8F_E4M3FNUZ, "float8_e4m3fnuz", 1 }, +}; +const int kNumNonConventionalDtypes = sizeof(kNonConventionalDtypes) / sizeof(kNonConventionalDtypes[0]); -const MlDtypeRegistry& mlDtypes() +bool g_allowNonConventionalDataTypes = false; + +// Resolved descriptors, kept for the life of the process. Only successful lookups are cached, +// so importing ml_dtypes after the first conversion still works. Accessed under the GIL. +PyArray_Descr* g_nonConventionalDescrs[kNumNonConventionalDtypes] = {}; + +PyArray_Descr* nonConventionalDescr(int idx) { - if (!g_mlDtypes) + if (!g_nonConventionalDescrs[idx]) { - const MlDtypeRegistry* r = new MlDtypeRegistry(); - if (!g_mlDtypes) // another thread may have finished first while the import ran - g_mlDtypes = r; + const NonConventionalDtype& t = kNonConventionalDtypes[idx]; + PyObject* name = PyUnicode_FromString(t.name); + PyArray_Descr* descr = nullptr; + if (!name || !PyArray_DescrConverter(name, &descr)) + descr = nullptr; + Py_XDECREF(name); + PyErr_Clear(); + // Another package could register a dtype under the same name; check the layout too. + // itemsize is read through Python because the descriptor struct differs in NumPy 1.x / 2.x. + long itemsize = -1; + if (descr) + { + PyObject* size = PyObject_GetAttrString((PyObject*)descr, "itemsize"); + itemsize = size ? PyLong_AsLong(size) : -1; + Py_XDECREF(size); + PyErr_Clear(); + } + if (descr && (descr->type_num < NPY_USERDEF || itemsize != t.itemsize)) + { + Py_DECREF(descr); + descr = nullptr; + } + g_nonConventionalDescrs[idx] = descr; } - return *g_mlDtypes; + return g_nonConventionalDescrs[idx]; } } // namespace -PyArray_Descr* mlDtypeDescrForCvDepth(int depth) +void setAllowNonConventionalDataTypes(bool allow) { - if (depth != CV_16BF && depth != CV_8F_E4M3FN && depth != CV_8F_E4M3FNUZ) - return nullptr; - const MlDtypeRegistry& r = mlDtypes(); - switch (depth) - { - case CV_16BF: return r.bf16; - case CV_8F_E4M3FN: return r.e4m3fn; - case CV_8F_E4M3FNUZ: return r.e4m3fnuz; - default: return nullptr; - } + g_allowNonConventionalDataTypes = allow; } -int mlDtypeToCvDepth(int typenum) +bool getAllowNonConventionalDataTypes() { - if (typenum < NPY_USERDEF) // ml_dtypes types are user-defined NumPy dtypes + return g_allowNonConventionalDataTypes; +} + +bool isNonConventionalDepth(int depth) +{ + return depth == CV_16BF || depth == CV_8F_E4M3FN || depth == CV_8F_E4M3FNUZ; +} + +PyArray_Descr* nonConventionalDescrForCvDepth(int depth) +{ + if (!g_allowNonConventionalDataTypes) + return nullptr; + for (int i = 0; i < kNumNonConventionalDtypes; i++) + if (kNonConventionalDtypes[i].depth == depth) + return nonConventionalDescr(i); + return nullptr; +} + +int nonConventionalTypeToCvDepth(int typenum) +{ + if (!g_allowNonConventionalDataTypes || typenum < NPY_USERDEF) return -1; - const MlDtypeRegistry& r = mlDtypes(); - if (r.bf16 && typenum == r.bf16->type_num) return CV_16BF; - if (r.e4m3fn && typenum == r.e4m3fn->type_num) return CV_8F_E4M3FN; - if (r.e4m3fnuz && typenum == r.e4m3fnuz->type_num) return CV_8F_E4M3FNUZ; + for (int i = 0; i < kNumNonConventionalDtypes; i++) + { + PyArray_Descr* descr = nonConventionalDescr(i); + if (descr && descr->type_num == typenum) + return kNonConventionalDtypes[i].depth; + } return -1; } diff --git a/modules/python/src2/cv2_util.hpp b/modules/python/src2/cv2_util.hpp index 7a98694e01..f0172f5167 100644 --- a/modules/python/src2/cv2_util.hpp +++ b/modules/python/src2/cv2_util.hpp @@ -16,9 +16,16 @@ PyObject* failmsgp(const char *fmt, ...); int cvDepthToNumpyType(int depth); int numpyTypeToCvDepth(int typenum); -// nullptr / -1 when ml_dtypes is not importable or the type has no OpenCV counterpart. -PyArray_Descr* mlDtypeDescrForCvDepth(int depth); -int mlDtypeToCvDepth(int typenum); + +// bfloat16 / float8 cross the binding with their exact NumPy dtype (registered by ml_dtypes) +// only when the user allows it; otherwise they are widened to float32 as before. Off by default. +void setAllowNonConventionalDataTypes(bool allow); +bool getAllowNonConventionalDataTypes(); +bool isNonConventionalDepth(int depth); +// nullptr / -1 when not allowed, when NumPy does not know the dtype (ml_dtypes not imported) +// or when the type has no OpenCV counterpart. +PyArray_Descr* nonConventionalDescrForCvDepth(int depth); +int nonConventionalTypeToCvDepth(int typenum); //====================================================================================================================== diff --git a/modules/python/src2/typing_stubs_generation/api_refinement.py b/modules/python/src2/typing_stubs_generation/api_refinement.py index b508276629..1edac68b55 100644 --- a/modules/python/src2/typing_stubs_generation/api_refinement.py +++ b/modules/python/src2/typing_stubs_generation/api_refinement.py @@ -58,6 +58,12 @@ def apply_manual_api_refinement(root: NamespaceNode) -> None: ) ]) + root.add_function("setAllowNonConventionalDataTypes", [ + FunctionNode.Arg("allow", PrimitiveTypeNode.bool_()) + ]) + root.add_function("getAllowNonConventionalDataTypes", + return_type=FunctionNode.RetType(PrimitiveTypeNode.bool_())) + def make_optional_none_return(root_node: NamespaceNode, function_symbol_name: SymbolName) -> None: diff --git a/modules/python/test/test_ml_dtypes.py b/modules/python/test/test_ml_dtypes.py index 44b08bc1b4..912defee0b 100644 --- a/modules/python/test/test_ml_dtypes.py +++ b/modules/python/test/test_ml_dtypes.py @@ -15,8 +15,13 @@ class ml_dtypes_test(NewOpenCVTests): def setUp(self): super(ml_dtypes_test, self).setUp() + self.addCleanup(cv.setAllowNonConventionalDataTypes, cv.getAllowNonConventionalDataTypes()) + cv.setAllowNonConventionalDataTypes(False) + if self._testMethodName == "test_disallowed_widens_to_float32": + return if ml_dtypes is None: self.skipTest("ml_dtypes is not installed") + cv.setAllowNonConventionalDataTypes(True) # (numpy dtype, OpenCV depth, typeToString prefix, relative half-ULP) self.cases = [ (ml_dtypes.bfloat16, cv.CV_16BF, "CV_16BF", 2.0 ** -8), @@ -24,6 +29,14 @@ class ml_dtypes_test(NewOpenCVTests): (ml_dtypes.float8_e4m3fnuz, cv.CV_8F_E4M3FNUZ, "CV_8FNUZ", 2.0 ** -4), ] + def test_disallowed_widens_to_float32(self): + for depth in (cv.CV_16BF, cv.CV_8F_E4M3FN, cv.CV_8F_E4M3FNUZ): + for m in cv.utils.generateVectorOfMat(1, 3, 4, depth): + self.assertEqual(m.dtype, np.float32) + if ml_dtypes is not None: + with self.assertRaises((cv.error, TypeError)): + cv.flip(np.zeros((2, 3), dtype=ml_dtypes.bfloat16), 1) + def assertSameBits(self, actual, expected): self.assertEqual(actual.dtype, expected.dtype) self.assertEqual(actual.shape, expected.shape)