使用 Python 在簡報中管理影像變換效果
概觀
Aspose.Slides 以有序的影像變換操作集合來表示圖片調整。對於圖片框,先取得框架的 Picture ,再呼叫 Picture.getImageTransform。回傳的 ImageTransformOperationCollection 讓您可以加入、列舉、檢查、移除以及清除效果,而不必重新寫入原始影像位元組。
本文章示範了亮度與對比度、顏色變換、模糊、透明度、有序效果鏈、實際值、移除,以及 PPTX 往返驗證的完整工作流程。
了解效果擁有權與影像重複使用
影像資源與顯示它的圖片是不同的物件:
- PPImage 會儲存或參考簡報所擁有的來源影像資料。
- Picture 屬於圖片填充,參考影像資源,同時儲存影像變換集合。
- PictureFrame 是投影片形狀,擁有相關的圖片填充、幾何、裁切設定與其他框架層級格式。
因此,影像變換操作不會修改 PPImage 中的位元組。當同一個 PPImage 多次傳遞給 ShapeCollection.addPictureFrame 時,每個新圖片框都會收到自己的 Picture 與自己的變換集合。對其中一個框套用灰階不會使其他框也變成灰階,即使它們都重複使用相同的嵌入影像資源。
相同的 Picture.getImageTransform 模型也被其他圖片填充使用,例如形狀或投影片背景。以下範例聚焦於圖片框。
使用有效的參數範圍與單位
示範的方法使用下列語意範圍與單位。即使特定函式庫版本未即時拒絕所有超出範圍的值,也請維持在這些範圍內;目標簡報格式可能在儲存或 PowerPoint 開啟檔案時正規化、忽略或拒絕無效資料。
| Operation | Parameters | Valid range and unit |
|---|---|---|
| addBrightnessContrastEffect | brightness, contrast |
-100 至 100,百分比;0 表示保持元件不變。 |
| addGrayScaleEffect | 無 | 無數值參數。Alpha 不變。 |
| addDuotoneEffect | color1, color2 |
兩種顏色用於暗像素與亮像素。java.awt.Color 的 RGB 與 alpha 通道值為 0 至 255。 |
| addTintEffect | hue, amount |
色相 0(含)至 360(未含),單位為度;色量 -100 至 100,百分比。 |
| addHSLEffect | hue, saturation, luminance |
色相 0(含)至 360(未含),單位為度;飽和度與亮度 -100 至 100,百分比。 |
| addColorReplaceEffect | color |
取代顏色的通道值為 0 至 255。現有 alpha 值不變。 |
| addBlurEffect | radius, grow |
半徑為非負值,以點為單位;grow 為布林值,決定模糊內容是否可延伸至原始邊界外。 |
| addAlphaModulateFixedEffect | amount |
非負百分比。使用 0 至 100 表示普通不透明度縮放:0 為完全透明,100 為保留現有 alpha。 |
| addAlphaReplaceEffect | alpha |
0 至 100,百分比不透明度。 |
| addAlphaBiLevelEffect | threshold |
0 至 100,百分比 alpha 閾值。低於此值的變為透明;等於或高於此值的變為不透明。 |
對於固定的 alpha 調變,透明度與不透明度互為補數。例如,35% 透明度對應的 alpha 調變量為 65%。
套用亮度與對比度
ImageTransformOperationCollection.addBrightnessContrastEffect 會回傳一個 BrightnessContrast 操作。其純量設定在建立操作時提供。BrightnessContrast.getEffective 會回傳計算後唯讀的值,供檢查或記錄使用。
以下範例將亮度提高 15%,對比度提高 20%,然後在不修改嵌入影像的情況下渲染預覽:
import jpype
import asposeslides
from pathlib import Path
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ImageFormat, Presentation, ShapeType
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
image_data = Path("photo.png").read_bytes()
image_bytes = jpype.JArray(jpype.JByte)(image_data)
image = presentation.getImages().addImage(image_bytes)
picture_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 50, 50, 400, 260, image)
image_transform = picture_frame.getPictureFormat().getPicture().getImageTransform()
brightness_contrast = image_transform.addBrightnessContrastEffect(15.0, 20.0)
effective_values = brightness_contrast.getEffective()
print("Brightness: ", effective_values.getBrightness(), "%", sep="")
print("Contrast: ", effective_values.getContrast(), "%", sep="")
preview = slide.getImage()
try:
preview.save("brightness-contrast-preview.png", ImageFormat.Png)
finally:
preview.dispose()
finally:
presentation.dispose()
BrightnessContrast 是 Office 2010 的圖片效果延伸,較標準 DrawingML 亮度效果的相容性差。如果需要在 PPTX 往返後仍可編輯亮度與對比度,請使用 ImageTransformOperationCollection.addLuminanceEffect 並在重新開啟檔案後驗證結果。格式限制節說明了此差異的更多細節。
套用顏色變換
顏色效果可以獨立套用到重複使用同一影像資源的不同圖片框。以下範例建立五個框,分別套用灰階、雙調、色調、HSL 調整與顏色取代。
Duotone 包含兩個可獨立編輯的顏色參數:color1 用於暗像素,color2 用於亮像素。這使它成為一個設定比單一純量更複雜的效果範例。
import jpype
import asposeslides
from pathlib import Path
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import Presentation, SaveFormat, ShapeType
from java.awt import Color
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
image_data = Path("photo.png").read_bytes()
image_bytes = jpype.JArray(jpype.JByte)(image_data)
image = presentation.getImages().addImage(image_bytes)
gray_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 20, 20, 180, 120, image)
gray_frame.getPictureFormat().getPicture().getImageTransform().addGrayScaleEffect()
duotone_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 220, 20, 180, 120, image)
duotone = duotone_frame.getPictureFormat().getPicture().getImageTransform().addDuotoneEffect()
duotone.getColor1().setColor(Color(0, 0, 128))
duotone.getColor2().setColor(Color(255, 215, 0))
tint_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 420, 20, 180, 120, image)
tint_frame.getPictureFormat().getPicture().getImageTransform().addTintEffect(210.0, 35.0)
hsl_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 120, 170, 180, 120, image)
hsl_frame.getPictureFormat().getPicture().getImageTransform().addHSLEffect(30.0, 20.0, -10.0)
replacement_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 320, 170, 180, 120, image)
color_replacement = replacement_frame.getPictureFormat().getPicture().getImageTransform().addColorReplaceEffect()
color_replacement.getColor().setColor(Color(100, 149, 237))
presentation.save("color-transformations.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
addColorReplaceEffect 會將每個像素的顏色取代為固定顏色,同時保留 alpha。它不同於 addColorChangeEffect,後者會將一個來源顏色映射到另一個顏色,並公開來源與目標顏色格式。
套用亮度閾值
亮度閾值可以讓掃描頁面的淡淡痕跡更易於與背景區分。addGrayScaleEffect 會保留中間的灰階陰影。addBiLevelEffect 會將亮度映射為黑或白,而 addAlphaBiLevelEffect 則對不透明度套用閾值。
亮度閾值範圍為 0% 至 100%,含端點。低於閾值的像素變為黑色,等於或高於閾值的像素變為白色。提升閾值會使更多陰影變黑,因為更多像素落在截斷以下。
下載 grayscale-swatches.png 至工作目錄。每個標籤顯示 0 到 255 的原始灰階等級。範例將原始圖放在兩個複本旁,並在簡報中儲存每個複本的閾值。
import jpype
import asposeslides
from pathlib import Path
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import Presentation, SaveFormat, ShapeType, SlideSizeScaleType
presentation = Presentation()
try:
presentation.getSlideSize().setSize(720.0, 150.0, SlideSizeScaleType.DoNotScale)
shapes = presentation.getSlides().get_Item(0).getShapes()
image_data = Path("grayscale-swatches.png").read_bytes()
image_bytes = jpype.JArray(jpype.JByte)(image_data)
image = presentation.getImages().addImage(image_bytes)
frames = []
for index, caption in enumerate(("Original", "Threshold 20%", "Threshold 60%")):
x = 12 + 240 * index
label = shapes.addAutoShape(ShapeType.Rectangle, x, 12, 216, 36)
label.getTextFrame().setText(caption)
frame = shapes.addPictureFrame(ShapeType.Rectangle, x, 60, 216, 72, image)
frames.append(frame)
frames[1].getPictureFormat().getPicture().getImageTransform().addBiLevelEffect(20.0)
frames[2].getPictureFormat().getPicture().getImageTransform().addBiLevelEffect(60.0)
presentation.save("luminance-threshold.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
在 PowerPoint 中開啟輸出簡報,以比較三個框。標記為 96 的樣本大約有 38% 亮度(96/255)。在 20% 閾值時變白,60% 閾值時變黑。

加入模糊、透明度與 Alpha 效果
addBlurEffect 會影響所有顏色通道,包括 alpha。當模糊邊緣可能超出原始圖片範圍時,將 grow 設為 True。
若要均勻透明度,使用 addAlphaModulateFixedEffect。它會乘以每個現有的 alpha 值,使部分透明的像素保持比例差異。addAlphaReplaceEffect 則會將所有像素指派為單一 alpha 值。addAlphaBiLevelEffect 會根據閾值將 alpha 轉為兩個層級。
import jpype
import asposeslides
from pathlib import Path
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import Presentation, SaveFormat, ShapeType
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
image_data = Path("photo.png").read_bytes()
image_bytes = jpype.JArray(jpype.JByte)(image_data)
image = presentation.getImages().addImage(image_bytes)
blurred_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 20, 20, 200, 140, image)
blur = blurred_frame.getPictureFormat().getPicture().getImageTransform().addBlurEffect(4.5, True)
blur.setRadius(5)
transparent_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 240, 20, 200, 140, image)
alpha_modulate = transparent_frame.getPictureFormat().getPicture().getImageTransform().addAlphaModulateFixedEffect(65.0)
alpha_modulate.setAmount(60.0)
uniform_alpha_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 20, 180, 200, 140, image)
uniform_alpha_frame.getPictureFormat().getPicture().getImageTransform().addAlphaReplaceEffect(55.0)
binary_alpha_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 240, 180, 200, 140, image)
alpha_bi_level = binary_alpha_frame.getPictureFormat().getPicture().getImageTransform().addAlphaBiLevelEffect(50.0)
alpha_bi_level.setThreshold(45.0)
binary_alpha_frame.getPictureFormat().getPicture().getImageTransform().addAlphaInverseEffect()
presentation.save("blur-and-alpha-effects.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
其他無參數的 alpha 操作包括 addAlphaCeilingEffect,會將所有非零 alpha 變為完全不透明;addAlphaFloorEffect,會將所有低於 100% 的 alpha 變為完全透明;以及 addAlphaInverseEffect,會將 alpha 變為 100% - alpha。
建立有序的效果鏈
每個 add...Effect 方法都會將新操作加到集合的末端。渲染器將集合視為有序的流水線:操作 0 的輸出成為操作 1 的輸入,依此類推。因此,相同的操作若順序不同,可能產生不同的影像。
例如,先灰階再色調會先移除色彩資訊,然後重新上色;先色調再灰階則會再次移除色調。類似地,alpha 取代可以覆寫先前操作計算的 alpha 值,而 alpha 調變則保留其相對差異。
以下範例建立四個操作的鏈,儲存為 PPTX,重新開啟簡報,檢查操作類型與順序,並渲染重新開啟的結果:
import jpype
import asposeslides
from pathlib import Path
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import AlphaModulateFixed, Blur, GrayScale, ImageFormat, PictureFrame, Presentation, SaveFormat, ShapeType, Tint
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
image_data = Path("photo.png").read_bytes()
image_bytes = jpype.JArray(jpype.JByte)(image_data)
image = presentation.getImages().addImage(image_bytes)
picture_frame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 50, 50, 400, 260, image)
image_transform = picture_frame.getPictureFormat().getPicture().getImageTransform()
image_transform.addGrayScaleEffect()
image_transform.addTintEffect(220.0, 25.0)
image_transform.addBlurEffect(2.5, False)
image_transform.addAlphaModulateFixedEffect(80.0)
presentation.save("image-transform-chain.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
reopened_presentation = Presentation("image-transform-chain.pptx")
try:
reopened_shape = reopened_presentation.getSlides().get_Item(0).getShapes().get_Item(0)
if isinstance(reopened_shape, PictureFrame):
reopened_transform = reopened_shape.getPictureFormat().getPicture().getImageTransform()
expected_types = (GrayScale, Tint, Blur, AlphaModulateFixed)
order_is_preserved = reopened_transform.size() == len(expected_types)
for index, expected_type in enumerate(expected_types):
order_is_preserved = order_is_preserved and isinstance(reopened_transform.get_Item(index), expected_type)
print("The effect chain was preserved." if order_is_preserved else "The effect chain changed during the round trip.")
rendered_slide = reopened_presentation.getSlides().get_Item(0).getImage()
try:
rendered_slide.save("reopened-effect-chain.png", ImageFormat.Png)
finally:
rendered_slide.dispose()
else:
print("The reopened shape is not a picture frame.")
finally:
reopened_presentation.dispose()
此集合不會強加相容性矩陣限制顏色、alpha 與模糊操作必須分開鏈。它們可以結合,但組合不一定有用。固定的顏色取代會移除先前顏色效果產生的 RGB 變化;灰階在雙調之後會移除兩個選定顏色;而 alpha ceiling、floor、replace 或 bi‑level 操作可能會拋棄先前產生的 alpha 細節。請依照期望的像素處理順序建構鏈,而非把項目當作無序的格式旗標。
In this illustrative Aspose.Slides for .NET 26.11 render, a 220° tint at 25% leaves the grayscale image unchanged. Applying the same tint before grayscale produces different tones.
檢查可編輯與實際值
可編輯的操作是儲存在 Picture.getImageTransform 中的物件。根據不同效果,它可能會直接公開可寫成員。例如,Blur 會公開可寫的 radius 與 grow,AlphaModulateFixed 會公開可寫的 amount,AlphaBiLevel 會公開可寫的 threshold。諸如 Duotone 的顏色效果則會公開可變的 ColorFormat 物件。
某些操作類別,包括 BrightnessContrast、HSL、Tint、以及 AlphaReplace,不會將其建立時的純量公開為可寫屬性。若要變更這些設定,請移除該操作並在所需位置加入新替代。
getEffective 回傳的實際資料是計算後唯讀的。它對於解析主題相關顏色以及讀取渲染器使用的正規化值很有用,但不是另一個編輯介面。以下範例列舉鏈並在對應的 API 提供時檢查實際值:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import AlphaBiLevel, AlphaModulateFixed, AlphaReplace, Blur, BrightnessContrast, ColorReplace, Duotone, HSL, Luminance, PictureFrame, Presentation, Tint
presentation = Presentation("image-transform-chain.pptx")
try:
picture_frame = None
for shape in presentation.getSlides().get_Item(0).getShapes():
if isinstance(shape, PictureFrame):
picture_frame = shape
break
if picture_frame is not None:
image_transform = picture_frame.getPictureFormat().getPicture().getImageTransform()
for index in range(image_transform.size()):
operation = image_transform.get_Item(index)
print(index, ": ", operation.getClass().getSimpleName(), sep="")
if isinstance(operation, BrightnessContrast):
data = operation.getEffective()
print(" Brightness: ", data.getBrightness(), sep="")
print(" Contrast: ", data.getContrast(), sep="")
elif isinstance(operation, Luminance):
data = operation.getEffective()
print(" Brightness: ", data.getBrightness(), sep="")
print(" Contrast: ", data.getContrast(), sep="")
elif isinstance(operation, Duotone):
data = operation.getEffective()
print(" Dark color: ", data.getColor1(), sep="")
print(" Light color: ", data.getColor2(), sep="")
elif isinstance(operation, ColorReplace):
data = operation.getEffective()
print(" Replacement color: ", data.getColor(), sep="")
elif isinstance(operation, HSL):
data = operation.getEffective()
print(" HSL: ", data.getHue(), ", ", data.getSaturation(), ", ", data.getLuminance(), sep="")
elif isinstance(operation, Tint):
data = operation.getEffective()
print(" Tint: ", data.getHue(), ", ", data.getAmount(), sep="")
elif isinstance(operation, Blur):
data = operation.getEffective()
print(" Blur radius: ", data.getRadius(), " pt", sep="")
elif isinstance(operation, AlphaModulateFixed):
data = operation.getEffective()
print(" Alpha amount: ", data.getAmount(), "%", sep="")
elif isinstance(operation, AlphaReplace):
data = operation.getEffective()
print(" Replacement alpha: ", data.getAlpha(), "%", sep="")
elif isinstance(operation, AlphaBiLevel):
data = operation.getEffective()
print(" Alpha threshold: ", data.getThreshold(), "%", sep="")
finally:
presentation.dispose()
無參數的效果如灰階、alpha ceiling、alpha inverse 仍會有實際資料物件,但沒有可列印的純量設定。它們在集合中的存在與位置才是重要資訊。
移除或清除影像變換
使用 ImageTransformOperationCollection.removeAt 依索引移除單一操作。因為移除後索引會移位,請先搜尋目標,列舉完成後再移除。使用 ImageTransformOperationCollection.clear 可以清除整個鏈。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import Blur, PictureFrame, Presentation, SaveFormat
presentation = Presentation("image-transform-chain.pptx")
try:
picture_frame = None
for shape in presentation.getSlides().get_Item(0).getShapes():
if isinstance(shape, PictureFrame):
picture_frame = shape
break
if picture_frame is not None:
image_transform = picture_frame.getPictureFormat().getPicture().getImageTransform()
blur_index = -1
for index in range(image_transform.size()):
if isinstance(image_transform.get_Item(index), Blur):
blur_index = index
break
if blur_index >= 0:
image_transform.removeAt(blur_index)
print("The blur operation was removed.")
image_transform.clear()
print("Remaining operations: ", image_transform.size(), sep="")
presentation.save("image-transforms-cleared.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
移除或清除變換只會改變圖片的格式設定,不會刪除、重新壓縮或以其他方式修改重複使用的 PPImage 資源。
考慮簡報格式與匯出目標
影像變換起源於 DrawingML,因此 PPTX 是效果鏈的首選可編輯格式。即使是 PPTX,也不是所有操作都有相同的相容性:
- 標準 DrawingML 操作如亮度、灰階、雙調、色調、HSL、模糊與常見 alpha 操作最有機會在 PPTX 往返後仍存活。若有保存需求,請始終重新開啟產生的檔案並檢查集合。
- BrightnessContrast 是 Office 2010 的延伸,而非標準 DrawingML 亮度操作。它可用於記憶體內渲染,但不保證在儲存與重新開啟 PPTX 後仍為可編輯的 BrightnessContrast。請使用 addLuminanceEffect 以持久化亮度與對比度調整。
- 二進位 PPT 格式早於完整的 DrawingML 效果模型。儲存為 PPT 可能會省略不支援的操作,將鏈縮減為支援的子集,或近似外觀。請勿將 PPT 作為複雜可編輯鏈的驗證格式。
- 渲染至 PNG、JPEG、TIFF、PDF、SVG、HTML 或其他視覺輸出時,會將支援的鏈套用至渲染結果。這些輸出不包含可編輯的
ImageTransformOperationCollection;點陣格式會將結果平鋪成像素,文件/向量匯出則儲存其自身的渲染表示。 - 效果不會使連結影像變成自包含。渲染連結圖片仍然依賴於載入簡報時連結資源的可用性。
不同的簡報消費者在處理邊緣案例時可能會有不同的渲染結果,尤其是多個 alpha 或顏色量化操作結合時。對於關鍵輸出,請使用相同的 Aspose.Slides 版本測試可編輯往返與最終匯出格式。
常見問與答
影像變換效果會修改嵌入的影像資料嗎?
不會。這些操作屬於用於圖片填充的 Picture。底層的 PPImage 位元組保持不變。
重複使用相同影像的兩個圖片框會共享它們的效果嗎?
不會。重複使用 PPImage 只避免了影像資料的重複,但每個圖片框通常都有各自的 Picture 與影像變換集合。
顏色、模糊與 alpha 效果可以結合使用嗎?
可以。集合接受它們在同一有序鏈中。請考慮每個操作對先前輸出的影響,因為取代與閾值操作可能會丟棄先前的顏色或 alpha 細節。
為什麼實際值是唯讀的?
實際資料代表渲染時使用的計算值,包括解析後的顏色。若操作在集合中有可寫成員,請直接編輯該操作;若沒有,請移除並以新的建立參數加入替代。
哪種格式才能保留變換鏈?
使用 PPTX,並透過重新開啟檔案驗證。傳統 PPT 無法完整表示 DrawingML 效果模型,而渲染匯出格式只能保留外觀,無法保留可編輯的變換操作。