image — visão de máquina#

O módulo image é o coração da pilha de visão de máquina da OpenMV. Ele expõe a classe Image – o buffer de pixels em memória sobre o qual toda rotina de desenho, filtragem, transformação e extração de características opera – junto com os objetos de resultado de apoio retornados por essas rotinas (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) e as classes auxiliares usadas para configurá-las (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Adquirindo uma Imagem#

Existem quatro maneiras de colocar uma Image na RAM:

  • Captura ao vivo a partir do sensor da câmera. Chame csi.CSI.snapshot() para capturar o próximo quadro diretamente no frame buffer; a Image retornada referencia esse buffer.

  • A partir de um arquivo. Passe um caminho para o construtor de Image (image.Image("/sd/photo.jpg")); os formatos suportados em disco são BMP, PPM/PGM, JPEG, PNG e o formato de gravação ImageIO da OpenMV.

  • A partir de um ndarray. Passe um ndarray float32 (h, w) ou (h, w, 3) ao construtor de Image. Os pixels são escalados de 0.0 -- 255.0 para uma imagem GRAYSCALE ou RGB565, respectivamente. Use isto para trazer a saída de tensores do ml (ou de qualquer pipeline ulab) de volta para uma imagem desenhável.

  • Buffer vazio. Construa uma Image com um tamanho e formato de pixel determinados (image.Image(320, 240, image.RGB565)) para desenhar nela do zero, ou para usar como superfície de rascunho em operações aritméticas de imagem.

Formatos de pixel#

Toda Image possui um dos seguintes formatos de pixel; a escolha equilibra memória, custo de processamento e quais algoritmos podem ser executados sobre ela. Use BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG ou PNG como argumento pixformat ao construir uma imagem ou configurar o sensor da câmera:

  • BINARY (1 bpp) – um bit por pixel. O menor formato; usado internamente pelas rotinas de limiarização e morfologia, mas raramente capturado diretamente do sensor.

  • GRAYSCALE (8 bpp) – um byte por pixel (o canal Y do YUV422). O formato mais rápido para a maioria dos algoritmos de visão computacional (AprilTag, detecção de bordas, fluxo óptico).

  • RGB565 (16 bpp) – dois bytes por pixel, 5 bits de vermelho / 6 bits de verde / 5 bits de azul. O formato de cor padrão.

  • BAYER (8 bpp) – dados de cor em padrão Bayer brutos, direto do sensor. Útil para de-mosaicing personalizado ou para armazenar mais pixels em menos memória antes de aplicar o debayering sob demanda.

  • YUV422 (16 bpp) – cor com crominância subamostrada em 4:2:2, dois bytes por pixel. Útil quando você quer algoritmos específicos de crominância sem pagar o custo total do RGB.

  • JPEG / PNG – buffers comprimidos. Melhores para armazenamento e transmissão em rede. Operações em nível de pixel exigem Image.to_grayscale() ou Image.to_rgb565() antes.

Trabalhando com resultados#

Os métodos de detecção / extração de características de Image retornam objetos sobre os quais você pode iterar e combinar – uma chamada a Image.find_blobs() retorna uma lista de Blob, uma chamada a Image.find_apriltags() retorna uma lista de AprilTag, etc. Cada classe de resultado expõe as propriedades geométricas da detecção (centroide, caixa delimitadora, área, valor do código, etc.) para que você possa agir sobre elas diretamente ou passá-las de volta para os métodos de desenho (Image.draw_rectangle(), Image.draw_string(), …).

Auxiliares de espaço de cor#

O módulo também expõe pequenas funções puras para converter valores de pixel individuais entre os espaços de cor binário / escala de cinza / RGB / LAB / YUV. Elas são úteis quando você precisa converter valores de limiar ou entradas de paleta em Python antes de passá-los para operações de imagem – para conversão de imagem completa, use os métodos to_* de Image, que são muito mais rápidos do que chamar esses auxiliares em um laço.

Classes#

Funções#

Auxiliares de conversão de espaço de cor#

Cada uma das funções X_to_Y abaixo realiza a conversão de um único valor de pixel. Todas recebem/retornam valores nas faixas canônicas da OpenMV:

  • binário – int 0 – 1.

  • escala de cinza – int 0 – 255.

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

  • LAB – tupla (l, a, b) com L em 0 – 100 e A/B em -128 – 127.

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

Para conversão de imagem completa, use os métodos to_* de Image, que são muito mais rápidos do que chamar esses auxiliares em um laço.

image.binary_to_grayscale(value: int) → int#

Converte um valor binário em um valor de escala de cinza.

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

Converte um valor binário em uma tupla RGB.

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

Converte um valor binário em uma tupla LAB.

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

Converte um valor binário em uma tupla YUV.

image.grayscale_to_binary(value: int) → int#

Converte um valor de escala de cinza em um valor binário.

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

Converte um valor de escala de cinza em uma tupla RGB.

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

Converte um valor de escala de cinza em uma tupla LAB.

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

Converte um valor de escala de cinza em uma tupla YUV.

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

Converte uma tupla RGB em um valor binário.

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

Converte uma tupla RGB em um valor de escala de cinza.

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

Converte uma tupla RGB em uma tupla LAB.

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

Converte uma tupla RGB em uma tupla YUV.

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

Converte uma tupla LAB em um valor binário.

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

Converte uma tupla LAB em um valor de escala de cinza.

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

Converte uma tupla LAB em uma tupla RGB.

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

Converte uma tupla LAB em uma tupla YUV.

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

Converte uma tupla YUV em um valor binário.

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

Converte uma tupla YUV em um valor de escala de cinza.

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

Converte uma tupla YUV em uma tupla RGB.

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

Converte uma tupla YUV em uma tupla LAB.

Descritores de características#

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

Carrega um Haar Cascade e retorna um handle Cascade para uso com Image.find_features().

path pode ser:

  • a string literal "frontalface" ou "eye" para carregar um dos dois cascades embutidos na ROM do firmware, ou

  • um caminho no sistema de arquivos para um arquivo binário .cascade personalizado, produzido pelas ferramentas de conversão de cascade da OpenMV.

stages seleciona quantos estágios do cascade avaliar no momento da detecção. -1 usa todos os estágios armazenados no arquivo. Reduzir esse valor acelera a detecção ao custo de mais falsos positivos.

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

Carrega um descritor a partir do arquivo em path e o retorna. A tag de tipo interna do arquivo seleciona qual classe de descritor será reconstruída:

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

Serializa descriptor (um descritor de pontos-chave ORB ou LBP) para o arquivo em path no formato de arquivo de descritor da OpenMV. O mesmo arquivo pode ser recarregado posteriormente via image.load_descriptor().

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

Compara dois descritores do mesmo tipo.

  • Para dois descritores LBP – retorna uma distância de Hamming inteira entre eles (quanto menor, mais próxima a correspondência).

  • Para dois descritores de pontos-chave ORB – retorna um kptmatch descrevendo o agrupamento de pontos-chave correspondentes, ou None se nenhuma correspondência passar de threshold.

threshold (0 – 100) define o quão rigorosa é a correspondência ORB ao aceitar um par de pontos-chave. Valores menores tornam a correspondência mais restritiva, rejeitando correspondências fracas de vizinho mais próximo.

filter_outliers habilita a rejeição de outliers no estilo RANSAC sobre o conjunto de pontos-chave correspondentes. Use-o quando você espera uma única transformação rígida entre as duas visões; desabilite-o quando os pontos-chave correspondentes abrangerem múltiplos objetos.

Auxiliares de geometria de blobs#

Esses auxiliares recebem um Blob (conforme retornado por Image.find_blobs()) e calculam propriedades geométricas adicionais sob demanda. Eles ficam no escopo do módulo – não em Blob – de modo que o caminho básico de find_blobs() não paga por eles a menos que você os solicite.

image.get_solidity(blob: blob) → float#

Retorna a solidez (blob.pixels / convex_hull_area) de blob. Float, 0 – 1; 1.0 significa que o blob preenche completamente sua envoltória convexa.

image.get_convexity(blob: blob) → float#

Retorna a convexidade (convex_hull_perimeter / blob.perimeter) de blob. Float, 0 – 1; 1.0 é um blob perfeitamente convexo.

image.get_major_axis_line(blob: blob) → line#

Retorna uma Line ao longo do eixo maior de blob (o mais longo dos dois eixos principais do retângulo rotacionado de área mínima).

image.get_minor_axis_line(blob: blob) → line#

Retorna uma Line ao longo do eixo menor de blob (o mais curto dos dois eixos principais do retângulo rotacionado de área mínima).

image.get_enclosing_circle(blob: blob) → circle#

Retorna um Circle que envolve blob.

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

Retorna uma 5-tupla (cx, cy, a, b, rotation) descrevendo a elipse inscrita no retângulo rotacionado de área mínima ao redor de blob:

  • cx / cy – centro da elipse em pixels (inteiro).

  • a / b – comprimentos dos semieixos em pixels (inteiro).

  • rotation – rotação da elipse em graus (inteiro).

Esta é uma tupla simples, não uma attrtuple, então os campos são acessíveis apenas por índice.

Constantes#

Formatos de pixel#

Passe qualquer um dos seguintes como argumento pixformat ao construtor de Image ou a csi.CSI.pixformat().

image.BINARY: int#

Bitmap de 1 bit por pixel. O menor formato – usado internamente pela limiarização e morfologia, raramente capturado diretamente de um sensor.

image.GRAYSCALE: int#

Escala de cinza de 8 bits por pixel (um byte por pixel). O formato mais rápido para a maioria dos algoritmos de visão computacional (AprilTag, detecção de bordas, fluxo óptico).

image.RGB565: int#

Cor de 16 bits por pixel empacotada como 5 bits de vermelho / 6 bits de verde / 5 bits de azul. O formato de cor padrão.

image.BAYER: int#

Dados Bayer brutos de 8 bits por pixel, direto do sensor. A maioria dos métodos de processamento de imagem não está disponível em imagens Bayer; use isto quando quiser aplicar o debayer sob demanda ou armazenar mais pixels em menos memória.

image.YUV422: int#

Cor com crominância subamostrada em 4:2:2, dois bytes por pixel, empacotada como Y1, U, Y2, V por par de pixels. Apenas alguns métodos de processamento de imagem funcionam diretamente em YUV422.

image.JPEG: int#

Buffer JPEG comprimido. Operações em nível de pixel exigem Image.to_grayscale() ou Image.to_rgb565() antes.

image.PNG: int#

Buffer PNG comprimido. Operações em nível de pixel exigem Image.to_grayscale() ou Image.to_rgb565() antes.

Paletas de cores#

Passe qualquer um dos seguintes para Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) ou para csi.CSI.color_palette() para colorizar uma imagem em escala de cinza.

