%% BEGIN psd-pict.tex

\part{Picture Tools\label{P-pictures}}

\Section{Pictures\label{S-pspic}}

The graphics objects and \n\rput{} and its variants do not change \TeX's
current point (i.e., they create a 0-dimensional box). If you string several
of these together (and any other 0-dimensional objects), they share the same
coordinate system, and so you can create a picture. For this reason, these
macros are called \emph{picture objects}.

If you create a picture this way, you will probably want to give the whole
picture a certain size. You can do this by putting the picture objects in a
\p{pspicture} environment, as in:
\begin{Ex}
  \object  \pspicture`*[baseline](\x0,\y0)'\c1
  <  picture objects>
  \object  \endpspicture
\end{Ex}
The picture objects are put in a box whose lower left-hand corner is at \c0
(by default, "(0,0)") and whose upper right-hand corner is at \c1.

By default, the baseline is set at the bottom of the box, but the optional
argument "[<baseline>]" sets the baseline fraction <baseline> from the bottom.
Thus, <baseline> is a number, generally but not necessarily between 0 and 1.
If you include this argument but leave it empty (\texttt{[\kern 1pt]}), then
the baseline passes through the origin.

Normally, the picture objects can extend outside the boundaries of the box.
However, if you include the "*", anything outside the boundaries is clipped.

Besides picture objects, you can put anything in a \n\pspicture{} that does
not take up space. E.g., you can put in font declarations and use \n\psset,
and you can put in braces for grouping. PSTricks will alert you if you include
something that does take up space.\footnote{%
When PSTricks picture objects are included in a \n\pspicture{} environment,
they gobble up any spaces that follow, and any preceding spaces as well,
making it less likely that extraneous space gets inserted. (PSTricks objects
always ignore spaces that follow. If you also want them to try to neutralize
preceding space when used outside the \n\pspicture{} environment (e.g., in a
\LaTeX{} "picture" environment), then use the command \Main\KillGlue. The
command \Main\DontKillGlue{} turns this behavior back off.)}

\LaTeX{} users can type
\begin{Ex}
  "\begin{pspicture}" \ldots\ "\end{pspicture}"
\end{Ex}
You can use PSTricks picture objects in a \LaTeX{} "picture" environment, and
you can use \LaTeX{} picture objects in a PSTricks {\UsageFont pspicture}
environment. However, the {\UsageFont pspicture} environment makes \LaTeX's
"picture" environment obsolete, and has a few small advantages over the
latter. Note that the arguments of the {\UsageFont pspicture} environment work
differently from the arguments of \LaTeX's "picture" environment (i.e., the
right way versus the wrong way).


\begin{drivers} The clipping option ("*") uses \n\pstVerb{} and
\n\pstverbscale.
\end{drivers}


\Section{Placing and rotating whatever\label{S-rput}}

PSTricks contains several commands for positioning and rotating an HR-mode
argument. All of these commands end in "put", and bear some similarity to
\LaTeX's "\put" command, but with additional capabilities. Like \LaTeX's
"\put" and unlike the box rotation macros described in Section
\ref{S-rotation}, these commands do not take up any space. They can be used
inside and outside \n\pspicture{} environments.

Most of the PSTricks "put" commands are of the form:
\begin{Ex}
  \Backslash <put>*<arg>"{<rotation>}(<coor>){<stuff>}"
\end{Ex}
With the optional "*" argument, <stuff> is first put in a
\begin{LVerb*}
  \psframebox*[boxsep=false]{<stuff>}
\end{LVerb*}
thereby blotting out whatever is behind <stuff>. This is useful for
positioning text on top of something else.

<arg> refers to other arguments that vary from one "put" command to another,
The optional <rotation> is the angle by which <stuff> should be rotated; this
arguments works pretty much the same for all "put" commands and is described
further below. The "(<coor>)" argument is the coordinate for positioning
<stuff>, but what this really means is different for each "put" command. The
"(<coor>)" argument is shown to be obligatory, but you can actually omit it if
you include the <rotation> argument.

The <rotation> argument should be an angle, as described in Section
\ref{S-coor}, but the angle can be preceded by an "*". This causes all the
rotations (except the box rotations described in Section \ref{S-rotation})
within which the \n\rput{} command is be nested to be undone before setting the
angle of rotation. This is mainly useful for getting a piece of text right
side up when it is nested inside rotations. For example,
\begin{MEx}[-1,-.5](2,2)
  \rput{34}{%
    \psframe(-1,0)(2,1)
    \rput[br]{*0}(2,1){\emph{stuff}}}
\end{MEx}

There are also some letter abbreviations for the command angles. These
indicate which way is up:
\begin{trivlist}\item[]
  \leavevmode
  \hbox to \hsize{\hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "U" & Up    & 0\\
      "L" & Left  & 90\\
      "D" & Down  & 180\\
      "R" & Right & 270\\
    \end{tabular}
    \hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "N" & North & *0\\
      "W" & West  & *90\\
      "S" & South & *180\\
      "E" & East  & *270
    \end{tabular}\hfill}
\end{trivlist}


This section describes just a two of the PSTricks "put" commands. The most
basic one command is
  \Mac  \rput`*[refpoint]{rotation}'\c~{stuff}
