canvas-cli

name	canvas-cli
description	一个命令行图片生成工具。可以通过读取一段简单的文本指令脚本，即可完成 2D 图形绘制，并可以将生成的图片输出为 PNG 图像文件或 Base64 Data URL。也可以使用本工具的 draw_image 指令对已有的 PNG 图片进行裁剪、缩放和重绘。

提示：canvas-cli 命令的可执行文件放在本技能目录中，下述说明中的 ./canvas-cli 指的就是这个可执行文件，canvas-cli 是可以直接运行的二进制可执行文件，不是脚本文件。。

命令行用法

./canvas-cli --input=<文件路径或内联指令> --output=<输出PNG路径>
./canvas-cli --input=<文件路径或内联指令> --output-data-url

选项：

选项	说明
--input=<path>	指令文件路径，或直接内联的指令字符串（用 ; 分隔）
--output=<path>	输出 PNG 文件路径
--output-data-url	将结果输出为 data:image/png;base64,... 字符串而非文件

---

指令脚本格式

每行一条指令，# 开头为注释，空行忽略。指令文件的第一行必须是 canvas 指令以初始化画布。

画布初始化

canvas <width> <height>

示例：canvas 1080 200

---

颜色与样式

set_fill_style <color>
set_stroke_style <color>
set_line_width <width>

<color> 支持：

• CSS 命名色：red、white、black、blue 等，例如 set_fill_style red
• 十六进制：#RGB、#RRGGBB、#RRGGBBAA，例如 set_fill_style #FF0000
• 函数式：rgb(255,0,0)、rgba(255,0,0,128)，例如 set_stroke_style rgba(0,255,0,0.5)

<width> 是线宽，单位像素，例如 set_line_width 5

---

字体

set_font <size>px <family>
set_text_align <align>

示例：set_font 32px common

• size：字号（像素），决定文字高度（等于 size）和宽度（全角字符等于 size，半角字符为 size / 2）。
• family：字体名，对应 lib/<family>.txt 位图字体文件，没有特别指定的情况下使用 common 这个内置字体。
• 内置字体：common（支持 ASCII 及常用中文字符）。

set_text_align 设置文本对齐方式：

• start / left：左对齐（默认），x 是文本左边缘。
• end / right：右对齐，x 是文本右边缘。
• center：居中对齐，x 是文本中心点。
• 绘制文字时的 y 坐标始终是文本上方顶部位置，因此生成文本的时候需要特别注意 y 坐标的设置，确保文本纵向位置正确。

示例：set_text_align center

---

矩形绘制

fill_rect <x> <y> <w> <h>

---

### round_rect

`round_rect` 用于把圆角矩形追加到当前路径中，然后配合 `fill` 或 `stroke` 使用。

语法：

```txt
begin_path
round_rect <x> <y> <w> <h> <radii>
fill
stroke

<radii> 支持 1 到 4 个半径值，顺序和 CSS 一样：

• 1 个值：四个角相同
• 2 个值：左上/右下，右上/左下
• 3 个值：左上，右上/左下，右下
• 4 个值：左上，右上，右下，左下

示例：

canvas 400 200
set_fill_style #2563EB
begin_path
round_rect 50 40 300 120 24,24,24,24
fill

stroke_rect clear_rect

- `fill_rect`：用当前 `fill_style` 填充矩形。
- `stroke_rect`：用当前 `stroke_style` 描边矩形轮廓。
- `clear_rect`：将矩形区域清除为完全透明（不受当前样式影响）。

---

### 文字绘制

```txt
fill_text "<text>" <x> <y>

• <text> 需用双引号包裹（支持空格和中文）。
• 坐标 (x, y) 的含义取决于当前 text_align 设置：
  • start / left：x 是文本左边缘位置。
  • end / right：x 是文本右边缘位置。
  • center：x 是文本中心位置。
• y 始终是文本上方顶部位置。

示例：fill_text "Hello, World!" 100 50 则代表从 (100, 50) 开始绘制文本，文本的左上角坐标为 (100, 50)。

---

路径绘制

路径操作与浏览器 Canvas API 完全对应：

begin_path
move_to <x> <y>
line_to <x> <y>
arc <cx> <cy> <radius> <start_angle> <end_angle>
close_path
fill
stroke

• 角度单位：弧度（0 = 右方，顺时针为正）。
• arc 参数依次为：圆心 x、圆心 y、半径、起始角、终止角。
• fill / stroke 分别以 fill_style / stroke_style 填充/描边已定义路径。

---

渐变

支持绘制线性渐变和径向渐变，当用户提到渐变时，没有特殊指定则认为是线性渐变。

创建渐变

