image — visión artificial#

El módulo image es el núcleo de la pila de visión artificial de OpenMV. Expone la clase Image – el búfer de píxeles en memoria sobre el que operan todas las rutinas de dibujo, filtrado, transformación y extracción de características – junto con los objetos de resultado de apoyo devueltos por esas rutinas (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) y las clases auxiliares usadas para configurarlas (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Adquisición de una imagen#

Hay cuatro formas de obtener una Image en la RAM:

  • Captura en vivo desde el sensor de la cámara. Llama a csi.CSI.snapshot() para capturar el siguiente fotograma directamente en el búfer de fotogramas (frame buffer); la Image devuelta hace referencia a ese búfer.

  • Desde un archivo. Pasa una ruta al constructor de Image (image.Image("/sd/photo.jpg")); los formatos en disco admitidos son BMP, PPM/PGM, JPEG, PNG y el formato de grabación ImageIO de OpenMV.

  • Desde un ndarray. Pasa un ndarray float32 (h, w) o (h, w, 3) al constructor de Image. Los píxeles se escalan de 0.0 -- 255.0 a una imagen GRAYSCALE o RGB565 respectivamente. Úsalo para llevar la salida tensorial de ml (o de cualquier canalización de ulab) de vuelta a una imagen dibujable.

  • Búfer vacío. Construye una Image con un tamaño y formato de píxel dados (image.Image(320, 240, image.RGB565)) para dibujar en ella desde cero, o para usarla como superficie de trabajo en operaciones aritméticas sobre imágenes.

Formatos de píxel#

Cada Image tiene uno de los siguientes formatos de píxel; la elección establece un compromiso entre memoria, coste de procesamiento y qué algoritmos pueden ejecutarse sobre ella. Usa BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG o PNG como argumento pixformat al construir una imagen o al configurar el sensor de la cámara:

  • BINARY (1 bpp) – un bit por píxel. El formato más pequeño; usado internamente por las rutinas de umbralización y morfología, pero rara vez capturado directamente desde el sensor.

  • GRAYSCALE (8 bpp) – un byte por píxel (el canal Y de YUV422). El formato más rápido para la mayoría de los algoritmos de visión por computadora (AprilTag, detección de bordes, flujo óptico).

  • RGB565 (16 bpp) – dos bytes por píxel, 5 bits de rojo / 6 bits de verde / 5 bits de azul. El formato de color por defecto.

  • BAYER (8 bpp) – datos de color con patrón Bayer en bruto directamente del sensor. Útil para un demosaico personalizado o para almacenar más píxeles en menos memoria antes de aplicar el debayer bajo demanda.

  • YUV422 (16 bpp) – color con submuestreo de croma 4:2:2, dos bytes por píxel. Útil cuando quieres algoritmos específicos de croma sin pagar el coste completo de RGB.

  • JPEG / PNG – búferes comprimidos. Los mejores para almacenamiento y transmisión por red. Las operaciones a nivel de píxel requieren primero Image.to_grayscale() o Image.to_rgb565().

Trabajar con resultados#

Los métodos de detección / extracción de características de Image devuelven objetos que puedes recorrer y combinar – una llamada a Image.find_blobs() devuelve una lista de Blob, una llamada a Image.find_apriltags() devuelve una lista de AprilTag, etc. Cada clase de resultado expone las propiedades geométricas de la detección (centroide, cuadro delimitador, área, valor de código, etc.) para que puedas actuar sobre ellas directamente o pasarlas de vuelta a los métodos de dibujo (Image.draw_rectangle(), Image.draw_string(), …).

Auxiliares de espacio de color#

El módulo también expone pequeñas funciones puras para convertir valores individuales de píxel entre los espacios de color binario / escala de grises / RGB / LAB / YUV. Son útiles cuando necesitas convertir valores de umbral o entradas de paleta en Python antes de pasarlos a operaciones sobre imágenes – para la conversión de imagen completa usa los métodos to_* de Image, que son mucho más rápidos que llamar a estos auxiliares en un bucle.

Clases#

Funciones#

Auxiliares de conversión de espacio de color#

Cada una de las funciones X_to_Y siguientes realiza una única conversión de valor de píxel. Todas toman/devuelven valores en los rangos canónicos de OpenMV:

  • binario – int 0 – 1.

  • escala de grises – int 0 – 255.

  • RGB – tupla (r, g, b) de enteros de 8 bits (cada uno 0 – 255).

  • LAB – tupla (l, a, b) con L en 0 – 100 y A/B en -128 – 127.

  • YUV – tupla (y, u, v) con Y en 0 – 255 y U/V en -128 – 127.

Para la conversión de imagen completa usa los métodos to_* de Image, que son mucho más rápidos que llamar a estos auxiliares en un bucle.

image.binary_to_grayscale(value: int) → int#

Convierte un valor binario en un valor de escala de grises.

image.binary_to_rgb(value: int) → Tuple[int, int, int]#

Convierte un valor binario en una tupla RGB.

image.binary_to_lab(value: int) → Tuple[int, int, int]#

Convierte un valor binario en una tupla LAB.

image.binary_to_yuv(value: int) → Tuple[int, int, int]#

Convierte un valor binario en una tupla YUV.

image.grayscale_to_binary(value: int) → int#

Convierte un valor de escala de grises en un valor binario.

image.grayscale_to_rgb(value: int) → Tuple[int, int, int]#

Convierte un valor de escala de grises en una tupla RGB.

image.grayscale_to_lab(value: int) → Tuple[int, int, int]#

Convierte un valor de escala de grises en una tupla LAB.

image.grayscale_to_yuv(value: int) → Tuple[int, int, int]#

Convierte un valor de escala de grises en una tupla YUV.

image.rgb_to_binary(value: Tuple[int, int, int]) → int#

Convierte una tupla RGB en un valor binario.

image.rgb_to_grayscale(value: Tuple[int, int, int]) → int#

Convierte una tupla RGB en un valor de escala de grises.

image.rgb_to_lab(value: Tuple[int, int, int]) → Tuple[int, int, int]#

Convierte una tupla RGB en una tupla LAB.

image.rgb_to_yuv(value: Tuple[int, int, int]) → Tuple[int, int, int]#

Convierte una tupla RGB en una tupla YUV.

image.lab_to_binary(value: Tuple[int, int, int]) → int#

Convierte una tupla LAB en un valor binario.

image.lab_to_grayscale(value: Tuple[int, int, int]) → int#

Convierte una tupla LAB en un valor de escala de grises.

image.lab_to_rgb(value: Tuple[int, int, int]) → Tuple[int, int, int]#

Convierte una tupla LAB en una tupla RGB.

image.lab_to_yuv(value: Tuple[int, int, int]) → Tuple[int, int, int]#

Convierte una tupla LAB en una tupla YUV.

image.yuv_to_binary(value: Tuple[int, int, int]) → int#

Convierte una tupla YUV en un valor binario.

image.yuv_to_grayscale(value: Tuple[int, int, int]) → int#

Convierte una tupla YUV en un valor de escala de grises.

image.yuv_to_rgb(value: Tuple[int, int, int]) → Tuple[int, int, int]#

Convierte una tupla YUV en una tupla RGB.

image.yuv_to_lab(value: Tuple[int, int, int]) → Tuple[int, int, int]#

Convierte una tupla YUV en una tupla LAB.

Descriptores de características#

image.HaarCascade(path: str, stages: int = -1) → Cascade#

Carga un Haar Cascade y devuelve un manejador Cascade para usar con Image.find_features().

path puede ser cualquiera de los siguientes:

  • la cadena literal "frontalface" o "eye" para cargar uno de los dos cascades integrados en la ROM del firmware, o

  • una ruta del sistema de archivos a un archivo binario .cascade personalizado producido por las herramientas de conversión de cascade de OpenMV.

stages selecciona cuántas etapas del cascade se evalúan en el momento de la detección. -1 usa todas las etapas almacenadas en el archivo. Reducir este valor acelera la detección a costa de más falsos positivos.

image.load_descriptor(path: str) → kp_desc | lbp_desc#

Carga un descriptor desde el archivo en path y lo devuelve. La etiqueta de tipo interna del archivo selecciona qué clase de descriptor se reconstruye:

image.save_descriptor(descriptor: kp_desc | lbp_desc, path: str) → None#

Serializa descriptor (un descriptor de puntos clave ORB o un descriptor LBP) al archivo en path en el formato de archivo de descriptor de OpenMV. El mismo archivo puede recargarse posteriormente mediante image.load_descriptor().

image.match_descriptor(descriptor0, descriptor1, threshold: int = 85, filter_outliers: bool = False) → int | kptmatch#

Compara dos descriptores del mismo tipo.

  • Para dos descriptores LBP – devuelve una distancia de Hamming entera entre ellos (cuanto menor, mejor coincidencia).

  • Para dos descriptores de puntos clave ORB – devuelve un kptmatch que describe el grupo de puntos clave coincidentes, o None si ninguna coincidencia supera threshold.

threshold (0 – 100) establece la estrictez de la comparación ORB al aceptar un par de puntos clave. Valores más bajos endurecen la comparación rechazando las coincidencias débiles del vecino más cercano.

filter_outliers habilita el rechazo de valores atípicos al estilo RANSAC en el conjunto de puntos clave coincidentes. Úsalo cuando esperes una única transformación rígida entre las dos vistas; desactívalo cuando los puntos clave coincidentes abarquen varios objetos.

Auxiliares de geometría de manchas (blobs)#

Estos auxiliares toman una Blob (tal como la devuelve Image.find_blobs()) y calculan propiedades geométricas adicionales bajo demanda. Residen en el ámbito del módulo – no en Blob – de modo que la ruta básica de find_blobs() no paga por ellas a menos que las solicites.

image.get_solidity(blob: blob) → float#

Devuelve la solidez (blob.pixels / convex_hull_area) de blob. Float, 0 – 1; 1.0 significa que la mancha (blob) llena completamente su envolvente convexa.

image.get_convexity(blob: blob) → float#

Devuelve la convexidad (convex_hull_perimeter / blob.perimeter) de blob. Float, 0 – 1; 1.0 es una mancha (blob) perfectamente convexa.

image.get_major_axis_line(blob: blob) → line#

Devuelve una Line a lo largo del eje mayor de blob (el más largo de los dos ejes principales del rectángulo rotado de área mínima).

image.get_minor_axis_line(blob: blob) → line#

Devuelve una Line a lo largo del eje menor de blob (el más corto de los dos ejes principales del rectángulo rotado de área mínima).

image.get_enclosing_circle(blob: blob) → circle#

Devuelve un Circle que encierra blob.

image.get_enclosed_ellipse(blob: blob) → Tuple[int, int, int, int, int]#

Devuelve una tupla de 5 elementos (cx, cy, a, b, rotation) que describe la elipse inscrita en el rectángulo rotado de área mínima alrededor de blob:

  • cx / cy – centro de la elipse en píxeles (entero).

  • a / b – longitudes de los semiejes en píxeles (entero).

  • rotation – rotación de la elipse en grados (entero).

Esta es una tupla simple, no una attrtuple, por lo que los campos solo son accesibles por índice.

Constantes#

Formatos de píxel#

Pasa cualquiera de los siguientes como argumento pixformat al constructor de Image o a csi.CSI.pixformat().

image.BINARY: int#

Mapa de bits de 1 bit por píxel. El formato más pequeño – usado internamente por la umbralización y la morfología, rara vez capturado directamente desde un sensor.

image.GRAYSCALE: int#

Escala de grises de 8 bits por píxel (un byte por píxel). El formato más rápido para la mayoría de los algoritmos de visión por computadora (AprilTag, detección de bordes, flujo óptico).

image.RGB565: int#

Color de 16 bits por píxel empaquetado como 5 bits de rojo / 6 bits de verde / 5 bits de azul. El formato de color por defecto.

image.BAYER: int#

Datos Bayer en bruto de 8 bits por píxel directamente del sensor. La mayoría de los métodos de procesamiento de imágenes no están disponibles para imágenes Bayer; úsalo cuando quieras aplicar el debayer bajo demanda o almacenar más píxeles en menos memoria.

image.YUV422: int#

Color con submuestreo de croma 4:2:2, dos bytes por píxel, empaquetado como Y1, U, Y2, V por cada par de píxeles. Solo algunos métodos de procesamiento de imágenes funcionan directamente sobre YUV422.

image.JPEG: int#

Búfer JPEG comprimido. Las operaciones a nivel de píxel requieren primero Image.to_grayscale() o Image.to_rgb565().

image.PNG: int#

Búfer PNG comprimido. Las operaciones a nivel de píxel requieren primero Image.to_grayscale() o Image.to_rgb565().

Paletas de color#

Pasa cualquiera de los siguientes a Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) o a csi.CSI.color_palette() para colorear una imagen en escala de grises.

