El módulo DNN de OpenCV permite correr una red neuronal entrenada dentro de la misma aplicación que lee imágenes, procesa video y dibuja los resultados. El modelo se exporta a ONNX, se carga con OpenCV y sus predicciones se usan sin cargar el framework de entrenamiento en la aplicación. El proyecto publicó un tutorial completo sobre la versión 5 en su sitio, reproducido el 16 de noviembre de 2026 por la Edge AI and Vision Alliance.
OpenCV 5 amplía ese flujo con un motor de inferencia nuevo, construido para una variedad mayor de modelos ONNX actuales. El tutorial lo usa en dos tareas, detección de objetos con YOLO26 y segmentación de instancias con RF-DETR. La primera dibuja un recuadro alrededor de cada objeto detectado. La segunda agrega una máscara que indica qué píxeles pertenecen a cada instancia.
Los dos ejemplos corren en la CPU y guardan sus resultados como imágenes, y vienen en Python y en C++. Una vez exportados los modelos, la inferencia en Python solo necesita OpenCV, NumPy y la biblioteca estándar de Python. En C++ usa OpenCV y la biblioteca estándar de C++.
Versión. Los ejemplos se ejecutaron con OpenCV 5.0.0. La API de desarrollo actual de la rama5.xse revisó por separado el 20 de septiembre de 2026, y ahí el motor integrado se llamaENGINE_OPENCV, mientras que en 5.0.0 se llamaENGINE_NEW. El código maneja los dos nombres. El tutorial anterior está en OpenCV 4 DNN Module.
¿Qué hace el módulo DNN?
Un despliegue típico tiene cuatro pasos. Preparar la imagen, correr la red, interpretar sus salidas y mostrar o usar las predicciones. OpenCV aporta las funciones de procesamiento de imagen y la API de inferencia, y la aplicación pone el preprocesamiento y la decodificación de salidas que espera el modelo.
El entrenamiento sigue siendo un paso aparte. En estos ejemplos, los paquetes originales de cada modelo descargan los pesos preentrenados y exportan los archivos ONNX. Después la aplicación carga los archivos .onnx con cv2.dnn.readNetFromONNX(), sin tocar los checkpoints originales de PyTorch.
Esa separación sirve cuando la aplicación ya usa OpenCV. El mismo cuadro puede pasar por el redimensionado, la inferencia, el dibujo y la salida de video sin que el framework de entrenamiento esté presente en producción.
¿Qué cambia en OpenCV 5?
El cambio más grande es un motor de inferencia DNN reescrito, con mejor soporte para formas dinámicas, subgrafos y funciones modernas de ONNX. OpenCV 5 agrega también una integración opcional con ONNX Runtime, y sus ejemplos cubren más tipos de redes, incluidos modelos de visión y lenguaje. El detalle está en el resumen de la versión OpenCV 5.
El motor se elige al cargar el modelo. Con una compilación que expone la API de desarrollo actual de 5.x, la selección explícita queda así.
net = cv2.dnn.readNetFromONNX("model.onnx", cv2.dnn.ENGINE_OPENCV)La API actual ya no expone ENGINE_NEW ni ENGINE_CLASSIC. DNN_BACKEND_OPENCV es una constante de backend distinta y no es el argumento de motor del ejemplo. Estas definiciones están verificadas en el código fuente de la API actual, fijado al commit revisado.
El paquete 5.0.0 publicado, que se usó en las pruebas, tiene la API de selección anterior. ENGINE_NEW elige en forma explícita el motor reescrito, y ENGINE_AUTO lo intenta primero y vuelve al motor clásico si la carga falla. El detalle está en la definición de la API 5.0.0. Los ejemplos completos prefieren ENGINE_OPENCV cuando existe y, si no, usan ENGINE_NEW.
En los ejemplos de Python, DNN_ENGINE guarda el valor del motor elegido y engine_name es un texto local que se usa para el registro. Ninguna de las dos variables es un atributo de cv2.dnn.
Conviene usar las constantes por nombre, porque sus valores numéricos cambiaron entre una API y otra. Los scripts exigen que la variable de entorno OPENCV_FORCE_DNN_ENGINE no esté definida, para que un valor numérico antiguo no elija otro motor. Para la API actual de 5.x no se asume ningún retorno al motor clásico.
¿Qué tan rápido es el motor nuevo?
El proyecto OpenCV publica mediciones de inferencia en CPU contra ONNX Runtime 1.25.1, con YOLO26 Nano como modelo de prueba y las etiquetas de hardware de la fuente original. En los resultados publicados, OpenCV es más rápido en las configuraciones con Apple M1 y con AMD, y ONNX Runtime es más rápido en las otras tres. Son comparaciones entre motores de ejecución sobre esos equipos, no mediciones de cuánto mejoró OpenCV 5 frente a OpenCV 4. Las tablas completas están en los benchmarks de DNN de OpenCV 5.
El propio tutorial advierte que las tablas publicadas no detallan lo suficiente la exportación de los modelos, las formas de entrada, los modelos exactos de CPU, el uso de hilos ni el método de medición como para reproducir cada número. La recomendación es usarlas para elegir qué configuraciones probar y después medir el modelo y la aplicación propios. Los modelos del tutorial se exportaron por separado, así que sus imágenes de salida demuestran la inferencia y no reproducen esos benchmarks.
Instalar OpenCV 5
Se necesita Python 3.11 o superior, y los ejemplos se probaron con Python 3.14.3. Lo ideal es partir en un entorno virtual nuevo. Los ejemplos guardan archivos y no abren ventanas, así que basta con el paquete sin interfaz gráfica (headless).
python -m venv .venv-dnn
# macOS / Linux:
source .venv-dnn/bin/activate
# Windows PowerShell: .venv-dnn\Scripts\Activate.ps1
python -m pip install opencv-python-headless==5.0.0.93 numpy==2.3.5
python -c "import cv2; print(cv2.__version__)"La revisión de versión debería imprimir 5.0.0. Esas versiones fijas son las que se usaron para validar los ejemplos, y conviene usar una versión de Python compatible con los dos paquetes. No hay que instalar varias variantes del paquete de OpenCV en el mismo entorno, porque comparten el espacio de nombres cv2. Si la aplicación necesita ventanas de OpenCV, se usa opencv-python en vez de la variante headless. Las instrucciones están en la página del paquete de Python de OpenCV.
La exportación tiene dependencias propias. Conviene dejarlas en otro entorno, para que los paquetes de los modelos no reemplacen la instalación de OpenCV que se usa para inferir. Una vez exportados, los archivos ONNX y sus archivos de etiquetas se copian a la aplicación de inferencia.
Compilar los ejemplos en C++
La descarga de ejemplos trae las versiones en C++ de los dos ejemplos, un dnn_engine.hpp compartido y un CMakeLists.txt que los compila juntos. La exportación de los modelos sigue usando los entornos de Python que se describen más abajo. Con los archivos ONNX listos, la inferencia en C++ solo necesita OpenCV y la biblioteca estándar de C++.
Hay que instalar OpenCV 5 con sus cabeceras y bibliotecas de C++ y los módulos core, imgproc, imgcodecs y dnn. El paquete de Python por sí solo no entrega ese entorno de desarrollo en C++. El README de la descarga incluye la receta de compilación desde el código fuente que se usó para validar. También se necesitan CMake y un compilador de C++17.
Desde la carpeta extraída de la descarga, la que contiene CMakeLists.txt, se corre lo siguiente.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
-DOpenCV_DIR=/path/to/opencv5/lib/cmake/opencv5
cmake --build build --config Release --parallel 4OpenCV_DIR debe apuntar a la carpeta que contiene el OpenCVConfig.cmake de OpenCV 5. La configuración de CMake revisa qué constante de motor traen las cabeceras instaladas, prefiere ENGINE_OPENCV y acepta ENGINE_NEW en la versión 5.0.0 probada. El encabezado compartido y el archivo de CMake deben quedar junto a los ejemplos. Ningún número de motor está escrito a mano en el código.
Los comandos asumen una compilación de configuración única en macOS o Linux. Con Visual Studio en Windows, los ejecutables se corren desde build\Release y llevan el sufijo .exe, y los comandos de varias líneas se escriben en una sola en la terminal de Windows. El lector de argumentos de C++ usa el formato --opcion=valor.
Ejemplo 1. Detección de objetos con YOLO26
El tutorial usa YOLO26 Nano, exportado con una entrada fija de 640 × 640. El ejemplo aprovecha la salida de detección de extremo a extremo del modelo, donde cada predicción ya trae el recuadro, el puntaje de confianza y el identificador de clase. El código de inferencia no tiene un paso aparte de supresión de no máximos (NMS). La familia de modelos y sus tareas están en la documentación de YOLO26 de Ultralytics.
Exportar el modelo una vez
Hay que descargar el código de ejemplo y abrir la carpeta yolo26. La descarga liviana trae scripts, imágenes de muestra, etiquetas y registros de validación, y los modelos se obtienen corriendo los exportadores. Se crea un entorno de exportación aparte y se instalan las versiones fijas.
python -m venv .venv-export-yolo
.venv-export-yolo/bin/python -m pip install -r requirements-export.txt
.venv-export-yolo/bin/python export_yolo26.pyEn Windows, .venv-export-yolo/bin/python se reemplaza por .venv-export-yolo\Scripts\python.exe. Usar ese intérprete en forma directa mantiene la instalación de exportación separada del entorno de inferencia activo.
El exportador descarga el checkpoint preentrenado yolo26n.pt y la imagen de muestra bus.jpg, escribe coco80.json con los nombres de clase del modelo y genera yolo26n.onnx. Sus parámetros principales son estos.
model.export(
format="onnx", imgsz=640, batch=1, dynamic=False, half=False,
opset=17, simplify=False, end2end=True, nms=False, device="cpu",
)La receta está fijada a Ultralytics 8.4.27. En esa versión, end2end=True elige la cabeza de extremo a extremo y nms=False evita agregar un envoltorio de NMS aparte. Las opciones de exportación pueden cambiar entre versiones del paquete, así que los requisitos y el exportador entregados deben usarse juntos. El grafo probado recibe [1, 3, 640, 640] y devuelve [1, 300, 6], donde cada fila es [x1, y1, x2, y2, confidence, class_id]. Las coordenadas son píxeles de la imagen de entrada de 640 × 640. Estos detalles se revisaron contra el grafo exportado y contra la cabeza de detección de Ultralytics en esa versión.
Preparar la imagen y correr la inferencia
YOLO espera píxeles RGB escalados entre 0 y 1. La imagen se redimensiona manteniendo su proporción y el área sobrante se rellena con el valor 114, una técnica que se llama letterboxing. Para dibujar las predicciones sobre la imagen original, se resta el relleno y se divide por la escala del redimensionado.
El código reparte el relleno sobrante entre los bordes opuestos. Si el relleno es un número impar de píxeles, un borde recibe el píxel extra y la entrada queda en 640 × 640 exactos.
El script se guarda como tutorial_yolo26.py, o se usa el archivo de la descarga, y se corre desde la carpeta yolo26 con el entorno de inferencia de OpenCV.
python tutorial_yolo26.py"""Article example: run after export_yolo26.py, from this directory."""
import json
import os
# Check before importing OpenCV: this variable overrides the named engine.
if "OPENCV_FORCE_DNN_ENGINE" in os.environ:
raise RuntimeError("Unset OPENCV_FORCE_DNN_ENGINE before running this script.")
import cv2
import numpy as np
# Current 5.x calls this ENGINE_OPENCV; the tested 5.0.0 wheel uses ENGINE_NEW.
if hasattr(cv2.dnn, "ENGINE_OPENCV"):
DNN_ENGINE = cv2.dnn.ENGINE_OPENCV
elif hasattr(cv2.dnn, "ENGINE_NEW"):
DNN_ENGINE = cv2.dnn.ENGINE_NEW
else:
raise RuntimeError("This example requires OpenCV 5's built-in DNN engine.")
image = cv2.imread("bus.jpg")
if image is None:
raise FileNotFoundError("Run export_yolo26.py to download bus.jpg first.")
with open("coco80.json") as stream:
classes = json.load(stream)El resto del script, con la decodificación de las salidas y el segundo ejemplo de segmentación con RF-DETR, viene completo en la descarga del tutorial.






