圖像處理器

圖像處理器(Image Manipulator)本身是一個可視組件。它會接受一個圖像或者另一個圖像處理器對象，對原有對象進行某些處理。圖像處理器只接受圖像或其他圖像處理器作為輸入。

任何能放可視組件的地方也可以放圖像處理器，但反過來不一定可行。 Image() 對象是一種圖像處理器，所以任何需要使用圖像處理器的地方都可以使用image對象。

Warning

圖像處理的應用具有重大意義。過去的一些圖像處理器由於各種的問題不應再使用。 除了使用 im.Data() 的情況，可視組件 Transform() 提供了很多類似的功能，並同時修復了過去的問題。

class im.AlphaMask(base, mask, **properties)

使用兩個圖像處理器 base 和 mask 作為入參，創建一個圖像處理器。其使用 mask 的紅色通道值替換了 base 的alpha通道值。

該函數用於向某個圖像提供alpha通道值，來源是另一個圖像。比如某個jpeg圖片提供色彩數據，使用另一個jpeg圖片提供alpha值。在某些情況下，兩張jpeg圖片的檔案大小可能比一張png圖文文件還要小。

需要注意，該函數與 AlphaMask() 使用不同的入參，AlphaMask()使用的是mask參數的alpha通道值。

兩張圖像需要是相同的尺寸，以及相同的過採樣係數。

class im.Blur(im, xrad, yrad=None, **properties)

可以將圖像 im 模糊化的圖像處理器。使用 xrad 和可選的 yrad 表示模糊區域的橢圓中心區域。

如果 yrad 的值是None，就與 xrad 的值相同，也就意味著中心區域是個圓形。

image logo blurred = im.Blur("logo.png", 1.5)

現在可以使用變換特性 blur 獲得相同的效果。

class im.Crop(im, rect)

該圖像處理器實現了圖像剪裁功能。對原圖像 im ，剪裁其在 rect 範圍內的圖像。 rect 參數是一個(x, y, width, height)形式的元組。

image logo crop = im.Crop("logo.png", (0, 0, 100, 307))

現在可以使用變換特性 crop 獲得相同的效果。

class im.Data(data, filename, **properties)

這個圖像處理器從二進位制文件載入圖像。

data

由byte組成的字串，表示標準檔案格式下的壓縮圖片數據。

filename

與圖像關聯的 filename 檔案名。這項用於向Ren’Py提供數據格式的提示。(圖像並不是從磁碟載入的。)

class im.FactorScale(im, width, height=None, bilinear=True, **properties)

該圖像處理器實現圖像(或圖像處理器) im 的等比縮放。縮放後的圖像寬高比不變。如果 height 入參為空，默認與 width 值相同。

如果 bilinear 為True，縮放時使用雙線性插值算法。否則，縮放時使用最近鄰插值算法。

image logo doubled = im.FactorScale("logo.png", 1.5)

現在可以使用變換特性 zoom 或 xzoom 和 yzoom 獲得相同的效果。

class im.Flip(im, horizontal=False, vertical=False, **properties)

該圖像處理器實現圖像(或圖像處理器) im 在垂直或水平方向的翻轉。 vertical 和 horizontal 參數控制具體的翻轉方向。

image eileen flip = im.Flip("eileen_happy.png", vertical=True)

現在可以使用變換特性 xzoom (水平翻轉)或 yzoom (垂直翻轉)獲得相同的效果。

im.Grayscale(im, desat=(0.2126, 0.7152, 0.0722), **properties)

該圖像處理器創建了一個 im 的灰度版本(即色彩飽和度為0)。

現在可以通過SaturationMatrix(0)傳入變換特性 matrixcolor 獲得相同的效果。

im.Sepia(im, desat=(0.2126, 0.7152, 0.0722), **properties)

該圖像處理器創建了一個 im 的舊化版本(即老照片樣式)。

現在可以通過SepiaMatrix()傳入變換特性 matrixcolor 獲得相同的效果。

class im.Tile(im, size=None, **properties)

在 size 範圍內平鋪(tile) im 。

size

如果不為None，該值是一個(width, height)元組。如果為空，預設值為(config.screen_width, config.screen_height)，即整個界面的尺寸。

7.4.0版本起，使用 Tile() 可以實現同樣效果。

im.MatrixColor

Warning

圖像處理器im.MatrixColor已經被Transform和ATL變換中的matrixcolor特性完全替代。 每個 im.matrix 生成器都會給定一個新的等效 Matrix，詳見 matrixcolor 。

im.MatrixColor圖像處理器是使用一個矩陣控制圖像色彩變換的圖像處理器。使用的矩陣可以是一個im.matrix對象，該矩陣使用一個支持矩陣乘法的5×5矩陣進行編碼，通過一系列函數返回編碼結果。im.matrix對象可以多重相乘並同時生效。例如：

image city blue = im.MatrixColor(
    "city.jpg",
    im.matrix.desaturate() * im.matrix.tint(0.9, 0.9, 1.0))

樣例中，先將圖像黑白化，然後提高圖像中藍色的純度(實際降低了紅色和綠色的純度)。如果處理過程環節中的圖片不需要儲存，多個矩陣的使用是非常高效的，無論是在處理時間和快取空間要求方面，都比單獨使用兩個im.MatrixColor矩陣好。

圖像處理器 im.MatrixColor 的功能已經被Transform類和ATL中transform的matrixcolor特性替代了。 每次生成 im.matrix 都會將賦值給一個新的 Matrix 對象，詳見 matrixcolor 。

