generate_puzzle()

The main entry point for creating puzzles

Description

generate_puzzle() is the unified entry point for creating all puzzle types in jigsawR. It handles rectangular, hexagonal, concentric, voronoi, random, and SNIC puzzles through a single consistent interface.

Usage

generate_puzzle(
  type = "rectangular",
  grid,
  size,
  seed = NULL,
  offset = 0,
  layout = "grid",
  fusion_groups = NULL,
  save_files = FALSE,
  output_dir = "output",
  ...
)

Arguments

Required Parameters

Parameter	Type	Description
`type`	string	Puzzle type: `"rectangular"`, `"hexagonal"`, `"concentric"`, `"voronoi"`, `"random"`, `"snic"`
`grid`	numeric vector	Grid dimensions (interpretation depends on type)
`size`	numeric vector	Physical dimensions in mm

Grid Parameter by Type

Type	Grid Format	Example
rectangular	`c(rows, cols)`	`c(3, 4)` = 3x4 grid
hexagonal	`c(rings)`	`c(3)` = 3 rings
concentric	`c(rings)`	`c(4)` = 4 rings
voronoi	`c(n_cells)`	`c(25)` = 25 cells
random	`c(n_interior)`	`c(10)` = 10 interior points
snic	`c(n_cells)`	`c(30)` = 30 superpixel cells

Size Parameter by Type

Type	Size Format	Example
rectangular	`c(height, width)`	`c(300, 400)` = 300mm tall, 400mm wide
hexagonal	`c(diameter)`	`c(250)`
concentric	`c(diameter)`	`c(200)`
voronoi	`c(height, width)`	`c(300, 400)` = 300mm tall, 400mm wide
random	`c(height, width)`	`c(300, 400)` = 300mm tall, 400mm wide
snic	`c(height, width)`	`c(300, 400)` = 300mm tall, 400mm wide

Optional Parameters

Parameter	Type	Default	Description
`seed`	integer	random	Random seed for reproducibility
`offset`	numeric (mm)	0	Piece separation distance
`layout`	string	“grid”	Layout algorithm: `"grid"` or `"repel"`
`repel_margin`	numeric (mm)	2	Minimum margin between pieces when `layout = "repel"`
`repel_max_iter`	integer	100	Maximum iterations for repel layout algorithm
`fusion_groups`	string	NULL	PILES notation for merging pieces
`save_files`	logical	FALSE	Whether to save SVG files
`output_dir`	string	“output”	Directory for saved files

Type-Specific Parameters (via `...`)

Common (all types):

Parameter	Type	Default	Description
`tabsize`	numeric (%)	6	Tab size as percentage of edge length
`jitter`	numeric (%)	2	Randomness in tab shape as percentage
`stroke_width`	numeric (mm)	1	SVG stroke width
`min_tab_size`	numeric (mm)	NULL	Minimum tab size constraint (all types)
`max_tab_size`	numeric (mm)	NULL	Maximum tab size constraint (all types)
`fill_palette`	string	NULL	Color palette for fills: `"viridis"`, `"magma"`, `"plasma"`, etc.
`fill_direction`	string	“forward”	Spatial color order: `"forward"` or `"reverse"`
`palette_invert`	logical	FALSE	Invert palette (dark↔︎light ends)

Hexagonal/Concentric:

Parameter	Type	Default	Description
`do_warp`	logical	TRUE	Apply circular warping
`do_trunc`	logical	TRUE	Truncate to boundary
`center_shape`	string	“hexagon”	Center shape (concentric only)

Voronoi:

Parameter	Type	Default	Description
`relaxation`	integer	0	Lloyd relaxation iterations

Random:

Parameter	Type	Default	Description
`n_corner`	integer	5	Corners per piece (3-8)

SNIC:

Parameter	Type	Default	Description
`image_path`	string	NULL	Path to image file (enables image-based segmentation)
`compactness`	numeric	0.5	Superpixel compactness (0.0-2.0)
`seed_type`	string	“hexagonal”	Seed grid: `"hexagonal"`, `"rectangular"`, `"diamond"`, `"random"`

Return Value

A list with the following components:

Component	Type	Description
`svg_content`	string	Complete SVG document as text
`pieces`	list	List of piece objects with paths and metadata
`canvas_size`	list	Canvas dimensions (`$width`, `$height`)
`files`	list	Paths to saved files (if `save_files = TRUE`)
`config`	list	Configuration used to generate the puzzle

Piece Object Structure

Each piece in pieces contains:

piece <- list(
  id = 1,                    # Piece ID
  path = "M0 0 L100 0...",   # SVG path data
  parsed_segments = list(),   # Parsed path segments
  group_id = 1,              # Fusion group ID
  is_boundary = TRUE         # Whether piece is on boundary
)

Examples

Basic Usage

# Rectangular puzzle
rect <- generate_puzzle(
  type = "rectangular",
  grid = c(3, 4),
  size = c(300, 400),
  seed = 42
)
n_pieces <- length(rect$pieces)
cli::cli_alert_info("Generated {n_pieces} pieces")

Hexagonal Puzzle

hex <- generate_puzzle(
  type = "hexagonal",
  grid = c(3),
  size = c(200),
  seed = 42,
  do_warp = TRUE,
  do_trunc = TRUE
)
n_hex_pieces <- length(hex$pieces)
cli::cli_alert_info("Generated {n_hex_pieces} hexagonal pieces")

With Fusion Groups

fused <- generate_puzzle(
  type = "rectangular",
  grid = c(3, 4),
  size = c(300, 400),
  seed = 42,
  fusion_groups = "1-2,5-6,11-12"
)
# Pieces 1&2, 5&6, and 11&12 are now merged

With Offset

separated <- generate_puzzle(
  type = "hexagonal",
  grid = c(3),
  size = c(200),
  seed = 42,
  offset = 10
)

Saving Files

result <- generate_puzzle(
  type = "rectangular",
  grid = c(3, 4),
  size = c(300, 400),
  seed = 42,
  save_files = TRUE,
  output_dir = "puzzles"
)
file_path <- result$files$svg
cli::cli_alert_success("Saved to: {.file {file_path}}")

Visualization

The result can be visualized using ggpuzzle:

ggplot() +
  geom_puzzle_hex(
    aes(fill = after_stat(piece_id)),
    rings = 3,
    diameter = 200,
    seed = 42
  ) +
  scale_fill_viridis_c(guide = "none") +
  coord_fixed() +
  theme_puzzle() +
  labs(title = "Hexagonal puzzle")

Or by writing the SVG:

result <- generate_puzzle(
  type = "hexagonal",
  grid = c(3),
  size = c(200),
  seed = 42
)

# Save as SVG
writeLines(result$svg_content, "puzzle.svg")