class Image -- 影像物件¶

Image 是 image 模組的核心資料型別——一個記憶體內的像素緩衝區，所有繪製常式、所有濾鏡、所有幾何變換以及所有特徵擷取常式都在其上運作。從 csi.CSI.snapshot() 取得的每一個影格都是 Image；從磁碟載入、由 JPEG 或 PNG 解碼、從 numpy 風格的 ndarray 配置而來，或建構為空白繪圖畫布的每一個影格也同樣如此。

Image 由三個數字——width、height 與 pixformat——加上一段連續的像素緩衝區所描述。像素格式同時決定了記憶體內的排列方式以及可用的操作：

BINARY (1 bpp)——每像素 1 位元；供形態學運算與閾值化使用。
GRAYSCALE (8 bpp)——每像素 1 位元組；是大多數電腦視覺運算（AprilTag、邊緣、ORB、光流）的標準格式。
RGB565 (16 bpp)——每像素 2 位元組（5R/6G/5B）；預設的色彩格式。
BAYER (8 bpp)——直接來自感測器的原始 Bayer 馬賽克資料。大多數電腦視覺方法無法用於 Bayer 影像；請先去馬賽克（debayer）為 GRAYSCALE / RGB565。
YUV422 (16 bpp)——4:2:2 色度次取樣的色彩格式，每像素兩個位元組。只有部分方法能直接在 YUV422 上運作。
JPEG / PNG——壓縮的緩衝區。進行像素層級的操作前需先呼叫 to_grayscale() 或 to_rgb565()。

Image 物件的來源¶

取得 Image 有四種方式：

從相機影格緩衝區——csi.CSI().snapshot() 會回傳下一個擷取到的影格。回傳的物件是對相機影格緩衝區記憶體的輕量包裝，因此對其進行任何繪製 / 濾鏡操作都會改變傳送到 IDE 預覽與顯示器的內容。
從檔案——將路徑字串傳給 Image 建構式。BMP、PGM、PPM、JPEG 與 PNG 會直接解碼到 RAM（若 copy_to_fb=True 則解碼到相機影格緩衝區）。
從 ndarray——傳入 (h, w) 或 (h, w, 3) 的 float32 陣列。像素值會分別從 0.0 -- 255.0 縮放為 GRAYSCALE 或 RGB565。
空白——傳入 (width, height, pixformat) 以配置一個填零的繪圖表面。對於壓縮的像素格式（JPEG / PNG）必須提供 buffer= 引數來存放壓縮的位元組串流。

典型的擷取-處理-顯示迴圈¶

import csi
import image

sensor = csi.CSI()
sensor.reset()
sensor.pixformat(csi.RGB565)
sensor.framesize(csi.QVGA)

while True:
    img = sensor.snapshot()                    # capture
    for blob in img.find_blobs([(30, 100, 15, 127, 15, 127)]):  # process
        img.draw_rectangle(blob.rect)          # annotate
    # img is shown automatically in the IDE preview and on any
    # attached display.

索引、長度、迭代與類位元組存取¶

索引——img[i] 讀取像素 i（以列為主、線性方式）。img[i] = value 寫入該像素。灰階 / Bayer 像素為 8 位元整數，RGB565 / YUV422 像素為 16 位元打包整數，二值像素為 0 / 1。對於 JPEG / PNG 影像，索引空間是壓縮的位元組串流，而非像素。
長度——對於未壓縮格式，len(img) 回傳像素數量；對於壓縮格式則回傳位元組數。
迭代——for px in img: ... 會以與 [] 索引相同的順序走訪像素陣列。
類位元組——Image 公開了讀取緩衝區協定，因此你可以將它直接傳給任何接受 bytes / bytearray 的對象（例如 uart.write(img)、socket.send(img)、hashlib.sha256(img)）。若需取得可讀寫的檢視，請改用 bytearray()。

提示旗標¶

許多 Image 方法接受 hint 引數，它是以下旗標的邏輯 OR：

image.AREA：縮小時使用區域縮放，而非預設的最近鄰插值。

image.BILINEAR：使用雙線性縮放，而非預設的最近鄰縮放。

image.BICUBIC：使用雙三次縮放，而非預設的最近鄰縮放。

image.CENTER：將繪製的影像置於顯示器中央。此項在縮放之後套用。

image.HMIRROR：水平鏡像影像。

image.VFLIP：垂直翻轉影像。

image.TRANSPOSE：轉置影像（交換 x/y）。

image.EXTRACT_RGB_CHANNEL_FIRST：在縮放之前先進行 rgb_channel 擷取。

image.APPLY_COLOR_PALETTE_FIRST：在縮放之前先套用色彩調色盤。

image.SCALE_ASPECT_KEEP：縮放繪製的影像使其容納於顯示器內。

image.SCALE_ASPECT_EXPAND：縮放繪製的影像使其填滿顯示器（會造成裁切）。

image.SCALE_ASPECT_IGNORE：縮放繪製的影像使其填滿顯示器（會造成拉伸）。

image.ROTATE_90：將影像旋轉 90 度（這只是 VFLIP | TRANSPOSE）。

image.ROTATE_180：將影像旋轉 180 度（這只是 HMIRROR | VFLIP）。

image.ROTATE_270：將影像旋轉 270 度（這只是 HMIRROR | TRANSPOSE）。

image.BLACK_BACKGROUND：假設被繪製的背景影像為黑色以加速混合。僅 Image.draw_image() 與 Image.get_similarity() 支援。

若 arg 是字串，則此項會從 arg 路徑的檔案建立一個新的影像物件。支援從磁碟載入 bmp/pgm/ppm/jpg/jpeg/png 影像檔。若 copy_to_fb 為真，影像會被複製到影格緩衝區，而非配置於堆積上。

若 arg 是 ndarray，則此項會從該 ndarray 建立一個新的影像物件。形狀為 (w, h) 的 ndarray 物件會被視為灰階影像，(w, h, 3) 則被視為 RGB565 影像。目前僅支援 float32 浮點的 ndarrays。以此方式建立影像時，若你傳入 buffer 引數，它會被用來儲存影像資料，而非在堆積上配置空間。若 copy_to_fb 為真，影像會被複製到影格緩衝區，而非配置於堆積上或使用 buffer。

若 arg 是 int，則它會被視為新影像的寬度，且後面必須接著一個 height 值與一個 format 值來建立新的空白影像物件。format 可以是任何影像 pixformat 值，例如 image.GRAYSCALE。影像會被初始化為全零。請注意，壓縮影像格式需要 buffer 值。以此方式建立影像時，buffer 會被視為影像資料的來源。若與 copy_to_fb 一起使用，buffer 的資料會被複製到影格緩衝區。若你想從 JPEG bytes() 或 bytearray() 物件建立 JPEG 影像，可傳入 JPEG 的 width、height、image.JPEG，並將 buffer 設為 JPEG 位元組串流以建立 JPEG 影像。

