jigsawR

Generate beautiful, mathematically-precise jigsaw puzzles in R

Features

• 6 Puzzle Types: Rectangular, hexagonal, concentric, voronoi, random, and SNIC
• ggplot2 Integration: Use geom_puzzle_*() functions in your plots
• PILES Notation: Fuse pieces together with intuitive syntax
• Reproducible: Same seed = same puzzle, every time
• Manufacturing-Ready: Export individual SVG pieces for laser cutting
• Interactive App: Shiny app for live preview and downloads

Architecture

jigsawR uses a 4-stage pipeline: generate → dispatch → position → render.

flowchart TD
    generate_puzzle(["generate_puzzle()"])
    positioning["Piece Positioning"]
    rand_gen["Random Generator"]
    svg_render[["SVG Rendering"]]
    snic_gen["SNIC Generator"]
    type_dispatch{"Type Dispatch"}
    rect_gen["Rectangular Generator"]
    hex_gen["Hexagonal Generator"]
    conc_gen["Concentric Generator"]
    vor_gen["Voronoi Generator"]

    generate_puzzle --> type_dispatch
    type_dispatch --> rect_gen
    type_dispatch --> hex_gen
    type_dispatch --> conc_gen
    type_dispatch --> vor_gen
    type_dispatch --> rand_gen
    type_dispatch --> snic_gen
    rect_gen --> positioning
    hex_gen --> positioning
    conc_gen --> positioning
    vor_gen --> positioning
    rand_gen --> positioning
    snic_gen --> positioning
    positioning --> svg_render

    classDef outputStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#15803d
    class svg_render outputStyle
    classDef decisionStyle fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#92400e
    class type_dispatch decisionStyle
    classDef startStyle fill:#fef3c7,stroke:#d97706,stroke-width:3px,color:#92400e
    class generate_puzzle startStyle

Loading

_{Generated with putior}

Quick Start

# Install from GitHub
devtools::install_github("pjt222/jigsawR")

# Generate your first puzzle
library(jigsawR)
puzzle <- generate_puzzle(
  type = "hexagonal",
  grid = c(3),
  seed = 42
)

# View the SVG
cat(puzzle$svg_content)

ggplot2 Integration

Create stunning puzzle visualizations with familiar ggplot2 syntax:

library(ggplot2)
library(jigsawR)

ggplot() +
  geom_puzzle_rect(
    aes(fill = after_stat(piece_id)),
    cols = 5, rows = 4, seed = 123
  ) +
  scale_fill_viridis_c(option = "turbo") +
  coord_fixed() +
  theme_void()

Quick Parameter Reference

Parameter	Default	Unit	Description
type	"rectangular"	-	Puzzle type: rectangular, hexagonal, concentric, voronoi, random, snic
grid	c(3, 4)	-	Rows × cols (rect), rings (hex/conc), or cell count (voronoi/random)
size	c(400, 300)	mm	Width × height (rect) or diameter (hex/conc)
seed	random	-	Integer for reproducibility
tabsize	6	%	Tab size as percentage of edge length
jitter	2	%	Random variation in tab shape
offset	0	mm	Piece separation (0 = complete puzzle)
layout	"grid"	-	Layout algorithm: "grid" or "repel"

Type-specific:

• Hexagonal: do_warp, do_trunc, do_circular_border
• Concentric: center_shape ("hexagon"/"circle"), boundary_facing
• Voronoi: point_distribution ("fermat"/"uniform"/"jittered")
• Random: n_corner (3-8 for base polygon shape)
• SNIC: image_path, compactness, n_superpixels

See the full API reference for all parameters.

Gallery

Rectangular	Hexagonal	Concentric	Voronoi	Random	SNIC

View full gallery

Documentation

• Getting Started
• API Reference
• Architecture
• Tutorials
• Live Shiny App

Installation

# From GitHub (recommended)
devtools::install_github("pjt222/jigsawR")

# With all optional dependencies
devtools::install_github("pjt222/jigsawR", dependencies = TRUE)

Requirements

• R: 4.0 or higher
• Core packages: ggplot2, ggfx, viridis
• Optional: rsvg, magick (for PNG conversion)

Contributing

Contributions welcome! Check out the open issues for ideas.

Credits

• Original Algorithm: Draradech's JavaScript implementation (CC0)
• R Translation: Philipp Thoss

License

jigsawR is dual-licensed:

• Open Source (GPL-3): Free for personal, academic, and open-source use
• Commercial License: Contact ph.thoss@gmx.de for proprietary use