image.PALETTE_RAINBOW: int#

Roda de cores arco-íris suave. A paleta OpenMV padrão para imagens térmicas.

image.PALETTE_IRONBOW: int#

Paleta “ironbow” não linear que imita a aparência do visor térmico FLIR Lepton.

image.PALETTE_DEPTH: int#

Paleta de imagem de profundidade. Disponível apenas em builds com suporte a sensor de profundidade (o pipeline ToF – por exemplo, a OpenMV Cam AE3 ou qualquer câmera com um Pmod ToF acoplado).

image.PALETTE_EVT_DARK: int#

Paleta para visualizar quadros da câmera de eventos GENX320 sobre um fundo escuro. Passe para csi.CSI.color_palette para fazer o driver GENX320 emitir quadros RGB565 colorizados em modo de histograma, ou para Image.draw_image() color_palette= ao colorizar uma imagem de eventos em escala de cinza.

Disponível apenas em builds com suporte a GENX320 (OpenMV Cam AE3 e o Pmod GENX320).

image.PALETTE_EVT_LIGHT: int#

Paleta para visualizar quadros da câmera de eventos GENX320 sobre um fundo claro. Mesmo despacho e disponibilidade que PALETTE_EVT_DARK.

Modos de escalonamento#

Passe qualquer um dos seguintes como argumento hint para Image.draw_image(), Image.scale() ou métodos de escalonamento semelhantes.