# 线性渐变：从点 (x0, y0) 到点 (x1, y1)
create_linear_gradient <id> <x0> <y0> <x1> <y1>

# 径向渐变：从内圆 (x0, y0, r0) 到外圆 (x1, y1, r1)
create_radial_gradient <id> <x0> <y0> <r0> <x1> <y1> <r1>

• <id>：渐变标识符，用于后续引用。
• 坐标和半径均为像素值。

添加颜色停止点

add_color_stop <gradient_id> <offset> <color>

• <offset>：位置偏移，范围 0 ~ 1（0 为起点，1 为终点）。
• <color>：颜色值，格式同 set_fill_style。

应用渐变

set_fill_gradient <gradient_id>
set_stroke_gradient <gradient_id>

渐变示例

# 创建线性渐变（从左到右）
create_linear_gradient my_gradient 0 0 200 0
add_color_stop my_gradient 0 red
add_color_stop my_gradient 0.5 yellow
add_color_stop my_gradient 1 blue
set_fill_gradient my_gradient
fill_rect 0 0 200 100

# 创建径向渐变（从中心向外）
create_radial_gradient radial 100 100 0 100 100 100
add_color_stop radial 0 white
add_color_stop radial 1 black
set_fill_gradient radial
fill_rect 0 0 200 200

---

状态保存与恢复

save
restore

保存/恢复当前绘图状态（包括样式、线宽、裁剪区域、字体设置等），但不包括当前路径。与 Web Canvas API 行为一致。

---

图片绘制

# 从 PNG 文件加载图片并绘制到画布
draw_image <path> <dx> <dy>
draw_image <path> <dx> <dy> <dWidth> <dHeight>
draw_image <path> <sx> <sy> <sWidth> <sHeight> <dx> <dy> <dWidth> <dHeight>

• <path>：PNG 文件路径，支持相对路径（相对于输入脚本文件所在目录）或绝对路径。
• dx / dy：目标画布中放置图片左上角的坐标。
• dWidth / dHeight：目标绘制尺寸，用于缩放图片。
• sx / sy：源图中裁剪区域左上角坐标。
• sWidth / sHeight：源图裁剪区域尺寸。

说明：

• 3 参数形式：按原始尺寸绘制整张图片。
• 5 参数形式：绘制整张图片，并缩放到指定目标尺寸。
• 9 参数形式：先从源图裁剪子区域，再绘制到目标区域并缩放。
• sWidth、sHeight、dWidth、dHeight 可以为负值，表示向相反方向扩展区域，但不会导致图片翻转。

示例：

# 按原图尺寸绘制
draw_image ./avatar.png 40 20

# 缩放到 120x120
draw_image ./avatar.png 200 20 120 120

# 从源图裁剪 (10, 10, 80, 80)，绘制到目标 (380, 20, 160, 160)
draw_image ./avatar.png 10 10 80 80 380 20 160 160

---

完整示例脚本

canvas 1080 200
# 左边一半背景 - 径向渐变 (从中心向外)
create_radial_gradient radial_bg 270 100 0 270 100 200
add_color_stop radial_bg 0 white
add_color_stop radial_bg 0.5 #fded43
add_color_stop radial_bg 1 #a1cffd
set_fill_gradient radial_bg
fill_rect 0 0 540 200

# 右边一半背景 - 线性渐变 (从左到右)
create_linear_gradient linear_bg 600 0 1080 0
add_color_stop linear_bg 0 #c3c3c3
add_color_stop linear_bg 0.2 #7c4105
add_color_stop linear_bg 0.5 #e8d8c8
add_color_stop linear_bg 1 #2b05b6
set_fill_gradient linear_bg
fill_rect 550 0 240 200

# 画一张图片，设置位置
draw_image ../images/tests/image_220x200.png 860 0

# 画一张图片，设置位置，并调整宽高
draw_image ../images/tests/image_220x200.png 800 0 50 95

# 画一张图片，选取部分图片，设置位置，并调整宽高
draw_image ../images/tests/image_220x200.png 50 50 100 100 800 105 50 95

# 设置文字颜色
set_fill_style black
set_font 32px common

# 设置抗锯齿，默认就是 4，设置为 1 则没有抗锯齿
set_text_antialias_grid 4

# 居中对齐
set_text_align center
fill_text "让天下没有难生成的图。" 450 50
set_fill_style #ff0000
set_text_align start
set_font 32px common
fill_text "Make it so that no graph is difficult to generate." 20 90
set_fill_style blue
set_font 16px common
set_text_align right
fill_text "--- 2026.03.15" 820 130

运行：

./canvas-cli --input=script.txt --output=output.png

---