image — 머신 비전

image 모듈은 OpenMV 머신 비전 스택의 핵심입니다. 모든 그리기, 필터링, 변환 및 특징 추출 루틴이 동작하는 대상인 메모리 내 픽셀 버퍼인 Image 클래스와 함께, 해당 루틴들이 반환하는 결과 객체들(Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) 그리고 이들을 구성하는 데 사용되는 헬퍼 클래스들(Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO)을 노출합니다.

이미지 획득

Image 를 RAM으로 가져오는 방법은 네 가지가 있습니다:

  • 카메라 센서에서 실시간 캡처. csi.CSI.snapshot() 을 호출하여 다음 프레임을 프레임 버퍼로 직접 캡처합니다; 반환된 Image 는 해당 버퍼를 참조합니다.

  • 파일에서. Image 생성자에 경로를 전달합니다(image.Image("/sd/photo.jpg")); 디스크에서 지원되는 형식은 BMP, PPM/PGM, JPEG, PNG 및 OpenMV ImageIO 녹화 형식입니다.

  • ndarray에서. float32 (h, w) 또는 (h, w, 3) ndarray 를 Image 생성자에 전달합니다. 픽셀은 0.0 -- 255.0 범위에서 각각 GRAYSCALE 또는 RGB565 이미지로 스케일링됩니다. ml (또는 모든 ulab 파이프라인)의 텐서 출력을 다시 그릴 수 있는 이미지로 가져올 때 이를 사용하세요.

  • 빈 버퍼. 주어진 크기와 픽셀 형식으로 Image 를 생성하여(image.Image(320, 240, image.RGB565)) 처음부터 그려 넣거나, 이미지 산술 연산을 위한 스크래치 표면으로 사용합니다.

픽셀 형식

모든 Image 는 다음 픽셀 형식 중 하나를 가집니다; 이 선택은 메모리, 처리 비용 및 실행 가능한 알고리즘 간의 절충을 결정합니다. 이미지를 생성하거나 카메라 센서를 구성할 때 pixformat 인수로 BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG 또는 PNG 를 사용하세요:

  • BINARY (1 bpp) – 픽셀당 1비트. 가장 작은 형식; 임계값 처리 및 모폴로지 루틴에서 내부적으로 사용되지만 센서에서 직접 캡처되는 경우는 드뭅니다.

  • GRAYSCALE (8 bpp) – 픽셀당 1바이트(YUV422의 Y 채널). 대부분의 컴퓨터 비전 알고리즘(AprilTag, 에지 검출, 옵티컬 플로우)에 가장 빠른 형식입니다.

  • RGB565 (16 bpp) – 픽셀당 2바이트, 5비트 빨강 / 6비트 초록 / 5비트 파랑. 기본 색상 형식입니다.

  • BAYER (8 bpp) – 센서에서 바로 나온 원시 Bayer 패턴 색상 데이터. 사용자 정의 디모자이크 처리나, 필요 시 디베이어 처리하기 전에 더 적은 메모리에 더 많은 픽셀을 저장하는 데 유용합니다.

  • YUV422 (16 bpp) – 4:2:2 크로마 서브샘플링 색상, 픽셀당 2바이트. 전체 RGB 비용을 들이지 않고 크로마 기반 알고리즘을 사용하려는 경우 유용합니다.

  • JPEG / PNG – 압축된 버퍼. 저장 및 네트워크 전송에 가장 적합합니다. 픽셀 단위 연산을 하려면 먼저 Image.to_grayscale() 또는 Image.to_rgb565() 가 필요합니다.

결과 다루기

Image 의 검출 / 특징 추출 메서드는 반복하고 조합할 수 있는 객체를 반환합니다 – Image.find_blobs() 호출은 Blob 의 리스트를 반환하고, Image.find_apriltags() 호출은 AprilTag 의 리스트를 반환하는 식입니다. 각 결과 클래스는 검출의 기하학적 속성(중심점, 경계 상자, 면적, 코드 값 등)을 노출하므로, 이를 직접 활용하거나 그리기 메서드(Image.draw_rectangle(), Image.draw_string(), …)에 다시 전달할 수 있습니다.

색 공간 헬퍼

이 모듈은 또한 binary / grayscale / RGB / LAB / YUV 색 공간 사이에서 개별 픽셀 값을 변환하는 작은 순수 함수들을 노출합니다. 이는 이미지 연산에 전달하기 전에 Python에서 임계값이나 팔레트 항목을 변환해야 할 때 유용합니다 – 전체 이미지 변환에는 Image 의 to_* 메서드를 사용하세요. 이는 이 헬퍼들을 루프에서 호출하는 것보다 훨씬 빠릅니다.