image.AREA: int#

Escalonador por média de área. Usado ao reduzir a escala; o Nearest-Neighbor é usado para aumentar a escala.

image.BILINEAR: int#

Escalonador bilinear. Subamostra ao reduzir a escala.

image.BICUBIC: int#

Escalonador bicúbico. Maior qualidade que BILINEAR, porém mais lento. Subamostra ao reduzir a escala.

Dicas de desenho / draw_image#

Combine qualquer uma destas com OR de bits e passe como argumento hint de Image.draw_image().

image.VFLIP: int#

Inverte a origem verticalmente durante o desenho.

image.HMIRROR: int#

Espelha a origem horizontalmente durante o desenho.

image.TRANSPOSE: int#

Transpõe (troca x/y) a origem durante o desenho.

image.CENTER: int#

Centraliza a origem no destino. Quaisquer deslocamentos x/y explícitos passam então a ser deslocamentos a partir do centro, em vez do canto superior esquerdo.

image.EXTRACT_RGB_CHANNEL_FIRST: int#

Ao extrair um canal RGB via Image.draw_image(), extrai o canal antes do escalonamento. Sem esta dica, o canal é extraído após o escalonamento.

image.APPLY_COLOR_PALETTE_FIRST: int#

Ao aplicar uma paleta de cores via Image.draw_image(), aplica a paleta antes do escalonamento. Sem esta dica, a paleta é aplicada após o escalonamento.

image.SCALE_ASPECT_KEEP: int#

Escala a origem para caber dentro do destino mantendo a proporção (adiciona letterbox quando as proporções diferem).

