图像编解码与变换处理

更新时间:
复制 MD 格式

本文介绍 Python DataFrame API 中的图像编解码、格式转换、尺寸变换和像素处理算子。

使用前须知

  • 仅实时计算引擎 VVR 11.8 及以上版本支持。

  • 编码图片列使用 DataType.binary(),解码后的图像列使用 DataType.image()。

  • image_compress 和 image_convert_format 可以直接处理编码图片。其他处理算子通常需要先通过 image_decode 获得 DataType.image(),处理完成后再按需通过 image_encode 转回编码图片。

  • “输入类型” 和 “返回类型” 使用 DataFrame API 类型表达;参数表使用 Python 类型。

算子清单

分类

算子

说明

编解码

image_decode

将原始图像字节解码为 DataType.image()。

image_encode

将解码后的图像编码为压缩字节或 Data URL。

编码转换

image_compress

将编码图像字节重新压缩。

image_convert_format

转换编码格式。

类型转换

image_convert_mode

转换图像模式。

image_to_tensor

将图像转换为定形状 float32 Tensor。

尺寸与裁剪

image_resize

缩放到指定尺寸。

image_rescale

按比例缩放。

image_crop

裁剪图像区域。

image_crop_black_border

检测并裁剪黑边。

图像增强

image_flip

翻转图像。

image_blur

模糊处理。

image_adjust_color

调整亮度、对比度和饱和度。

图像背景处理

image_remove_background

移除图像背景。

通用 Runtime 参数

函数签名保留各算子实际支持的 Runtime 参数。为避免重复解释,算子参数表只说明业务参数,Runtime 参数统一说明如下。

参数

类型

默认值

适用范围

说明

concurrency

Optional[int]

None

本页全部算子

UDF 并发度。None 表示使用框架默认值。

model_sharing

Optional[str]

None

image_remove_background

模型共享方式。None 表示使用框架默认值。

batch_size

Optional[int]

None

image_remove_background

Batch UDF 批大小。None 表示使用框架默认值。

num_gpus

Optional[float]

None

image_remove_background

每个模型实例申请的 GPU 数量或份额,例如 1。

gpu_type

Optional[str]

None

image_remove_background

GPU 类型,与 num_gpus 配套设置。

编解码与类型转换

image_decode

将原始图像字节解码为 Flink 内置图像类型 DataType.image()。

输入类型: DataType.binary(),编码图片字节列。

函数签名:

image_decode(
    *columns,
    on_error="raise",
    mode=None,
    pixel_limit=None,
    concurrency=None
)

参数

类型

默认值

说明

on_error

str

"raise"

"raise" 表示抛出解码异常;"null" 表示对无法解码或超出像素限制的输入返回空值。需要注意,Python 默认值与 SQL 不同。

mode

Optional[str]

None

目标图像模式。None 表示尽量保留源图模式;源模式无法表示时转换为 RGB 或 RGBA。

pixel_limit

Optional[int]

None

最大像素数。超过限制的输入按 on_error 处理。

返回类型: 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
)

参数

类型

默认值

说明

quality

int

85

编码质量,取值范围为 [1, 100];只影响 JPEG、WebP 等有损格式。

output

str

"bytes"

bytes 返回编码字节;data_url 返回 Base64 Data URL。

format

Optional[str]

None

目标格式,例如 "JPEG" 或 "PNG"。注意None 默认使用 JPEG;RGBA 图像编码为 JPEG 时默认转换为 RGB。

返回类型:

  • 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
)

参数

类型

默认值

说明

quality

int

85

压缩质量,取值范围为 [1, 100];影响 JPEG、WebP 等有损格式。

format

str

"JPEG"

输出格式,例如 "JPEG"、"PNG"。

返回类型: 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
)

参数

类型

默认值

说明

format

str

必填

目标格式,例如 "PNG"、"JPEG"、"WEBP" 或 "BMP"。

返回类型: 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
)

参数

类型

默认值

说明

mode

str

必填

目标模式,例如 RGB、RGBA、L 或 L16。

返回类型: 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
)

参数

类型

默认值

说明

width

int

必填

输入图像必须具备的宽度。

height

int

必填

输入图像必须具备的高度。

mode

str

"RGB"

用于声明输出 Tensor 的通道数,例如 "RGB" 为 3 通道、"L" 为 1 通道。算子只校验输入图像的实际通道数,不校验图像模式名称。

layout

str

"CHW"

"CHW" 返回 (channels, height, width);"HWC" 返回 (height, width, channels)。

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
)

参数

类型

默认值

说明

width

int

必填

目标宽度,必须为正整数。

height

int

必填

目标高度,必须为正整数。

method

str

"lanczos"

缩放算法。支持 "lanczos"、"bilinear"、"bicubic" 和 "nearest"。

返回类型: 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
)

参数

类型

默认值

说明

scale

float

必填

缩放比例,必须大于 0。例如,0.5 表示缩小一半。

method

str

"lanczos"

缩放算法。支持 "lanczos"、"bilinear"、"bicubic" 和 "nearest"。

返回类型: 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
)

参数

类型

默认值

说明

crop_coords

Optional[Sequence[int]]

None

绝对像素框 (x1, y1, x2, y2)。设置后自动使用 "coordinate";超出原图的区域以零值像素填充。

crop_type

str

"center"

裁剪方式。支持 "center"、"ratio" 和 "coordinate"。

crop_ratio

Sequence[float]

(0.8, 0.8)

保留的宽、高比例 (width_ratio, height_ratio),每项范围为 (0, 1]。

crop_size

Optional[Union[List[int], Tuple[int, int]]]

None

中心裁剪的固定输出 (width, height),仅用于 "center"。

返回类型: 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
)

参数

类型

默认值

说明

threshold

Optional[int]

None

black_threshold 的兼容参数,不能与 black_threshold 同时设置。

detect_algorithm

str

"auto"

检测算法。支持 "auto"、"threshold"、"histogram" 和 "edge"。

black_threshold

Optional[int]

None

0~255 的亮度阈值;None 使用 10。亮度不高于该值的像素视为黑色。

edge_sensitivity

float

1.0

边缘检测灵敏度,取值范围为 [0.1, 2.0]。

min_border_size

int

1

触发裁剪的最小黑边宽度,单位为像素。

返回类型: 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
)

参数

类型

默认值

说明

mode

str

"horizontal"

翻转方式。支持 "horizontal"、"vertical" 和 "rotate180"。

返回类型: 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
)

参数

类型

默认值

说明

radius

float

2

模糊半径,必须为有限的非负数。blur_type="mean" 时该参数不生效。

blur_type

str

"gaussian"

模糊方式。支持 "gaussian"、"box" 和 "mean"。

返回类型: 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
)

参数

类型

默认值

说明

brightness

float

1.0

亮度系数,必须为非负数;1.0 表示不变。

contrast

float

1.0

对比度系数,必须为非负数;1.0 表示不变。

saturation

float

1.0

饱和度系数,必须为非负数;1.0 表示不变。

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

bool

False

是否启用 Alpha Matting。

alpha_matting_foreground_threshold

int

240

Alpha Matting 前景阈值,取值范围为 [0, 255]。

alpha_matting_background_threshold

int

10

Alpha Matting 背景阈值,取值范围为 [0, 255]。

alpha_matting_erode_size

int

10

Alpha Matting 腐蚀核大小,必须为正整数。

bgcolor

Optional[Union[List[int], Tuple[int, int, int, int]]]

None

RGBA 背景颜色 (R, G, B, A),列表长度必须为 4;每个分量范围为 [0, 255]。None 使用透明背景。

返回类型: 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)
    )
)