%%
%% example-rot1.tex
%% package examples using the rubikrotation package
%% Requires  tikz and rubikcube packages
%% January 20, 2014
%%--------NOTE-------------------------------------------
%% USAGE:   (pdf)latex  --shell-escape   example-rot1.tex
%% run three times to get all labels and fig nos correct
%%-------------------------------------------------------
\documentclass[a4paper]{article}
\usepackage{tikz}   %% load tikz before rubikcube
\usepackage{rubikcube,rubikrotation} 
\usepackage{url}
\pagestyle{myheadings}
\markright{\textsc{rubikrotation} package; \hspace{2cm}file = example-rot1.tex}
%-----------
%% some well known sequences (see the web page of Reid)
\newcommand{\sixTs}{*sixTs,F2,R2,U2,Fp,B,D2,L2,F,B}
\newcommand{\CubeInCube}{*CubeInCube,F,L,F,Up,R,U,F2,L2,Up,Lp,B,Dp,Bp,L2,U}
\newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
%%==================
\begin{document}

%%------------------
\section*{Example~1}

In Figure~\ref{fig:cubeincube} we show  the so-called ``sixspot'' configuration,
 generated from a solved cube using the rotation sequence 
\rrU, \rrDp, \rrR, \rrLp, \rrF, \rrBp, \rrU, \rrDp
(see the website of Reid at \url{www.math.ucf.edu/~reid/Rubik/}).
%%--------FIGURE 1 -----------
\begin{figure}[hbt]
\centering
\begin{tikzpicture}[scale=0.7]
   \RubikCubeSolved
   \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
   \DrawRubikCubeFlat
\end{tikzpicture}
\caption{\label{fig:cubeincube}The  so-called `sixspot' configuration (Reid).}
\end{figure}
%----------------
\begin{verbatim}
----------------
\documentclass[a4paper]{article}
\usepackage{tikz,rubikcube,rubikrotation}
\thispagestyle{empty} %% disables pagenumbers
\begin{document}
\begin{tikzpicture}[scale=0.9]
    \RubikCubeSolved
    \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
    \DrawRubikCubeFlat
\end{tikzpicture}
\end{document}
--------------
\end{verbatim}
Note that a more flexible approach is to   incorporate such  rotation sequences into a `newcommand'. For example, in this case we can write
\begin{verbatim}
\newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
\end{verbatim}
which allows the code to Figure~\ref{fig:cubeincube} to be more easily written as:
\begin{verbatim}
\begin{tikzpicture}
    \RubikCubeSolved
    \RubikRotation{\sixspot}
    \DrawRubikCubeFlat
\end{tikzpicture}
\end{verbatim}



\pagebreak
%%-------------------------
\section*{Example~2}

 In this example we show  the use of the  \verb!\ShowRubikErrors! command, which
 places a copy of the Perl output file (\verb!rubikstateERRORS.dat!) underneath the graphic 
 so you can see a list of all the  errors, if any (in this example we have introduced a couple
 of errors).  It is important to note that  the  \verb!\ShowRubikErrors! command must be 
 placed \textit{after}  the TikZ picture environment. Note also  that full details of all 
 errors are included in the .log file. 

%%--------FIGURE 2 -----------

\RubikCubeSolved
\RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,UU,Dpp}

\begin{figure}[hbt]
\centering
\begin{tikzpicture}[scale=0.7]
   \DrawRubikCubeFlat
\end{tikzpicture}
\ShowRubikErrors
\caption{\label{fig:cubeincubeE}The same `sixspot' sequence of rotations as before, but now with some typo errors in the rotation sequence (should be \texttt{U,Dp,R,Lp,F,Bp,U,Dp}.}
\end{figure}
Note that only `Draw' commands really need to be inside the TikZ picture environment---see the following code which we used for the above figure.
%-----------------
\begin{verbatim}
----------------
\RubikCubeSolved
\RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,UU,Dpp}
%
\begin{tikzpicture}
   \DrawRubikCubeFlat