image.SCALE_ASPECT_EXPAND: int#

Escala a origem para preencher o destino mantendo a proporção (recorta quando as proporções diferem).

image.SCALE_ASPECT_IGNORE: int#

Escala a origem para preencher o destino, ignorando a proporção.

image.BLACK_BACKGROUND: int#

Informa ao caminho de mesclagem alfa que o destino é sabidamente preto, para que ele possa pular a releitura do pixel de destino. Acelera os efeitos alfa em buffers recém-limpos.

image.ROTATE_90: int#

Atalho para VFLIP | TRANSPOSE (rotaciona 90 graus no sentido horário).

image.ROTATE_180: int#

Atalho para HMIRROR | VFLIP (rotaciona 180 graus).

image.ROTATE_270: int#

Atalho para HMIRROR | TRANSPOSE (rotaciona 270 graus no sentido horário).

Subamostragem JPEG#

Passe qualquer um dos seguintes como argumento subsampling para Image.to_jpeg(), Image.compress() ou Image.save() ao gravar um JPEG.

image.JPEG_SUBSAMPLING_AUTO: int#

Escolhe a subamostragem de crominância automaticamente com base na configuração de qualidade do JPEG.

image.JPEG_SUBSAMPLING_444: int#

Força a subamostragem de crominância 4:4:4 (sem compressão de crominância).

image.JPEG_SUBSAMPLING_422: int#

Força a subamostragem de crominância 4:2:2. Recomendado ao transmitir MJPEG para players de vídeo de terceiros que se comportam mal com 4:2:0.

image.JPEG_SUBSAMPLING_420: int#

Força a subamostragem de crominância 4:2:0.

Correspondência de modelo#

Passe um dos seguintes como argumento search para Image.find_template().

image.SEARCH_EX: int#

Busca exaustiva – avalia cada posição na ROI. A mais lenta, mas garante encontrar a melhor correspondência.

image.SEARCH_DS: int#

Busca em diamante – busca de grosseira a fina, muito mais rápida que SEARCH_EX, mas que pode perder o ótimo global em modelos altamente auto-similares.

Detecção de bordas#

Passe um dos seguintes como argumento algorithm para Image.find_edges().

image.EDGE_CANNY: int#

Detector de bordas Canny – magnitude do gradiente + supressão de não máximos + histerese. Maior qualidade, mais lento.

image.EDGE_SIMPLE: int#

Detector de bordas por filtro passa-alta com limiar. Mais rápido, mas produz bordas mais grossas e ruidosas que EDGE_CANNY.

Detectores de cantos ORB#

Passe um dos seguintes como argumento corner_detector para Image.find_keypoints().

image.CORNER_FAST: int#

Detector de cantos FAST. Mais rápido que CORNER_AGAST, mas menos preciso.

image.CORNER_AGAST: int#

Detector de cantos AGAST. Mais lento que CORNER_FAST, mas produz pontos-chave mais estáveis.

Famílias AprilTag#

Combine qualquer combinação dos seguintes com OR de bits e passe como argumento families para Image.find_apriltags(). Cada família é controlada por sua própria opção de build no firmware; famílias não suportadas ficam ausentes em tempo de execução, em vez de sempre retornarem zero.

image.TAG16H5: int#

Família AprilTag 16h5 (30 IDs únicos, correção de erro de 0 bits).

image.TAG25H9: int#

Família AprilTag 25h9 (35 IDs únicos, correção de erro de até 3 bits).

image.TAG36H10: int#

Família AprilTag 36h10 (2320 IDs únicos, correção de erro de até 3 bits).

image.TAG36H11: int#

Família AprilTag 36h11 (587 IDs únicos, correção de erro de até 4 bits). A família mais comum.

image.TAGCIRCLE21H7: int#

Família AprilTag Circle21h7.

image.TAGCIRCLE49H12: int#

Família AprilTag Circle49h12.

image.TAGCUSTOM48H12: int#

Família AprilTag Custom48h12.

image.TAGSTANDARD41H12: int#

Família AprilTag Standard41h12.

image.TAGSTANDARD52H13: int#

Família AprilTag Standard52h13.

Simbologias de código de barras#

Os valores reportados em BarCode.type para entradas retornadas por Image.find_barcodes().

image.EAN2: int#

Código de barras suplementar EAN-2.

image.EAN5: int#

Código de barras suplementar 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 empilhado 2D PDF417. A constante existe por completude, mas o decodificador de código de barras atualmente não implementa PDF417 – Image.find_barcodes() não retornará detecções deste tipo.

image.CODE93: int#

Código de barras Code 93.

image.CODE128: int#

Código de barras Code 128.