ml.utils — ML 유틸리티

ml.utils 모듈은 머신 비전을 위한 유틸리티 클래스와 함수를 포함합니다.

함수

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

전달된 ndarray의 모든 값에 대한 로짓(logit)을 반환합니다.

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

전달된 ndarray의 모든 값에 대한 시그모이드(sigmoid)를 반환합니다.

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

scores(int8, uint8, int16 또는 uint16의 양자화된 ndarray)를 양자화된 threshold로 임계 처리하고, 임계값을 통과하는 모든 인덱스의 ndarray를 반환합니다.

scale은 역양자화된 값이 양수인지 음수인지 판단하기 위해 검사됩니다. scale > 0일 때는 scores > threshold인 인덱스가 반환되고, 그렇지 않으면 scores < threshold인 인덱스가 반환됩니다.

find_max가 True이면, scores를 find_max_axis를 따라 계산한 최댓값(또는 scale에 따라 최솟값)의 ndarray로 내부적으로 대체합니다.

find_max_axis는 find_max가 True일 때 최댓값/최솟값 축소가 계산되는 축입니다.

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

전달된 ndarray를 스케일로 나누고 모델의 영점(zero point)을 더하여 변환합니다. index의 모델 출력 dtype이 float인 경우 value를 변경하지 않고 반환합니다.

model은 출력 양자화 매개변수가 사용되는 모델입니다.

value는 양자화할 ndarray입니다.

index는 model의 어느 텐서 출력에 대해 양자화할지 선택합니다.

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

전달된 ndarray를 영점을 빼고 모델의 스케일을 곱하여 변환합니다. index의 모델 출력 dtype이 float인 경우 value를 변경하지 않고 반환합니다.

model은 출력 양자화 매개변수가 사용되는 모델입니다.

value는 역양자화할 ndarray입니다.

index는 model의 어느 텐서 출력에 대해 역양자화할지 선택합니다.

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

텍스트 레이블과 함께 경계 상자(또는 중심점 마커)를 image에 그립니다.

boxes는 (x, y, w, h) 튜플의 리스트입니다.

labels는 박스당 하나씩의 레이블 문자열 리스트입니다.

colors는 박스당 하나씩의 (r, g, b) 튜플 리스트입니다.

scores는 None이 아닌 경우 박스별 신뢰도 점수의 리스트입니다. 제공되면 렌더링되는 각 레이블 뒤에 " %.2f" 형식으로 점수가 추가됩니다.

format은 박스 좌표를 해석하는 방식을 제어합니다:

• "pascal_voc" – 0.0에서 1.0 범위로 정규화된 (xmin, ymin, xmax, ymax).

• "point" – 절대 픽셀 (x, y, w, h); 사각형 대신 박스 중심에 채워진 원형 마커가 그려집니다(중심점 검출기에 유용함).

• 그 외의 값 – 절대 픽셀 (x, y, w, h); 사각형으로 그려집니다.

font_width는 레이블 각 문자의 너비(픽셀 단위)입니다.

font_height는 레이블 배경의 높이(픽셀 단위)입니다.

text_color는 레이블 텍스트에 사용되는 (r, g, b) 색상입니다.

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

키포인트 (x, y, ...) 값의 ndarray를 image에 그립니다.

radius는 키포인트 원의 반지름입니다. radius == 0일 때 키포인트는 단일 픽셀로 그려집니다.

color는 (r, g, b) 키포인트 색상입니다.

thickness는 원 외곽선의 두께입니다.

fill이 True이면 키포인트 원을 채웁니다.

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

키포인트 (x, y, ...) 값의 ndarray를 image에 그린 다음 선분으로 연결합니다.

lines는 연결할 키포인트 쌍을 지정하는 (kp0_idx, kp1_idx) 튜플의 리스트입니다.

kp_radius는 키포인트 원의 반지름입니다(draw_keypoints로 전달됨).

kp_color는 (r, g, b) 키포인트 색상입니다.

kp_thickness는 키포인트 원 외곽선의 두께입니다.

kp_fill이 True이면 키포인트 원을 채웁니다.

line_color는 (r, g, b) 선 색상입니다.

line_thickness는 선의 두께입니다.

class NMS – Soft-Non-Maximum Suppression

NMS 객체는 연관된 점수와 함께 경계 상자 리스트를 수집하고, Soft-NMS를 통해 점수가 더 낮은 겹치는 박스를 필터링하며, 하위 윈도우에서 검출된 박스를 원본 이미지 좌표로 다시 매핑합니다.

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

NMS 객체를 생성합니다.

window_w와 window_h는 모델 입력 텐서/윈도우의 너비와 높이입니다.

roi는 모델이 실행된 원본 이미지의 (x, y, w, h) 관심 영역입니다(일반적으로 Normalization() 객체가 반환함). 검출된 박스를 원본 이미지 좌표 공간으로 다시 매핑하는 데 사용됩니다. roi[2]와 roi[3]은 1 이상이어야 합니다.

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

NMS 객체에 경계 상자를 추가합니다. score가 [0.0, 1.0] 범위를 벗어나거나 클리핑 후 너비나 높이가 0 이하인 박스는 폐기됩니다.

xmin, ymin, xmax, ymax는 윈도우 픽셀 공간의 경계 상자 좌표로, [0, window_w] / [0, window_h]로 클리핑됩니다.

score는 경계 상자의 신뢰도 점수입니다(0.0-1.0).

label_index는 경계 상자와 연관된 클래스 레이블의 인덱스입니다.

keypoints는 이 경계 상자와 연관된 키포인트 (x, y, ...) 값의 선택적 ndarray입니다.

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

추가된 모든 박스에 대해 Soft-NMS를 수행하고, label_index로 인덱싱된 클래스별 리스트의 리스트를 반환합니다. 각 내부 리스트는 원본 이미지 좌표로 다시 매핑된 ((x, y, w, h), score) 튜플을 포함합니다. 추가 시 keypoints가 제공되었다면 튜플은 다시 매핑된 keypoints ndarray로 확장됩니다.

이 메서드를 호출한 후에는 새로운 경계 상자 집합을 처리하기 위해 새 NMS 객체를 생성하십시오.

threshold는 박스가 유지되기 위해 Soft-NMS 억제 후 보유해야 하는 최소 점수입니다.

sigma는 겹치는 경계 상자의 점수에 페널티를 주는 데 사용되는 가우시안을 제어합니다. sigma가 작을수록 더 적극적인 억제가 이루어집니다. sigma <= 0.0이면 가우시안 페널티가 비활성화됩니다(겹치는 박스의 점수가 감쇠되지 않음).