image.PALETTE_RAINBOW: int#

Rueda de color de arcoíris suave. La paleta OpenMV por defecto para imágenes térmicas.

image.PALETTE_IRONBOW: int#

Paleta «ironbow» no lineal que imita el aspecto del visor térmico de la FLIR Lepton.

image.PALETTE_DEPTH: int#

Paleta de imagen de profundidad. Solo disponible en compilaciones con soporte de sensor de profundidad (la canalización ToF – p. ej. la OpenMV Cam AE3 o cualquier cámara con un Pmod ToF acoplado).

image.PALETTE_EVT_DARK: int#

Paleta para visualizar fotogramas de la cámara de eventos GENX320 sobre fondo oscuro. Pásala a csi.CSI.color_palette para que el controlador GENX320 emita fotogramas RGB565 coloreados en modo histograma, o a Image.draw_image() color_palette= al colorear una imagen de eventos en escala de grises.

Solo disponible en compilaciones con soporte de GENX320 (la OpenMV Cam AE3 y el Pmod GENX320).

image.PALETTE_EVT_LIGHT: int#

Paleta para visualizar fotogramas de la cámara de eventos GENX320 sobre fondo claro. Mismo despacho y disponibilidad que PALETTE_EVT_DARK.

Modos de escalado#

Pasa cualquiera de los siguientes como argumento hint a Image.draw_image(), Image.scale() o métodos de escalado similares.

