跳到主要内容
vane
Star联系我们
Vane Data / API 参考

多模态数据

Vane 使用 FILE 家族类型表示不可变文件引用，使用 IMAGE 表示解码后的图像像素，使用 TENSOR 表示数值数组，包括音频波形。下文按文件、图像、音频、视频和张量介绍相关的 Python 与 SQL 接口。图像、音频和视频函数默认使用 python 后端；加载 native_media 扩展后，可以切换到 native 后端。

Expression 调用返回惰性的 vane.Expression，可用 .alias(...) 命名。SQL 标量函数可用于 SELECT 表达式，通过 AS 命名结果；list_files、read_video_frames 等表函数用于 FROM 子句。

函数分类

  • 文件函数：构造和查看 FILE 家族值。
  • 图像函数：解码、查看、变换和编码 IMAGEFILE 与 IMAGE 值。
  • 音频函数：查看 AUDIOFILE 元数据并重采样波形。
  • 视频函数：按行输出解码帧，并构建或解析可复用寻址索引。
  • 张量函数：构造和查看 TENSOR 值。

类型

SQL 类型存储含义
FILESTRUCT(url VARCHAR, content_type VARCHAR, position BIGINT, size BIGINT, checksum VARCHAR)通用不可变对象引用，可带字节窗口（position、size）
IMAGEFILE同上五字段，IMAGE 子类型编码后的图像对象
AUDIOFILE同上五字段，AUDIO 子类型编码后的音频对象
VIDEOFILE同上五字段，VIDEO 子类型编码后的视频对象
IMAGE动态 STRUCT(data, channel, height, width, mode)；固定形状的 IMAGE(mode, H, W) 为稠密 ARRAY解码后的交错 HWC 像素
TENSOR(dtype, shape)可变形状用 STRUCT(data LIST, shape INTEGER[rank])，同列的秩固定；固定形状用稠密 ARRAY稠密行主序数值张量

FILE 家族的构造器为 file、image_file、audio_file、video_file；图像为 IMAGE、IMAGE('RGB')、IMAGE('RGB', H, W)；张量为 tensor(data, shape)。SQL 中 image(data, width, height, channels, mode) 从打包像素字节构建动态 IMAGE；data 必须恰好包含 width * height * channels 个该模式的像素元素。Python 中 vane.File、vane.ImageFile、vane.AudioFile、vane.VideoFile 是同五字段的不可变引用。

类型构造器与枚举

Python 的类型构造器生成 Vane 类型，vane.MediaType 选择 FILE 子类型：

API返回
vane.file_type(media_type=vane.MediaType.unknown())media_type 对应的 FILE 家族类型
vane.image_type(mode=None, height=None, width=None)IMAGE 类型；常量 mode 与尺寸会收窄它
vane.tensor_type(type, shape)TENSOR 类型；None 表示可变维度
vane.MediaType.unknown() / image() / audio() / video()FILE 子类型选择器

image_type() 返回动态 IMAGE；给出 mode 会收窄类型，要固定两个维度则必须同时给出 mode, height, width。tensor_type(type, shape) 接收 Vane 元素类型和非空形状，形状项为非负整数或表示可变维度的 None（可变形状秩为 1–32）。非法模式、维度或形状会报错。

vane.ImageProperty（height、width、channel、mode）是 image_attribute 的属性名；vane.ImageMode 与 vane.ImageFormat 枚举支持的像素模式与编码格式。

IMAGE 模式

像素 dtype 由模式决定：

模式像素 dtype通道数
L、LA、RGB、RGBAUInt81、2、3、4
L16、LA16、RGB16、RGBA16UInt161、2、3、4
RGB32F、RGBA32FFloat323、4

泛型 IMAGE 存储为 Float32，一列可无损容纳全部模式；已知模式存储其原生像素 dtype。读取的单元格物化为形状 (height, width, channels) 的 C 连续 NumPy 数组；vane.Image 是这些 UInt8、UInt16 或 Float32 数组的 Python 类型别名。Arrow 用 vane.image 扩展承载固定形状图像。

expr.as_image(mode=None, height=None, width=None) 检查已有图像表达式是否满足指定 IMAGE 类型的约束。普通 cast 不转换颜色、不缩放像素，布局不匹配时 TRY_CAST 返回 NULL。

音频特化

音频波形使用形状 (frames, channels) 的 Float64 张量；两维都可逐行变化，通道数为正，零帧（(0, channels)）表示空音频。重采样契约见音频函数。

取值契约

非 NULL 图像要求所有字段和像素非 NULL，宽高为正。非 NULL 张量没有 NULL 维度或元素，任一维度的大小为 0 时表示空张量，与 NULL 张量不同。File 值的查看、子类型分类、相等与转换见文件函数。

后端

图像、音频和视频分别通过 image_backend、audio_backend、video_backend 独立选择执行后端。三项设置的默认值都是 python，仅接受 python 或 native。

native 为实验性功能：其 native_media 扩展与 provider wheel 可能随版本变化。

后端使用的实现需要安装
python图像用 Pillow/tifffile/imagecodecs，音频用 SoundFile/SoXR，视频用 PyAVvane-ai[image]、vane-ai[audio]、vane-ai[video]
native可选 native_media C++ 扩展（FFmpeg、libsndfile、SoXR）vane-extension-native-media provider wheel
example.py
import vane


con = vane.connect()
vane.load_installed_extension("native_media", connection=con)
con.execute("SET image_backend = 'native'")

image_to_tensor 与 IMAGE 访问器属于基础引擎，无论选择哪种后端都不需要可选扩展。

来源与相关页面

编辑本页