Warning

Matrix對象的乘法規則與 im.Matrixcolor 相反。為了獲得相同的效果， im.a*im.b*im.c 要改成 C*B*A 。

class im.MatrixColor(im, matrix, **properties)

使用 matrix 線性化轉換圖像處理器 im 。

matrix 是一個列表元組或者 im.matrix() 對象，包含20或者25個元素。如果對象中包含25個元素，第20個元素之後的部分在計算時忽略。

假設原圖像的色彩值有4項，分別為R、G、B和A，值的範圍為0.0至1.0；轉換後的色彩值為R’、G’、B’和A’，值的範圍為0.0至1.0；色彩轉換矩陣的各項值如下：

[ a, b, c, d, e,
  f, g, h, i, j,
  k, l, m, n, o,
  p, q, r, s, t ]

轉換後的顏色可以使用如下方程計算：

R' = (a * R) + (b * G) + (c * B) + (d * A) + e
G' = (f * R) + (g * G) + (h * B) + (i * A) + j
B' = (k * R) + (l * G) + (m * B) + (n * A) + o
A' = (p * R) + (q * G) + (r * B) + (s * A) + t

轉換後圖像的各項顏色值會被限制在區間[0.0, 1.0]裡。

class im.matrix

從 matrix 參數構造一個im.matrix對象。im.matrix對象支持矩陣乘法、標量乘法(scalar multiplication)、點位(element-wise)加法和點位(element-wise)減法。進行這些運算時，使用標準的數學符號(分別使用*、*、+和-)。兩種乘法的使用取決於兩個因子：如果兩個im.matrix相乘就使用矩陣乘法，如果有一個因子不是矩陣則使用標量乘法。

matrix 是一個列表元組或者im.matrix對象，包含20或者25個元素。如果對象中包含20個元素，後面會加(0, 0, 0, 0, 1)填充成5×5矩陣，為了符合乘法運算的需求。

im.matrix.brightness(b)

返回一個im.matrix矩陣對象，可用於轉換某個圖像的明度。

b

圖像明度的變化值。該值是一個介於-1和1之間的數值。-1表示最低明度，1表示最高明度。

等效於 matrixcolor 變換特性BrightnessMatrix(b)。

im.matrix.colorize(black_color, white_color)

為黑白圖像添加色調分離效果的im.matrix矩陣。 black_color 和 white_color 是Ren’Py中的樣式色彩，所以可以表示為一個色彩字串或者0-255範圍內色彩值組成的元組。

# 這個矩陣能使圖像黑色變為紅色，而白色變為藍色。
image logo colored = im.MatrixColor(
    "bwlogo.png",
    im.matrix.colorize("#f00", "#00f"))

等效於 matrixcolor 變換特性ColorizeMatrix(black_color, white_color)。

im.matrix.contrast(c)

返回一個im.matrix矩陣對象，可用於轉換某個圖像的對比度。 c 應是一個大於0.0的值，其值介於0.0和1.0之間時降低對比度，其值大於1.0時增加對比度。

等效於變換特性 matrixcolor 設置為ContrastMatrix(c)。

im.matrix.desaturate()

返回一個im.matrix矩陣對象，可以將某個圖像轉為黑白(變成灰度圖像)。等效於調用im.matrix.saturation(0)。

等效於變換特性 matrixcolor 設置為SaturationMatrix(0)。

im.matrix.hue(h)

返回一個im.matrix矩陣對象，用於調整色相，保持亮度的情況下轉動色相環 h 度。

等效於變換特性 matrixcolor 設置為HueMatrix(h)。

im.matrix.identity()

返回一個標識符矩陣，標識某些色彩或者alpha值不會改變。

等效於變換特性 matrixcolor 設置為IdentityMatrix()。

im.matrix.invert()

返回一個im.matrix矩陣對象，在不改變alpha通道的情況下，反轉圖像的紅、綠、藍三色值。

等效於變換特性 matrixcolor 設置為InvertMatrix(1.0)。

im.matrix.opacity(o)

返回一個im.matrix矩陣對象，改變圖像的透明度。 o 為0.0表示完全透明，為1.0表示完全不透明。

等效於變換特性 matrixcolor 設置為OpacityMatrix(o)。

im.matrix.saturation(level, desat=(0.2126, 0.7152, 0.0722))

返回一個im.matrix矩陣對象，改變圖像的飽和度。這種改變與alpha通道無關。

level

處理後圖像的色彩飽和度相對值。1.0表示原圖色彩飽和度，0.0表示灰度圖。

desat

這是一個3元素元組，每個元素對應紅、綠、藍三個通道的飽和度相對值。預設值基於NTSC色彩空間亮度通道的值。由於人眼對綠色最敏感，所以綠色通道保留的資訊通常比其他兩個通道多。

等效於變換特性 matrixcolor 設置為SaturationMatrix(value, desat)。

im.matrix.tint(r, g, b)

返回一個im.matrix矩陣對象，圖像增亮，但不改變alpha通道。 r 、 g 和 b 是介於0跟1之間的數值，各個通道原值與入參的乘積就是最終圖像的值。(例如，若 r 是0.5，原圖像紅色通道的值是100，轉換後的圖像紅色通道值就是50。)

等效於變換特性 matrixcolor 設置為TintMatrix(Color((r, g, b)))。