5.7. 合成影像

上一頁的繪圖基本元素是在影像上畫出幾何標記——一條線、一個矩形、一段文字。這涵蓋了演算法需要呈現的大多數標註，但並非全部。有時標註本身就是一張影像：擷取下來的參考影格，要與當前影格並排顯示；先前擷取影像的縮圖，顯示在預覽畫面的角落；或是先前儲存的範本，疊加在即時影格之上用於校正。將一張影像繪製到另一張影像上的機制只有一個方法——draw_image()——它具備足夠的參數來處理真正的合成所需的位置、縮放、色彩調色盤以及透明度。

5.7.1. 基本呼叫

在最簡單的形式中，draw_image 接受另一張 Image 以及一個繪製位置：

reference = image.Image("/sdcard/reference.bmp")
img.draw_image(reference, x=10, y=10)

目的影像是 img；來源影像是 reference；來源的左上角像素落在 img 的 (10, 10) 處，來源其餘的像素則由此向右、向下延伸。被來源覆蓋的目的影像像素會被來源對應的像素覆寫；位於來源範圍之外的像素則維持不變。

如果來源超出目的影像的邊緣，超出的部分會被靜默裁切——這與 set_pixel 對超出範圍位置所表現的寬容行為相同。應用程式碼不必事先將位置限制在影像尺寸之內；它可以傳入想要的位置，讓方法自行處理裁切。

5.7.2. 內嵌載入檔案

draw_image 接受以檔案路徑取代 Image 引數，並在合成前先載入該檔案：

img.draw_image("/sdcard/reference.bmp", x=10, y=10)

這看起來像是個便利寫法——一行取代兩行——確實如此，但差異不僅止於語法。從檔案建構一張 Image 會配置一個緩衝區來保存解碼後的像素，而該緩衝區會一直存在，直到垃圾回收將其釋放。直接將路徑傳給 draw_image 則可讓模組將檔案解碼到一個暫存緩衝區、從中進行合成，並在呼叫返回時釋放該緩衝區，應用程式碼不必在各影格之間保有對另一個 Image 的參考。

5.7.3. 縮放

當來源與目的影像尺寸不同時——例如將低解析度的擷取影像合成到較高解析度的畫布上，或是需要將縮圖調整為影格特定比例的大小——兩個縮放參數會在繪製來源時處理其重新調整尺寸：

img.draw_image(reference, x=10, y=10, x_scale=2.0, y_scale=2.0)

x_scale 與 y_scale 是各自獨立的浮點數；兩者傳入相同的值會等比例縮放，傳入不同的值則會沿單一軸向拉伸或壓縮來源。縮放發生在繪製時；來源 reference 並不會被修改。

由提示旗標組成的位元遮罩決定縮放實際上如何在像素之間進行內插。image.BILINEAR 可產生較平滑的結果，但代價是更多的運算量；image.BICUBIC 可產生更為平滑的結果，代價也更高；預設使用最近鄰法，這是最廉價的方式，當來源已經處於目的影像的像素解析度時，它是正確的選擇。寬高比處理旗標——SCALE_ASPECT_KEEP、SCALE_ASPECT_EXPAND、SCALE_ASPECT_IGNORE——則決定當來源的寬高比與其要繪入的矩形不相符時該如何處理。

5.7.4. Alpha 混合

預設情況下，draw_image 會以來源像素取代目的像素。當目標是製作半透明疊加層——讓目的影像能透過來源顯現出來——時，alpha 參數可控制兩者如何混合。alpha=0 只顯示目的影像（不顯示來源）；alpha=255 是預設值，只顯示來源（完全取代）；中間值則按比例混合兩者：

img.draw_image(overlay, x=0, y=0, alpha=128)

另有一個 alpha_palette 引數，是模組唯一的逐像素 alpha 機制。它接受一張 GRAYSCALE 影像，其數值會被當作來源中對應位置的 alpha 值——例如一張 alpha 隨其強度而變化的熱圖。alpha 必須以該獨立的灰階引數提供；本身帶有 alpha 通道的來源影像（例如帶透明度的 PNG）不會自動將其帶入。

5.7.5. 來源 ROI 與調色盤

另有兩個參數補足了整個合成機制：

  • roi=(x, y, w, h) 將來源限制在其自身的一個子矩形範圍內，因此只有該矩形會被合成到目的影像上。適合在同一次呼叫中進行裁切，而無需事先準備一張裁切過的中間影像。

  • color_palette 在繪製前會透過查找表替換每個來源像素的數值——這與 to_rainbow() 和 to_ironbow() 所使用的機制相同，在此處公開，讓疊加層在繪製到目的影像的過程中即可套用調色盤，而不需另外進行一次轉換。

兩者都能與呼叫中的其他所有設定一起組合運作：縮放、alpha、目的端的 mask 引數，以及將寫入範圍限定在目的影像某個矩形的目的端 roi 參數。