<refpoint> determines the reference point of <stuff>, and this reference point
is translated to \c{}.

By default, the reference point is the center of the box. This can be changed
by including one or two of the following in the optional <refpoint> argument:
\begin{center}
\begin{tabular}{rlcrl}
\multicolumn{2}{l}\emph{Horizontal} & & \multicolumn{2}{l}\emph{Vertical}\\
"l" & Left  & & "t" & Top\\
"r" & Right & & "b" & Bottom\\
    &       & & "B" & Baseline
\end{tabular}
\end{center}
Visually, here is where the reference point is set of the various combinations
(the dashed line is the baseline):
\begin{center}
\begin{pspicture}(-2.4,-.9)(2.4,1.9)
  \ttfamily\bfseries
  \psframe(-2,-.5)(2,1.5)
  \psline[linestyle=dashed](-2,0)(2,0)
  \uput[u](0,1.5){t}
  \uput[d](0,-.5){b}
  \rput*(0,0){B}
  \uput[l](-2,.5){l}
  \uput[l](-2,0){Bl}
  \uput[dl](-2,-.5){bl}
  \uput[ul](-2,1.5){tl}
  \uput[r](2,.5){r}
  \uput[r](2,0){Br}
  \uput[dr](2,-.5){br}
  \uput[ur](2,1.5){tr}
\end{pspicture}
\end{center}

There are numerous examples of \n\rput{} in this documentation, but for now
here is a simple one:
\begin{example**}
  \rput[b]{90}(-1,0){Here is a marginal note.}
\end{example**}

One common use of a macro such as \n\rput{} is to put labels on things.
PSTricks has a variant of \n\rput{} that is especially designed for labels:
  \Mac  \uput`*{labelsep}'[refangle]`{rotation}\c~'{stuff}
This places <stuff> distance <labelsep> from \c{}, in the direction
<refangle>.

The default value of <labelsep> is the dimension register
  \Mac \pslabelsep
You can also change this be setting the
\begin{Ex}
  \Par{labelsep=dim}
\end{Ex}
parameter (but remember that \n\uput{} does have an optional argument for
setting parameters).

Here is a simple example:
\begin{MEx}(3,2)
  \qdisk(1,1){1pt}
  \uput[45](1,1){(1,1)}
\end{MEx}

Here is a more interesting example where \n\uput{} is used to make a pie
chart:
\begin{example}
  \psset{unit=1.2cm}
  \pspicture(-2.2,-2.2)(2.2,2.2)
    \pswedge[fillstyle=solid,fillcolor=gray]{2}{0}{70}
    \pswedge[fillstyle=solid,fillcolor=lightgray]{2}{70}{200}
    \pswedge[fillstyle=solid,fillcolor=darkgray]{2}{200}{360}
    \SpecialCoor
    \psset{framesep=1.5pt}
    \rput(1.2;35){\psframebox*{\small\$9.0M}}
    \uput{2.2}[45](0,0){Oreos}
    \rput(1.2;135){\psframebox*{\small\$16.7M}}
    \uput{2.2}[135](0,0){Heath}
    \rput(1.2;280){\psframebox*{\small\$23.1M}}
    \uput{2.2}[280](0,0){M\&M}
  \endpspicture
