image — visão por computador

O módulo image é o núcleo da pilha de visão por computador do OpenMV. Expõe a classe Image – o buffer de pixels em memória sobre o qual operam todas as rotinas de desenho, filtragem, transformação e extração de características – juntamente com os objetos de resultado retornados por essas rotinas (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) e as classes auxiliares utilizadas para os configurar (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Adquirir uma Imagem

Existem quatro formas de colocar uma Image em RAM:

  • Captura em direto a partir do sensor da câmara. Chame csi.CSI.snapshot() para capturar o fotograma seguinte diretamente para o buffer de fotograma; a Image devolvida referencia esse buffer.

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

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

  • Buffer vazio. Construa uma Image com um tamanho e formato de pixel definidos (image.Image(320, 240, image.RGB565)) para desenhar de raiz, ou para usar como superfície de trabalho em operações aritméticas sobre imagens.

Formatos de pixel

Cada Image tem um dos seguintes formatos de pixel; a escolha implica um compromisso entre memória, custo de processamento e os algoritmos que podem ser executados. Utilize BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG ou PNG como argumento pixformat ao construir uma imagem ou ao configurar o sensor da câmara:

  • BINARY (1 bpp) – um bit por pixel. O formato mais pequeno; utilizado internamente por rotinas de limiarização e morfologia, mas raramente capturado diretamente pelo 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 por computador (AprilTag, deteção de arestas, fluxo ótico).

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

  • BAYER (8 bpp) – dados de cor em padrão de Bayer em bruto, diretamente do sensor. Útil para demosaicização personalizada ou para armazenar mais pixels em menos memória antes de efetuar o debayering a pedido.

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

  • JPEG / PNG – buffers comprimidos. Indicados para armazenamento e transmissão em rede. As operações ao nível do pixel requerem primeiro Image.to_grayscale() ou Image.to_rgb565().

Trabalhar com resultados

Os métodos de deteção / extração de características em Image devolvem objetos que podem ser iterados e combinados – uma chamada a Image.find_blobs() devolve uma lista de Blob, uma chamada a Image.find_apriltags() devolve uma lista de AprilTag, etc. Cada classe de resultado expõe as propriedades geométricas da deteção (centroide, caixa delimitadora, área, valor do código, etc.) para que possa agir sobre elas diretamente ou passá-las de volta para 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 cinzentos / RGB / LAB / YUV. São úteis quando é necessário converter valores de limiar ou entradas de paleta em Python antes de os passar para operações de imagem – para conversão de imagem completa utilize os métodos to_* da classe Image, que são muito mais rápidos do que chamar estes auxiliares num ciclo.

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 do valor de um único pixel. Todas recebem/devolvem valores nos intervalos canónicos do OpenMV:

  • binário – int 0 – 1.

  • escala de cinzentos – int 0 – 255.

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

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

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

Para conversão de imagem completa utilize os métodos to_* da classe Image, que são muito mais rápidos do que chamar estes auxiliares num ciclo.

image.binary_to_grayscale(value: int) → int

Converte um valor binário num valor em escala de cinzentos.

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

Converte um valor binário num tuplo RGB.

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

Converte um valor binário num tuplo LAB.

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

Converte um valor binário num tuplo YUV.

image.grayscale_to_binary(value: int) → int

Converte um valor em escala de cinzentos num valor binário.

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

Converte um valor em escala de cinzentos num tuplo RGB.

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

Converte um valor em escala de cinzentos num tuplo LAB.

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

Converte um valor em escala de cinzentos num tuplo YUV.

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

Converte um tuplo RGB num valor binário.

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

Converte um tuplo RGB num valor em escala de cinzentos.

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

Converte um tuplo RGB num tuplo LAB.

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

Converte um tuplo RGB num tuplo YUV.

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

Converte um tuplo LAB num valor binário.

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

Converte um tuplo LAB num valor em escala de cinzentos.

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

Converte um tuplo LAB num tuplo RGB.

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

Converte um tuplo LAB num tuplo YUV.

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

Converte um tuplo YUV num valor binário.

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

Converte um tuplo YUV num valor em escala de cinzentos.

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

Converte um tuplo YUV num tuplo RGB.

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

Converte um tuplo YUV num tuplo LAB.

Descritores de características

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

Carrega um Haar Cascade e devolve um identificador Cascade para utilizar com Image.find_features().

path pode ser:

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

  • um caminho do sistema de ficheiros para um ficheiro binário .cascade personalizado produzido pelas ferramentas de conversão de cascades do OpenMV.

stages seleciona quantos estágios do cascade avaliar durante a deteção. -1 utiliza todos os estágios armazenados no ficheiro. Reduzir este valor acelera a deteção ao custo de mais falsos positivos.

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

Carrega um descritor do ficheiro em path e devolve-o. A etiqueta de tipo interna do ficheiro seleciona a classe de descritor a reconstruir:

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

Serializa descriptor (um descritor de pontos-chave ORB ou LBP) para o ficheiro em path no formato de ficheiro de descritores do OpenMV. O mesmo ficheiro 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 – devolve a distância de Hamming inteira entre eles (valor mais baixo indica maior similaridade).

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

threshold (0 – 100) define a exigência da correspondência ORB ao aceitar um par de pontos-chave. Valores mais baixos tornam a correspondência mais restrita ao rejeitar correspondências com vizinhos mais próximos fracos.

filter_outliers ativa a rejeição de outliers ao estilo RANSAC sobre o conjunto de pontos-chave correspondentes. Utilize-o quando espera uma única transformação rígida entre as duas vistas; desative-o quando os pontos-chave correspondentes abrangem múltiplos objetos.

Auxiliares de geometria de manchas

Estes auxiliares recebem uma Blob (conforme devolvida por Image.find_blobs()) e calculam propriedades geométricas adicionais a pedido. Residem no âmbito do módulo – não em Blob – para que o caminho básico de find_blobs() não incorra no seu custo a menos que sejam solicitados.

image.get_solidity(blob: blob) → float

Devolve a solidez (blob.pixels / convex_hull_area) de blob. Float entre 0 – 1; 1.0 significa que a mancha preenche completamente o seu invólucro convexo.

image.get_convexity(blob: blob) → float

Devolve a convexidade (convex_hull_perimeter / blob.perimeter) de blob. Float entre 0 – 1; 1.0 corresponde a uma mancha perfeitamente convexa.

image.get_major_axis_line(blob: blob) → line

Devolve 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

Devolve 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

Devolve um Circle que envolve blob.

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

Devolve um tuplo de 5 elementos (cx, cy, a, b, rotation) que descreve a elipse inscrita no retângulo rotacionado de área mínima em torno de blob:

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

  • a / b – comprimentos dos semi-eixos em pixels (inteiro).

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

Trata-se de um tuplo simples, não de um attrtuple, pelo que os campos só são acessíveis por índice.

Constantes

Formatos de pixel

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

image.BINARY: int

Bitmap de 1 bit por pixel. Formato mais pequeno – utilizado internamente por limiarização e morfologia, raramente capturado diretamente de um sensor.

image.GRAYSCALE: int

Escala de cinzentos de 8 bits por pixel (um byte por pixel). O formato mais rápido para a maioria dos algoritmos de visão por computador (AprilTag, deteção de arestas, fluxo ótico).

image.RGB565: int

Cor de 16 bits por pixel compactada como 5 bits de vermelho / 6 bits de verde / 5 bits de azul. O formato de cor predefinido.

image.BAYER: int

Dados de Bayer em bruto de 8 bits por pixel diretamente do sensor. A maioria dos métodos de processamento de imagem não está disponível em imagens Bayer; utilize este formato quando pretender efetuar o debayering a pedido ou armazenar mais pixels em menos memória.

image.YUV422: int

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

image.JPEG: int

Buffer JPEG comprimido. As operações ao nível do pixel requerem primeiro Image.to_grayscale() ou Image.to_rgb565().

image.PNG: int

Buffer PNG comprimido. As operações ao nível do pixel requerem primeiro Image.to_grayscale() ou Image.to_rgb565().

Paletas de cor

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

image.PALETTE_RAINBOW: int

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

image.PALETTE_IRONBOW: int

Paleta «ironbow» não linear que imita o aspeto do visor térmico do FLIR Lepton.

image.PALETTE_DEPTH: int

Paleta para imagens de profundidade. Apenas disponível em compilações com suporte para sensor de profundidade (o pipeline ToF – por exemplo, OpenMV Cam AE3 ou qualquer câmara com um ToF Pmod ligado).

image.PALETTE_EVT_DARK: int

Paleta para visualizar fotogramas da câmara de eventos GENX320 sobre fundo escuro. Passe a csi.CSI.color_palette para que o controlador GENX320 emita fotogramas RGB565 coloridos em modo histograma, ou a Image.draw_image() color_palette= ao colorir uma imagem de eventos em escala de cinzentos.

Apenas disponível em compilações com suporte para GENX320 (OpenMV Cam AE3 e o GENX320 Pmod).

image.PALETTE_EVT_LIGHT: int

Paleta para visualizar fotogramas da câmara de eventos GENX320 sobre fundo claro. Mesmo despacho e disponibilidade que PALETTE_EVT_DARK.

Modos de escalonamento

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

image.AREA: int

Escalonador por média de área. Utilizado ao reduzir a escala; para aumentar a escala é usado o Vizinho Mais Próximo.

image.BILINEAR: int

Escalonador bilinear. Usa subsampling ao reduzir a escala.

image.BICUBIC: int

Escalonador bicúbico. Maior qualidade do que BILINEAR mas mais lento. Usa subsampling ao reduzir a escala.

Sugestões de desenho / draw_image

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

image.VFLIP: int

Inverte verticalmente a fonte durante o desenho.

image.HMIRROR: int

Espelha horizontalmente a fonte durante o desenho.

image.TRANSPOSE: int

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

image.CENTER: int

Centra a fonte no destino. Quaisquer deslocamentos explícitos de x/y passam então a ser relativos ao centro em vez de ao 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 sugestão, o canal é extraído após o escalonamento.

image.APPLY_COLOR_PALETTE_FIRST: int

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

image.SCALE_ASPECT_KEEP: int

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

image.SCALE_ASPECT_EXPAND: int

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

image.SCALE_ASPECT_IGNORE: int

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

image.BLACK_BACKGROUND: int

Indica ao caminho de mistura alpha que o destino é sabidamente preto, podendo assim ignorar a leitura do pixel de destino. Acelera efeitos alpha em buffers recém-limpos.

image.ROTATE_90: int

Atalho para VFLIP | TRANSPOSE (rotação 90 graus no sentido dos ponteiros do relógio).

image.ROTATE_180: int

Atalho para HMIRROR | VFLIP (rotação 180 graus).

image.ROTATE_270: int

Atalho para HMIRROR | TRANSPOSE (rotação 270 graus no sentido dos ponteiros do relógio).

Subsampling JPEG

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

image.JPEG_SUBSAMPLING_AUTO: int

Escolhe automaticamente o subsampling de crominância com base na definição de qualidade JPEG.

image.JPEG_SUBSAMPLING_444: int

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

image.JPEG_SUBSAMPLING_422: int

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

image.JPEG_SUBSAMPLING_420: int

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

Correspondência de modelos

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

image.SEARCH_EX: int

Pesquisa exaustiva – avalia todas as posições na ROI. A mais lenta, mas garante encontrar a melhor correspondência.

image.SEARCH_DS: int

Pesquisa em diamante – pesquisa de grosseiro para fino, muito mais rápida do que SEARCH_EX, mas pode perder o ótimo global em modelos muito semelhantes entre si.

Deteção de arestas

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

image.EDGE_CANNY: int

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

image.EDGE_SIMPLE: int

Detetor de arestas por filtro passa-alto com limiarização. Mais rápido, mas produz arestas mais espessas e ruidosas do que EDGE_CANNY.

Detetores de cantos ORB

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

image.CORNER_FAST: int

Detetor de cantos FAST. Mais rápido do que CORNER_AGAST mas menos preciso.

image.CORNER_AGAST: int

Detetor de cantos AGAST. Mais lento do 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 a Image.find_apriltags(). Cada família é controlada pela sua própria opção de compilação no firmware; as famílias não suportadas estão ausentes em tempo de execução em vez de devolverem sempre zero.

image.TAG16H5: int

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

image.TAG25H9: int

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

image.TAG36H10: int

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

image.TAG36H11: int

Família AprilTag 36h11 (587 IDs únicos, correção de erros 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.

Simbologia de códigos de barras

Os valores reportados em BarCode.type para entradas devolvidas 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 PDF417 2D empilhado. A constante existe por completude, mas o descodificador de códigos de barras não implementa atualmente PDF417 – Image.find_barcodes() não devolverá deteções deste tipo.

image.CODE93: int

Código de barras Code 93.

image.CODE128: int

Código de barras Code 128.