本文介绍图像函数的使用限制、调用规则、图像数据形态、Flink SQL 内置 IMAGE 类型,以及多个图像处理 Pipeline 示例。
使用限制
仅实时计算引擎 VVR 11.8 及以上版本支持。
使用方法
使用说明
在平台 SQL 作业中,大部分图像函数(例如 IMAGE_DECODE、IMAGE_ENCODE、IMAGE_RESIZE)由内置 python 模块提供,无需在作业中引入额外依赖。使用由 python 模块提供的函数前,需要先加载该模块,再启用 python 和 core 模块:
LOAD MODULE python;
USE MODULES python, core;基本调用
图像处理通常包含“解码—处理—编码”三个阶段:先将编码图片字节解码为 IMAGE,再调用图像处理函数,最后按下游需要编码为图片字节或 Data URL。
LOAD MODULE python;
USE MODULES python, core;
WITH decoded AS (
SELECT
id,
IMAGE_DECODE(image_bytes, 'null', 'RGB') AS image_value
FROM raw_images
)
SELECT
id,
IMAGE_METADATA(image_value).width AS width,
IMAGE_METADATA(image_value).height AS height,
IMAGE_ENCODE(
IMAGE_RESIZE(image_value, 512, 512),
'JPEG',
85,
'bytes'
) AS resized_image_bytes
FROM decoded
WHERE image_value IS NOT NULL;参数调用
SQL 函数按签名中的顺序传参,只支持位置参数。函数签名中的 [ ] 表示可选参数。例如,IMAGE_ENCODE 的签名如下:
IMAGE_ENCODE(image_input [, format [, quality [, output]]])调用时遵循以下规则:
省略的可选参数会使用参数默认值进行填充。
如果需要显式设置靠后的可选参数,前面的可选参数也需要明确写出。
NULL会作为参数值传入,不等同于省略参数时的默认值。除逐行图像输入(例如
image_bytes和image_input)以及函数文档明确标注的数据参数外,模式、格式、尺寸、阈值和算法等配置参数必须使用 SQL 字面量,不能使用表字段或CAST表达式。
数据类型说明
图像数据形态
图像处理链路中的数据通常以三种形态存在:
数据形态 | SQL 类型 | 说明 |
编码图像 |
| JPEG、PNG、WebP 等编码格式的图片文件字节。适合在连接器、表和外部系统之间保存或传输。 |
解码图像 |
| Flink SQL 内置图像类型,保存解码后的像素及必要元数据,主要作为图像函数之间的中间数据结构。 |
Data URL |
| 形如 |
不同函数接受的数据形态不同,请以各函数的参数表为准。
大部分图像处理函数的输入类型为
IMAGE,如果数据源中存储的是编码图片字节,通常需要先调用IMAGE_DECODE进行解码,只有部分边界函数支持BYTES或同时支持两种输入。图像编码相关函数通常支持以下编码格式:
JPEG、PNG、TIFF、WEBP、BMP、GIF。
内置类型 IMAGE
类型定位
IMAGE 表示解码后的静态图片,包含图片像素数据,以及图片模式、高度和宽度三项元数据。
IMAGE 不保留原图片文件的编码格式,也不保留 EXIF、ICC 等文件级元数据。因此,IMAGE 适合作为内置图像函数或 UDF 计算过程中的中间数据载体,不适合作为外部系统中持久化读写的字段类型。
类型声明
IMAGE 在函数返回值、类型推导、类型展示或显式转换中可能出现以下形态:
类型 | 含义 | 示例 |
| 图片模式和尺寸均不固定。 |
|
| 固定图片模式,尺寸不固定。 |
|
| 固定图片模式和精确尺寸。 |
|
其中,<mode> 表示图片模式,<height> 和 <width> 分别表示图片高度和宽度。类型参数既用于描述解码后像素的元数据,也会作为约束校验实际数据。
图片模式
图片模式决定通道含义、通道数和每个通道元素的数据类型。目前支持以下图片模式:
模式 | 通道数 | 通道类型 | 说明 |
| 1 |
| 8-bit 灰度图。 |
| 2 |
| 带 Alpha 通道的 8-bit 灰度图。 |
| 3 |
| 8-bit RGB 图片。 |
| 4 |
| 带 Alpha 通道的 8-bit RGB 图片。 |
| 1 |
| 16-bit 灰度图。 |
图片模式与图片文件的编码格式是两个不同概念。例如,RGB 描述解码后的像素通道,而 JPEG 和 PNG 描述编码后的文件格式。
类型转换
IMAGE类型之间只支持放宽约束的转换,例如IMAGE('RGB', 224, 224) -> IMAGE('RGB') -> IMAGE;不支持收紧或改变约束的转换,例如IMAGE -> IMAGE('RGB')或IMAGE('RGB') -> IMAGE('L')。CAST(image_value AS STRING)只输出图片元数据摘要,不能用于预览图片。样例输出:
IMAGE(mode='RGB', height=224, width=224)图像预览
根据当前数据是解码后的 IMAGE,还是编码后的 BYTES,可以使用以下两种方式生成 Data URL。
预览解码后的 IMAGE
对于 IMAGE 值,可以通过 IMAGE_ENCODE 的 'data_url' 输出模式完成图片编码和 Base64 转换:
SELECT
IMAGE_ENCODE(
image_value,
'JPEG', -- 图像编码格式,例如'JPEG'、'PNG'等
85, -- 图像压缩质量,影响'JPEG'、'WEBP'等有损格式
'data_url' -- 'bytes'表示输出原始编码字节,'data_url'表示输出 Data URL
) AS preview_url
FROM processed_images;预览编码后的图片字节
如果已经有编码后的图片字节和对应的 MIME 类型,则不需要先解码再编码。可以使用 TO_BASE64 对图片字节进行 Base64 编码,再通过 CONCAT 拼接 Data URL:
SELECT
id,
CONCAT(
'data:',
mime_type,
';base64,',
TO_BASE64(image_bytes)
) AS preview_url
FROM encoded_images;生成结果类似:
data:image/jpeg;base64,...图片较小时,可以直接复制到浏览器地址栏预览。
图片较大时,建议把完整 Data URL 写入 HTML 文件,并作为
img标签的src属性查看。例如:
<!doctype html>
<html>
<body>
<img src="data:image/jpeg;base64,..." />
</body>
</html>Pipeline 示例
基础示例:统一尺寸并生成输出
以下示例先将原始图片字节解码为 RGB 图片,再统一缩放到 512 × 512,最后同时输出图片元数据、JPEG 字节和用于预览的 Data URL:
LOAD MODULE python;
USE MODULES python, core;
-- 步骤 1:解码原始图片;无法解码的数据返回 NULL,避免单条坏数据中断作业。
WITH decoded AS (
SELECT
id,
IMAGE_DECODE(
image_bytes,
'null',
'RGB'
) AS image_value
FROM raw_images
),
-- 步骤 2:过滤解码失败的数据,并将有效图片统一缩放到 512 × 512。
resized AS (
SELECT
id,
IMAGE_RESIZE(
image_value,
512,
512,
'lanczos'
) AS image_value
FROM decoded
WHERE image_value IS NOT NULL
)
-- 步骤 3:输出处理后的元数据、编码字节和浏览器预览地址。
SELECT
id,
IMAGE_METADATA(image_value).mode AS image_mode,
IMAGE_METADATA(image_value).width AS image_width,
IMAGE_METADATA(image_value).height AS image_height,
IMAGE_ENCODE(
image_value,
'JPEG',
85,
'bytes'
) AS image_bytes,
IMAGE_ENCODE(
image_value,
'JPEG',
85,
'data_url'
) AS preview_url
FROM resized;场景一:电商商品主图标准化
商品图片可能存在复杂背景、尺寸不一致等问题。以下示例先解码商品图片,再移除原背景并填充白色背景,随后统一为 800 × 800 的 JPEG 主图,最后基于编码后的字节生成预览地址:
LOAD MODULE python;
USE MODULES python, core;
-- 步骤 1:将商品图片解码为 RGB;坏图返回 NULL。
WITH decoded AS (
SELECT
sku_id,
IMAGE_DECODE(
image_bytes,
'null',
'RGB'
) AS image_value
FROM product_images
),
-- 步骤 2:移除商品背景,并使用不透明白色作为新背景。
white_background AS (
SELECT
sku_id,
IMAGE_REMOVE_BACKGROUND(
image_value,
FALSE,
240,
10,
10,
ARRAY[255, 255, 255, 255]
) AS image_value
FROM decoded
WHERE image_value IS NOT NULL
),
-- 步骤 3:按照商品平台规范统一主图尺寸。
standardized AS (
SELECT
sku_id,
IMAGE_RESIZE(
image_value,
800,
800,
'lanczos'
) AS image_value
FROM white_background
),
-- 步骤 4:将标准化图片编码为 JPEG 字节,供对象存储或下游表保存。
encoded AS (
SELECT
sku_id,
IMAGE_ENCODE(
image_value,
'JPEG',
90,
'bytes'
) AS image_bytes
FROM standardized
)
-- 步骤 5:保留编码字节,并按需生成运营审核页面使用的预览地址。
SELECT
sku_id,
image_bytes,
CONCAT(
'data:image/jpeg;base64,',
TO_BASE64(image_bytes)
) AS preview_url
FROM encoded;场景二:扫描件 OCR 前处理
合同、票据等扫描件经常带有黑边、彩色噪声或较低对比度。以下示例先裁剪黑边,再转换为灰度图并增强对比度,最后执行 OCR,同时保留预处理后的 PNG 图片用于结果复核:
LOAD MODULE python;
USE MODULES python, core;
-- 步骤 1:解码每一页扫描图片;坏图返回 NULL。
WITH decoded AS (
SELECT
document_id,
page_no,
IMAGE_DECODE(
image_bytes,
'null',
'RGB'
) AS image_value
FROM scanned_document_pages
),
-- 步骤 2:自动检测并裁剪页面四周的黑边。
cropped AS (
SELECT
document_id,
page_no,
IMAGE_CROP_BLACK_BORDER(
image_value,
'auto',
10,
1.0,
1
) AS image_value
FROM decoded
WHERE image_value IS NOT NULL
),
-- 步骤 3:转换为 8-bit 灰度图,减少颜色信息对文字识别的干扰。
grayscale AS (
SELECT
document_id,
page_no,
IMAGE_CONVERT_MODE(
image_value,
'L'
) AS image_value
FROM cropped
),
-- 步骤 4:保持亮度不变,将对比度提高到原图的 1.25 倍。
enhanced AS (
SELECT
document_id,
page_no,
IMAGE_ADJUST_COLOR(
image_value,
1.0,
1.25,
1.0
) AS image_value
FROM grayscale
)
-- 步骤 5:识别英文文本,并保留预处理图片以便人工复核。
SELECT
document_id,
page_no,
IMAGE_OCR(
image_value,
ARRAY['en']
) AS ocr_result,
IMAGE_ENCODE(
image_value,
'PNG'
) AS preprocessed_image_bytes
FROM enhanced;