\end{example}

You can use the following abbreviations for <refangle>, which indicate the
direction the angle points:%
\footnote{Using the abbreviations when applicable is more efficient.}%
\footnote{%
There is an obsolete command \n\Rput\MainIndex{\Rput}{} that has the same
syntax as \n\uput{} and that works almost the same way, except the <refangle>
argument has the syntax of \n\rput's <refpoint> argument, and it gives the
point in <stuff> that should be aligned with \c{}. E.g.,
\begin{Ex}
  "\qdisk(4,0){2pt}"\qdisk(4,0){2pt}\Rput[tl](4,0){$(x,y)$}\\
  "\Rput[tl](4,0){$(x,y)$}"
\end{Ex}
Here is the equivalence between \n\uput's <refangle> abbreviations and
\n\Rput's <refpoint> abbreviations:
\begin{center}
  \ttfamily
  \begin{tabular}{rcccccccc}
    \n\uput & r & u & l & d & ur & ul & dr & dl \\
    \n\Rput & l & b & r & t & bl & br & tr & rl \\
  \end{tabular}
\end{center}
Some people prefer \n\Rput's convention for specifying the position of <stuff>
over \n\uput's.}%
\begin{trivlist}\item[]
  \leavevmode
  \hbox to \hsize{\hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "r" & right &   0\\
      "u" & up    &  90\\
      "l" & left  & 180\\
      "d" & down  & 270\\
    \end{tabular}
    \hfill
    \begin{tabular}{clr}
      \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\
      "ur" & up-right   &  45\\
      "ul" & up-left    & 135\\
      "dl" & down-left  & 225\\
      "dr" & down-right & 315
    \end{tabular}\hfill}
\end{trivlist}
The first example could thus have been written:
\begin{MEx}(3,2)
  \qdisk(1,1){1pt}
  \uput[ur](1,1){(1,1)}
\end{MEx}

\begin{drivers} The rotation macros use \n\pstVerb{} and \n\pstrotate.
\end{drivers}


\Section{Repetition\label{S-loops}}

The macro
  \Mac  \multirput`*[refpoint]{angle}\c0'\c1{int}{stuff}
is a variant of \n\rput{} that puts down <int> copies, starting at \c0 and
advancing by \c1 each time. \c0 and \c1 are always interpreted as Cartesian
coordinates. For example:
\begin{MEx}(4,1.3)
  \multirput(.5,0)(.3,.1){12}{*}
\end{MEx}

If you want copies of pure graphics, it is more efficient to use
  \Mac  \multips`{angle}\c0'\c1{int}{graphics}
<graphics> can be one or more of the pure graphics objects described in Part
\ref{P-graphics}, or \n\pscustom. Note that \n\multips{} has the same syntax as
\n\multirput, except that there is no <refpoint> argument (since the graphics
are zero dimensional anyway). Also, unlike \n\multirput, the coordinates can
be of any type. An "Overfull \hbox" warning indicates that the <graphics>
argument contains extraneous output or space. For example:
\begin{MEx}[0,-.25](4,.25)
  \def\zigzag{\psline(0,0)(.5,1)(1.5,-1)(2,0)}%
  \psset{unit=.25,linewidth=1.5pt}
  \multips(0,0)(2,0){8}{\zigzag}
\end{MEx}

PSTricks can heavily benefit of a much more general loop macro, called
\n\multido.
\File{multido} You must input the file "multido.tex" or "multido.sty". See the
documentation "multido.doc" for details. Here is a sample of what you can do:
\begin{example}
  \begin{pspicture}(-3.4,-3.4)(3.4,3.4)
    \newgray{mygray}{0}  % Initialize `mygray' for benefit
    \psset{fillstyle=solid,fillcolor=mygray}  % of this line.
    \SpecialCoor
    \degrees[1.1]
    \multido{\n=0.0+.1}{11}{%
      \newgray{mygray}{\n}
      \psset{fillcolor=mygray}%
      \rput{\n}{\pswedge{3}{-.05}{.05}}
      \uput{3.2}[\n](0,0){\small\n}}
  \end{pspicture}
\end{example}

All of these loop macros can be nested.


\Section{Axes\label{S-axes}}

\File{pst-plot}
The axes command described in this section is defined in "pst-plot.tex" /
"pst-plot.sty", which you must input first. "pst-plot.tex", in turn, will
automatically input "multido.tex", which is used for putting the labels on the
axes.

The macro for making axes is:
  \Mac  \psaxes`*[par]{arrows}\c0\c1'\c2

The coordinates must be Cartesian coordinates. They work the same way as with
\n\psgrid. That is, if we imagine that the axes are enclosed in a rectangle,
\c1 and \c2 are opposing corners of the rectangle. (I.e., the x-axis extends
from \x1 to \x2 and the y-axis extends from \y1 to \y2.) The axes intersect at
\c0. For example:
\begin{MEx*}(4,3)
  \psaxes[linewidth=1.2pt,labels=none,
    ticks=none]{<->}(2,1)(0,0)(4,3)
  "\psset{nodesep=3pt}
  "\pnode(4,3){B}
  "\rput*[tr](4,2.3){\rnode{A}{\c2}}
  "\ncline{->}{A}{B}
  "\pnode(2,1){B}
  "\rput*[br](1.3,1.7){\rnode{A}{\c0}}
  "\ncline{->}{A}{B}
  "\pnode(0,0){B}
  "\rput*[bl](0,-.9){\rnode{A}{\c1}}
  "\ncline{->}{A}{B}
\end{MEx*}

If \c0 is omitted, then the origin is \c1. If both \c0 and \c1 are omitted,
"(0,0)" is used as the default. For example, when the axes enclose a single
orthont, only \c2 is needed:
\begingroup
\psset{unit=.8}
\begin{MEx}[-.5,-.5](4,2)
  "\small
  \psaxes{->}(4,2)
\end{MEx}
\endgroup

Labels (numbers) are put next to the axes, on the same side as \x1 and \y1.
Thus, if we enclose a different orthont, the numbers end up in the right
place:
\begingroup
\psset{unit=.8}
\begin{MEx}[-.5,-2](4,.5)
  "\small
  \psaxes{->}(4,-2)
\end{MEx}
\endgroup

Also, if you set the \p{arrows} parameter, the first arrow is used for the
tips at <x1> and <y1>, while the second arrow is used for the tips at <x2> and
<y2>. Thus, in the preceding examples, the arrowheads ended up in the right
place too.\footnote{%
Including a first arrow in these examples would have had no effect because
arrows are never drawn at the origin.}

When the axes don't just enclose an orthont, that is, when the origin is not
at a corner, there is some discretion as to where the numbers should go. The
rules for positioning the numbers and arrows described above still apply, and
so you can position the numbers as you please by switching <y1> and <y2>, or
<x1> and <x2>. For example, compare
\begingroup
\psset{unit=.8}
\begin{MEx}[-1.5,-.5](2.5,2.5)
  "\small
  \psaxes{<->}(0,0)(-2.5,0)(2.5,2.5)
\end{MEx}
\endgroup
with what we get when <x1> and <x2> are switched:
\begingroup
\psset{unit=.8}
\begin{MEx}[-1.5,-.5](2.5,2.5)
  "\small
  \psaxes{<->}(0,0)(2.5,0)(-2.5,2.5)
\end{MEx}
\endgroup

\n\psaxes{} puts the ticks and numbers on the axes at regular intervals, using
the following parameters:
\newbox\axesbox
\MainParIndex{Ox}
\MainParIndex{Dx}
\MainParIndex{dx}
\MainParIndex{Oy}
\MainParIndex{Dy}
\MainParIndex{dy}
\setbox\axesbox=\hbox{%
  \large
  \begin{tabular}{|c|c|c|l|}
    \hline
    \emph{Horitontal}  & \emph{Vertical} & \emph{Dflt} &
      \emph{Description}\\[2pt]
    \p{Ox=num} & \p{Oy=num} & "0"   & Label at origin.\\
    \p{Dx=num} & \p{Dy=num} & "1"   & Label increment.\\
    \p{dx=dim} & \p{dy=dim} & "0pt" & Dist btwn labels.\\
    \hline
  \end{tabular}}
\addtoquickref{center}{%
  {\large\textbf{Axes label parameters}}\par
  \leavevmode\box\axesbox}
\begin{center}
\leavevmode\copy\axesbox
\end{center}
When \p{dx} is 0, "Dx\psxunit" is used instead, and similarly for \p{dy}.
Hence, the default values of "0pt" for \p{dx} and \p{dy} are not as peculiar
as they seem.

You have to be very careful when setting \p{Ox}, \p{Dx}, \p{Oy} and \p{Dy} to
non-integer values. "multido.tex" increments the labels using rudimentary
fixed-point arithmetic, and it will come up with the wrong answer unless
\p{Ox} and \p{Dx}, or \p{Oy} and \p{Dy}, have the same number of digits to the
right of the decimal. The only exception is that \p{Ox} or \p{Oy} can always
be an integer, even if \p{Dx} or \p{Dy} is not. (The converse does not work,
however.)%
\footnote{For example, \p{Ox=1.0} and \p{Dx=1.4} is okay, as is \p{Ox=1} and
\p{Dx=1.4}, but \p{Ox=1.4} and \p{Dx=1}, or \p{Ox=1.4} and \p{Dx=1.15}, is not
okay. If you get this wrong, PSTricks won't complain, but you won't get the
right labels either.}

Note that \n\psaxes's first coordinate argument determines the physical
position of the origin, but it doesn't affect the label at the origin. E.g.,
if the origin is at "(1,1)", the origin is still labeled "0" along each axis,
unless  you explicitly change \p{Ox} and \p{Oy}. For example:
\begin{MEx}[-2,0](2,3)
  \psaxes[Ox=-2](-2,0)(2,3)
\end{MEx}

The ticks and labels use a few other parameters as well:
\begin{description}

\pitem[labels=all/x/y/none]
  To specify whether labels appear on both axes, the x-axis, the y-axis, or
neither.

\pitem[showorigin=true/false]
  If "true", then labels are placed at the origin, as long as the label
doesn't end up on one of the axes. If "false", the labels are never placed at
the origin.

\pitem[ticks=all/x/y/none]
  To specify whether ticks appear on both axes, the x-axis, the y-axis, or
neither.

\pitem[tickstyle=full/top/bottom]
  For example, if \p{tickstyle=top}, then the ticks are only on the side of
the axes away from the labels. If \p{tickstyle=bottom}, the ticks are on the
same side as the labels. "full" gives ticks extending on both sides.

\pitem[ticksize=dim]
  Ticks extend <dim> above and/or below the axis.

\end{description}

The distance between ticks and labels is \n\pslabelsep, which you can change
with the \p{labelsep} parameter.

The labels are set in the current font (ome of the examples above were
preceded by "\small" so that the labels would be smaller). You can do fancy
things with the labels by redefining the commands:
\begin{Ex}
  \object  \pshlabel
  \object  \psvlabel
\end{Ex}
E.g., if you want change the font of the horizontal labels, but not the
vertical labels, try something like
\begin{LVerb}
  \def\pshlabel#1{\small #1}
\end{LVerb}

You can choose to have a frame instead of axes, or no axes at all (but you
still get the ticks and labels), with the parameter:
\begin{Ex}
  \Par{axesstyle=axes/frame/none}
\end{Ex}
The usual \p{linestyle}, \p{fillstyle} and related paremeters apply.

For example:
\begin{MEx}[-3,-.5](.5,3)
  \psaxes[Dx=.5,dx=1,tickstyle=top,axesstyle=frame](-3,3)
\end{MEx}

The \n\psaxes{} macro is pretty flexible, but PSTricks contains some other
tools for making axes from scratch. E.g., you can use \n\psline{} and
\n\psframe{} to draw axes and frames, respectively, \n\multido{} to generate
labels (see the documentation for "multido.tex"), and \n\multips{} to make
ticks.

\endinput

%% END psd-pict.tex