影像支援「[]」標記法。使用 image[index] = 8/16-bit value 來指派影像像素，或使用 image[index] 來取得影像像素；對於灰階/bayer 影像會是 8 位元值，對於 RGB565/YUV 影像會是 16 位元值。二值影像則回傳 1 位元值。

對於 JPEG 影像，「[]」可讓你以位元組陣列的形式存取壓縮的 JPEG 影像 blob。但對該資料陣列的讀寫是不透明的，因為 JPEG 影像是壓縮的位元組串流。

影像也支援讀取緩衝區操作。你可以將影像傳給各種 MicroPython 函式，就如同影像是位元組陣列物件一樣。特別是，若你想傳輸影像，只需將它傳給 UART/SPI/I2C 寫入函式即可自動傳輸。

基本方法¶

width() → int¶: 回傳影像寬度（像素）。

height() → int¶: 回傳影像高度（像素）。

format() → int¶: 對灰階影像回傳 image.GRAYSCALE，對 RGB565 影像回傳 image.RGB565，對 bayer 樣式影像回傳 image.BAYER，對 JPEG 影像回傳 image.JPEG。

size() → int¶: 回傳影像大小（位元組）。

bytearray() → bytearray¶: 回傳一個指向影像資料的 bytearray 物件，用於位元組層級的讀/寫存取。

備註

當影像物件被傳給需要 bytes 類物件的 MicroPython 驅動程式時，會自動被轉型為 bytes 物件。這是唯讀存取。呼叫 bytearray() 以取得讀/寫存取。

get_pixel(x: int, y: int, rgbtuple: bool | None = None) → int | Tuple[int, int, int]¶

對於灰階影像：回傳位置 (x, y) 的灰階像素值。對於 RGB565 影像：回傳位置 (x, y) 的 RGB888 像素元組 (r, g, b)。對於 bayer 樣式影像：回傳位置 (x, y) 的像素值。

若 x 或 y 在影像範圍之外則回傳 None。

x 與 y 可以分別傳入，或以元組形式傳入。

rgbtuple 若為 True 會使此方法回傳 RGB888 元組。否則，此方法回傳底層像素的整數值。亦即對於 RGB565 影像，此方法回傳 RGB565 值。對於 RGB565 影像預設為 True，其餘情況預設為 False。

不支援壓縮影像。

備註

Image.get_pixel() 與 Image.set_pixel() 是唯一能讓你操作 bayer 樣式影像的方法。Bayer 樣式影像是字面上的影像，其中偶數列的像素為 R/G/R/G/…，奇數列為 G/B/G/B/…。每個像素為 8 位元。若你在呼叫此方法時設定了 rgbtuple，則 Image.get_pixel() 會在該像素位置對來源影像去馬賽克，並回傳該像素位置有效的 RGB888 元組。

set_pixel(x: int, y: int, pixel: int | Tuple[int, int, int]) → Image¶

對於灰階影像：將位置 (x, y) 的像素設為灰階值 pixel。對於 RGB565 影像：將位置 (x, y) 的像素設為 RGB888 元組 (r, g, b) pixel。對於 bayer 樣式影像：將位置 (x, y) 的像素值設為 pixel。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

x 與 y 可以分別傳入，或以元組形式傳入。

pixel 可以是 RGB888 元組 (r, g, b) 或底層像素值（亦即對 RGB565 影像為 RGB565 值，對灰階影像為 8 位元值）。

不支援壓縮影像。

備註

Image.get_pixel() 與 Image.set_pixel() 是唯一能讓你操作 bayer 樣式影像的方法。Bayer 樣式影像是字面上的影像，其中偶數列的像素為 R/G/R/G/…，奇數列為 G/B/G/B/…。每個像素為 8 位元。若你在呼叫此方法時傳入 RGB888 元組，則會擷取該 RGB888 元組的灰階值並設定到該像素位置。

轉換方法¶

to_ndarray(dtype: str, buffer: bytes | bytearray | memoryview | None = None) → ndarray¶

回傳一個從影像建立的 ndarray 物件。目前僅適用於 GRAYSCALE 或 RGB565 影像。

dtype 可以是 b、B 或 f，分別用於建立有號 8 位元、無號 8 位元或 32 位元浮點的 ndarray。GRAYSCALE 影像會直接轉換為無號 8 位元 ndarray 物件。對於有號 8 位元 ndarray 物件，值 (0:255) 會被對應到 (-127:128)。對於浮點 32 位元 ndarray 物件，值會被對應到 (0.0:255.0)。RGB565 影像會被轉換為 3 通道 ndarray 物件，並依 dtype 對每個通道套用上述針對 GRAYSCALE 影像所描述的相同程序。請注意，dtype 也接受 b、B 與 f 各自的整數值（例如 ord()）。

buffer 若不為 None，則為用作 ndarray 緩衝區的 bytearray 物件。若為 None，則會在堆積上配置一個新緩衝區來儲存 ndarray 影像資料。你可以使用 buffer 引數直接在預先配置的緩衝區中配置 ndarray，省去一次堆積配置與一次複製操作。

回傳的 ndarray 對於 GRAYSCALE 影像具有 (height, width) 的形狀，對於 RGB565 影像具有 (height, width, 3) 的形狀。