클래스

함수

색 공간 변환 헬퍼

아래의 각 X_to_Y 함수는 단일 픽셀 값 변환을 수행합니다. 모두 표준 OpenMV 범위의 값을 받고 반환합니다:

  • binary – int 0 – 1.

  • grayscale – int 0 – 255.

  • RGB – 8비트 정수의 (r, g, b) 튜플(각각 0 – 255).

  • LAB – L 은 0 – 100, A/B 는 -128 – 127 범위인 (l, a, b) 튜플.

  • YUV – Y 는 0 – 255, U/V 는 -128 – 127 범위인 (y, u, v) 튜플.

전체 이미지 변환에는 Image 의 to_* 메서드를 사용하세요. 이는 이 헬퍼들을 루프에서 호출하는 것보다 훨씬 빠릅니다.

image.binary_to_grayscale(value: int) → int

binary 값을 grayscale 값으로 변환합니다.

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

binary 값을 RGB 튜플로 변환합니다.

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

binary 값을 LAB 튜플로 변환합니다.

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

binary 값을 YUV 튜플로 변환합니다.

image.grayscale_to_binary(value: int) → int

grayscale 값을 binary 값으로 변환합니다.

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

grayscale 값을 RGB 튜플로 변환합니다.

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

grayscale 값을 LAB 튜플로 변환합니다.

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

grayscale 값을 YUV 튜플로 변환합니다.

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

RGB 튜플을 binary 값으로 변환합니다.

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

RGB 튜플을 grayscale 값으로 변환합니다.

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

RGB 튜플을 LAB 튜플로 변환합니다.

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

RGB 튜플을 YUV 튜플로 변환합니다.

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

LAB 튜플을 binary 값으로 변환합니다.

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

LAB 튜플을 grayscale 값으로 변환합니다.

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

LAB 튜플을 RGB 튜플로 변환합니다.

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

LAB 튜플을 YUV 튜플로 변환합니다.

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

YUV 튜플을 binary 값으로 변환합니다.

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

YUV 튜플을 grayscale 값으로 변환합니다.

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

YUV 튜플을 RGB 튜플로 변환합니다.

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

YUV 튜플을 LAB 튜플로 변환합니다.

특징 디스크립터

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

Haar Cascade를 로드하고 Image.find_features() 와 함께 사용할 Cascade 핸들을 반환합니다.

path 는 다음 중 하나일 수 있습니다:

  • 펌웨어 ROM에 내장된 두 개의 캐스케이드 중 하나를 로드하기 위한 리터럴 문자열 "frontalface" 또는 "eye", 또는

  • OpenMV 캐스케이드 변환 도구로 생성된 사용자 정의 .cascade 바이너리 파일에 대한 파일 시스템 경로.

stages 는 검출 시 평가할 캐스케이드 단계의 수를 선택합니다. -1 은 파일에 저장된 모든 단계를 사용합니다. 이 값을 줄이면 더 많은 오탐을 대가로 검출 속도가 빨라집니다.

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

path 의 파일에서 디스크립터를 로드하여 반환합니다. 파일의 내부 타입 태그가 어떤 디스크립터 클래스를 재구성할지 선택합니다:

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

descriptor (ORB 키포인트 또는 LBP 디스크립터)를 OpenMV 디스크립터 파일 형식으로 path 의 파일에 직렬화합니다. 동일한 파일은 나중에 image.load_descriptor() 를 통해 다시 로드할 수 있습니다.

image.match_descriptor(descriptor0, descriptor1, threshold: int = 85, filter_outliers: bool = False) → int | kptmatch

동일한 타입의 두 디스크립터를 매칭합니다.

  • 두 LBP 디스크립터의 경우 – 둘 사이의 정수 Hamming 거리를 반환합니다(값이 낮을수록 더 가까운 매칭).

  • 두 ORB 키포인트 디스크립터의 경우 – 매칭된 키포인트 클러스터를 설명하는 kptmatch 를 반환하거나, threshold 를 통과하는 매칭이 없으면 None 을 반환합니다.

threshold (0 – 100)는 키포인트 쌍을 받아들일 때 ORB 매칭이 얼마나 엄격할지를 설정합니다. 값이 낮을수록 약한 최근접 이웃 매칭을 거부하여 매칭을 더 엄격하게 만듭니다.

