ml.utils — Utilitários de ML

O módulo ml.utils contém classes e funções utilitárias para aprendizado de máquina.

Funções

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

Retorna o logit de todos os valores no ndarray passado.

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

Retorna a sigmoide de todos os valores no ndarray passado.

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) por meio de um threshold quantizado e retorna um ndarray com todos os índices que passam pelo limiar.

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

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

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

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

Converte o ndarray passado dividindo pela escala e somando o zero point do modelo. Retorna value inalterado quando o dtype da saída do modelo em index é float.

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

value é o ndarray a ser quantizado.

index seleciona qual saída de tensor do model será usada como referência para a quantização.

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

Converte o ndarray passado subtraindo o zero point e em seguida multiplicando pela escala do modelo. Retorna value inalterado quando o dtype da saída do modelo em index é float.

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

value é o ndarray a ser dequantizado.

index seleciona qual saída de tensor do model será usada como referência para a dequantizaçã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 rótulos de texto sobre image.

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

labels é uma lista de strings de rótulo, uma por caixa.

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

scores se não for None, uma lista de pontuações de confiança por caixa. Quando fornecida, cada rótulo renderizado recebe como sufixo a pontuação formatada como " %.2f".

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

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

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

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

font_width é a largura em pixels de cada caractere no rótulo.

font_height é a altura em pixels do fundo do rótulo.

text_color é a cor (r, g, b) usada no texto do rótulo.

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, ...) sobre image.

radius é o raio do círculo do ponto-chave. Quando radius == 0 os pontos-chave são desenhados como pixels 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, ...) sobre image e em seguida os conecta com segmentos de linha.

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

kp_radius é o raio do círculo do ponto-chave (repassado 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.

class NMS – Supressão Não Máxima Suave (Soft-Non-Maximum Suppression)

O objeto NMS coleta uma lista de caixas delimitadoras com pontuações associadas, filtra caixas sobrepostas com pontuações menores por meio de Soft-NMS e remapeia as caixas detectadas em uma sub-janela de volta às 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 a altura do tensor de entrada / janela do modelo.

roi é a região de interesse (x, y, w, h) da imagem original sobre a qual o modelo foi executado (tipicamente retornada pelo objeto Normalization()). Usada para remapear as caixas detectadas de volta ao 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. Caixas com score fora de [0.0, 1.0] ou com largura ou altura zero/negativa após o recorte são descartadas.

xmin, ymin, xmax, ymax são as coordenadas da caixa delimitadora no espaço de pixels 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 do rótulo de classe associado à caixa delimitadora.

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

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

Executa Soft-NMS sobre todas as caixas adicionadas e retorna uma lista de listas por classe, indexada por label_index. Cada lista interna contém tuplas de ((x, y, w, h), score) mapeadas de volta às coordenadas da imagem original. Se keypoints foi fornecido na adição, a tupla é estendida 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 manter após a supressão Soft-NMS para ser preservada.

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