lievisual
声明式视觉场景 IR + 可插拔渲染后端。
lievisual 是一个 Rust 图形库,定位为 liecharts / liemermaid / liepress 共享的"绘图层":
上层业务(图表 / 流程图 / Markdown)只产出声明式的 Scene(描述"画什么"),再由所选
后端输出 SVG 矢量、vello_cpu 栅格 PNG 或(规划中的)GPU 加速画面(描述"怎么画")。
- 纯 Rust,
edition 2024,无 unsafe 业务代码 - 无 feature gate:SVG / vello / 文本排版默认全部启用
- 文本 API 对齐 Web Canvas
CanvasRenderingContext2D,方便从浏览器习惯迁移
特性
- IR 与后端分离:
Scene/Element描述画什么,Renderertrait 描述怎么画。 新增后端(如 GPU)不影响 IR;新增图元变体只需在Renderer各实现里加一个match分支,且draw_*均有默认实现(几何转BezPath后走draw_path), 新后端不实现也能正确渲染。 - 统一层级与节点属性:
z_index/Transform/clip/opacity/name/visible提升为SceneNode的字段。transform与opacity对Group子树递归 复合,clip限制整棵子树,visible = false整棵子树跳过。 - 图层(Layer):
Scene可携带一组有序图层(从底到顶),整层控制name/visible/opacity/transform;层内节点再按z_index稳定排序。 - 图元丰富:矩形、圆、椭圆(可旋转)、圆角矩形、线、折线、多边形、圆弧(开放描边)、 扇形(闭合,适合饼图)、路径、渐变路径、文本(双形态)、组合 Group。
- 填充多样:纯色 / 线性渐变 / 径向渐变(坐标一律为绝对用户坐标);描边支持
线帽 / 连接 / 虚线(
dash_array/dash_offset)/miter_limit。 - 裁剪:矩形 / 圆角矩形 / 圆 / 椭圆 / 任意贝塞尔路径,跨后端一致
(SVG
<clipPath>/ vellopush_clip_path)。 - 场景元数据:
title/description(SVG 输出<title>/<desc>)与scale(像素密度,SVG 放大输出尺寸而保持viewBox)。 - 文本(Canvas 风格):
font-family/font-size/font-weight/font-style/line-height+textAlign+textBaseline;measure_text对应ctx.measureText(), 返回TextMetrics。排版上下文按线程缓存(thread-local),避免反复系统字体扫描。
快速开始
Cargo.toml:
[]
= "0.1"
构建一个场景并输出 SVG:
use ;
use SvgRenderer;
use ;
let mut scene = new.with_background;
// 矩形 + 文本
scene.push;
scene.push;
// 输出 SVG
let mut svg = new;
scene.render;
let svg_str = svg.into_string;
输出 PNG(VelloPixmapRenderer):
use VelloPixmapRenderer;
let mut renderer = new.with_background;
let png: = renderer.render_png;
运行仓库自带的丰富演示(同时输出 demo.svg 与 demo.png):
后端
| 后端 | 输出 | 文本处理 |
|---|---|---|
SvgRenderer |
矢量 SVG 字符串 | 原生 <text>(text-anchor / dominant-baseline / font-weight / font-style),不依赖 parley |
VelloPixmapRenderer |
Pixmap → PNG 字节 |
parley 排版(统一 TLS 上下文),优先用调用者提供的 TextLayout |
GPU(vello_hybrid) |
GPU 加速(规划中) | 同 vello,仅 Scene 提交方式不同 |
所有后端默认启用,无需 feature 开关。图层在 SVG 端输出为 <g id="layer-name">
(含整层 opacity / transform),栅格端并入透明度 / 变换栈。
模块结构
src/
geometry.rs 点 / 向量 / 尺寸 / 矩形 / 颜色 / 仿射变换(f64 精度,与 kurbo / parley / vello 对齐)
scene.rs Scene(元数据 + 图层 layers)/ Layer / SceneNode(层级 + 节点属性)/
Element(图元枚举)/ 样式(FillStrokeStyle / Fill / Stroke 含虚线)/ Clip
text.rs Canvas 风格文本 API:TextStyle / TextAlign / TextBaseline / TextMetrics /
measure_text(thread-local 排版上下文缓存)
render/
mod.rs Renderer trait + 默认 render_scene_ordered(排序 + 节点属性 + 图层 + 递归 Group / 变换)
svg.rs SvgRenderer(原生标签 + 用户坐标渐变 + title/desc/scale + 图层 <g>)
vello_pixmap.rs VelloPixmapRenderer(vello_cpu 0.2 → PNG;统一渐变填充、虚线描边、变换栈与透明度栈)
设计原则
- IR 与后端分离。
Scene/Element描述"画什么",Renderertrait 描述"怎么画"。 新增后端不影响 IR;新增图元只需在Renderer各实现里加match分支。 - 层级与节点属性提升。
z_index/Transform/clip/opacity/name/visible是SceneNode的字段,而非每个图元重复携带。 - 图层(Layer)。
Scene可携带一组有序Layer,整层控制name/visible/opacity/transform;Scene::nodes作为默认层(最底)保留,向后兼容。 - 填充多样。纯色 / 线性渐变 / 径向渐变,坐标一律为绝对用户坐标(SVG 端以
gradientUnits="userSpaceOnUse"保证与 IR 一致)。 - 文本(Canvas 风格)。对齐 Web Canvas,方便上层从浏览器习惯迁移;排版上下文 按线程缓存(thread-local)。
- 无 feature gate。SVG / vello / text 默认全部启用。
颜色约定
geometry::Color:RGBA,分量 0.0–1.0,贯穿整个 IR。- 作为 parley 的 brush 类型:
Color自动满足parley::Brushmarker trait,无需转换。 - 栅格化时由后端
to_vello转为AlphaColor<Srgb>,并乘入当前节点透明度。
依赖版本对齐
kurbo = "0.13":与vello_cpu 0.2内部 kurbo 0.13 对齐,避免双版本类型不兼容。parley = "0.11"、vello_cpu = "0.2":参考 liemermaid 已验证可用的组合。peniko 0.6(随 vello_cpu):支持 Linear / Radial 两种渐变。image = "0.25"(仅 PNG 特性):PNG 编码。
测试
50 个单元测试覆盖:场景构建、图层排序 / 迭代、元素构造器、渐变、裁剪、变换、SVG 输出 (标签 / 路径 / 转义 / 锚点 / 元数据)、vello 像素渲染(层序 / 透明度 / 裁剪 / 虚线 / 字形 / 渲染器复用)、文本测量与 TLS 上下文复用,以及 Bug 回归用例。
后续规划
- GPU 后端:新增
VelloGpuRenderer(基于 linebender/vello 的vello_hybridsparse_strips)。 Scene::bounds()几何求交:为布局 / 命中测试提供图元包围盒计算。- SVG 文本矢量保真(可选):将
TextLayout的字形转为<path>,替代<text>。 - 接入 liecharts / liemermaid:收敛各自的 IR 到 lievisual 的
Scene,删除重复定义。 - 接入 liepress:四端(PDF/PNG/SVG/DOCX)统一走
Scene中间表示。
License
Apache-2.0