filter_outliers 는 매칭된 키포인트 집합 전반에 걸쳐 RANSAC 방식의 이상치 제거를 활성화합니다. 두 시점 사이에 단일 강체 변환이 예상될 때 사용하세요; 매칭된 키포인트가 여러 객체에 걸쳐 있을 때는 비활성화하세요.

블롭 기하 헬퍼

이 헬퍼들은 (Image.find_blobs() 가 반환하는) Blob 을 받아 추가적인 기하학적 속성을 필요 시 계산합니다. 이들은 Blob 이 아니라 모듈 범위에 존재하므로, 기본 find_blobs() 경로는 요청하지 않는 한 이에 대한 비용을 치르지 않습니다.

image.get_solidity(blob: blob) → float

blob 의 견고도(blob.pixels / convex_hull_area)를 반환합니다. 0 – 1 범위의 부동소수점; 1.0은 블롭이 볼록 껍질을 완전히 채움을 의미합니다.

image.get_convexity(blob: blob) → float

blob 의 볼록도(convex_hull_perimeter / blob.perimeter)를 반환합니다. 0 – 1 범위의 부동소수점; 1.0은 완벽하게 볼록한 블롭입니다.

image.get_major_axis_line(blob: blob) → line

blob 의 장축(최소 면적 회전 직사각형의 두 주축 중 더 긴 것)을 따르는 Line 을 반환합니다.

image.get_minor_axis_line(blob: blob) → line

blob 의 단축(최소 면적 회전 직사각형의 두 주축 중 더 짧은 것)을 따르는 Line 을 반환합니다.

image.get_enclosing_circle(blob: blob) → circle

blob 을 둘러싸는 Circle 을 반환합니다.

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

blob 주위의 최소 면적 회전 직사각형에 내접하는 타원을 설명하는 5-튜플 (cx, cy, a, b, rotation) 을 반환합니다:

  • cx / cy – 픽셀 단위 타원 중심(정수).

  • a / b – 픽셀 단위 반축 길이(정수).

  • rotation – 타원 회전 각도 (도 단위) (정수).

이것은 attrtuple이 아닌 일반 튜플이므로 필드는 인덱스로만 접근할 수 있습니다.

상수

픽셀 형식

다음 중 아무거나 Image 생성자나 csi.CSI.pixformat() 에 pixformat 인수로 전달하세요.

image.BINARY: int

픽셀당 1비트 비트맵. 가장 작은 형식 – 임계값 처리 및 모폴로지에서 내부적으로 사용되며 센서에서 직접 캡처되는 경우는 드뭅니다.

image.GRAYSCALE: int

픽셀당 8비트 grayscale(픽셀당 1바이트). 대부분의 컴퓨터 비전 알고리즘(AprilTag, 에지 검출, 옵티컬 플로우)에 가장 빠른 형식입니다.

image.RGB565: int

5비트 빨강 / 6비트 초록 / 5비트 파랑으로 패킹된 픽셀당 16비트 색상. 기본 색상 형식입니다.

image.BAYER: int

센서에서 바로 나온 픽셀당 8비트 원시 Bayer 데이터. 대부분의 이미지 처리 메서드는 Bayer 이미지에서 사용할 수 없습니다; 필요 시 디베이어 처리하거나 더 적은 메모리에 더 많은 픽셀을 저장하려는 경우 이를 사용하세요.

image.YUV422: int

4:2:2 크로마 서브샘플링 색상, 픽셀당 2바이트, 픽셀 쌍당 Y1, U, Y2, V 로 패킹됨. 일부 이미지 처리 메서드만 YUV422에서 직접 동작합니다.

image.JPEG: int

압축된 JPEG 버퍼. 픽셀 단위 연산을 하려면 먼저 Image.to_grayscale() 또는 Image.to_rgb565() 가 필요합니다.

image.PNG: int

압축된 PNG 버퍼. 픽셀 단위 연산을 하려면 먼저 Image.to_grayscale() 또는 Image.to_rgb565() 가 필요합니다.

색상 팔레트

grayscale 이미지에 색을 입히려면 다음 중 아무거나 Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) 또는 csi.CSI.color_palette() 에 전달하세요.

image.PALETTE_RAINBOW: int

부드러운 무지개 색상환. 열화상 이미지를 위한 기본 OpenMV 팔레트입니다.

image.PALETTE_IRONBOW: int