to_bitmap(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為點陣圖影像（每像素 1 位元）。

x_scale 控制顯示影像在 x 方向上的縮放程度（浮點）。若此值為負，影像會被水平翻轉。請注意，若未指定 y_scale，則它會與 x_scale 一致以維持長寬比。

y_scale 控制顯示影像在 y 方向上的縮放程度（浮點）。若此值為負，影像會被垂直翻轉。請注意，若未指定 x_scale，則它會與 x_scale 一致以維持長寬比。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

rgb_channel 是要從 RGB565 影像（若有傳入）擷取並渲染到目標影像上的 RGB 通道（0=R、1=G、2=B）。例如，若你傳入 rgb_channel=1，這會擷取來源 RGB565 影像的綠色通道並以灰階繪製到目標影像上。

alpha 控制要將多少來源影像混合到目標影像中。值為 255 會繪製不透明的來源影像，而低於 255 的值會在來源與目標影像之間產生混合。0 則表示不修改目標影像。

color_palette 若不為 None，可以是色彩調色盤列舉值，或一個總計 256 像素的 RGB565 影像，用作對來源影像（無論其格式）灰階值的色彩查找表。若有使用 rgb_channel 擷取，則此項在其後套用。

alpha_palette 若不為 None，可以是一個總計 256 像素的 GRAYSCALE 影像，用作 alpha 調色盤，以在像素層級調變所繪製來源影像的 alpha 值，讓你能根據像素的灰階值精確控制其 alpha 值。alpha 查找表中值為 255 的像素為不透明，任何低於 255 的值則越趨透明，直到 0。若有使用 rgb_channel 擷取，則此項在其後套用。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

備註

點陣圖影像就像灰階影像，但只有兩種像素值——0 與 1。此外，點陣圖影像經過打包，因此每像素僅儲存 1 位元，使其非常小。OpenMV 影像函式庫允許在所有可使用 sensor.GRAYSCALE 與 sensor.RGB565 影像的場合使用點陣圖影像。然而，許多操作套用於點陣圖影像時並無意義，因為點陣圖影像只有 2 種值。OpenMV 建議在操作中將點陣圖影像用於 mask 值之類的用途，因為它們很容易容納於 MicroPython 堆積上。最後，當套用於 sensor.GRAYSCALE 或 sensor.RGB565 影像時，點陣圖影像的像素值 0 與 1 會被解讀為黑色與白色。函式庫會自動處理轉換。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_grayscale(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為灰階影像（每像素 8 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_rgb565(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 RGB565 影像（每像素 16 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_rainbow(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_RAINBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 RGB565 彩虹影像（每像素 16 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_ironbow(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 RGB565 鐵紅熱像影像（每像素 16 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_depth(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 RGB565 深度影像（每像素 16 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

color_palette 若不為 None，可以是 image.PALETTE_DEPTH，或一個總計 256 像素的 RGB565 影像，用作對來源影像（無論其格式）灰階值的色彩查找表。若有使用 rgb_channel 擷取，則此項在其後套用。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_evt_dark(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 RGB565 暗事件影像（每像素 16 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_evt_light(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 RGB565 亮事件影像（每像素 16 位元）。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_jpeg(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False, quality: int = 90, subsampling: int = 0) → Image¶

將影像轉換為 JPEG 影像。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

quality 控制 jpeg 影像壓縮品質。值可介於 0 與 100 之間。

subsampling 可以是：

image.JPEG_SUBSAMPLING_AUTO：根據品質為影像使用最佳的次取樣。

image.JPEG_SUBSAMPLING_444：使用 4:4:4 次取樣。

image.JPEG_SUBSAMPLING_422：使用 4:2:2 次取樣。

image.JPEG_SUBSAMPLING_420：使用 4:2:0 次取樣。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

to_png(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

將影像轉換為 PNG 影像。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

compress(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False, quality: int = 90, subsampling: int = 0) → Image¶

將影像轉換為 JPEG 影像。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

quality 控制 jpeg 影像壓縮品質。值可介於 0 與 100 之間。

subsampling 可以是：

image.JPEG_SUBSAMPLING_AUTO：根據品質為影像使用最佳的次取樣。

image.JPEG_SUBSAMPLING_444：使用 4:4:4 次取樣。

image.JPEG_SUBSAMPLING_422：使用 4:2:2 次取樣。

image.JPEG_SUBSAMPLING_420：使用 4:2:0 次取樣。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

備註

Image.compress 是 Image.to_jpeg 的別名。

copy(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy_to_fb: bool = False) → Image¶

建立影像物件的深層複本。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

crop(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

就地修改影像，而不變更底層的影像型別。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

scale(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

就地修改影像，而不變更底層的影像型別。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（不含此處不支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

copy 若為 True，會在堆積上建立已轉換影像的深層複本，而非就地轉換原始影像。

copy_to_fb 若為 True，影像會被直接載入影格緩衝區。copy_to_fb 的優先權高於 copy。若影像已在影格緩衝區中則無特殊效果。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

備註

Image.scale 是 Image.crop 的別名。

save(path: str, roi: Tuple[int, int, int, int] | None = None, quality: int = 50) → Image¶

將影像的複本儲存到檔案系統的 path。

支援 bmp/pgm/ppm/jpg/jpeg 影像檔。請注意，你無法將 jpeg 壓縮影像儲存為未壓縮格式。

roi 是要從中儲存的感興趣區域矩形 (x, y, w, h)。若未指定，則等於影像矩形，即複製整張影像。此引數不適用於 JPEG 影像。

quality 是當影像尚未壓縮時，用來將影像儲存為 jpeg 格式的 jpeg 壓縮品質 (0-100)（int）。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

flush() → None¶: 以相機影格緩衝區中的影像更新 IDE 中的影格緩衝區。

繪製方法¶

clear(mask: Image | None = None) → Image¶

將影像中所有像素設為零（非常快速）。

mask 是用作此操作之像素層級遮罩的另一張影像。遮罩應為僅含黑色或白色像素的影像，且應與被操作的影像大小相同。只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像。

draw_line(x0: int, y0: int, x1: int, y1: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1) → Image¶

在影像上從 (x0, y0) 到 (x1, y1) 繪製一條線。你可以分別傳入 x0、y0、x1、y1，或以元組 (x0, y0, x1, y1) 傳入。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

thickness 控制線條的粗細（像素）。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_rectangle(x: int, y: int, w: int, h: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1, fill: bool = False) → Image¶

在影像上繪製一個矩形。你可以分別傳入 x、y、w、h，或以元組 (x, y, w, h) 傳入。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

thickness 控制線條的粗細（像素）。

將 fill 設為 True 以填滿矩形。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_circle(x: int, y: int, radius: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1, fill: bool = False) → Image¶

在影像上繪製一個圓形。你可以分別傳入 x、y、radius，或以元組 (x, y, radius) 傳入。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

thickness 控制邊緣的粗細（像素）。

將 fill 設為 True 以填滿圓形。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_ellipse(cx: int, cy: int, rx: int, ry: int, rotation: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1, fill: bool = False) → Image¶

在影像上繪製一個橢圓。你可以分別傳入 cx、cy、rx、ry 與旋轉角度（度數），或以元組 (cx, yc, rx, ry, rotation) 傳入。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

thickness 控制邊緣的粗細（像素）。

將 fill 設為 True 以填滿橢圓。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_string(x: int, y: int, text: str, color: int | Tuple[int, int, int] | None = None, scale: float = 1, x_spacing: int = 0, y_spacing: int = 0, mono_space: bool = True, char_rotation: int = 0, char_hmirror: bool = False, char_vflip: bool = False, string_rotation: int = 0, string_hmirror: bool = False, string_vflip: bool = False) → Image¶

在影像中從位置 (x, y) 開始繪製 8x10 文字。你可以分別傳入 x、y，或以元組 (x, y) 傳入。

text 是要寫入影像的字串。\n、\r 與 \r\n 行尾會將游標移到下一行。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

scale 可加大以增大／縮小影像上文字的大小。你可以傳入大於 0 的整數或浮點值。

x_spacing 讓你在字元之間增加（若為正）或減少（若為負）x 像素。

y_spacing 讓你在字元之間增加（若為正）或減少（若為負）y 像素（用於多行文字）。

mono_space 預設為 True，會強制文字等寬排列。對於較大的文字縮放這看起來很糟。設為 False 以取得非固定寬度的字元間距，看起來會好上許多。

char_rotation 可為 0、90、180、270，將字串中每個字元旋轉此角度。

char_hmirror 若為 True，會水平鏡像字串中所有字元。

char_vflip 若為 True，會垂直翻轉字串中所有字元。

string_rotation 可為 0、90、180、270，將字串旋轉此角度。

string_hmirror 若為 True，會水平鏡像字串。

string_vflip 若為 True，會垂直翻轉字串。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_cross(x: int, y: int, color: int | Tuple[int, int, int] | None = None, size: int = 5, thickness: int = 1) → Image¶

在位置 x, y 繪製一個十字。你可以分別傳入 x、y，或以元組 (x, y) 傳入。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

size 控制十字線條延伸的長度。

thickness 控制邊緣的粗細（像素）。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_arrow(x0: int, y0: int, x1: int, y1: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1) → Image¶

在影像上從 (x0, y0) 到 (x1, y1) 繪製一個箭頭。你可以分別傳入 x0、y0、x1、y1，或以元組 (x0, y0, x1, y1) 傳入。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

thickness 控制線條的粗細（像素）。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_detection(detection: Tuple[int, int, int, int, int, int], color1: int | Tuple[int, int, int] | None = None, color2: int | Tuple[int, int, int] | None = None, size: int = 5, thickness: int = 1, fill: bool = False, label: str | None = None, label_offset: Tuple[int, int] | None = None) → Image¶

在影像上繪製偵測結果。detection 是一個 6 元組 (rx, ry, rw, rh, cx, cy)，描述一個邊界矩形與一個質心（通常由神經網路或色彩追蹤程式碼回傳）。

color1 是矩形顏色，color2 是質心十字顏色。size 是質心十字大小，thickness 控制外框寬度，fill 則填滿矩形。

label 若有提供，會繪製於矩形附近，並以 label_offset (x, y) 偏移。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_edges(corners: List[Tuple[int, int]], color: int | Tuple[int, int, int] | None = None, size: int = 0, thickness: int = 1, fill: bool = False) → Image¶

在由 blob.corners 等方法回傳的角點列表之間繪製線條邊緣。Corners 是一個由兩值 x/y 元組組成的四值元組。例如 [(x1,y1),(x2,y2),(x3,y3),(x4,y4)]。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

size 若大於 0，會將角點繪製為半徑為 size 的圓形。

thickness 控制線條的粗細（像素）。

若有繪製角點圓形，將 fill 設為 True 以填滿它們。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

draw_image(image: Image, x: int = 0, y: int = 0, x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, mask: Image | None = None) → Image¶

繪製一張左上角起於位置 x, y 的 image。你可以分別傳入 x、y，或以元組 (x, y) 傳入。此方法會自動處理將傳入的影像渲染為目標影像的正確像素格式，同時無縫處理裁切。

你也可以為此方法傳入路徑而非影像物件，以一步自動從磁碟載入影像並使用它。例如 draw_image("test.jpg")。

roi 是來源影像要繪製的感興趣區域矩形元組 (x, y, w, h)。這讓你能僅擷取 ROI 內的像素來縮放並繪製到目標影像上。

hint 是提示旗標中所列旗標的邏輯 OR（含此處支援的 image.BLACK_BACKGROUND）。

transform 是用來對影像執行透視變換的 3x3 ndarray。目前僅 OpenMV Cam N6 支援，因為它具有可用硬體完成此運算的 GPU。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

draw_keypoints(keypoints: kp_desc | List[Tuple[int, int, int]], color: int | Tuple[int, int, int] | None = None, size: int = 10, thickness: int = 1, fill: bool = False) → Image¶

在影像上繪製 keypoints 物件的關鍵點。你也可以傳入一個由三值元組 (x, y, rotation_angle_in_degrees) 組成的列表，以重複利用此方法繪製關鍵點符號，亦即一個帶有指向特定方向之線條的圓形。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

size 控制關鍵點的大小。

thickness 控制線條的粗細（像素）。

將 fill 設為 True 以填滿關鍵點。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

flood_fill(x: int, y: int, seed_threshold: float = 0.05, floating_threshold: float = 0.05, color: int | Tuple[int, int, int] | None = None, invert: bool = False, clear_background: bool = False, mask: Image | None = None) → Image¶

從位置 x, y 開始對影像的某個區域進行漫水填充。你可以分別傳入 x、y，或以元組 (x, y) 傳入。

seed_threshold 控制填充區域中任何像素與原始起始像素的差異可達多少。

floating_threshold 控制填充區域中任何像素與任何相鄰像素的差異可達多少。

color 對於灰階或 RGB565 影像是 RGB888 元組。預設為白色。然而，你也可以傳入灰階影像的底層像素值 (0-255) 或 RGB565 影像的 RGB565 值。

將 invert 傳為 True 以重新著色漫水填充連通區域以外的所有部分。

將 clear_background 傳為 True 以將漫水填充未重新著色的其餘像素歸零。

mask 是用作此操作之像素層級遮罩的另一張影像。遮罩應為僅含黑色或白色像素的影像，且應與被操作的影像大小相同。漫水填充時只有遮罩中被設定的像素才會被評估。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

OpenMV Cam M4 上不提供此方法。

draw_event_histogram(array: ndarray, clear: bool = True, brightness: int = 128, contrast: int = 16) → Image¶

將事件 ndarray（由 csi.IOCTL_GENX320_READ_EVENTS 填入）光柵化到 Image 上以供視覺化。影像緩衝區必須是 320x320 GRAYSCALE 影像。

對於每個 csi.PIX_ON_EVENT 列，該事件的像素會被加上 +contrast；對於每個 csi.PIX_OFF_EVENT 列，該像素會被加上 -contrast。觸發事件會被忽略。像素值會被箝制在 0-255。

clear 若為 True，會在繪製前將影像緩衝區重設為 brightness——每個影格都成為全新的純事件渲染。設為 False 則跨多次呼叫累積事件（對長曝光的運動軌跡很有用）。

brightness 控制當 clear 為 True 時緩衝區所重設到的中灰基準值。預設 128 會將 ON 事件置於亮端、OFF 事件置於暗端，並具有相等的餘裕。

contrast 控制每個事件對其像素的偏移量——較高的值會讓事件更突出，但代價是當許多事件落在同一像素上時會迅速飽和。

遮罩方法¶

mask_rectangle(x: int, y: int, w: int, h: int) → Image¶

將影像的矩形部分歸零。若未提供任何引數，此方法會將影像中央歸零。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

mask_circle(x: int, y: int, radius: int) → Image¶

將影像的圓形部分歸零。若未提供任何引數，此方法會將影像中央歸零。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

mask_ellipse(x: int, y: int, radius_x: int, radius_y: int, rotation_angle_in_degrees: int) → Image¶

將影像的橢圓形部分歸零。若未提供任何引數，此方法會將影像中央歸零。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

二值方法¶

binary(thresholds: List[Tuple[int, int]], invert: bool = False, zero: bool = False, mask: Image | None = None, to_bitmap: bool = False, copy: bool = False) → Image¶

依據每個像素是否落在 thresholds 中其中一個閾值元組內，將影像中所有像素設為黑色或白色。

thresholds 對於灰階影像是 (lo, hi) 元組的列表，對於 RGB565 影像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元組的列表。對調的最小／最大值會被自動修正；缺少的分量預設為最大範圍。

invert 反轉閾值匹配。

zero 若為 True，會將通過閾值的像素歸零並保留其餘像素不變。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

to_bitmap 若為 True，會將影像資料轉換為每像素 1 位元的點陣圖。對於非常小的影像，這可能需要 copy=True。

copy 若為 True，會在堆積上回傳一張新影像，而非修改來源影像。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

invert() → Image¶

反轉影像中所有像素值（每個 8 位元通道的像素變成 255 - pixel）。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

b_and(image: Image, mask: Image | None = None) → Image¶

將此影像與另一張影像進行邏輯 AND。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

b_nand(image: Image, mask: Image | None = None) → Image¶

將此影像與另一張影像進行邏輯 NAND。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

b_or(image: Image, mask: Image | None = None) → Image¶

將此影像與另一張影像進行邏輯 OR。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

b_nor(image: Image, mask: Image | None = None) → Image¶

將此影像與另一張影像進行邏輯 NOR。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

b_xor(image: Image, mask: Image | None = None) → Image¶

將此影像與另一張影像進行邏輯 XOR。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

b_xnor(image: Image, mask: Image | None = None) → Image¶

將此影像與另一張影像進行邏輯 XNOR。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

ISP 方法¶

awb(max: bool = False) → Image¶

使用灰世界（gray-world）演算法對影像執行自動白平衡。可在 RAW Bayer 或 RGB565 影像上運作。對二值/灰階影像無效。

max 若為 True，改用白塊（white-patch）演算法。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 yuv 影像。

ccm(matrix: List[List[float]]) → Image¶

將傳入的浮點色彩校正矩陣與影像相乘。矩陣可為 3x3 或 3x4（含偏移欄），以巢狀列表或扁平列表形式表示:

[[rr, rg, rb], [gr, gg, gb], [br, bg, bb]]
[[rr, rg, rb, ro], [gr, gg, gb, go], [br, bg, bb, bo]]
[rr, rg, rb, ro, gr, gg, gb, go, br, bg, bb, bo]

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

gamma(gamma: float = 1.0, contrast: float = 1.0, brightness: float = 0.0) → Image¶

調整影像的 gamma、對比與亮度。

gamma 在正規化後套用 pow(pixel, 1/gamma)。大於 1.0 的值會變亮；小於 1.0 的值會變暗。

contrast 在正規化後套用 pixel * contrast。

brightness 在正規化後套用 pixel + brightness。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

gamma_corr(gamma: float = 1.0, contrast: float = 1.0, brightness: float = 0.0) → Image¶: Image.gamma 的別名。

數學方法¶

negate() → Image¶: Image.invert 的別名。

replace(image: Image | None = None, **kwargs) → Image¶: Image.draw_image() 的別名。以 image 取代此影像（若省略 image 則就地變換此影像），並使用標準的 draw_image 關鍵字引數。transform 引數是描述透視變換的 3x3 ndarray（僅在啟用 ULAB 的 OpenMV 相機上支援）。

assign(image: Image | None = None, **kwargs) → Image¶: Image.replace() 的別名。

set(image: Image | None = None, **kwargs) → Image¶: Image.replace() 的別名。

add(image: Image, mask: Image | None = None) → Image¶

將一張影像以像素為單位加到此影像上。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

sub(image: Image, mask: Image | None = None) → Image¶

將 image 以像素為單位從此影像中減去（self - image）。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

此方法也接受 Image.draw_image() 的完整關鍵字引數集（x、y、x_scale、y_scale、roi、rgb_channel、alpha、color_palette、alpha_palette、hint、transform）。

不支援壓縮影像或 bayer 影像。

rsub(image: Image, mask: Image | None = None) → Image¶: 反向相減：以像素為單位將此影像取代為 image - self。其餘與 Image.sub() 相同。

min(image: Image, mask: Image | None = None) → Image¶

以像素為單位回傳兩張影像的最小值影像。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

max(image: Image, mask: Image | None = None) → Image¶

以像素為單位回傳兩張影像的最大值影像。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

difference(image: Image, mask: Image | None = None) → Image¶

回傳兩張影像之間以像素為單位的絕對差影像（例如 ||a-b||）。

image 可以是影像物件、未壓縮影像檔的路徑 (bmp/pgm/ppm)，或純量值（RGB888 元組或底層像素值）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

blend(image: Image, x: int = 0, y: int = 0, alpha: int = 128, mask: Image | None = None, **kwargs) → Image¶: Image.draw_image() 的別名。將 image 以 alpha 混合方式融入此影像。alpha 是 0-256 的整數；越接近 256 越偏向來源影像。接受所有 Image.draw_image() 關鍵字引數。

histeq(adaptive: bool = False, clip_limit: float = -1, mask: Image | None = None) → Image¶

對影像執行直方圖均衡化以正規化對比與亮度。

adaptive 若為 True，會執行自適應直方圖均衡化（較慢但通常較佳）。

clip_limit 在自適應變體中限制對比（像 10 這樣的小值可產生良好的 CLAHE 結果）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

濾波方法¶

erode(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

從分割區域的邊緣移除像素。在影像上卷積一個 ((size*2)+1)x((size*2)+1) 的核，若有超過 threshold 個相鄰像素為清除狀態，則清除中央像素（當 threshold 為 None 時作為標準腐蝕運算）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

dilate(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

在分割區域的邊緣加上像素。在影像上卷積一個 ((size*2)+1)x((size*2)+1) 的核，若有超過 threshold 個相鄰像素為設定狀態，則設定中央像素（當 threshold 為 None 時作為標準膨脹運算）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

open(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

先腐蝕後膨脹。參見 Image.erode() 與 Image.dilate()。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

不支援壓縮影像或 bayer/yuv 影像。

close(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

先膨脹後腐蝕。參見 Image.dilate() 與 Image.erode()。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

不支援壓縮影像或 bayer/yuv 影像。

top_hat(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

回傳影像與經 Image.open() 處理後影像之間的影像差。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

不支援壓縮影像或 bayer/yuv 影像。

black_hat(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

回傳影像與經 Image.close() 處理後影像之間的影像差。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

不支援壓縮影像或 bayer/yuv 影像。

mean(size: int, threshold: bool | None = False, offset: int | None = 0, invert: bool | None = False, mask: Image | None = None) → Image¶

使用方框濾波器的標準均值模糊濾鏡。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

threshold 若為 True，會自適應地將濾鏡輸出閾值化為二值影像。offset 移動二值化結果（負值使更多像素變白，正值使更少像素變白）。invert 反轉二值輸出。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

對影像執行百分位數濾鏡（預設為中值）。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

percentile 是要從每個核中選取的百分位數（0 = 最小、0.5 = 中值、1.0 = 最大）。預設為 0.5。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

mode(size: int, threshold: bool | None = False, offset: int | None = 0, invert: bool | None = False, mask: Image | None = None) → Image¶

以每個像素鄰域的眾數取代該像素。由於此非線性操作，可能在 RGB 影像邊緣產生假影。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

對影像執行中點濾鏡。此濾鏡會求出影像中每個像素鄰域的中點 ((max-min)/2)。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

bias 控制最小／最大的混合。0 表示僅最小值濾波，1.0 表示僅最大值濾波。透過 bias 你可以對影像進行最小／最大濾波。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

以任意的濾波核對影像進行卷積。

size 控制核大小，必須為 ((size*2)+1)x((size*2)+1) 個元素。

kernel 是要卷積的核，為含 ((size*2)+1)*((size*2)+1) 個元素的扁平 1D 列表/元組，或為含 ((size*2)+1) 列、每列 ((size*2)+1) 個元素的 2D 列表/元組。

mul 是乘法式的對比縮放（預設 1.0）。

add 是加法式的亮度偏移（預設 0.0）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

以平滑高斯核對影像進行卷積。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

unsharp 若為 True，會執行 unsharp 遮罩操作（銳化邊緣）而非單純的高斯模糊。

mul 是乘法式的對比縮放（預設 1.0）。

add 是加法式的亮度偏移（預設 0.0）。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

laplacian(size: int, sharpen: bool | None = False, mul: float | None = 1.0, add: float | None = 0.0, threshold: bool | None = False, offset: int | None = 0, invert: bool | None = False, mask: Image | None = None) → Image¶: 以邊緣偵測的拉普拉斯核對影像進行卷積。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

sharpen 若為 True，會銳化影像而非輸出原始未閾值化的邊緣響應。

mul 是乘法式的對比縮放（預設 1.0）。

add 是加法式的亮度偏移（預設 0.0）。

threshold 若為 True，會自適應地將濾鏡輸出閾值化為二值影像。offset 移動二值化結果（負值使更多像素變白，正值使更少像素變白）。invert 反轉二值輸出。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

以雙邊濾波器（保留邊緣的平滑）對影像進行卷積。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

color_sigma 控制色彩匹配容忍度；值越大產生越多色彩模糊。

space_sigma 控制空間模糊；值越大產生越多像素模糊。

mask 是用作像素層級遮罩的二值影像；只有遮罩中被設定的像素才會被修改。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer/yuv 影像。

幾何方法¶

linpolar(reverse: bool = False, *, x: int | None = None, y: int | None = None) → Image¶

將影像從笛卡兒座標重新投影為線性極座標。

設定 reverse=True 以反方向重新投影。

x 與 y 以影像像素指定變換的中心座標。若 x 為 None（預設），則設為影像寬度的一半；同樣地 y 預設為影像高度的一半。

線性極座標重新投影會將影像的旋轉轉換為 x 方向的平移。

不支援壓縮影像或 bayer 影像。

OpenMV Cam M4 上不提供此方法。

logpolar(reverse: bool = False, *, x: int | None = None, y: int | None = None) → Image¶

將影像從笛卡兒座標重新投影為對數極座標。

設定 reverse=True 以反方向重新投影。

x 與 y 以影像像素指定變換的中心座標。若 x 為 None（預設），則設為影像寬度的一半；同樣地 y 預設為影像高度的一半。

對數極座標重新投影會將影像的旋轉轉換為 x 方向的平移，並將縮放／放大轉換為 y 方向的平移。

不支援壓縮影像或 bayer 影像。

OpenMV Cam M4 上不提供此方法。

lens_corr(strength: float = 1.8, zoom: float = 1.0, x_corr: float = 0.0, y_corr: float = 0.0) → Image¶

執行鏡頭校正以消除因鏡頭畸變造成的影像魚眼效果。

strength 是定義消除影像魚眼程度的浮點數。先試試預設的 1.8，然後從那裡增加或減少，直到影像看起來良好。

zoom 是對影像放大的量。預設為 1.0。

x_corr 自中心起算的浮點像素偏移。可為負或正。

y_corr 自中心起算的浮點像素偏移。可為負或正。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

rotation_corr(x_rotation: float = 0.0, y_rotation: float = 0.0, z_rotation: float = 0.0, x_translation: float = 0.0, y_translation: float = 0.0, zoom: float = 1.0, fov: float = 60.0, corners: List[Tuple[int, int]] | None = None) → Image¶

藉由對影格緩衝區進行 3D 旋轉來校正影像中的透視問題。

x_rotation 是要將影格緩衝區中影像繞 x 軸旋轉的度數（亦即這會使影像上下翻轉）。

y_rotation 是要將影格緩衝區中影像繞 y 軸旋轉的度數（亦即這會使影像左右翻轉）。

z_rotation 是要將影格緩衝區中影像繞 z 軸旋轉的度數（亦即這會使影像就地旋轉）。

x_translation 是旋轉後要將影像向左或向右移動的單位數。由於此平移是在 3D 空間中套用，單位並非像素…

y_translation 是旋轉後要將影像向上或向下移動的單位數。由於此平移是在 3D 空間中套用，單位並非像素…

zoom 是對影像放大的量。預設為 1.0。

fov 是內部 2D->3D 投影所用的視野角。當 fov 趨近 0 時影像被置於無限遠處；趨近 180 時影像被置於視口內。

corners 是由四個 (x, y) 元組組成的列表，用於建立一個 4 點單應性，在套用 3D 旋轉之前將這些角點對應到 (0, 0)、(image_width-1, 0)、(image_width-1, image_height-1) 與 (0, image_height-1)。對鳥瞰視角變換很有用。

回傳影像物件，以便你能使用 . 標記法呼叫另一個方法。

不支援壓縮影像或 bayer 影像。

OpenMV Cam M4 上不提供此方法。

取得方法¶

get_similarity(image: Image, x: int = 0, y: int = 0, x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, dssim: bool = False) → Similarity¶

使用結構相似性指標 (SSIM) 計算兩張影像之間的相似度。SSIM 範圍從 -1（相反）到 1（完全相同）。回傳一個 image.similarity 物件。

image 是要比較的對象影像（影像物件或路徑字串，例如 "test.jpg"）。

x、y、x_scale、y_scale、roi、rgb_channel、alpha、color_palette、alpha_palette、hint 與 transform 接受與 Image.draw_image() 相同的值。

dssim 若為 True，則改回傳結構相異性指標 (DSSIM)，其中 0 表示完全相同，1 表示完全不同。

get_histogram(thresholds: List[Tuple[int, int]] | None = None, invert: bool = False, roi: Tuple[int, int, int, int] | None = None, bins: int = -1, l_bins: int = -1, a_bins: int = -1, b_bins: int = -1, difference: Image | None = None) → histogram¶

計算 roi 上所有色彩通道的正規化直方圖，並回傳一個 image.histogram 物件。亦可透過 Image.get_hist() 或 Image.histogram() 取得。

thresholds 對於灰階影像是 (lo, hi) 元組的列表，對於 RGB565 影像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元組的列表。若有傳入，則僅針對閾值範圍內的像素計算直方圖。

invert 反轉閾值匹配。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

bins（灰階）或 l_bins/a_bins/b_bins（RGB565）設定每個通道的直方圖區間數。必須大於 2。預設為每個通道的最大區間數。

difference 可設為一個影像物件，以在不需額外緩衝區的情況下對目前影像與該影像之間的差進行運算。

不支援壓縮影像或 bayer 影像。

get_statistics(thresholds: List[Tuple[int, int]] | None = None, invert: bool = False, roi: Tuple[int, int, int, int] | None = None, bins: int = -1, l_bins: int = -1, a_bins: int = -1, b_bins: int = -1, difference: Image | None = None) → statistics¶

計算 roi 上所有色彩通道的平均值、中位數、眾數、標準差、最小值、最大值、下四分位數與上四分位數，並回傳一個 image.statistics 物件。亦可透過 Image.get_stats() 或 Image.statistics() 取得。

thresholds 對於灰階影像是 (lo, hi) 元組的列表，對於 RGB565 影像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元組的列表。若有傳入，則僅針對閾值範圍內的像素計算統計值。

invert 反轉閾值匹配。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

bins（灰階）或 l_bins/a_bins/b_bins（RGB565）設定每個通道的直方圖區間數。必須大於 2。預設為每個通道的最大區間數。

difference 可設為一個影像物件，以在不需額外緩衝區的情況下對目前影像與該影像之間的差進行運算。

不支援壓縮影像或 bayer 影像。

get_regression(thresholds: List[Tuple[int, int]], invert: bool = False, roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, area_threshold: int = 10, pixels_threshold: int = 10, target_size: Tuple[int, int] = (80, 60)) → line¶

對影像中所有通過閾值的像素計算線性回歸（Theil-Sen）。回傳一個 image.line 物件，若未找到線則回傳 None。

thresholds 對於灰階影像是 (lo, hi) 元組的列表，對於 RGB565 影像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元組的列表。

invert 反轉閾值匹配。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

x_stride 與 y_stride 控制評估影像時要跳過多少像素。

area_threshold 最小邊界框面積；較小的結果回傳 None。

pixels_threshold 最小通過閾值的像素數；較小的結果回傳 None。

target_size 是一個 (w, h) 元組。在執行 O(N^2) 演算法之前，ROI 會被區域縮小以容納於此大小內。預設為 (80, 60)。

不支援壓縮影像或 bayer 影像。

偵測方法¶

find_blobs(thresholds: List[Tuple[int, int]], invert: bool = False, roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, area_threshold: int = 10, pixels_threshold: int = 10, merge: bool = False, margin: int = 0, threshold_cb: Callable | None = None, merge_cb: Callable | None = None, x_hist_bins_max: int = 0, y_hist_bins_max: int = 0) → List[blob]¶

找出影像中所有色塊（通過閾值測試的連通像素區域），並回傳一個 image.blob 物件列表。

thresholds 對於灰階影像是 (lo, hi) 元組的列表，對於 RGB565 影像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元組的列表（LAB 通道）。最多可傳入 32 個元組。對調的最小／最大值會被自動修正；缺少的分量預設為最大範圍。

invert 反轉閾值匹配。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

x_stride 與 y_stride 控制搜尋色塊時要跳過多少像素。若已知色塊很大可增大此值。

area_threshold 最小邊界框面積；較小的色塊會被濾除。

pixels_threshold 最小通過閾值的像素數；較小的色塊會被濾除。

merge 若為 True，會合併邊界矩形相交的色塊。margin 會放大／縮小用於相交判定的邊界矩形。合併後的色塊會將其 code 位元向量進行 OR（每個閾值一個位元）。

threshold_cb 會在閾值化後對每個色塊呼叫；回傳 True 以保留、False 以濾除。

merge_cb 會對每一對即將合併的色塊呼叫；回傳 True 以允許合併、False 以防止合併。

x_hist_bins_max 若非零，會以此數量的區間為每個色塊填入 x_histogram 投影。

y_hist_bins_max 若非零，會以此數量的區間為每個色塊填入 y_histogram 投影。

不支援壓縮影像或 bayer 影像。

find_lines(roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, threshold: int = 1000, theta_margin: int = 25, rho_margin: int = 25) → List[line]¶

使用霍夫變換找出影像中所有無限長直線。回傳一個 image.line 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

x_stride 與 y_stride 控制霍夫變換期間要跳過多少像素。

threshold 最小線量值（沿線的 sobel 量值總和）；低於此值的線會被濾除。

theta_margin 與 rho_margin 控制合併：在這些閾值範圍內的線會被合併。

不支援壓縮影像或 bayer 影像。

OpenMV Cam M4 上不提供此方法。

find_line_segments(roi: Tuple[int, int, int, int] | None = None, merge_distance: int = 0, max_theta_difference: int = 15) → List[line]¶

找出影像中的線段。回傳一個 image.line 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

merge_distance 是兩條線段要被合併的最大像素間距。

max_theta_difference 是線段之間要被合併的最大 theta 差異（度數）。

OpenMV Cam M4 上不提供此方法。

find_circles(roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, threshold: int = 2000, x_margin: int = 10, y_margin: int = 10, r_margin: int = 10, r_min: int = 2, r_max: int | None = None, r_step: int = 2) → List[circle]¶

使用霍夫變換找出影像中的圓形。回傳一個 image.circle 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

x_stride 與 y_stride 控制霍夫變換期間要跳過多少像素。

threshold 最小圓量值（沿圓的 sobel 量值總和）；低於此值的圓會被濾除。

x_margin、y_margin 與 r_margin 控制合併：在這些閾值範圍內的圓會被合併。

r_min 最小圓半徑。預設為 2。

r_max 最大圓半徑。預設為 min(roi.w/2, roi.h/2)。

r_step 半徑步進大小。預設為 2。

OpenMV Cam M4 上不提供此方法。

find_rects(roi: Tuple[int, int, int, int] | None = None, threshold: int = 1000) → List[rect]¶

使用 apriltag 四邊形偵測演算法找出影像中的矩形。回傳一個 image.rect 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

threshold 最小邊緣量值（沿矩形邊緣的 sobel 量值總和）；低於此值的矩形會被濾除。

OpenMV Cam M4 上不提供此方法。

find_qrcodes(roi: Tuple[int, int, int, int] | None = None) → List[qrcode]¶

找出 roi 內所有 qrcode，並回傳一個 image.qrcode 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

OpenMV Cam M4 上不提供此方法。

找出 roi 內所有 apriltag，並回傳一個 image.apriltag 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

families 是要解碼的標籤家族的位元遮罩。它是以下各項的邏輯 OR：

image.TAG16H5

image.TAG25H9

image.TAG36H10

image.TAG36H11

image.TAGCIRCLE21H7

image.TAGCIRCLE49H12

image.TAGCUSTOM48H12

image.TAGSTANDARD41H12

image.TAGSTANDARD52H13

預設為 image.TAG36H11。偵測時間會隨啟用的家族數量而增加。

fx 與 fy 是相機 X 與 Y 方向的焦距（像素）。

cx 與 cy 是影像中心，通常為 image.width()/2 與 image.height()/2。

不支援壓縮影像。

OpenMV Cam M4 上不提供此方法。

find_datamatrices(roi: Tuple[int, int, int, int] | None = None, effort: int = 200) → List[datamatrix]¶

找出 roi 內所有 datamatrix，並回傳一個 image.datamatrix 物件列表。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

effort 控制要花多少時間嘗試尋找 data matrix 匹配。較高的值會以幀率為代價提升偵測。低於約 160 的值無法偵測；高於約 240 的值收益遞減。預設為 200。

OpenMV Cam M4 上不提供此方法。

find_barcodes(roi: Tuple[int, int, int, int] | None = None) → List[barcode]¶

找出 roi 內所有 1D 條碼，並回傳一個 image.barcode 物件列表。會同時水平與垂直掃描。

支援的條碼類型：image.EAN2、image.EAN5、image.EAN8、image.UPCE、image.ISBN10、image.UPCA、image.EAN13、image.ISBN13、image.I25、image.DATABAR (RSS-14)、image.DATABAR_EXP (RSS-Expanded)、image.CODABAR、image.CODE39、image.PDF417、image.CODE93、image.CODE128。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

OpenMV Cam M4 上不提供此方法。

find_displacement(template: Image, roi: Tuple[int, int, int, int] | None = None, template_roi: Tuple[int, int, int, int] | None = None, logpolar: bool = False, fix_rotation_scale: bool = False) → displacement¶

使用相位相關找出此影像相對於 template 的平移偏移量。回傳一個 image.displacement 物件。

roi 是感興趣區域矩形 (x, y, w, h)。預設為影像矩形。

template_roi 是樣板的感興趣區域。預設為樣板影像矩形。roi 與 template_roi 必須有相同的寬度與高度。

logpolar 若為 True，會回傳旋轉/縮放變化而非 x/y 平移。

fix_rotation_scale 若為 True，會在對齊旋轉與縮放後計算位移（僅在 logpolar=False 時有意義）。

備註

請在 2 的次方影像大小（例如 sensor.B64X64）上使用此方法。

不支援壓縮影像或 bayer 影像。OpenMV Cam M4 上不提供。

find_template(template: Image, threshold: float, roi: Tuple[int, int, int, int] | None = None, step: int = 2, search: int = SEARCH_EX) → Tuple[int, int, int, int] | None¶

嘗試使用正規化交叉相關找出影像中 template 首次匹配的位置。回傳一個邊界框元組 (x, y, w, h)，或 None。

template 是要與此影像比對的灰階影像。

threshold 是介於 0.0-1.0 的值。較高的值會減少誤判與偵測；較低的值則相反。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

step 是搜尋時要跳過的像素數（僅在 image.SEARCH_EX 模式中使用）。

search 為 image.SEARCH_DS（較快的菱形搜尋）或 image.SEARCH_EX（窮舉搜尋）。

僅適用於灰階影像。

find_features(cascade: Cascade, threshold: float = 0.5, scale: float = 1.5, roi: Tuple[int, int, int, int] | None = None) → List[Tuple[int, int, int, int]]¶

在影像中搜尋與傳入的 Haar 級聯相符的區域，並回傳一個邊界框元組列表 (x, y, w, h)。若未找到特徵則回傳空列表。

cascade 是一個 Haar 級聯物件（參見 image.HaarCascade()）。

threshold（0.0-1.0）。較低的值會提高偵測率與誤判率。

scale 必須大於 1.0。較高的值執行較快但產生較差的匹配。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

find_eye(roi: Tuple[int, int, int, int]) → Tuple[int, int]¶

在眼睛周圍的感興趣區域 (x, y, w, h) 元組中搜尋瞳孔。回傳瞳孔的 (x, y) 位置，若未找到則回傳 (0, 0)。

roi 是感興趣區域矩形元組 (x, y, w, h)。

僅適用於灰階影像。

find_lbp(roi: Tuple[int, int, int, int]) → lbp_descriptor¶

從感興趣區域擷取 LBP（局部二值樣式）關鍵點。使用 image.match_descriptor() 來比較兩個描述子。

roi 是感興趣區域矩形元組 (x, y, w, h)。

僅適用於灰階影像。

find_keypoints(roi: Tuple[int, int, int, int] | None = None, threshold: int = 20, normalized: bool = False, scale_factor: float = 1.5, max_keypoints: int = 100, corner_detector: int = CORNER_AGAST) → kp_descriptor | None¶

從感興趣區域擷取 ORB 關鍵點。使用 image.match_descriptor() 來比較兩個描述子。若未找到關鍵點則回傳 None。

roi 是感興趣區域矩形元組 (x, y, w, h)。預設為影像矩形。

threshold（0-255）控制擷取的角點數量。較低的閾值產生較多角點。AGAST 使用約 20，FAST 使用約 60-80。

normalized 若為 True，會停用多解析度關鍵點擷取。

scale_factor 必須大於 1.0。較高的值執行較快但產生較差的匹配。

max_keypoints 是要保留的最大關鍵點數量。

corner_detector 為 image.CORNER_FAST 或 image.CORNER_AGAST。

僅適用於灰階影像。

find_edges(edge_type: int, threshold: Tuple[int, int] = (100, 200)) → Image¶

將影像轉為黑白，只留下邊緣作為白色像素。

image.EDGE_SIMPLE - 簡單的閾值化高通濾波器演算法。

image.EDGE_CANNY - Canny 邊緣偵測演算法。

threshold 是一個包含低閾值與高閾值的兩值元組。你可以透過調整這些值來控制邊緣的品質。它預設為 (100, 200)。

僅適用於灰階影像。

find_hog(roi: Tuple[int, int, int, int] | None = None, size: int = 8) → Image¶

以 HOG（方向梯度直方圖）線條取代 ROI 中的像素。

roi 是感興趣區域矩形元組 (x, y, w, h)。若未指定，則等於影像矩形。只有 roi 內的像素會被運算。

僅適用於灰階影像。

OpenMV Cam M4 上不提供此方法。

stereo_disparity(reversed: bool = False, max_disparity: int = 64, threshold: int = 64) → Image¶

接受一張包含兩個並排相機感測器輸出的雙倍寬灰階影像，並將其中一半取代為立體視差影像（每個像素代表深度）。例如，對於兩個 320x240 相機，請傳入一張 640x240 影像。

reversed 預設情況下會將左影像與右影像比較並取代右影像。設為 True 以將右影像與左影像比較（右->左）並取代左影像。

max_disparity 是使用絕對差總和搜尋匹配像素區塊的最大距離 (1-255)。較大的值耗時呈指數成長，但產生較高品質的輸出。

threshold 若兩個區塊之間的絕對差總和小於或等於此閾值，則視為匹配。

selective_search(threshold: int = 500, size: int = 20, a1: float = 1.0, a2: float = 1.0, a3: float = 1.0) → List[Tuple[int, int, int, int]]¶

對影像執行選擇性搜尋，並回傳物件候選的邊界框元組列表 (x, y, w, h)。

threshold 是分割閾值；較高的值產生較少／較大的區域。

size 是合併後的最小區域大小。

a1、a2、a3 是合併區域時所用的色彩/紋理/大小相似度權重。