\end{tikzpicture}
\ShowRubikErrors
----------------
\end{verbatim}




\pagebreak
%-------------------------------
\section*{Example~3}

In this example we use the \verb!\RubikRotation! command to scramble a `solved' Rubik 
cube via  a sequence of 120 random rotations, using the following  command (the details 
of the process can be seen in the \texttt{.log} file):
\begin{verbatim}
\RubikRotation{random,120}
\end{verbatim}
In this example, we also save the final  configuration (state) to a file 
(\texttt{exmpfig4.tex}) using the command
\verb!\SaveRubikState{exmpfig4.tex}!
so we can  display the cube in the same state later (see Example~4) but 
in  a different format.
Note that since we are using a random sequence, it follows that each 
time this file is run not only will a visually different  cube  be generated,  
but the same state  will be shown in both Figures~\ref{fig:randomone} and \ref{fig:randomtwo}.
%%--------FIGURE 3 -----------
\begin{figure}[hbt]
\centering
\begin{tikzpicture}[scale=0.7]
   \RubikCubeSolved
   \RubikRotation{random,120}
   \SaveRubikState{exmpfig4.tex}
   \DrawRubikFlat
\end{tikzpicture}
\caption{\label{fig:randomone}This shows a cube  generated by 120 random rotations}
\end{figure}
%----------------
\begin{verbatim}
-------------------
\begin{figure}[hbt]
\centering
\begin{tikzpicture}[scale=0.8]
    \RubikCubeSolved
    \RubikRotation{random,120}
    \SaveRubikState{exmpfig4.tex}
    \DrawRubikFlat
\end{tikzpicture}
\end{figure}
------------------
\end{verbatim}



\pagebreak
%----------------------
\section*{Example~4}

In this example we display a cube having the same state as that shown in 
Figure~\ref{fig:randomone}. The configuration state was saved from 
Figure~\ref{fig:randomone} using the  command 
\verb!\SaveRubikState{exmpfig4.tex}!, and then input here  
using \verb!\input{exmpfig4.tex}!. These commands therefore allow  the 
state of a previous cube to be saved to a file, and then  displayed again 
later in  a different format.
%%-----------FIGURE 4 -----------
\begin{figure}[hbt]
\centering
\begin{tikzpicture}[scale=0.8]
   \input{exmpfig4.tex}
   \DrawRubikCubeLD
\end{tikzpicture}
\caption{\label{fig:randomtwo}This shows a Rubik cube in exactly the  same 
state as  the one shown in Figure~\ref{fig:randomone}} 
\end{figure}
%%---------------------------------
\begin{verbatim}
-------------------
\begin{figure}[hbt]
\centering
\begin{tikzpicture}[scale=0.8]
   \input{exmpfig4.tex}
   \DrawRubikCubeLD
\end{tikzpicture}
\end{figure}
------------------
\end{verbatim}



\pagebreak
%----------------------
\section*{Example~5}

Here we show a convenient way of displaying a series of small cubes showing 
a sequence of rotations (\rrU, \rrR, \rrF). Following each rotation 
we save the state to a file and then, finally, display each cube state in sequence,
using a  couple of useful macros (\verb!\showcube!, and \verb!\lift!),
to `show' the cubes and  to `lift' the  rotation command slightly off the baseline.
Note that embedding the TikZ picture environment in the  \verb!\showcube! command brings 
considerable flexibility. 
%%-----------FIGURE 5 -----------
\newcommand{\showcube}[1]{%
   \begin{tikzpicture}[scale=0.5]
   \input{#1}
   \DrawRubikCubeRU
   \end{tikzpicture}
}
\newcommand{\lift}[1]{\raisebox{8mm}{#1}\hspace{2mm}}
%%
\RubikCubeSolved  \SaveRubikState{exmpfig5a.tex}
\RubikRotation{U} \SaveRubikState{exmpfig5b.tex}
\RubikRotation{R} \SaveRubikState{exmpfig5c.tex}
\RubikRotation{F} \SaveRubikState{exmpfig5d.tex}
%%
\begin{figure}[hbt]
\centering
\noindent     \showcube{exmpfig5a.tex}\hspace{-4mm}(a) 
\lift{\RubikU}\showcube{exmpfig5b.tex}\hspace{-4mm}(b) 
\lift{\RubikR}\showcube{exmpfig5c.tex}\hspace{-4mm}(c) 
\lift{\RubikF}\showcube{exmpfig5d.tex}\hspace{-4mm}(d) 
\caption{The rotations \rrU, \rrR, \rrF\ on a solved cube.} 
\end{figure}
%%---------------------------------

Note that even though the \verb!\RubikCubeSolved! command (which allocates the 
 colours to the `solved' cube) is used  prior to  the TikZ picture environment, 
 its effects are still available to the \verb!\Draw...! command inside each of  the 
picture environments.
\begin{verbatim}
-------------------
\newcommand{\showcube}[1]{%
   \begin{tikzpicture}[scale=0.5]
   \input{#1}
   \DrawRubikCubeRU
   \end{tikzpicture}
}
\newcommand{\lift}[1]{\raisebox{8mm}{#1}\hspace{2mm}}
%%
\RubikCubeSolved  \SaveRubikState{exmpfig5a.tex}
\RubikRotation{U} \SaveRubikState{exmpfig5b.tex}
\RubikRotation{R} \SaveRubikState{exmpfig5c.tex}
\RubikRotation{F} \SaveRubikState{exmpfig5d.tex}
%%
\begin{figure}[hbt]
   \centering
   \noindent     \showcube{exmpfig5a.tex}\hspace{-4mm}(a)  
   \lift{\RubikU}\showcube{exmpfig5b.tex}\hspace{-4mm}(b)  
   \lift{\RubikR}\showcube{exmpfig5c.tex}\hspace{-4mm}(c) 
   \lift{\RubikF}\showcube{exmpfig5d.tex}\hspace{-4mm}(d) 
   \ShowRubikErrors
\caption{The rotations \rrU, \rrR, \rrF\ on a solved cube.} 
\end{figure}
------------------
\end{verbatim}

\pagebreak
%----------------------
\section*{Example~6}

In this example we show how commands used inside a TikZ picture environment remain 
local to that picture environment.

In this case the first fig uses the \verb!\RubikCubeSolved! inside the TikZ environment.
However, if we then perform the rotation  \textRubikR\  the command \verb!RubikRotation{R}! 
results in  something quite unexpected (and obviously not correct). This is because 
 the effect of the \verb!\RubikCubeSolved! command is not visible outside its TikZ environment, and hence the  \verb!RubikRotation{R}! command has to  operate on the state of the next earliest figure 
(ie~Figure~5d), hence the strange form of the second figure below.

\medskip

   \begin{tikzpicture}[scale=0.5]
   \RubikCubeSolved
   \DrawRubikCubeRU
   \end{tikzpicture}
\hspace{5mm}\lift{\RubikR}\hspace{5mm}%
\RubikRotation{R}%
  \begin{tikzpicture}[scale=0.5]
   \DrawRubikCubeRU
   \end{tikzpicture}

\medskip

Since we are not here using any `minipage' environments, we need to use the \verb!\lift{}! command to raise the \rrhR\ hieroglyph off the baseline.

\begin{verbatim}
-------------------
\begin{tikzpicture}[scale=0.5]
   \RubikCubeSolved
   \DrawRubikCubeRU
\end{tikzpicture}
\hspace{5mm}\lift{\RubikR}\hspace{5mm}%
\RubikRotation{R}%
\begin{tikzpicture}[scale=0.5]
   \DrawRubikCubeRU
\end{tikzpicture}
-------------------
\end{verbatim}

\begin{center}
------ END ------
\end{center}

\end{document}