% !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.
%

\section{Shape: Superellipse}
\begin{pgflibrary}{ext.shapes.superellipse}
  Shape in the form of a ``superellipse''.
  \inspiration{ShapeSuperEllipse-Q}{ShapeSuperEllipse-A}
\end{pgflibrary}

\begin{ext_shape}{superellipse}
This shape is defined by formula
\begin{equation*}
  \biggl|\frac x{r_x}\biggr|^m + \biggl|\frac y{r_y}\biggr|^n = 1
\end{equation*}
and will be plotted by
\begin{align*}
  x(t) &= |\cos t|^{\frac 2m} \cdot r_x \sgn(\cos t) \\
  y(t) &= |\sin t|^{\frac 2n} \cdot r_y \sgn(\sin t) \\
\end{align*}
where $r_x$ is half the node's width and $r_y$ is half the node's height.

\begin{key}{/\pgfext/superellipse x exponent=\meta{x exponent}(initially 2.5)}\keycompat{pgf}
This sets $m$.
\end{key}
\begin{key}{/\pgfext/superellipse y exponent=\meta{y exponent}(initially 2.5)}\keycompat{pgf}
This sets $n$.
\end{key}
\begin{key}{/\pgfext/superellipse step=\meta{step}(initially 5)}
This specifies the step of the underlying plot handler.
The smaller \meta{step} is, the slower computation will be.

Sensible values for \meta{step} are integer dividers of 90, i.\,e.
2, 3, 5, 6, 9, 10, 15, 18, 30 and 45.
\end{key}
\begin{key}{/\pgfext/superellipse exponent=\meta{exponent}}\keycompat{pgf}
  Sets both |superellipse x exponent| and |superellipse y exponent| to \meta{exponent}.
\end{key}

\paragraph{Notes on Implementation}
For implementing this shape, additional mathematical functions were declared.
\begin{math-function}{ext\textunderscore superellipsex(\mvar{t}, \mvar{2/m}, \mvar{$r_x$})}
\mathcommand[extsuperellipsex(\mvar{t}, \mvar{2/m}, \mvar{$r_x$})]
Returns the $x$ value on a point of the superellipse with its center on the origin following
\begin{equation*}
   x = r_x\cos^{2/m} t
\end{equation*}
for values of $0 \leq t \leq 90$.
\end{math-function}
\begin{math-function}{ext\textunderscore superellipsey(\mvar{t}, \mvar{2/n}, \mvar{$r_y$})}
\mathcommand[extsuperellipsey(\mvar{t}, \mvar{2/m}, \mvar{$r_x$})]
Returns the $y$ value on a point of the superellipse with its center on the origin following
\begin{equation*}
   y = r_y\cos^{2/n} t
\end{equation*}
for values of $0 \leq t \leq 90$.
\end{math-function}

Both \pgfname math functions can be used at once with the following macro.
\begin{command}{\pgfextmathsuperellipseXY\marg{t}\marg{2/m}\marg{2/n}\marg{a}\marg{b}}
Returns the $x$ value (in |\pgfmathresultX|) and the $y$ value (in |\pgfmathresultY|) of the superellipse with its center on the origin following
\begin{align*}
   x & = a\cos^{2/m} t \\
   y & = b\cos^{2/n} t
\end{align*}
for values of $0 \leq t \leq 90$.

Note: all arguments must be a valid number since they will not be parsed by \pgfname math.
\end{command}

\begin{codeexample}[preamble=\usetikzlibrary{ext.shapes.superellipse}]
\begin{tikzpicture}[ext/superellipse step=1]\Huge
\node[name=s,shape=ext_superellipse,shape example] {Superellipse\vrule width 1pt height 2cm};
\foreach \anchor/\placement in
  {north west/above left, north/above, north east/above right,
   west/left, center/above, east/right,
   mid west/right, mid/above, mid east/left,
   base west/left, base/below, base east/right,
   south west/below left, south/below, south east/below right,
   text/left, 10/right, 130/above}
   \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
     node[\placement] {\scriptsize\texttt{(s.\anchor)}};
\end{tikzpicture}
\end{codeexample}
%
\begin{codeexample}[width=8cm,preamble=\usetikzlibrary{ext.shapes.superellipse}]
\begin{tikzpicture}[minimum width=1cm, minimum height=3cm]
\foreach \xe/\ye[count=\i] in {.5/.5, 1/1, 2/2, 3/3, .5/5}
  \node[draw, ext_superellipse, ext/superellipse x exponent=\xe, ext/superellipse y exponent=\ye] at (1.5*\i,0) {};
\end{tikzpicture}
\end{codeexample}
\end{ext_shape}
\endinput