OpenCV C++ core and Python cv2 binding: Mat ownership and deallocation across the language boundary

Ownership Transfer and Deallocation Rules

When a cv::Mat is returned from a C++ extension to Python via the cv2 bindings, ownership is managed through a shared reference-counting mechanism. The C++ cv::Mat is wrapped into a NumPy array. The Python object does not copy the image data; instead, it maintains a pointer to the original C++ data buffer and increments the internal C++ reference count.

Native memory is guaranteed to be freed only when the C++ reference count reaches zero. In a standard return scenario, this occurs when the Python NumPy object is finalized by the Python Garbage Collector (GC). Because Python's GC is non-deterministic, the actual release of native memory may be deferred until a collection cycle is triggered, even if the Python variable is deleted or goes out of scope.

Deterministic Deallocation and Explicit Release

Explicit release is not required for memory safety, but it is necessary for deterministic deallocation. Because the Python wrapper holds a reference to the C++ cv::Mat, calling del on the Python object only decrements the Python-side reference count. It does not force the immediate destruction of the C++ object if other references exist (e.g., views created via NumPy slicing).

To encourage faster release in memory-constrained environments, you can:

• Use del image_var to remove the Python reference.
• Manually invoke gc.collect() to trigger the finalization of the wrapper and the subsequent decrement of the C++ refcount.

UMat and Device Buffer Lifetimes

The lifetime of cv::UMat (Universal Mat) buffers follows the same reference-counting logic as cv::Mat, but with an added layer of abstraction for OpenCL/GPU memory. The device buffer remains allocated as long as at least one cv::UMat or cv::Mat header points to it.

When the Python wrapper for a UMat is finalized, it decrements the C++ reference count. If this is the final reference, the C++ destructor is called, which signals the OpenCL runtime to release the device memory. However, if the UMat was converted to a Mat (CPU access) within the C++ core before being passed to Python, the memory may stay pinned in a state that prevents immediate device-side freeing until all CPU-side views are also destroyed.

Verification Method

To verify that a Python object is sharing memory with the C++ core rather than holding a copy, compare the data pointers:

import cv2
# Assuming 'img' is returned from your C++ extension
print(img.__array_interface__['data']) # Check the memory address in Python

If the address matches the mat.data pointer in your C++ logs, the shared ownership model is active.