python: gate bfloat16 / float8 dtypes behind setAllowNonConventionalDataTypes() and drop the ml_dtypes import

Signed-off-by: Abhishek Gola <abhishek.gola@bigvisionllc.com>
This commit is contained in:
Abhishek Gola
2026-10-14 17:36:26 +05:30
parent 3220c1b35d
commit 7feb8acd5e
7 changed files with 140 additions and 82 deletions

View File

@@ -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"},

View File

@@ -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);

View File

@@ -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);

View File

@@ -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;
}

View File

@@ -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);
//======================================================================================================================

View File

@@ -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: