% Regression test for \stgroup and \stcallout.
%   - a group over three adjacent head faces (the trio is one composite q);
%     the first face carries bracket=true, probing that bracket ink is part
%     of the group's fit -- the outline must clear the bracket arms,
%   - a group over a \stcol partition (two shards tiling one parent W),
%   - one side card for the whole figure, hanging off a finished band.
% No absolute coordinate appears anywhere in this figure.
%   ../scripts/build.sh group-callout.tex
\documentclass[border=10pt]{standalone}
\usepackage[cjk]{supertensor}

\stsetrole{act}{stTeal}
\stsetrole{w}{stOrange}
\stsetrole{q}{stViolet}

\stdim{T}{7}
\stdim{d}{5}
\stdim{dh}{3}

\begin{document}
\begin{tikzpicture}

\ststage{S1}{一、分组框：三个相邻的头合起来是一个复合对象}
\strow{R1}{T}
  \stface[role=act, bracket=true]{X}{}{T}{d}
  \stlink{l1}{按头切分}
  \stgroup[role=q]{QG}
    \stface[role=q, bracket=true]{Q1}{}{T}{dh}
    \stface[role=q, gap=2mm]{Q2}{}{T}{dh}
    \stface[role=q, gap=2mm]{Q3}{}{T}{dh}
  \stgroupend
\strowend
\stcaption{X}{$\mathbf X$}{$T\times d$}
\stcaption{QG}{$\mathbf q$}{$h\times T\times d_h$}

\ststage{S2}{二、分组框圈住两片相邻的分片，标注它们合起来是谁}
\strow{R2}{T}
  \stface[role=act]{H}{}{T}{d}
  \stglyph{m2}{$\times$}
  \stgroup[role=w, pad=2.2mm]{WG}
    \stcol{Wc}{d}
      \stface[role=w]{Wa}{}{dh}{T}
      \stface[role=w, gap=0pt]{Wb}{}{2}{T}
    \stcolend
  \stgroupend
  \stlink{l2}{}
  \stface[role=q, bracket=true]{Z}{}{T}{T}
\strowend
\stcaption{H}{$\mathbf H$}{$T\times d$}
\stcaption{WG}{$\mathbf W$}{$d\times T$}
\stcaption{Z}{$\mathbf Z$}{$T\times T$}
\stcallout{N1}{4.2cm}{R2}{分组框在说什么}%
  {外框与成员同色，因为它圈的是同一个对象的分片视图，不是一个新张量。
   括号等装饰墨迹也计入外框的包围盒，所以框永远不会被成员的括号穿过；
   整张图默认只允许一张这样的卡片，再多就是仪表盘。}

\sttopformula{F}{$\displaystyle \mathbf Z=\mathbf H\,\mathbf W,\qquad
  \mathbf W=\begin{bmatrix}\mathbf W_a\\ \mathbf W_b\end{bmatrix}$}

\stbbox{all}
\stmeaningbox{mb}{17cm}{all}
  {$T$ 序列长，$d$ 模型维，$d_h$ 头宽，$h$ 头数}
  {}
  {分组框是横向的子流：成员写在块里，所以它只能圈住相邻的对象；
   它必须绑定至少两个成员或一个 \texttt{stcol} 分片，单个对象外再画框是装饰。
   连接线不能在框内起止——\texttt{stlink} 写在组里是构建错误，
   闭合后箭头接在外框上，而不是穿过一个并非自己端点的边。}

\end{tikzpicture}
\end{document}