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.