# How does \uput determine the touching point between the object box and the hypothetical circle?

This question offers 4 bounties of 500 each only for a single answer that fit this question best.

I am interested in describing the behavior of \uput for non-zero dimensional objects. Non-zero dimensional objects are objects with prepared containers at TeX level. Zero dimensional objects have zero containers at TeX level.

For zero dimensional objects, its behavior has been known as follows and now it is no longer interesting to me.

Lets consider the 2 cases below:

## Case 1:

\documentclass[pstricks,border=12pt]{standalone}
\SpecialCoor
\usepackage{multido}

\def\NonZeroDimenObject{%
\pspicture(2,1)
\psframe(2,1)
\psline[linecolor=blue]{->}(1,.5)(2,.5)
\endpspicture}

\SpecialCoor

\begin{document}

\multido{\i=0+15}{24}{%
\begin{pspicture}[showgrid](8,8)
\pscircle(4,4){2}
\psline[origin={4,4}](3.5;\i)
\rput(4,4){\i}
\uput{2}[\i]{0}(4,4){\NonZeroDimenObject}
\end{pspicture}}

\end{document}


## Case 2:

\documentclass[pstricks,border=12pt]{standalone}
\SpecialCoor
\usepackage{multido}

\def\NonZeroDimenObject{%
\pspicture(2,1)
\psframe(2,1)
\psline[linecolor=blue]{->}(1,.5)(2,.5)
\endpspicture}

\SpecialCoor

\begin{document}

\multido{\i=0+15}{24}{%
\begin{pspicture}[showgrid](8,8)
\pscircle(4,4){2}
\rput(4,4){\i}
\uput{2}[0]{\i}(4,4){\NonZeroDimenObject}
\end{pspicture}}

\end{document}


## Questions:

I have 3 questions:

1. For the given \alpha (or the second argument), a line from (i_x,i_y) to (i_x,i_y)+(r;\alpha) does not always point to the touching point between the object box and the hypothetical circle of radius labelsep. How does \uput determine the touching point? Explaining the internal algorithm should be fine.

2. The pivot seems not to be static. How does \uput determine the touching point? Explaining the internal algorithm should be fine.

3. When do we really need \uput? Please give me at least 2 practical unique examples that cannot be replaced by other put macros.

-

\documentclass[pstricks,border=12pt]{standalone}
\SpecialCoor
\usepackage{multido}

\def\Width{3 }
\def\Height{1 }
\def\NonZeroDimenObject#1{%
\pspicture(\Width,\Height)\psframe(\Width,\Height)\endpspicture}
\SpecialCoor
\psset{dotscale=0.5}
\begin{document}

\multido{\i=0+5}{73}{%
\begin{pspicture}[showgrid](9,8)
\multido{\iB=0+1}{\i}{\uput{2}[\iB]{0}(4,4){\pspicture(\Width,\Height)\psdot(!\Width 2 div \Height 2 div)\endpspicture}}
\pscircle(4,4){2}
\rput(4,4){\psline[linecolor=blue]{->}(3;\i)}
\rput(4,4){\i}
\uput{2}[\i]{0}(4,4){\NonZeroDimenObject{\i}}
\end{pspicture}}

\end{document}


The first one with labelsep=0. If it is not a square it will be translatet with a transformation matrix.

-
I need the relationship between the angle \alpha (the second argument) and the coordinate of the touching point. :-) –  In PSTricks we trust May 6 '13 at 20:11

In my opinion, the interpretation is obvious:

1. \uput{2}[\i]{0}(4,4){\NonZeroDimenObject}

Consider the 4 arguments before object \NonZeroDimenObject. It is placed

• at a radial distance of 2 units (runits to be specific) - first argument {.};
• at a variable angle of \i (which ranges from 0 to 345 in steps of 15 degree increments ~ 24 steps in total; according to the definition of \multido{<type/var>=<start>+<diff>}{<repititions>}{<stuff>}) - second argument [.];
• with a fixed rotation of 0 degrees around the object's centre origin - third argument {.}; and
• from the point (x,y) = (4,4) - fourth argument (.,.).
2. \uput{2}[0]{\i}(4,4){\NonZeroDimenObject}

Consider the 4 arguments before object \NonZeroDimenObject. It is placed

• at a radial distance of 2 units (runits to be specific) - first argument {.};
• at a fixed angle of 0 - second argument [.];
• with a variable rotation of \i degrees around the object's centre origin (which ranges from 0 to 360 in steps of 5 degree increments ~ 73 steps in total; according to the definition of \multido{<type/var>=<start>+<diff>}{<repititions>}{<stuff>})- third argument {.}; and
• from the point (x,y) = (4,4) - fourth argument (.,.).
3. \uput{<labelsep>}[<refangle>]{<rotation>}(<x,y>){<stuff>} is a convenience-macro for \rput that also does a large amount of heavy-lifting in terms of placing the object at a required reference point. In some (very) special cases, you can use a combination of \rput commands to obtain a similar placement to that of \uput, as in the following example (a 45 degree angle, say):

\documentclass{article}
\usepackage{pstricks}% http://tug.org/PSTricks/main.cgi/
\begin{document}
\SpecialCoor

\noindent
\begin{minipage}{0.5\linewidth}
\begin{pspicture}[showgrid](3,3)
\pscircle*(1.5,1.5){1}
\uput{1.2}[45]{0}(1.5,1.5){$v$}
\end{pspicture}
\end{minipage}%
\begin{minipage}{0.5\linewidth}
\begin{pspicture}[showgrid](3,3)
\pscircle*(1.5,1.5){1}
\rput{0}(1.5,1.5){\rput[bl]{0}(1.2;45){$v$}}
\end{pspicture}
\end{minipage}
\end{document}


The output, as expected, is the same.

Wherein lies the convenience? Well, \uput automatically decides the reference point to use when placing the object so that it is guaranteed to be a radial distance <labelsep> away from the point of placement. The following example shows this:

\documentclass[pstricks,border=12pt]{standalone}% http://ctan.org/pkg/standalone
\usepackage{multido}% http://ctan.org/pkg/multido
\begin{document}

\SpecialCoor
\multido{\i=0+15}{24}{%
\begin{pspicture}[showgrid](3,3)
\psline[linecolor=gray,origin={1.5,1.5}](1.2;\i)
\pscircle(1.5,1.5){1}
\rput(1.5,1.5){\i}
\uput{1.2}[\i]{0}(1.5,1.5){$v$}% Example 1
%\rput{0}(1.5,1.5){\rput{0}(1.2;\i){$v$}}% Example 2
%\rput{0}(1.5,1.5){\rput[bl]{0}(1.2;\i){$v$}}% Example 3
\end{pspicture}
}

\end{document}


The respective output of the three animations are obtained from the above code by commenting in/out the required line for Example 1, 2 or 3.

Note how \uput always maintains a fixed radial distance, while \rput suffers from this when using a fixed reference point. Without a fixed reference point, it defaults to the object's centre.

The following shows the difference in distances and translations that have to be calculated in order to adequately answer the question:

\documentclass[pstricks,border=12pt]{standalone}% http://ctan.org/pkg/standalone
\usepackage{multido,pst-node}% http://ctan.org/pkg/{multido,pst-node)
\def\Width{3 }
\def\Height{1 }
\def\NonZeroDimenObject{%
\pspicture(\Width,\Height)\psframe(\Width,\Height)\endpspicture}
\SpecialCoor
\psset{dotscale=0.5}
\begin{document}

\multido{\i=0+5}{73}{%
\begin{pspicture}[showgrid](9,8)
\pscircle(4,4){2}
\uput{2}[\i]{0}(4,4){\rnode{MyNode}{\NonZeroDimenObject}\pnode(! \psGetNodeCenter{MyNode} MyNode.x MyNode.y){NZDOcentre}}
\rput{0}(4,4){\psline[linecolor=blue]{->}(2;\i)}
\psline[linecolor=red]{->}(4,4)(NZDOcentre)
\rput(4,4){\i}
\end{pspicture}}


The blue line indicates the exact angle and distance the \uput command points to, while the red line indicates the centre of \NonZeroDimenObject.

-
The statement "\uput always maintains a fixed radial distance" might be misleading because the referenced points on the object always change. –  In PSTricks we trust May 6 '13 at 19:19
@Bugbusters: Yes, \uput updates to the appropriate reference point such that the radial distance from the origin (<x,y>) to the object is always <labelsep>. To me the phrase is not misleading, but I hope these comments clarify it. –  Werner May 6 '13 at 19:25
For the given angle \alpha (or the second argument), a line from (i_x,i_y) to (i_x,i_y)+(r;\alpha) does not point to the touching point on which the box of non-zero object and the hypothetical circle touch. –  In PSTricks we trust May 6 '13 at 19:32
@Werner: The difference between \uput and \rput is that \rput’s reference point is replaced by labelsep and reference angle arguments. –  Herbert May 6 '13 at 19:38
Please see my update for the first case to know what part confused me. If you can explain this, the mission will be accomplished for the first case. –  In PSTricks we trust May 6 '13 at 19:43