jigsaw-doc.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Documentation for the jigsaw package
% A package to draw jigsaw pieces with tikz
% Maintained by samcarter
%
% Project repository and bug tracker:
% https://github.com/samcarter/jigsaw
%
% Released under the LaTeX Project Public License v1.3c or later
% See https://www.latex-project.org/lppl.txt
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% arara: latexmk
\documentclass{scrartcl}

% meta %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{The jigsaw package}
\subtitle{Drawing jigsaw pieces in \TikZ}
\author{%
  \texorpdfstring{
    \begin{tikzpicture}
       \piece[lightgray!70!white]{1}{-1}{1}{-1}
    \end{tikzpicture}\\[0.8em]
    \texttt{samcarter}\\
    \url{https://github.com/samcarter/jigsaw}\\
    \url{https://www.ctan.org/pkg/jigsaw}
  }{samcarter}}
\date{Version v0.5 \textendash{} 2024/04/25}

\usepackage[
  themecolor=samlgreen
]{\jobname-settings}

\colorlet{teal}{samlgreen}
\colorlet{violet}{samviolet}

\usepackage{jigsaw}
\usetikzlibrary{matrix}

\begin{document}
\maketitle

\section{Introduction}
\label{intro}

The jigsaw package allows to draw adjustable jigsaw pieces in \TikZ, to combine them and even to automatically create complete jigsaws. It is based on the TeX.Stackexchange answers \url{https://tex.stackexchange.com/a/446296/36296}.

The package is included in both \texlive and \miktex and available from \CTAN (\url{https://ctan.org/pkg/jigsaw}). The development version of this package is located at \url{github.com/samcarter/jigsaw}. If you have any problems, ideas or other feedback, please make constructive use of its bug tracker.

Copyright \raisebox{0.2em}{\tiny\fontfamily{cmr}\selectfont\textcopyright} \texttt{samcarter}. Permission is granted to copy, distribute and\slash or modify this software under the terms of the LaTeX project public licence, version 1.3c or later \url{https://www.latex-project.org/lppl.txt}.

\section{Usage}

An individual jigsaw piece can be drawn with

\begin{tcolorbox}[title={Jigsaw piece}]
\begin{samcode}
\piece{<bottom>}{<right>}{<top>}{<left>}
\end{samcode}
\tcblower
\begin{tikzpicture}
\piece{1}{-1}{1}{1}
\end{tikzpicture}
\end{tcolorbox}

wherein arguments specify for each side if it should be a tab (-1), a straight line (0) or a slot (1).

The following example will produce a jigsaw piece with one tab sticking out, one straight boarder and two slots:

\begin{tcblisting}{title={Jigsaw piece}}
\begin{tikzpicture}
  \piece{1}{-1}{0}{1}
\end{tikzpicture}
\end{tcblisting}

With an optional argument, a fill colour can be passed to the piece:

\begin{tcblisting}{title={Filled piece}}
\begin{tikzpicture}
  \piece[teal]{-1}{1}{-1}{1}
\end{tikzpicture}
\end{tcblisting}

Or to change the line colour:

\begin{tcblisting}{title={Coloured piece}}
\begin{tikzpicture}
  \color{teal}\piece{-1}{-1}{1}{1}
\end{tikzpicture}
\end{tcblisting}

The piece shape is also available as \TikZ \saminline|pic|:

\begin{tcblisting}{title={\texttt{pic}}}
\begin{tikzpicture}
  \path (2,-3) pic[
    fill=lightgray, draw=teal, thick,
    scale=2, pic text={Some Text},
    pic text options={text=violet}
  ]{piece={1}{-1}{1}{0}};
\end{tikzpicture}
\end{tcblisting}

Using the \TikZ \saminline|pic| allows to apply various \TikZ option like \saminline|scale| or add text in the centre of the piece via \saminline|pic text={...}|.

The shapes of the jigsaw pieces are designed to seamlessly fit into each other which allows to produce tile patters in various ways:

\begin{tcblisting}{title={Manual tile pattern}}
\begin{tikzpicture}
\begin{scope}
  \piece[teal]{1}{1}{0}{0}
\end{scope}
\begin{scope}[xshift=1cm]
  \piece[lightgray]{1}{0}{0}{-1}
\end{scope}
\begin{scope}[yshift=-1cm]
  \piece[lightgray]{0}{-1}{-1}{0}
\end{scope}
\begin{scope}[xshift=1cm,yshift=-1cm]
  \piece[teal]{0}{0}{-1}{1}
\end{scope}
\end{tikzpicture}
\end{tcblisting}

\begin{tcblisting}{title={Manual pattern using \texttt{\textbackslash pic}}}
\begin{tikzpicture}
  \pic at (0,1) [fill=lightgray,draw]
    {piece={1}{1}{0}{0}};
  \pic at (1,1) [fill=teal,draw]
    {piece={1}{0}{0}{-1}};
  \pic at (0,0) [fill=teal,draw]
    {piece={0}{-1}{-1}{0}};
  \pic at (1,0) [fill=lightgray,draw]
    {piece={0}{0}{-1}{1}};
\end{tikzpicture}
\end{tcblisting}

\begin{tcblisting}{title={Manual pattern using Ti\emph{k}Z matrix}}
% \usetikzlibrary{matrix}
\begin{tikzpicture}
  \matrix [nodes=draw]{
    \pic [fill=lightgray]
      {piece={-1}{1}{0}{0}}; &
    \pic [fill=teal]
      {piece={1}{0}{0}{-1}}; \\
    \pic [fill=teal]
      {piece={0}{-1}{1}{0}}; &
    \pic [fill=lightgray]
      {piece={0}{0}{-1}{1}};\\
  };
\end{tikzpicture}
\end{tcblisting}

Manually position each jigsaw piece at the correct position can be tedious, therefore the command \saminline|\tile[<colour>]{<bottom>}{<right>}{<top>}{<left>}| was added. It can be used outside of of the \saminline|tikzpicture| environment to place the pieces besides each other like normal letters in a text. Line breaks have to be added at the appropriate positions and one has to be careful not to introduce additional spaces between the jigsaw pieces from unprotected line endings.

\begin{tcblisting}{title={The tile command}}
\tile[violet]{1}{1}{0}{0}%
\tile[lightgray]{1}{-1}{0}{-1}%
\tile[teal]{1}{0}{0}{1}

\tile[teal]{1}{-1}{-1}{0}%
\tile[violet]{1}{-1}{-1}{1}%
\tile[lightgray]{-1}{0}{-1}{1}

\tile[lightgray]{0}{-1}{-1}{0}%
\tile[teal]{0}{-1}{-1}{1}%
\tile[violet]{0}{0}{1}{1}
\end{tcblisting}

Finally there is also the possibility to automatically generate complete jigsaw puzzles using the command \saminline|\jigsaw{<x>}{<y>}|, with \saminline|<x>| and \saminline|<y>| the number of rows and columns, respectively.

\begin{tcblisting}{title={Automatic jigsaw generation},righthand width=6.1cm}
\begin{tikzpicture}
  \jigsaw{6}{4}
\end{tikzpicture}
\end{tcblisting}

This automatically generated jigsaw can also be overlaid on a picture:

\begin{tcblisting}{title={Overlaid image},righthand width=6.1cm}
\begin{tikzpicture}
  \clip (0,0) rectangle (6,4);
  \node at (3,2) {%
    \includegraphics[
      width=6cm,height=4cm
    ]{example-image-duck}%
  };
  \jigsaw{6}{4}
\end{tikzpicture}
\end{tcblisting}

\end{document}