image.AREA: int#

Escalador de promediado de áreas. Usado al reducir la escala; para ampliar se usa Nearest-Neighbor.

image.BILINEAR: int#

Escalador bilineal. Submuestrea al reducir la escala.

image.BICUBIC: int#

Escalador bicúbico. Mayor calidad que BILINEAR pero más lento. Submuestrea al reducir la escala.

Sugerencias de dibujo / draw_image#

Combina con OR a nivel de bits cualquiera de estas y pásalas como argumento hint de Image.draw_image().

image.VFLIP: int#

Voltea verticalmente el origen al dibujar.

image.HMIRROR: int#

Refleja horizontalmente el origen al dibujar.

image.TRANSPOSE: int#

Transpone (intercambia x/y) el origen al dibujar.

image.CENTER: int#

Centra el origen sobre el destino. Cualquier desplazamiento x/y explícito pasa entonces a ser un desplazamiento desde el centro en lugar de desde la esquina superior izquierda.

image.EXTRACT_RGB_CHANNEL_FIRST: int#

Al extraer un canal RGB mediante Image.draw_image(), extrae el canal antes de escalar. Sin esta sugerencia, el canal se extrae después de escalar.

image.APPLY_COLOR_PALETTE_FIRST: int#

Al aplicar una paleta de color mediante Image.draw_image(), aplica la paleta antes de escalar. Sin esta sugerencia, la paleta se aplica después de escalar.

