---

name: generate-puzzle description: > 通过 generate_puzzle() 或 geom_puzzle_*() 生成拼图，并根据 inst/config.yml 进行参数验证。支持矩形、六边形、同心圆、Voronoi 和 SNIC 拼图类型，可配置 网格、尺寸、种子、偏移和布局参数。适用于为特定类型和配置创建拼图 SVG 文件、 使用不同参数测试生成效果、为文档或演示生成样例输出，以及创建 ggplot2 拼图 可视化。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: jigsawr complexity: basic language: R tags: jigsawr, puzzle, svg, generation, ggplot2 locale: zh-CN source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16

生成拼图

使用 jigsawR 包的统一 API 生成拼图。

适用场景

• 为特定类型和配置创建拼图 SVG 文件
• 使用不同参数测试拼图生成
• 为文档或演示生成样例输出
• 使用 geom_puzzle_*() 创建 ggplot2 拼图可视化

输入

• 必需：拼图类型（"rectangular"、"hexagonal"、"concentric"、"voronoi"、"random"、"snic"）
• 必需：网格尺寸（取决于类型：c(cols, rows) 或 c(rings)）
• 可选：尺寸（毫米，默认值因类型而异）
• 可选：随机种子（默认：42）
• 可选：偏移量（0 = 拼合状态，>0 = 分离碎片）
• 可选：布局（"grid" 或 "repel"，适用于矩形）
• 可选：融合组（PILES 表示法字符串）

步骤

第 1 步：读取配置约束

R_EXE="/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe"
"$R_EXE" -e "cat(yaml::yaml.load_file('inst/config.yml')[['{TYPE}']]$grid$max)"

或直接读取 inst/config.yml 检查所选类型的有效范围。

预期结果： 已知所选拼图类型的 grid、size、tabsize 等参数的最小/最大值。

失败处理： 如果 config.yml 缺失或类型键不存在，请检查是否在 jigsawR 项目根目录中，以及包是否已至少构建过一次。

第 2 步：确定类型和参数

将用户请求映射到有效的 generate_puzzle() 参数：

类型	grid	size	额外参数
rectangular	c(cols, rows)	c(width, height) mm	offset、layout、tabsize
hexagonal	c(rings)	c(diameter) mm	do_warp、do_trunc、tabsize
concentric	c(rings)	c(diameter) mm	center_shape、tabsize
voronoi	c(cols, rows)	c(width, height) mm	n_interior、tabsize
random	c(cols, rows)	c(width, height) mm	n_interior、tabsize
snic	c(cols, rows)	c(width, height) mm	n_interior、compactness、tabsize

预期结果： 用户请求已映射为有效的 generate_puzzle() 参数，类型、网格维度和尺寸值均在 config.yml 的范围内。

失败处理： 如果不确定使用哪种参数格式，请参考上表。矩形和 voronoi 类型使用 c(cols, rows) 作为 grid；六边形和同心圆类型使用 c(rings)。

第 3 步：创建 R 脚本

编写脚本文件（对于复杂命令优于 -e）：

library(jigsawR)

result <- generate_puzzle(
  type = "rectangular",
  seed = 42,
  grid = c(3, 4),
  size = c(400, 300),
  offset = 0,
  layout = "grid"
)

cat("Pieces:", length(result$pieces), "\n")
cat("SVG length:", nchar(result$svg_content), "\n")
cat("Files:", paste(result$files, collapse = ", "), "\n")

保存到临时脚本文件。

预期结果： R 脚本文件已保存到临时位置，包含 library(jigsawR)、generate_puzzle() 调用（含所有参数）和诊断输出行。

失败处理： 如果脚本有语法错误，请验证所有字符串参数是否加引号，数值向量是否使用 c()。始终使用脚本文件以避免复杂的 shell 转义。

第 4 步：通过 WSL R 执行

R_EXE="/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe"
"$R_EXE" /path/to/script.R

预期结果： 脚本无错误完成。SVG 文件已写入 output/。

失败处理： 检查 renv 是否已恢复（renv::restore()）。验证包是否已加载（devtools::load_all()）。不要使用 --vanilla 标志（renv 需要 .Rprofile）。

第 5 步：验证输出

• SVG 文件存在于 output/ 目录中
• SVG 内容以 <?xml 或 <svg 开头
• 碎片数量与预期一致：cols * rows（矩形）、环形公式（六边形/同心圆）
• 对于 ggplot2 方式，验证绘图对象渲染无错误

预期结果： SVG 文件存在于 output/ 中，内容以 <?xml 或 <svg 开头，碎片数量与网格规格一致（矩形为 cols * rows，六边形/同心圆为环形公式）。

失败处理： 如果 SVG 文件缺失，检查 output/ 目录是否存在。如果碎片数量不对，验证网格维度是否符合拼图类型的预期公式。对于 ggplot2 输出，使用 tryCatch() 包裹检查渲染是否出错。

第 6 步：保存输出

生成的文件默认保存到 output/。result 对象包含：

• $svg_content — 原始 SVG 字符串
• $pieces — 碎片数据列表
• $canvas_size — 尺寸
• $files — 已写入文件的路径

预期结果： result 对象包含 $svg_content、$pieces、$canvas_size 和 $files 字段。$files 中列出的文件存在于磁盘上。

失败处理： 如果 $files 为空，拼图可能仅在内存中生成。使用 writeLines(result$svg_content, "output/puzzle.svg") 显式保存。

验证清单

• 脚本执行无错误
• SVG 文件是格式良好的 XML
• 碎片数量与网格规格一致
• 相同种子产生相同输出（可重现性）
• 参数在 config.yml 约束范围内

常见问题

• 使用 --vanilla 标志：会破坏 renv 激活。绝对不要使用。
• 复杂的 -e 命令：使用脚本文件替代；shell 转义会导致退出码 5。
• Grid 与 size 混淆：Grid 是碎片数量，size 是物理尺寸（毫米）。
• 偏移量语义：0 = 组装好的拼图，正值 = 爆炸/分离的碎片。
• SNIC 缺少包：snic 类型需要安装 snic 包。

相关技能

• add-puzzle-type — 端到端搭建新拼图类型
• validate-piles-notation — 在传递给 generate_puzzle() 之前验证融合组字符串
• run-puzzle-tests — 在修改生成逻辑后运行测试套件
• write-testthat-tests — 为新生成场景添加测试