Configurar OpenCV en Raspberry Pi 4

OpenCV se puede compilar desde el código fuente en una Raspberry Pi y, después, comprobar mediante la importación de cv2 con Python 3. Esta guía presupone una Raspberry Pi con Raspberry Pi OS y una sesión de terminal con conexión a Internet. La compilación puede tardar bastante y requiere mucho espacio libre; el tiempo y el paralelismo viable dependen de la placa, la memoria y los módulos de OpenCV seleccionados.

Elegir una Raspberry Pi y un sistema operativo

El procedimiento de compilación desde el código fuente está pensado para una Raspberry Pi 4 Model B, aunque otros modelos de Raspberry Pi también podrían compilar OpenCV si usan sistemas operativos compatibles. Los comandos siguientes están orientados a Raspberry Pi OS. Es una suposición explícita de esta guía, no una afirmación de que se haya probado una versión concreta del sistema operativo o una configuración específica de la placa. Una placa antigua o con menos memoria puede tardar más en compilar, y el espacio disponible en disco puede limitar la compilación.

Preparar Raspberry Pi OS

Abre una terminal en la Pi y actualiza el índice de paquetes y los paquetes instalados ejecutando sudo apt update y luego sudo apt upgrade. Instala el compilador y las herramientas necesarias, incluidos build-essential, cmake, git, pkg-config, python3-dev y python3-numpy, con sudo apt install build-essential cmake git pkg-config python3-dev python3-numpy. Los nombres y la disponibilidad de los paquetes pueden variar según la versión de Raspberry Pi OS; resuelve cualquier error del gestor de paquetes correspondiente a la versión instalada antes de continuar. Deja suficiente espacio libre para los árboles de código fuente y los archivos generados durante la compilación.

El paquete python3-dev proporciona los encabezados de desarrollo de Python necesarios para configurar un enlace de Python. Usa la misma instalación y el mismo entorno de Python 3 para compilar y verificar OpenCV. Si utilizas un entorno virtual, planifica cómo hará la compilación para localizar el intérprete y NumPy de ese entorno; no des por hecho que el Python del sistema y el entorno virtual son intercambiables.

Compilar e instalar OpenCV desde el código fuente

Elige una versión de OpenCV compatible con el sistema operativo y el entorno de Python instalados. Si necesitas módulos adicionales, elige la versión correspondiente de opencv-contrib; sus módulos están en un repositorio separado del repositorio principal de OpenCV. Ambos árboles de código fuente deben usar versiones coincidentes. Consulta la guía relacionada sobre opencv-contrib para obtener información sobre esos módulos adicionales.

Los pasos siguientes son comandos para una terminal con Raspberry Pi OS, no un programa independiente. Sustituye VERSION en cada comando por la misma etiqueta de versión de OpenCV. Clona los árboles de código fuente correspondientes en el directorio personal con git clone --branch VERSION --depth 1 https://github.com/opencv/opencv.git ~/opencv-VERSION y, si necesitas módulos adicionales, con git clone --branch VERSION --depth 1 https://github.com/opencv/opencv_contrib.git ~/opencv_contrib-VERSION. Crea un directorio de compilación con mkdir -p ~/opencv-VERSION/build y entra en él con cd ~/opencv-VERSION/build.

Desde ese directorio, configura la compilación con cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local -D OPENCV_EXTRA_MODULES_PATH="$HOME/opencv_contrib-VERSION/modules" ... Usa en esa opción el directorio contrib de la misma versión; omite la opción si no vas a compilar los módulos contrib. Estas son opciones de configuración; las disponibles dependen de la versión elegida y de las dependencias del sistema.

Compila desde el directorio configurado con make -j2 y luego instala con sudo make install. Si la Pi se queda sin memoria, elige un número menor de trabajos; con menos tareas en paralelo, la compilación suele tardar más. Los comandos de compilación e instalación dependen del código fuente descargado, de un conjunto de herramientas de compilación funcional y de dependencias compatibles, por lo que aquí no se presentan como un ejemplo de ejecución aislado.

Verificar OpenCV en Python

Ejecuta la comprobación con el entorno de Python 3 utilizado para la compilación. Importa el enlace y muestra la versión indicada por el módulo instalado. La ejecución suministrada terminó con el código de salida 0, pero informó que cv2 no estaba disponible en ese entorno de ejecución; por tanto, no demostró que OpenCV se pudiera importar correctamente. La versión depende de la instalación.

import importlib.util

if importlib.util.find_spec("cv2") is None:
    print("cv2 is not available in this Python environment.")
else:
    import cv2
    print(cv2.__version__)

Una importación correcta confirma que este intérprete encuentra el módulo cv2. Si Python indica que no encuentra el módulo, comprueba que la compilación instaló el enlace de Python y que el comando usa el intérprete previsto. Una cadena de versión, por sí sola, no confirma que todos los módulos opcionales o dispositivos de cámara estén disponibles.

Solucionar fallos habituales de instalación

Si la compilación se detiene porque la Pi tiene poca memoria disponible, vuelve a ejecutarla con menos trabajos; por ejemplo, usa make -j1 desde el directorio de compilación. Esto puede reducir el uso simultáneo de recursos, pero aumenta el tiempo de compilación y no garantiza que se resuelvan todos los fallos. Busca en el registro el primer error de compilación o de CMake, confirma que CMake apunta al directorio de módulos de opencv_contrib correspondiente y comprueba que ambos árboles de código fuente usan la misma etiqueta de versión.

Si import cv2 falla después de la instalación, verifica que python3 sea el intérprete configurado para la compilación y comprueba si la instalación colocó el enlace en un directorio que ese intérprete busca. Instalar NumPy en otro entorno de Python no lo hace disponible para el intérprete utilizado durante la compilación.

Conclusión

Una compilación desde el código fuente en Raspberry Pi OS usa CMake para configurar OpenCV, lo compila con un número de trabajos adecuado para el dispositivo e instala las bibliotecas resultantes. Importar cv2 en el entorno de Python 3 correspondiente es la comprobación práctica de que el enlace está disponible. Elige versiones compatibles y coincidentes de OpenCV y opencv-contrib para el sistema instalado; esta guía no establece una matriz de compatibilidad probada ni garantiza que la compilación funcione en todas las configuraciones de Raspberry Pi.