image.SCALE_ASPECT_KEEP: int#

Escala el origen para que quepa dentro del destino manteniendo la relación de aspecto (añade bandas negras cuando las relaciones difieren).

image.SCALE_ASPECT_EXPAND: int#

Escala el origen para que llene el destino manteniendo la relación de aspecto (recorta cuando las relaciones difieren).

image.SCALE_ASPECT_IGNORE: int#

Escala el origen para que llene el destino, ignorando la relación de aspecto.

image.BLACK_BACKGROUND: int#

Indica a la ruta de mezcla alfa que se sabe que el destino es negro, de modo que pueda omitir la relectura del píxel de destino. Acelera los efectos alfa en búferes recién borrados.

image.ROTATE_90: int#

Atajo para VFLIP | TRANSPOSE (rotar 90 grados en sentido horario).

image.ROTATE_180: int#

Atajo para HMIRROR | VFLIP (rotar 180 grados).

image.ROTATE_270: int#

Atajo para HMIRROR | TRANSPOSE (rotar 270 grados en sentido horario).

Submuestreo JPEG#

Pasa cualquiera de los siguientes como argumento subsampling a Image.to_jpeg(), Image.compress() o Image.save() al escribir un JPEG.

image.JPEG_SUBSAMPLING_AUTO: int#

Elige el submuestreo de croma automáticamente según el ajuste de calidad JPEG.

image.JPEG_SUBSAMPLING_444: int#

