图像函数使用概述

更新时间:
复制 MD 格式

本文介绍图像函数的使用限制、调用规则、图像数据形态、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 类型

说明

编码图像

BYTES

JPEG、PNG、WebP 等编码格式的图片文件字节。适合在连接器、表和外部系统之间保存或传输。

解码图像

IMAGE

Flink SQL 内置图像类型,保存解码后的像素及必要元数据,主要作为图像函数之间的中间数据结构。

Data URL

STRING

形如 data:image/...;base64,... 的字符串,可用于浏览器预览或传给支持 Data URL 的下游接口。

  • 不同函数接受的数据形态不同,请以各函数的参数表为准。

  • 大部分图像处理函数的输入类型为 IMAGE,如果数据源中存储的是编码图片字节,通常需要先调用 IMAGE_DECODE 进行解码,只有部分边界函数支持 BYTES 或同时支持两种输入。

  • 图像编码相关函数通常支持以下编码格式:JPEG、PNG、TIFF、WEBP、BMP、GIF。

内置类型 IMAGE

类型定位

IMAGE 表示解码后的静态图片,包含图片像素数据,以及图片模式、高度和宽度三项元数据。

IMAGE 不保留原图片文件的编码格式,也不保留 EXIF、ICC 等文件级元数据。因此,IMAGE 适合作为内置图像函数或 UDF 计算过程中的中间数据载体,不适合作为外部系统中持久化读写的字段类型。

类型声明

IMAGE 在函数返回值、类型推导、类型展示或显式转换中可能出现以下形态:

类型

含义

示例

IMAGE

图片模式和尺寸均不固定。

IMAGE

IMAGE('<mode>')

固定图片模式,尺寸不固定。

IMAGE('RGB')

IMAGE('<mode>', <height>, <width>)

固定图片模式和精确尺寸。

IMAGE('RGB', 224, 224)

其中,<mode> 表示图片模式,<height> 和 <width> 分别表示图片高度和宽度。类型参数既用于描述解码后像素的元数据,也会作为约束校验实际数据。

图片模式

图片模式决定通道含义、通道数和每个通道元素的数据类型。目前支持以下图片模式:

模式

通道数

通道类型

说明

L

1

UINT8

8-bit 灰度图。

LA

2

UINT8

带 Alpha 通道的 8-bit 灰度图。

RGB

3

UINT8

8-bit RGB 图片。

RGBA

4

UINT8

带 Alpha 通道的 8-bit RGB 图片。

L16

1

UINT16

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;