本文介绍 Python DataFrame API 中的图像编解码、格式转换、尺寸变换和像素处理算子。
使用前须知
-
仅实时计算引擎 VVR 11.8 及以上版本支持。
-
编码图片列使用
DataType.binary(),解码后的图像列使用DataType.image()。 -
image_compress和image_convert_format可以直接处理编码图片。其他处理算子通常需要先通过image_decode获得DataType.image(),处理完成后再按需通过image_encode转回编码图片。 -
“输入类型” 和 “返回类型” 使用 DataFrame API 类型表达;参数表使用 Python 类型。
算子清单
|
分类 |
算子 |
说明 |
|
编解码 |
将原始图像字节解码为 |
|
|
将解码后的图像编码为压缩字节或 Data URL。 |
||
|
编码转换 |
将编码图像字节重新压缩。 |
|
|
转换编码格式。 |
||
|
类型转换 |
转换图像模式。 |
|
|
将图像转换为定形状 float32 Tensor。 |
||
|
尺寸与裁剪 |
缩放到指定尺寸。 |
|
|
按比例缩放。 |
||
|
裁剪图像区域。 |
||
|
检测并裁剪黑边。 |
||
|
图像增强 |
翻转图像。 |
|
|
模糊处理。 |
||
|
调整亮度、对比度和饱和度。 |
||
|
图像背景处理 |
移除图像背景。 |
通用 Runtime 参数
函数签名保留各算子实际支持的 Runtime 参数。为避免重复解释,算子参数表只说明业务参数,Runtime 参数统一说明如下。
|
参数 |
类型 |
默认值 |
适用范围 |
说明 |
|
|
|
|
本页全部算子 |
UDF 并发度。 |
|
|
|
|
|
模型共享方式。 |
|
|
|
|
|
Batch UDF 批大小。 |
|
|
|
|
|
每个模型实例申请的 GPU 数量或份额,例如 |
|
|
|
|
|
GPU 类型,与 |
编解码与类型转换
image_decode
将原始图像字节解码为 Flink 内置图像类型 DataType.image()。
输入类型: DataType.binary(),编码图片字节列。
函数签名:
image_decode(
*columns,
on_error="raise",
mode=None,
pixel_limit=None,
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
|
|
|
|
|
目标图像模式。 |
|
|
|
|
最大像素数。超过限制的输入按 |
返回类型: DataType.image()。
from pyflink.dataframe import col
from pyflink.multimodal.operators import image_decode
result = df.with_column(
"image",
image_decode(
col("image_bytes"),
on_error="null",
mode="RGB",
pixel_limit=8192 * 8192
)
)
image_encode
将解码后的图像编码为压缩字节,或编码为 Base64 Data URL 字符串。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_encode(
*columns,
format=None,
quality=85,
output="bytes",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
编码质量,取值范围为 |
|
|
|
|
|
|
|
|
|
目标格式,例如 |
返回类型:
-
output="bytes"时为DataType.binary(); -
output="data_url"时为DataType.string()。
from pyflink.multimodal.operators import image_encode
result = (
df
.with_column(
"jpeg_bytes",
image_encode(col("image"), format="JPEG", quality=90)
)
.with_column(
"data_url",
image_encode(col("image"), format="PNG", output="data_url")
)
)
image_compress
将编码图像按照指定的格式和质量系数重新压缩。
输入类型: DataType.binary(),编码图片列。
函数签名:
image_compress(
*columns,
quality=85,
format="JPEG",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
压缩质量,取值范围为 |
|
|
|
|
输出格式,例如 |
返回类型: DataType.binary()。
from pyflink.multimodal.operators import image_compress
result = df.with_column(
"compressed",
image_compress(
col("image_bytes"),
quality=60,
format="JPEG"
)
)
image_convert_format
将编码图像转换为不同的编码格式。
输入类型: DataType.binary(),编码图片列。
函数签名:
image_convert_format(
*columns,
format,
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
必填 |
目标格式,例如 |
返回类型: DataType.binary()。
from pyflink.multimodal.operators import image_convert_format
result = df.with_column(
"png_bytes",
image_convert_format(
col("image_bytes"),
format="PNG"
)
)
image_convert_mode
将图像转换为目标模式。
输入类型: DataType.image(),解码图像列。
函数签名:
image_convert_mode(
*columns,
mode,
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
必填 |
目标模式,例如 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_convert_mode
result = df.with_column(
"grayscale",
image_convert_mode(
col("image"),
mode="L"
)
)
image_to_tensor
将图像转换为定形状 float32 Tensor。该算子不会自动缩放或转换模式;尺寸或通道数不匹配时返回 None。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_to_tensor(
*columns,
width,
height,
mode="RGB",
layout="CHW",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
必填 |
输入图像必须具备的宽度。 |
|
|
|
必填 |
输入图像必须具备的高度。 |
|
|
|
|
用于声明输出 Tensor 的通道数,例如 |
|
|
|
|
|
uint8 或 uint16 像素会转换为 float32,并缩放到 [0, 1]。
返回类型: DataType.tensor("float32", shape=...)。输出形状由 width、height、mode 和 layout 确定。
from pyflink.multimodal.operators import (
image_convert_mode,
image_resize,
image_to_tensor,
)
result = df.with_column(
"tensor",
image_to_tensor(
col("image"),
width=224,
height=224,
mode="RGB",
layout="CHW"
)
)
尺寸与裁剪
image_resize
将图像缩放到指定尺寸(非等比放缩,等比放缩使用 image_rescale)。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_resize(
*columns,
width,
height,
method="lanczos",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
必填 |
目标宽度,必须为正整数。 |
|
|
|
必填 |
目标高度,必须为正整数。 |
|
|
|
|
缩放算法。支持 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_resize
result = df.with_column(
"resize_image",
image_resize(
col("image"),
width=256,
height=256
)
)
image_rescale
按比例缩放图像。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_rescale(
*columns,
scale,
method="lanczos",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
必填 |
缩放比例,必须大于 0。例如, |
|
|
|
|
缩放算法。支持 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_rescale
result = df.with_column(
"half_size",
image_rescale(
col("image"),
scale=0.5
)
)
image_crop
裁剪图像区域。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_crop(
*columns,
crop_coords=None,
crop_type="center",
crop_ratio=(0.8, 0.8),
crop_size=None,
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
绝对像素框 |
|
|
|
|
裁剪方式。支持 |
|
|
|
|
保留的宽、高比例 |
|
|
|
|
中心裁剪的固定输出 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_crop
result = df.with_column(
"roi",
image_crop(
col("image"),
crop_coords=(100, 100, 500, 500)
)
)
image_crop_black_border
检测并裁剪图像黑边。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_crop_black_border(
*columns,
threshold=None,
detect_algorithm="auto",
black_threshold=None,
edge_sensitivity=1.0,
min_border_size=1,
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
|
|
|
|
|
检测算法。支持 |
|
|
|
|
0~255 的亮度阈值; |
|
|
|
|
边缘检测灵敏度,取值范围为 |
|
|
|
|
触发裁剪的最小黑边宽度,单位为像素。 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_crop_black_border
result = df.with_column(
"clean",
image_crop_black_border(
col("image"),
black_threshold=15
)
)
图像增强
image_flip
翻转图像。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_flip(
*columns,
mode="horizontal",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
翻转方式。支持 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_flip
result = df.with_column(
"flipped",
image_flip(
col("image"),
mode="vertical"
)
)
image_blur
对图像应用模糊处理。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_blur(
*columns,
radius=2,
blur_type="gaussian",
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
模糊半径,必须为有限的非负数。 |
|
|
|
|
模糊方式。支持 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_blur
result = df.with_column(
"blurred",
image_blur(
col("image"),
radius=5,
blur_type="gaussian"
)
)
image_adjust_color
调整亮度、对比度和饱和度。
输入类型: DataType.image(),解码后的图像列。
函数签名:
image_adjust_color(
*columns,
brightness=1.0,
contrast=1.0,
saturation=1.0,
concurrency=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
亮度系数,必须为非负数; |
|
|
|
|
对比度系数,必须为非负数; |
|
|
|
|
饱和度系数,必须为非负数; |
L16 模式不支持实际的颜色调整。
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_adjust_color
result = df.with_column(
"enhanced",
image_adjust_color(
col("image"),
brightness=1.1,
contrast=1.2,
saturation=0.9
)
)
image_remove_background
移除图像背景,返回透明背景或指定背景色填充的图像。
输入类型: DataType.image(),解码后的图像列。
依赖: pip install rembg
函数签名:
image_remove_background(
*columns,
alpha_matting=False,
alpha_matting_foreground_threshold=240,
alpha_matting_background_threshold=10,
alpha_matting_erode_size=10,
bgcolor=None,
model_sharing=None,
concurrency=None,
batch_size=None,
num_gpus=None,
gpu_type=None
)
|
参数 |
类型 |
默认值 |
说明 |
|
|
|
|
是否启用 Alpha Matting。 |
|
|
|
|
Alpha Matting 前景阈值,取值范围为 |
|
|
|
|
Alpha Matting 背景阈值,取值范围为 |
|
|
|
|
Alpha Matting 腐蚀核大小,必须为正整数。 |
|
|
|
|
RGBA 背景颜色 |
返回类型: DataType.image()。
from pyflink.multimodal.operators import image_remove_background
result = df.with_column(
"foreground",
image_remove_background(
col("image"),
alpha_matting=True,
bgcolor=(255, 255, 255, 255)
)
)