Fuerza el submuestreo de croma 4:4:4 (sin compresión de croma).

image.JPEG_SUBSAMPLING_422: int#

Fuerza el submuestreo de croma 4:2:2. Recomendado al transmitir MJPEG a reproductores de vídeo de terceros que no se comportan bien con 4:2:0.

image.JPEG_SUBSAMPLING_420: int#

Fuerza el submuestreo de croma 4:2:0.

Coincidencia de plantillas#

Pasa cualquiera de los siguientes como argumento search a Image.find_template().

image.SEARCH_EX: int#

Búsqueda exhaustiva – evalúa todas las posiciones en la ROI. La más lenta pero garantiza encontrar la mejor coincidencia.

image.SEARCH_DS: int#

Búsqueda en diamante – búsqueda de grueso a fino que es mucho más rápida que SEARCH_EX pero puede pasar por alto el óptimo global en plantillas muy autosimilares.

Detección de bordes#

Pasa cualquiera de los siguientes como argumento algorithm a Image.find_edges().

image.EDGE_CANNY: int#

Detector de bordes Canny – magnitud del gradiente + supresión de no máximos + histéresis. Mayor calidad, más lento.

image.EDGE_SIMPLE: int#

Detector de bordes por filtro paso alto umbralizado. Más rápido pero produce bordes más gruesos y ruidosos que EDGE_CANNY.

Detectores de esquinas ORB#

Pasa cualquiera de los siguientes como argumento corner_detector a Image.find_keypoints().

image.CORNER_FAST: int#

Detector de esquinas FAST. Más rápido que CORNER_AGAST pero menos preciso.

image.CORNER_AGAST: int#

Detector de esquinas AGAST. Más lento que CORNER_FAST pero produce puntos clave más estables.

Familias de AprilTag#

Combina con OR a nivel de bits cualquier combinación de las siguientes y pásala como argumento families a Image.find_apriltags(). Cada familia está condicionada por su propia opción de compilación en el firmware; las familias no admitidas están ausentes en tiempo de ejecución en lugar de devolver siempre cero.

image.TAG16H5: int#

Familia 16h5 de AprilTag (30 IDs únicos, corrección de errores de 0 bits).

image.TAG25H9: int#

Familia 25h9 de AprilTag (35 IDs únicos, corrección de errores de hasta 3 bits).

image.TAG36H10: int#

Familia 36h10 de AprilTag (2320 IDs únicos, corrección de errores de hasta 3 bits).

image.TAG36H11: int#

Familia 36h11 de AprilTag (587 IDs únicos, corrección de errores de hasta 4 bits). La familia más común.

image.TAGCIRCLE21H7: int#

Familia Circle21h7 de AprilTag.

image.TAGCIRCLE49H12: int#

Familia Circle49h12 de AprilTag.

image.TAGCUSTOM48H12: int#

Familia Custom48h12 de AprilTag.

image.TAGSTANDARD41H12: int#

Familia Standard41h12 de AprilTag.

image.TAGSTANDARD52H13: int#

Familia Standard52h13 de AprilTag.

Simbologías de código de barras#

Los valores reportados en BarCode.type para las entradas devueltas por Image.find_barcodes().

image.EAN2: int#

Código de barras suplementario EAN-2.

image.EAN5: int#

Código de barras suplementario EAN-5.

image.EAN8: int#

Código de barras EAN-8.

image.UPCE: int#

Código de barras UPC-E.

image.ISBN10: int#

Código de barras ISBN-10.

image.UPCA: int#

Código de barras UPC-A.

image.EAN13: int#

Código de barras EAN-13.

image.ISBN13: int#

Código de barras ISBN-13.

image.I25: int#

Código de barras Interleaved 2-of-5.

image.DATABAR: int#

Código de barras GS1 DataBar.

image.DATABAR_EXP: int#

Código de barras GS1 DataBar Expanded.

image.CODABAR: int#

Código de barras Codabar.

image.CODE39: int#

Código de barras Code 39.

image.PDF417: int#

Código de barras apilado 2D PDF417. La constante existe por completitud, pero el decodificador de códigos de barras no implementa actualmente PDF417 – Image.find_barcodes() no devolverá detecciones de este tipo.

image.CODE93: int#

Código de barras Code 93.

image.CODE128: int#

Código de barras Code 128.