FLIR Lepton 열화상 뷰파인더의 모양을 모방하는 비선형 “ironbow” 팔레트.

image.PALETTE_DEPTH: int

깊이 이미지 팔레트. 깊이 센서 지원(ToF 파이프라인 – 예: OpenMV Cam AE3 또는 ToF Pmod가 부착된 모든 카메라)이 있는 빌드에서만 사용할 수 있습니다.

image.PALETTE_EVT_DARK: int

어두운 배경에서 GENX320 이벤트 카메라 프레임을 시각화하기 위한 팔레트. GENX320 드라이버가 히스토그램 모드에서 색상화된 RGB565 프레임을 출력하도록 하려면 csi.CSI.color_palette 에 전달하거나, grayscale 이벤트 이미지를 색상화할 때 Image.draw_image() 의 color_palette= 에 전달하세요.

GENX320 지원(OpenMV Cam AE3 및 GENX320 Pmod)이 있는 빌드에서만 사용할 수 있습니다.

image.PALETTE_EVT_LIGHT: int

밝은 배경에서 GENX320 이벤트 카메라 프레임을 시각화하기 위한 팔레트. PALETTE_EVT_DARK 와 동일한 디스패치 및 가용성을 가집니다.

스케일링 모드

다음 중 아무거나 Image.draw_image(), Image.scale() 또는 유사한 스케일링 메서드에 hint 인수로 전달하세요.

image.AREA: int

영역 평균 스케일러. 축소 시 사용됩니다; 확대에는 Nearest-Neighbor가 사용됩니다.

image.BILINEAR: int

이중 선형(Bilinear) 스케일러. 축소 시 서브샘플링합니다.

image.BICUBIC: int

이중 삼차(Bicubic) 스케일러. BILINEAR 보다 품질이 높지만 느립니다. 축소 시 서브샘플링합니다.

그리기 / draw_image 힌트

다음 중 아무거나 비트 OR로 결합하여 Image.draw_image() 의 hint 인수로 전달하세요.

image.VFLIP: int

그리는 동안 소스를 수직으로 뒤집습니다.

image.HMIRROR: int

그리는 동안 소스를 수평으로 미러링합니다.

image.TRANSPOSE: int

그리는 동안 소스를 전치합니다(x/y 교환).

image.CENTER: int

소스를 대상에 중앙 정렬합니다. 그러면 명시적인 x/y 오프셋은 좌상단이 아니라 중심으로부터의 오프셋이 됩니다.

image.EXTRACT_RGB_CHANNEL_FIRST: int

Image.draw_image() 를 통해 RGB 채널을 추출할 때, 스케일링 전에 채널을 추출합니다. 이 힌트가 없으면 스케일링 후에 채널이 추출됩니다.

image.APPLY_COLOR_PALETTE_FIRST: int

Image.draw_image() 를 통해 색상 팔레트를 적용할 때, 스케일링 전에 팔레트를 적용합니다. 이 힌트가 없으면 스케일링 후에 팔레트가 적용됩니다.

image.SCALE_ASPECT_KEEP: int

종횡비를 유지하면서 소스를 대상 안에 맞도록 스케일링합니다(비율이 다르면 레터박스 처리).

image.SCALE_ASPECT_EXPAND: int

종횡비를 유지하면서 소스를 대상에 채우도록 스케일링합니다(비율이 다르면 잘라냄).

image.SCALE_ASPECT_IGNORE: int

종횡비를 무시하고 소스를 대상에 채우도록 스케일링합니다.

image.BLACK_BACKGROUND: int

알파 블렌딩 경로에 대상이 검은색임이 확인되었음을 알려 대상 픽셀의 읽기 회수를 건너뛸 수 있게 합니다. 막 지워진 버퍼에서 알파 효과의 속도를 높입니다.

image.ROTATE_90: int

VFLIP | TRANSPOSE 의 단축(시계 방향 90도 회전).

image.ROTATE_180: int

HMIRROR | VFLIP 의 단축(180도 회전).

image.ROTATE_270: int

HMIRROR | TRANSPOSE 의 단축(시계 방향 270도 회전).

JPEG 서브샘플링

JPEG를 쓸 때 다음 중 아무거나 Image.to_jpeg(), Image.compress() 또는 Image.save() 에 subsampling 인수로 전달하세요.

image.JPEG_SUBSAMPLING_AUTO: int

JPEG 품질 설정에 따라 크로마 서브샘플링을 자동으로 선택합니다.

image.JPEG_SUBSAMPLING_444: int

