% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
\clearpage
\section{Scaling Pictures to a Specific Size}
\label{library:scalepicture}

\begin{tikzlibrary}{ext.scalepicture}
  This library scales \tikzname\ pictures to a specific width or height
  by scaling the whole picture.
\end{tikzlibrary}

\begin{multicols}{2}
If one of the keys below are used on a \tikzname\ picture, meaning
as an option to |\tikzpicture| or \texttt{\textbackslash begin\{tikzpicture\}},
the size of the picture%
\footnote{This is the size of the pseudo-node \texttt{current bounding box}.}
will be measured and written to the \filetype{aux} file
so that it will be available at the next compilation run
and an appropriate scaling for the picture can be installed.

\begin{command}{\tikzextpicturewidth}
  Returns the last measured width of the picture.
  
  This will expand to |0pt| if the picture hasn't been measured before.
\end{command}
\begin{command}{\tikzextpictureheight}
  Returns the last measured height of the picture.
  
  This will expand to |0pt| if the picture hasn't been measured before.
\end{command}

\begin{stylekey}{/\tikzext/save picture size}\keycompat{tikz}
  This key is usually used by the keys provided by this library.
  Normally, this is not needed to be explicitly given.
\end{stylekey}

\subsection{Externalization}
As this library usually needs multiple compilations
to produce stable pictures it is incompatible
with the \referenceLibraryandIndexO{external} library.

However, the library provides support for the
\referencePackageandIndexO{memoize} \cite{memoize} package.
When it is used the arguments to the keys below
will be saved as the context of the memo.
This means that the arguments need to be a valid
\referenceCommandandIndexExt{\dimexpr} expression.

\subsection{Keeping the aspect ratio}
The following \emph{unstarred} keys do not change the aspect ratio of the picture.

\begin{key}{/\tikzext/picture width=\meta{dimension}}\keycompat{tikz}
  Scales the picture so that the width of the picture will be \meta{dimension}.
  This will keep the aspect ratio the same.
\end{key}

\begin{key}{/\tikzext/minimum picture width=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its width is greater than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/maximum picture width=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its width is less than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/picture height=\meta{dimension}}\keycompat{tikz}
  Scales the picture so that the height of the picture will be \meta{dimension}.
  This will keep the aspect ratio the same.
\end{key}

\begin{key}{/\tikzext/minimum picture height=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its height is greater than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/maximum picture height=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its height is less than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/minimum picture size=\marg{width}\marg{height}}\keycompat{tikz}
  Scales the picture so that its height will be at least \meta{width}
  and its height will be at least \meta{height}.
\end{key}

\begin{key}{/\tikzext/maximum picture size=\marg{width}\marg{height}}\keycompat{tikz}
  Scales the picture so that its height will be at most \meta{width}
  and its height will be at most \meta{height}.
\end{key}

\subsection{Changing the aspect ratio}
The following \emph{starred} keys do change the aspect ratio.
\begin{key}{/\tikzext/picture width*=\meta{dimension}}\keycompat{tikz}
  Scales the picture so that the width of the picture will be \meta{dimension}.
  This will only scale the $x$ axis.
\end{key}

\begin{key}{/\tikzext/minimum picture width*=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its width is greater than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/maximum picture width*=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its width is less than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/picture height*=\meta{dimension}}\keycompat{tikz}
  Scales the picture so that the height of the picture will be \meta{dimension}.
  This will only scale the $y$ axis.
\end{key}

\begin{key}{/\tikzext/minimum picture height*=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its height is greater than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/maximum picture height*=\meta{dimension}}\keycompat{tikz}
  As above but will not change the size of the picture
  if its height is less than \meta{dimension}.
\end{key}

\begin{key}{/\tikzext/picture size*=\marg{width}\marg{height}}\keycompat{tikz}
  Scales the picture so that its width will be \meta{width}
  and its height will be \meta{height}.
  
  This will scale both axes but independent from each other.
\end{key}
\end{multicols}