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.