4:4:4 크로마 서브샘플링을 강제합니다(크로마 압축 없음).

image.JPEG_SUBSAMPLING_422: int

4:2:2 크로마 서브샘플링을 강제합니다. 4:2:0에서 오작동하는 타사 비디오 플레이어로 MJPEG를 스트리밍할 때 권장됩니다.

image.JPEG_SUBSAMPLING_420: int

4:2:0 크로마 서브샘플링을 강제합니다.

템플릿 매칭

다음 중 하나를 Image.find_template() 에 search 인수로 전달하세요.

image.SEARCH_EX: int

전수 검색 – ROI의 모든 위치를 평가합니다. 가장 느리지만 최적의 매칭을 찾는 것이 보장됩니다.

image.SEARCH_DS: int

다이아몬드 검색 – SEARCH_EX 보다 훨씬 빠른 거친-에서-세밀한 검색이지만, 자기 유사성이 높은 템플릿에서는 전역 최적값을 놓칠 수 있습니다.

에지 검출

다음 중 하나를 Image.find_edges() 에 algorithm 인수로 전달하세요.

image.EDGE_CANNY: int

Canny 에지 검출기 – 그래디언트 크기 + 비최대 억제 + 히스테리시스. 품질이 더 높지만 느립니다.

image.EDGE_SIMPLE: int

임계값 처리된 고역 통과 필터 에지 검출기. 더 빠르지만 EDGE_CANNY 보다 더 두껍고 노이즈가 많은 에지를 생성합니다.

ORB 코너 검출기

다음 중 하나를 Image.find_keypoints() 에 corner_detector 인수로 전달하세요.

image.CORNER_FAST: int

FAST 코너 검출기. CORNER_AGAST 보다 빠르지만 정확도가 낮습니다.

image.CORNER_AGAST: int

AGAST 코너 검출기. CORNER_FAST 보다 느리지만 더 안정적인 키포인트를 생성합니다.

AprilTag 패밀리

다음의 조합을 비트 OR로 결합하여 Image.find_apriltags() 에 families 인수로 전달하세요. 각 패밀리는 펌웨어에서 자체 빌드 옵션으로 제어됩니다; 지원되지 않는 패밀리는 항상-0이 아니라 런타임에 부재합니다.

image.TAG16H5: int

AprilTag 16h5 패밀리(고유 ID 30개, 0비트 오류 정정).

image.TAG25H9: int

AprilTag 25h9 패밀리(고유 ID 35개, 최대 3비트 오류 정정).

image.TAG36H10: int

AprilTag 36h10 패밀리(고유 ID 2320개, 최대 3비트 오류 정정).

image.TAG36H11: int

AprilTag 36h11 패밀리(고유 ID 587개, 최대 4비트 오류 정정). 가장 일반적인 패밀리입니다.

image.TAGCIRCLE21H7: int

AprilTag Circle21h7 패밀리.

image.TAGCIRCLE49H12: int

AprilTag Circle49h12 패밀리.

image.TAGCUSTOM48H12: int

AprilTag Custom48h12 패밀리.

image.TAGSTANDARD41H12: int

AprilTag Standard41h12 패밀리.

image.TAGSTANDARD52H13: int

AprilTag Standard52h13 패밀리.

바코드 심볼로지

Image.find_barcodes() 가 반환하는 항목에 대해 BarCode.type 에 보고되는 값입니다.

image.EAN2: int

EAN-2 보조 바코드.

image.EAN5: int

EAN-5 보조 바코드.

image.EAN8: int

EAN-8 바코드.

image.UPCE: int

UPC-E 바코드.

image.ISBN10: int

ISBN-10 바코드.

image.UPCA: int

UPC-A 바코드.

image.EAN13: int

EAN-13 바코드.

image.ISBN13: int

ISBN-13 바코드.

image.I25: int

Interleaved 2-of-5 바코드.

image.DATABAR: int

GS1 DataBar 바코드.

image.DATABAR_EXP: int

GS1 DataBar Expanded 바코드.

image.CODABAR: int

Codabar 바코드.

image.CODE39: int

Code 39 바코드.

image.PDF417: int

PDF417 2D 적층형 바코드. 이 상수는 완전성을 위해 존재하지만, 바코드 디코더는 현재 PDF417을 구현하지 않습니다 – Image.find_barcodes() 는 이 타입의 검출을 반환하지 않습니다.

image.CODE93: int

Code 93 바코드.

image.CODE128: int

Code 128 바코드.