ml.utils — Utilitários ML

O módulo ml.utils contém classes e funções utilitárias para aprendizagem automática.

Funções

ml.utils.logit(x: ndarray) → ndarray

Devolve o logit de todos os valores no ndarray fornecido.

ml.utils.sigmoid(x: ndarray) → ndarray

Devolve a sigmoide de todos os valores no ndarray fornecido.

ml.utils.threshold(scores: ndarray, threshold: float, scale: float, find_max: bool = False, find_max_axis: int = 1) → ndarray

Aplica um limiar a scores (um ndarray quantizado de int8, uint8, int16 ou uint16) usando um threshold quantizado e devolve um ndarray com todos os índices que passam o limiar.

scale é testado para determinar se os valores desquantizados são positivos ou negativos. Quando scale > 0, são devolvidos os índices onde scores > threshold; caso contrário, são devolvidos os índices onde scores < threshold.

find_max se True, substitui internamente scores por um ndarray do máximo (ou mínimo, consoante scale) ao longo de find_max_axis.

find_max_axis é o eixo ao longo do qual a redução máx/mín é calculada quando find_max é True.

ml.utils.quantize(model: ml.Model, value: ndarray, index: int = 0) → ndarray

Converte o ndarray fornecido dividindo pela escala e adicionando o ponto zero do modelo. Devolve value inalterado quando o dtype de saída do modelo no index é float.

model é o modelo cujos parâmetros de quantização de saída são utilizados.

value é o ndarray a quantizar.

index seleciona qual saída tensorial do model usar para a quantização.

ml.utils.dequantize(model: ml.Model, value: ndarray, index: int = 0) → ndarray

Converte o ndarray fornecido subtraindo o ponto zero e multiplicando pela escala do modelo. Devolve value inalterado quando o dtype de saída do modelo no index é float.

model é o modelo cujos parâmetros de quantização de saída são utilizados.

value é o ndarray a desquantizar.

index seleciona qual saída tensorial do model usar para a desquantização.

ml.utils.draw_predictions(image: image.Image, boxes: list[tuple[float, float, float, float]], labels: list[str], colors: list[tuple[int, int, int]], scores: list[float] | None = None, format: str = 'pascal_voc', font_width: int = 8, font_height: int = 10, text_color: tuple[int, int, int] = (255, 255, 255)) → None

Desenha caixas delimitadoras (ou marcadores de ponto central) com etiquetas de texto na image.

boxes é uma lista de tuplos (x, y, w, h).

labels é uma lista de cadeias de etiquetas, uma por caixa.

colors é uma lista de tuplos (r, g, b), um por caixa.

scores se não for None, uma lista de pontuações de confiança por caixa. Quando fornecida, cada etiqueta apresentada é sufixada com a pontuação formatada como " %.2f".

format controla como as coordenadas da caixa são interpretadas:

• "pascal_voc" – (xmin, ymin, xmax, ymax) normalizados no intervalo 0.0 a 1.0.

• "point" – pixel absoluto (x, y, w, h); é desenhado um marcador de círculo preenchido no centro da caixa em vez de um retângulo (útil para detetores de ponto central).

• qualquer outro valor – pixel absoluto (x, y, w, h); desenhado como um retângulo.

font_width é a largura em pixéis de cada caráter na etiqueta.

font_height é a altura em pixéis do fundo da etiqueta.

text_color é a cor (r, g, b) utilizada para o texto da etiqueta.

ml.utils.draw_keypoints(image: image.Image, keypoints: ndarray, radius: int = 4, color: tuple[int, int, int] = (255, 0, 0), thickness: int = 1, fill: bool = False) → None

Desenha um ndarray de valores de ponto-chave (x, y, ...) na image.

radius é o raio do círculo do ponto-chave. Quando radius == 0, os pontos-chave são desenhados como pixéis individuais.

color é a cor (r, g, b) do ponto-chave.

thickness é a espessura do contorno do círculo.

fill se True, preenche os círculos dos pontos-chave.

ml.utils.draw_skeleton(image: image.Image, keypoints: ndarray, lines: list[tuple[int, int]], kp_radius: int = 4, kp_color: tuple[int, int, int] = (255, 0, 0), kp_thickness: int = 1, kp_fill: bool = False, line_color: tuple[int, int, int] = (0, 255, 0), line_thickness: int = 1) → None

Desenha um ndarray de valores de ponto-chave (x, y, ...) na image e liga-os com segmentos de linha.

lines é uma lista de tuplos (kp0_idx, kp1_idx) que especificam quais pares de pontos-chave ligar.

kp_radius é o raio do círculo do ponto-chave (passado para draw_keypoints).

kp_color é a cor (r, g, b) do ponto-chave.

kp_thickness é a espessura do contorno do círculo do ponto-chave.

kp_fill se True, preenche os círculos dos pontos-chave.

line_color é a cor (r, g, b) da linha.

line_thickness é a espessura da linha.

classe NMS – Supressão Não-Máxima Suave

O objeto NMS recolhe uma lista de caixas delimitadoras com pontuações associadas, filtra caixas sobrepostas com pontuações mais baixas via Soft-NMS, e remapeia as caixas detetadas numa sub-janela de volta para as coordenadas da imagem original.

class ml.utils.NMS(window_w: int, window_h: int, roi: tuple[int, int, int, int])

Cria um objeto NMS.

window_w e window_h são a largura e altura do tensor de entrada do modelo / janela.

roi é a região de interesse (x, y, w, h) da imagem original em que o modelo foi executado (tipicamente devolvida pelo objeto Normalization()). Utilizada para remapear as caixas detetadas de volta para o espaço de coordenadas da imagem original. roi[2] e roi[3] devem ser >= 1.

add_bounding_box(xmin: float, ymin: float, xmax: float, ymax: float, score: float, label_index: int, keypoints: ndarray | None = None) → None

Adiciona uma caixa delimitadora ao objeto NMS. As caixas com score fora de [0.0, 1.0] ou com largura ou altura zero/negativa após recorte são descartadas.

xmin, ymin, xmax, ymax são as coordenadas da caixa delimitadora no espaço de pixéis da janela, recortadas para [0, window_w] / [0, window_h].

score é a pontuação de confiança da caixa delimitadora (0.0-1.0).

label_index é o índice da etiqueta de classe associada à caixa delimitadora.

keypoints é um ndarray opcional de valores de ponto-chave (x, y, ...) associados a esta caixa delimitadora.

get_bounding_boxes(threshold: float = 0.1, sigma: float = 0.1) → list[list[tuple]]

Realiza Soft-NMS sobre todas as caixas adicionadas e devolve uma lista de listas por classe, indexadas por label_index. Cada lista interna contém tuplos de ((x, y, w, h), score) mapeados de volta para as coordenadas da imagem original. Se keypoints foi fornecido ao adicionar, o tuplo é estendido com o ndarray de keypoints remapeado.

Após chamar este método, crie um novo objeto NMS para processar um novo conjunto de caixas delimitadoras.

threshold é a pontuação mínima que uma caixa deve reter após supressão Soft-NMS para ser mantida.

sigma controla a Gaussiana utilizada para penalizar as pontuações de caixas delimitadoras sobrepostas. Um sigma mais pequeno resulta numa supressão mais agressiva. sigma <= 0.0 desativa a penalização Gaussiana (as pontuações de caixas sobrepostas não são reduzidas).