diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /usergrps/uktug/baskervi/6_1/bv61pst.tex |
Initial commit
Diffstat (limited to 'usergrps/uktug/baskervi/6_1/bv61pst.tex')
-rw-r--r-- | usergrps/uktug/baskervi/6_1/bv61pst.tex | 1010 |
1 files changed, 1010 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/6_1/bv61pst.tex b/usergrps/uktug/baskervi/6_1/bv61pst.tex new file mode 100644 index 0000000000..5df61fd482 --- /dev/null +++ b/usergrps/uktug/baskervi/6_1/bv61pst.tex @@ -0,0 +1,1010 @@ +\newpsobject{usergrid}{psgrid}{subgriddiv=1,griddots=10,gridlabels=7pt} + +\iffalse +\author{Sebastian Rahtz} +\title{An introduction to PSTricks, part I} +\begin{Article} +aaaaa +\end{Article} +\endinput +\fi + +\def\CurrentPackages{spqr,pstcol} +\newcounter{myN} +\setlongtables +\author{Sebastian Rahtz} +\title{An introduction to PSTricks, part I} +\begin{Article} +\section{Preface} +In all the questions about \TeX\ and drawing that appear in \emph{fora} like +\texttt{comp.text.tex}, surprisingly little attention is paid to what seems +to me one of the most delightful macro packages available. This is \PST, +which allows the \TeX\ user almost full access to the power of \PS, +using the \verb|\special| mechanism. In this, and the following two +issues of, \BV, I will attempt to offer a survey of what \PST\ can do, +and perhaps persuade more \BV\ readers to experiment. + +This material is drawn from a forthcoming book by myself and Michel +Goossens; we are grateful to Timothy van Zandt (the author of \PST) +and Denis Girou (its best-known exponent) for the many helpful +insights and examples which they have vouchsafed during the several +years we have been working on the material. + +This first tutorial looks at the principles of \PST, and the basic +building blocks; the next will consider nodes, trees, matrices and the +like, and the final part will look at customising \PST\ and some +programming examples. + +\section{Introduction} +\PST\ consists of a core of picture drawing primitives +implemented by \Special{}s which pass \PS\ through to a driver. It +also contains a set of higher-level macros for particular +applications. With it you can: +\begin{enumerate} +\item draw lines, polygons, circles and curves; +\item place and manipulate \TeX\ text; +\item plot data with complicated labelled axes; +\item draw nodes and connectors (including trees); +\item colour lines and fill objects; +\item define new graphical commands. +\end{enumerate} +This is an extremely powerful package, and its facilities can take +some time to understand. It is documented in +\cite{Zandt:1993a}, and its implementation is described in +\cite{Zandt-Girou:1994}. \cite{Girou:1994} provides an excellent +demonstration of the abilities of the package, and I am grateful to +Denis Girou for permission to reproduce some of his examples below. + +The package relies on the ability of a dvi driver to pass through +literal \PS\ code, and know that it will interact with the \TeX\ text +in a controlled way. The \Program{dvips} driver provides the reference +implementation, but it works with other drivers (like Textures) as +well. The \PST\ installation guide explains what a driver has to be +able to do. + +\PST\ is not a tool for drawing just one type of diagram well, like +so many of the other packages you can find on \textsc{ctan}. +It is a programming environment for as close a +combination of \TeX\ and \PS\ as is possible with existing +software; its strength is its modularity, extensibility, and ability +to access all the power of \PS. + +The main package, and the subsidiary ones, need access to various +\PS\ header files; the user does not need to explicitly load them, +but the driver must be capable of doing so. The method for loading header +files, and other \Special{} communication, is defined by a configuration file. + +The majority of \PST\ is loaded in a single package, but some +more complicated facilities need an extra file to be loaded: + +\begin{center} +\begin{tabular}{ll} +\emph{File} & \emph{Function}\\ +\hline +\texttt{pst-coil} & Coil and zigzag objects\\ +\texttt{textpath} & Typesetting text on a path\\ +\texttt{charpath} & Stroking and filling character paths\\ +\texttt{pst-plot} & Data plotting\\ +\texttt{pst-3d} & Three-dimensional drawing\\ +\texttt{pst2eps} & Export of objects direct to EPS files\\ +\texttt{pst-node} & Placing and joining nodes\\ +\texttt{pstree} & Tree macros\\ +\texttt{gradient} & Gradient colour fills\\ +\hline +\end{tabular} +\end{center} + +In the descriptions that follow, we do \emph{not} normally indicate +which file needs loading for a particular function, since this may +change with new releases of the package. + +Most of the commands provided will draw some kind of object at +specified coordinates, which are relative to the current point in +\TeX. The objects do not usually take up any space, in \TeX\ terms; +they can either be mixed in with normal commands, or used in a picture +environment to construct a whole drawing. The \LaTeX\ environment +corresponding to the command: +\begin{quote} + \PSTCom \pspicture`*[baseline](\x0,\y0)'\c1 +\end{quote} +is normally used for pictures; space is reserved in \TeX\ for a rectangle +with corners at \c0 and \c1 (as in other cases, \c0 defaults to (0,0)). +The * form clips graphic objects which appear outside the frame. +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. + +I will not attempt to describe absolutely every \PST\ +macro, or give examples of all the possible combinations and tricks, +as this would require a large book, so we strongly commend the reader to +study the published examples by Denis Girou for ideas on \PST\ +programming, as well as the manual itself. + + +\subsection{Basic \protect\PST\ concepts} +Luckily, almost all the commands have the same (complex) structure; +they need some or all of the following arguments, each of which has +its consistent delimiters: + +\noindent\begin{tabular}{@{}l@{}rl@{}} +\emph{Type} & \emph{Delimiters} & \emph{Example} \\ +\hline +Obligatory parameter &curly brackets & \verb"{arg}" \\ +Optional settings & square brackets & \verb"[par1=val1,".\,.\\ +Coordinates & parentheses & \verb"(x,y)" \\ +\end{tabular} + +Many macros can +have a lot of arguments, so it is useful to know that you can leave a +space or new line between arguments, except those enclosed in curly +braces. + +The layout of a command is +\begin{small} +\begin{verbatim} +\command*[settings]{arrows/parameters} + (coordinates) +\end{verbatim} +\end{small} +\begin{itemize} +\item The * form of the command generally means that the object being drawn +is to be solid, rather than an outline; +\item The \emph{settings} are optional, and consists of a set of +\emph{key=value} pairs +which over-ride, for the current object, \PST's drawing defaults; this is +discussed below; +\item Many commands which draw lines have an argument which specifies +whether, and how, arrow heads are to be drawn at either end; or they +need an argument like a rotation angle; +\item Most objects require one or more coordinates; these consist of two +numbers separated by a comma; multiple coordinate pairs each have +their own set of brackets. +\end{itemize} +A simple complete example is +\begin{GridPSExample}(0,0)(2,2) +\psline[linewidth=1pt,linecolor=gray] + {<->}(0.5,0)(0,1)(1,1.5)(1.5,1)(.5,.5) +\end{GridPSExample} +where a grid has been superimposed to show the coordinate system. + +\subsubsection{Coordinates} +By default the coordinate system is in units of 1cm in the $x$ and $y$ +directions, but that can be simply overridden as we shall see in a +moment. Coordinate pairs can not only be given in the default units, +but also in any \TeX\ dimensions. This applies to all `quantity' +settings, so +\verb|linewidth=.5| means .5 of whatever the current unit is, but +\verb|linewidth=2pt| is an absolute size. + +The command \Usage{SpecialCoor} lets you use polar coordinates, in the +form "(<r>;<a>)", where <r> is the radius (a dimension) and <a> is the +angle. You can still use Cartesian coordinates. + +The <unit> parameter actually sets the $x$ and $y$ parameters which +can also be set individually, so that you can scale the $x$ and $y$ +dimensions in Cartesian coordinates unevenly. + + +Angles, in polar coordinates and other arguments, should be a number +giving the angle in degrees, by default. You can also change the units +used for angles with the command +%%%%% put this at the end of a line and add a space after it!!!! +\PSTCom \degrees`[num]' +\ where <num> is the number of units in a circle. Thus +\begin{verbatim} + \degrees[100] +\end{verbatim} +could be used when +making a pie chart where the data values are supplied as percentages. +The command \Lcs{radians} is short for +"\degrees[6.28319]" + +\subsubsection{Colouring objects} +\PST\ comes with its own collection of colour macros, which provide +a basic set of colours, and allow one to define new colour names in +terms of RGB, CMYK or HSB models; however, we recommend that \LaTeX\ +users should stick with the \Lpack{color} package. The standard +package and \PST\ can be used together by loading the package +\Lpack{pstcol}, which comes with the colour and graphics bundle. +The \Lpack{gradient} package adds facilities for gradations of colour +in filled objects. + +The following colours are predefined:\\ +"black", "darkgray", "gray", "lightgray", "white", +"red", "green", "blue", "cyan", "magenta", and "yellow". + +\subsubsection{Setting graphics parameters} +\PST\ uses a notation similar to that introduced +for the \Lpack{graphicx} package, \ie `key=value' pairs. This is used +for setting a large number of graphical parameters which apply to almost +all objects. These can be set in two ways: +\begin{enumerate} +\item On a per-object basis, with the optional parameter +in square brackets; in this +case the effect is local to the object with no further grouping needed; +\item Globally, using the \Lcs{psset} command. +The syntax is: +\begin{quote} + \PSTCom \psset{par1=value1`,par2=value2,\ldots'} +\end{quote} +\end{enumerate} +Extra spaces are only allowed following the comma that +separates <par>"="<value> pairs (which is therefore +a good place to start a new line if you are giving a long list). +A selection of the commoner +graphics parameters that can be set for objects +are listed in Table~\ref{PSTparms}; the first group +can be applied to more or less anything, but the others only apply to +a particular group. + +\begin{small} +\begin{longtable}{llP{.5\textwidth}} +\caption{\protect\PST\ Graphical parameters} +\label{PSTparms}\\[1mm] +\emph{Parameter} & \emph{Default} & \emph{Explanation}\\ +\hline +\endfirsthead +\caption*{\protect\PST\ Graphical parameters \emph{cont.}}\\[1mm] +\emph{Parameter} & \emph{Default} & \emph{Explanation}\\ +\hline +\endhead +\mbox{}\\ +\endfoot +\multicolumn{3}{l}{\bfseries\itshape General}\\ + \Par{unit=dim} (1cm) \\ + \Par{xunit=dim} (1cm) \\ + \Par{yunit=dim} (1cm) \\ + \Par{linewidth=dim} (.8pt) \\ + \Par{linecolor=colour} (black) \\ + \Par{fillcolor=colour} (white) \\ + \Par{fillstyle=style} (none)&{Other possibilities are solid, vlines, +vlines*, hlines, hlines*, crosshatch and crosshatch*. The * versions also +fill the background. The \Lpack{gradient} package adds the extra +\emph{gradient} style for a graded fill, and the following keys.}\\ +\Par{gradbegin=colour} ()&{The starting and ending colour of a graded +fill} \\ +\Par{gradend=colour} ()&{The colour at the midpoint.} \\ +\Par{gradlines=int} (500)&{The number of lines in the graded fill. +More lines means finer gradiation, but slower printing.}\\ +\Par{gradmidpoint=num} (.9)&{The position of the midpoint, as a +fraction of the +distance from top to bottom (the <num> will be between 0 and 1)}.\\ +\Par{gradangle=angle} (0)&{The gradation is rotated by <angle>.} \\ + \Par{hatchwidth=dim} (.8pt)&{Width of fill lines} \\ + \Par{hatchsep=dim} (4pt)&{The gap between fill lines} \\ + \Par{hatchcolor=colour} (black) \\ + \Par{hatchangle=angle} (45) \\ +\Par{arrows=style} (none) &The possibilities are listed in +Table~\ref{PSTarrows}; +any symbol, or none, can be put at either end of a line \\[6pt] +\multicolumn{3}{l}{\bfseries\itshape Lines, curves and boxes}\\ +\Par{linestyle=style} (solid)&{Other possibilities are \emph{dashed}, + \emph{dotted} and \emph{none}} \\ + \Par{dash=dim1 dim2} (5pt 3pt)&{The black/white dash pattern for +dashed lines.} \\ + \Par{dotsep=dim} (3pt) \\ + \Par{doubleline=true/false} (false)&{Draw lines as double line, +separated by \emph{bordersep} and with colour \emph{bordercolor} between the +lines.} \\ + \Par{doublesep=dim} (1.25 of linewidth) \\ + \Par{shadow=true/false} (false)&{A shadow is drawn at +angle \emph{shadowangle}, of depth \emph{shadowsize} and colour +\emph{shadowcolor}.} \\ + \Par{shadowsize=dim} (3pt) \\ + \Par{shadowangle=angle} (-45) \\ + \Par{shadowcolor=colour} (darkgray) \\ + \Par{linearc=dim} (0pt)&{The radius of arcs drawn at + the corners of a box or set of line segments.} \\ + \Par{framearc=dim} (0pt)&{If \emph{cornersize} is `relative', then +the radius of rounded corners of + framing boxes is set to \emph{num} times the width of height of +the frame, whichever is less. \emph{num} cannot be greater than 1. If +\emph{cornersize} is `absolute', \emph{num} sets the radius of arcs of rounded +corners.} \\ + \Par{cornersize=relative/absolute} (relative) \\[6pt] +\multicolumn{3}{l}{\bfseries\itshape Text frames}\\ +\Par{framesep=dim} (3pt)&{The gap between a frame and the enclosed +text} \\ +\Par{boxsep=true/false} (true)&{Whether the \TeX\ box that is produced +includes the size of the frame itself or not} \\[6pt] +\multicolumn{3}{l}{\bfseries\itshape Dots}\\ + \Par{dotstyle=style} (*)&The possible styles are listed in + Table \ref{dotstyles} \\ + \Par{dotsize=dim <num>} (2pt 2)&The diameter of a circle or disc + is \emph{dim} plus \emph{num} times the current linewidth \\ +\hline +\end{longtable} +\end{small} + +\section{The graphic objects} +We list in Table \ref{PSTbasic} the most common basic objects which \PST\ can +draw; they all, with the exception of the text-framing commands, take +up no \TeX\ space, and so should be used inside a \texttt{pspicture} +environment when creating a free-standing picture. In almost every +case, an initial first coordinate can be omitted, and defaults to +$0,0$. Lines and open curves can optionally be terminated with +various symbols, and it is this that the \texttt{arrows}\ldots styles +set. + +\PST\ has two powerful commands for positioning (and rotating, if +necessary) something, including normal \LaTeX\ material; they are +analagous to \LaTeX's basic "\put" command. The more common command +is +\begin{quote} + \PSTCom \rput*`[refpoint]{angle}'(\x0,\y0){stuff} +\end{quote} +The * form puts a "\psframebox" around <stuff>, +which effectively blocks out anything underneath. +<stuff> is rotated by <angle> if the argument is present; the <angle> +it can be preceded by a "*", which has the effect of undoing all +rotations in outer calls to \Usage{rput}. This is needed when placing +text labels, to make it easy to place them consistently in the +right orientation. Since many rotations are in steps of 90\degrees, +you can use the following letter abbreviations + +\vskip 3pt +\noindent +\begin{tabular}{c>{\itshape}lr@{\hspace{.25cm}}c>{\itshape}lr} + \em Letter & &\em degrees & + \em Letter & &\em degrees\\ + "U" & Up & 0 &"N" & North & *0\\ + "L" & Left & 90&"W" & West & *90\\ + "D" & Down & 180&"S" & South & *180\\ + "R" & Right & 270&"E" & East & *270\\ +\end{tabular} +\vskip 3pt + +<refpoint> describes the reference point of <stuff>, +and this reference point is what is placed at \c{}. +By default, it is the center of the box. +This can be changed setting <refpoint> to one or two of the +following +\begin{quote} +\begin{tabular}{rlcrl} +\multicolumn{2}{l}{\em Horizontal} & & \multicolumn{2}{l}{\em Vertical}\\ +"l" & Left & & "t" & Top\\ +"r" & Right & &"b" & Bottom\\ + & & &"B" & Baseline +\end{tabular} +\end{quote} +The following diagram shows the reference point represented +by the various combinations (the dotted line is the baseline): +\begin{quote} +\begin{pspicture}(-2.4,-.9)(2.4,1.9) + \UsageFont + \psframe(-2,-.5)(2,1.5) + \psline[linestyle=dotted](-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{quote} +\begin{quote} + \PSTCom \rput*`[refpoint]{rotation}'\cAny{stuff} +\end{quote} +It is important to realize that "\rput" resets the (0,0) point +to the chosen coordinate, as shown in the following example: +\begin{GridPSExample}(0,0)(2.2,2) +\rput(.1,.1){\psline(0,0)(1.3,1.3)} +\rput{-20}(1.2,.4){\psline(0,0)(1,0)} +\end{GridPSExample} +Note that rotation was applied last of all. +Because it is very often a requirement to \emph{put} a label +next to some object, a variant of "\rput" is provided: + + \PSTCom \uput*`{labsep}'[refangle]`{rotation}'\cAny{stuff} + +which places <stuff> in the direction <angle>, +at a distance of <labsep> from \c{}. <labsep> defaults to 5pt. +As before, since angles are often in steps of 45\degrees, letter abbreviations +are provided for common cases: + +\vskip3pt\noindent + \begin{tabular}{@{}c>{\itshape}lr@{\hspace{.25cm}}c>{\itshape}lr@{}} + {\em Letter} & &\em degrees& + {\em Letter} & & \em degrees\\ + "r" & right & 0 & "ur" & up-right & 45\\ + "u" & up & 90 & "ul" & up-left & 135\\ + "l" & left & 180 & "dl" & down-left & 225\\ + "d" & down & 270&"dr" & down-right & 315\\ + \end{tabular} +\vskip3pt + +\begin{small} +\begin{longtable}{>\small lP{.41\textwidth}} +\caption{\protect\PST\ basic drawing commands\label{PSTbasic}}\\ +\hline +\endfirsthead +\caption*{\protect\PST\ basic drawing commands \emph{cont.}}\\ +\hline +\endhead +\PSTComOpt \parabola`{arrows}'\c0\c1 +&Draw a parabola that starts at \c0, +passes through \c0, and whose maximum or minimum is \c1 \\ +\PSTComOpt \psarc`{arrows}\c~'{radius}{angleA}{angleB} +&Draw a circle segment between \emph{angle1} and \emph{angle2} +(counter-clockwise); \\ +\PSTComOpt \psarcn`{arrows}\c~'{radius}{angleA}{angleB} +&As \Usage{psarc}, but the arc is drawn \emph{clockwise} \\ +\PSTComOpt \psbezier`{arrows}(\x0,\y0)'(\x1,\y1)(\x2,\y2)(\x3,\y3) +&Draw a Bezier curve with four control points \\ +\PSTComOpt \psccurve`{arrows}'\c1`\ldots\c n' +&Draw a closed curve between the points \\ +\PSTCom \pscharclip`*[settings]'{text} ... \Main \endpscharclip +&Set the clipping path to the character shapes\\ +\PSTCom \pscharpath`*[settings]'{text} +&The \emph{text} obeys the \PST\ \textbf{linestyle} and +\textbf{fillstyle} commands; +this is only effective if the font used is a \PS\ Type1 font\\ +\PSTComOpt \pscircle`(\x0,\y0)'{radius} +& Draw a circle with the center at \c0 \\ +\PSTComOpt \pscirclebox{text} +&Draw a circle around the text \\ +\PSTCom \pscoil`*[settings]{arrows}\c0'\c1 +&Draw a 3D coil from \c0 to \c1 \\ +\PSTCom \psCoil`*[settings]'{angle1}{angle2} +&Draw a coil horizontally from \emph{angle1} to \emph{angle2}\\ +\PSTComOpt \pscurve`{arrows}'(\x1,\y1)`\ldots(\x n,\y n)' +&Draw an open curve through the points \\ +\PSTComOpt \psdblframebox{text} +&Draw a double box around the text \\ +\PSTComOpt \psdiabox{text} +&Draw a diamond around the text\\ +\PSTCom \psdiamond`(\x0,\y0)'(\x1,\y1) +&Draw diamond centred at \c0 with the half width \x1 and height \y1 \\ +\PSTCom \psdots`*[settings]'(\x1,\y1)`(\x2,\y2)\ldots(\x n,\y n)' +&Draw dot at each coordinate \\ +\PSTComOpt \psecurve`{arrows}'(\x1,\y1)`\ldots(\x n, \y n)' +&Draw an open curve, but omitting the last and first points \\ +\PSTComOpt \psellipse`(\x0,\y0)'(\x1,\y1) +&Draw an ellipse with centre at \c0, and horizontal and vertical radii of +\x1 and \y1 \\ +\PSTComOpt \psframe`(\x0,\y0)'(\x1,\y1) +& Draw a rectangular frame with corners at \c0 and \c1\\ +\PSTComOpt \psframebox{text} +&Draw a box around the text \\ +\PSTCom \psgrid`(\x0,\y0)(\x1,\y1)(\x2,\y2)' +&Superimpose a grid with corners at \c1 and \c2, labelled on the axes +starting from \c0 \\[6pt] +\PSTComOpt \psline`{arrows}(\x0,\y0)'(\x1,\y1)`\ldots(\x n,\y n)' +& Draw a line through a series of coordinates\\ +\PSTComOpt \psovalbox{text} +&Draw an oval around the text\\ +\PSTComOpt \pspolygon`(\x0,\y0)'(\x1,\y1)(\x2,\y2)`\ldots(\x n,\y n)' +& Draw a line through the coordinates, and then close the path to make +an object that can be filled\\ +\PSTComOpt \psshadowbox{text} +&Draw a box around the text, with a shadow\\ +\PSTCom \pstextpath`[pos]\cAny'{graphics object}{text} +&The \emph{text} is drawn along the line defined by the +\emph{graphics object}. \emph{pos} determines how the text relates to the +path; by default (l), it starts at the beginning of the path; +\texttt{c} will center the text along the path and \texttt{r} will +make it finish at the end of the path. \c{} provides an offset for the +text in relation to the path. By default it is offset above the line +by .7ex. \emph{This macro, and} +\verb|\pscharclip|, \emph{are not guaranteed to work with +every dvi to \PS\ driver!}\\ +\PSTCom \pstriangle`(\x0,\y0)'(\x1,\y1) +&Draw isoceles triangle with base +centred at \c0, width \x1, and height \y1 \\ +\PSTComOpt \pstribox{text} +&Draw a triangle around the text \\ +\PSTComOpt \pswedge`(\x0,\y0)'{radius}{angle1}{angle2} +&Draw a wedge segment between \emph{angle1} and \emph{angle2} +(counter-clockwise) \\ +\PSTCom \pszigzag`*[settings]{arrows}\c0'\c1 +&Draw a zigzag from \c0 to \c1 \\ +\hline +\end{longtable} + +\end{small} + + +\begin{table*} +\begin{minipage}[b]{.5\textwidth}\centering +\def\myline#1{\psline{#1}(0,1ex)(1.3,1ex)}% + \catcode`\<=12 + \begin{tabular}[b]{cll}% + {\em Value} & \hbox to 1.3cm{\em Example\hss} & \\ \hline + "-" & \myline{-} & None\\ + "<->" & \myline{<->} & Arrowheads.\\ + ">-<" & \myline{>-<} & Reverse arrowheads.\\ + "<<->>" & \myline{<<->>} & Double arrowheads.\\ + ">>-<<" & \myline{>>-<<} & Double reverse arrowheads.\\ + "|-|" & \myline{|-|} & T-bars, flush to endpoints.\\ + "|*-|*" & \myline{|*-|*} & T-bars, centered on endpoints.\\ + "[-]" & \myline{[-]} & Square brackets.\\ + "(-)" & \myline{(-)} & Rounded brackets.\\ + "o-o" & \myline{o-o} & Circles, centered on endpoints.\\ + "*-*" & \myline{*-*} & Disks, centered on endpoints.\\ + "oo-oo" & \myline{oo-oo} & Circles, flush to endpoints.\\ + "**-**" & \myline{**-**} & Disks, flush to endpoints.\\ + "c-c" & \myline{c-c} & Extended, rounded ends.\\ + "cc-cc" & \myline{cc-cc} & Flush round ends.\\ + "C-C" & \myline{C-C} & Extended, square ends.\\ + "|<->|" & \myline{|<->|} & T-bars and arrowheads.\\ + "|<*->|*" & \myline{|<*->|*} & T-bars and arrowheads, flush.\\ + \end{tabular} + \caption{\protect\PST\ line terminators} + \label{PSTarrows} +\end{minipage}% +\begin{minipage}[b]{.5\textwidth}\centering + \def\mydots#1{% + \psdots[dotstyle=#1](.1,1ex)(.55,1ex)(1,1ex)(1.45,1ex)(1.9,1ex)}% +\begin{tabular}[b]{ll} +\emph{Style}&\emph{Example\qquad\qquad}\\ +\hline + "*" & \mydots{*} \\ + "o" & \mydots{o} \\ + "+" & \mydots{+} \\ + "x" & \mydots{x} \\ + "|" & \mydots{|} \\ + "asterisk" & \mydots{asterisk} \\ + "oplus" & \mydots{oplus} \\ + "otimes" & \mydots{otimes} \\ + "triangle" & \mydots{triangle}\\ + "triangle*" & \mydots{triangle*}\\ + "square" & \mydots{square}\\ + "square*" & \mydots{square*}\\ + "diamond" & \mydots{diamond}\\ + "diamond*" & \mydots{diamond*}\\ + "pentagon" & \mydots{pentagon} \\ + "pentagon*" & \mydots{pentagon*}\\ +\mbox{}\\ +\mbox{} + \end{tabular}% + \caption{\protect\PST\ dot styles} + \label{dotstyles} +\end{minipage} +\end{table*} + +\section{Examples of basic graphic objects} +The following examples demonstrate some of the \PST\ building blocks, +and the use of the graphics parameters. We must remember that all +these simple objects take up no space; the surrounding +\texttt{pspicture} defines the space \TeX\ is to leave, but within +that, we are drawing entirely by coordinates. +\begin{GridPSExample}(0,0)(2,1) + \psline(2,1) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(2,1) + \psline[linestyle=dashed](2,1) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(2,1) + \psline[linewidth=0.6mm,doubleline=true, + doublesep=0.5mm]{->}(2,1) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(4,2) + \psline[linearc=0.25,showpoints=true]{->}% + (1,0)(4,0.3)(2,2)(0,0.5) + \psline[linestyle=dotted,linecolor=blue, + arrowlength=3]{<->}(0,1)(3,0)(4,2) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(4,2) + \psframe[fillstyle=solid,fillcolor=pink] + (1,0)(4,1) + \psframe[fillstyle=solid,fillcolor=white, + framearc=0.5](3,0.2)(3.8,0.8) + \pspolygon[linewidth=0.7mm,dimen=inner] + (0,1)(2,2)(3,1)(2,0) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(4,2) + \psdiamond(1.5,1.5)(1.5,0.5) + \pstriangle[fillstyle=solid, + fillcolor=yellow](2,0)(3,1) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(3,2) + \pscircle[linewidth=1mm,linecolor=green] + (1,1){1} + \pscircle[linestyle=none,fillstyle=solid, + fillcolor=lightblue](1,1){0.5} + \pscircle[fillstyle=crosshatch](2.5,1.5) + {0.5} +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(4,2) + \psellipse[linecolor=green, + fillstyle=vlines,hatchangle=0, + hatchcolor=red](1,1)(1,0.5) + \pswedge[fillstyle=solid, + fillcolor=lightgray] + (2.5,1){1}{0}{120} +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(3,2) + \psdots[linecolor=blue,dotstyle=triangle, + dotscale=2](0,0.5)(1,2)(2.8,1.5) + \pscurve[linecolor=cyan,showpoints=true] + {->}% + (0,1.2)(1.3,1.8)(3,0.4)(0.5,0.2) + \psarc(2,1.5){1}{180}{320} + \parabola[linecolor=red]{<->}% + (0.3,0.3)(1.5,1.5) +\end{GridPSExample} + +\begin{GridPSExample}(0,0)(4,2) + \psbezier[linewidth=0.8mm,linecolor=red, + showpoints=true]{|->}% + (1,0)(4,1)(2,2)(0,0) +\end{GridPSExample} + +\section{Mixing text and graphics} +When we come to consider text, the situation is rather +different; now the size of objects is determined by the size of the +enclosed text. Here \TeX\ \emph{is} aware of the space used, so +successive objects are placed as if they were letters, and coordinates +are not used. +\begin{example**} +\psframebox{The Buck Stops Here} +\end{example**} + +\begin{example**} + \psframebox[fillstyle=solid, + fillcolor=black] + {\bfseries\color{white}\LARGE + Beware of The Dog} +\end{example**} + +\begin{example**} + \psframebox{The dragon} + \psframebox + {\psframebox[linecolor=green]{ate} + \psframebox[linecolor=blue] + {\psframebox[linecolor=red]{the women} + and + \psframebox[linecolor=red]{children}}} +\end{example**} + + +\begin{example**} + \psshadowbox[fillstyle=solid, + fillcolor=yellow] + {\color{red}\begin{tabular}{c} + Chapter 1\\We go to sea + \end{tabular}} +\end{example**} + +\begin{example**} + \pscirclebox[doubleline=true] + {\bfseries STOP!} +\end{example**} + + +\begin{example**} + \psdblframebox[linecolor=green] + {\color{red}All Hail Caesar!} +\end{example**} + +\begin{example**} + \psdiabox{\sffamily No Parking} +\end{example**} + +\begin{example**} + \pstribox[shadow=true,fillstyle=gradient, + gradbegin=green,gradend=red] + {\color{white}\Large$\Omega$ } +\end{example**} + + +\begin{example**} + \psovalbox[linecolor=red] + {\color{blue}Today's Menu} +\end{example**} + +\PS\ aficionados will be aware that text in \PS\ is treated just like +any other graphical object (this was one of the great revolutions +introduced by the language), and can be manipulated. The following +examples demonstrate the \Lcs{pstextpath} macro, which has two +parameters: a graphic object, and some text. The text is made to fit +the graphical object; only simple text is allowed, but that includes +maths. + +\begin{PSExample}(-4,-3)(3,0) + \psset{linecolor=lightgray} + \pstextpath + {\pscurve(-4,-2)(-2,0)(0,-3)(2,-1)(3,-3)} + {\color{blue} If you + want to type $2=\int_0^\pi \sin\theta\, + \mathrm{d}\theta$ and let it follow + along a curving line \ldots} +\end{PSExample} + + +It is also possible to set text as if it were a graphic, with the +fill, colour and line properties. This is done with the +\Lcs{pstextpath} macro; it has limitations (for instance, it cannot be mixed +with \Lcs{pstextpath}), but it is still a useful tool for special occasions: +\begingroup\fontfamily{ptm} +\begin{GridPSExample}(0,-.2)(2.5,1.8) + \pscharpath[fillstyle=solid, + fillcolor=lightblue, + linewidth=.4pt] + {\fontsize{72}{72}\selectfont \LaTeX} +\end{GridPSExample} +\endgroup +Admirers of the distinctive style of Dorling Kindersley publications +may like to try the following effect: + +\begin{example**} +\begin{pspicture}(-4,-3)(4,1) +\psset{fillstyle=solid,shadow=true,shadowangle=0} +\DeclareFixedFont{\babyfont}{T1}{ptm}{m}{n}{2cm} +\DeclareFixedFont{\wordfont}{T1}{ptm}{m}{n}{1.5cm} +\def\Cc#1#2{\pscharpath[fillcolor=#1]{#2}} +\bfseries +\rput(0,0){\babyfont +\Cc{red}B\Cc{green}A\Cc{yellow}B% +\Cc{red}{Y'}\Cc{blue}S} +\rput(0,-2){{\wordfont\Cc{blue}{WORLD}}} +\end{pspicture} +\end{example**} + + +The third of these tools which treat text like a graphic is +\Lcs{pscharclip}; this takes a parameter of some text, and its effect +is terminated by \Lcs{endpscharclip}. Any objects drawn inside this +group are clipped to the shape of the letters. + +%%% Bounding box corrected by hand to +%%%%%BoundingBox: 145 635 380 667 +%%% dvips -E came up with which leaves far too much space +%%%%%BoundingBox: 119 351 380 667 +\begin{Example**} +\newcounter{myN} + +\DeclareFixedFont{\bigsf}{T1}{phv}{b}{n}{1.3cm} +\DeclareFixedFont{\tinyrm}{T1}{ptm}{m}{n}{2mm} +\setcounter{myN}{110} +\begin{pspicture}(0,0)(8.2,1) +\pscharclip[linecolor=yellow,fillstyle=solid, + fillcolor=red] + {\rput[bl](0,0){\bigsf CHOCOLATE}} +\rput[t]{90}(0,0) + {\vbox + {\hsize=2cm \offinterlineskip + \tinyrm\color{black} + \loop + \addtocounter{myN}{-1} + \ifnum\value{myN}>0 + nuts and raisins + \repeat}} +\endpscharclip +\end{pspicture} +\end{Example**} + +\section{Working with a third dimension} +Later versions of \PST\ offer some experimental facilities for viewing +objects in three dimensions. Two-dimensional objects can be projected +in a 3D coordinate system, and arbitrary viewpoints established. At +the present time, \PST\ does not support true 3D solid objects, +perspective projection, hidden-line removal, or lighting of objects, +so the usefulness of this part of the package is limited. However, +with some patience, pleasing effects can be obtained (well +demonstrated, as usual, by \cite{Girou:1994}). Table~\ref{PST3d} +lists the new commands, and Table~\ref{PSTparms3d} describes the +extra graphics parameters which apply to them. + +\begin{table*} +\begin{tabular}{lP{.5\textwidth}} +\hline +\PSTComOpt \psshadow{text} +&Draw a shadow on the text\\ +\PSTComOpt \pstilt{degrees}{text} +&Place \texttt{text} tilted\\ +\PSTCom \ThreeDPut`(\x0,\y0,\z0)'{object} +&Place \emph{object} at coordinate \x0,\y0,\z0, displayed according to +the current viewpoint\\ +\hline +\end{tabular} +\caption{\protect\PST\ 3D commands}\label{PST3d} +\end{table*} + +\begin{table*} +\begin{tabular}{llP{.5\textwidth}} +\emph{Parameter} & \emph{Default} & \emph{Explanation}\\ +\hline +\Par{Tshadowsize=size} (1)&Length of shadow\\ +\Par{Tshadowcolor=colour} (lightgray)&Colour of shadow\\ +\Par{Tshadowangle=angle} (60)&Angle of shadow\\ +\Par{viewpoint=x y z} (1 -1 1) &position of the observer looking + at the object origin \\ +\Par{normal=x y z} (0 0 1) & +A vector orthogonal to the plane of the 2D object, +which specifies its position in 3D space\\ +\Par{embedangle=angle} (0) & +The rotation around the axis through the reference point of the object +in the direction of the positioning vector\\ +\hline +\end{tabular} +\caption{\protect\PST\ 3D graphical parameters}\label{PSTparms3d} +\end{table*} + +There are two high-level `3D' commands, and one general tool. The +high-level commands are \Lcs{psshadow}, which attaches a shadow to +some text, and \Lcs{pstilt}, which angles an object into the third +dimension. +\begin{example**} + \psshadow[Tshadowangle=45, + Tshadowsize=2.5]{% + \LARGE\bfseries Words with a shadow} +\end{example**} + +\begin{PSExample}(0,-3)(3,1.5) +\rput(0,1){\pstilt{45}{I Feel Ill!}} +\rput(0,0){\pstilt{-75}{\psgrid(2,2)}} +\end{PSExample} + +\begin{figure*}[!t]\centering +\def\CurrentPackages{pstcol} +\begin{Escape} +\makeatletter +\def\DieFrame{\@ifnextchar[{\DDieFrame}{\DDieFrame[darkgray]}} +\def\DDieFrame[#1]{\psframe[linecolor=black,fillcolor=#1,fillstyle=solid](4,4)} +\makeatother +\def\SpotColor{white} +\def\DieOne{\DieFrame[lightgray] +\pscircle*[linecolor=\SpotColor](2,2){.3} +} +\def\DieTwo{\DieFrame[lightgray] +\pscircle*[linecolor=\SpotColor](1,2){.3} +\pscircle*[linecolor=\SpotColor](3,2){.3} +} +\def\DieThree{\DieFrame[lightgray] +\pscircle*[linecolor=\SpotColor](1,1){.3} +\pscircle*[linecolor=\SpotColor](2,2){.3} +\pscircle*[linecolor=\SpotColor](3,3){.3} +} +\def\DieFour{\DieFrame +\pscircle*[linecolor=\SpotColor](1,1){.3} +\pscircle*[linecolor=\SpotColor](3,3){.3} +\pscircle*[linecolor=\SpotColor](1,3){.3} +\pscircle*[linecolor=\SpotColor](3,1){.3} +} +\def\DieFive{\DieFrame +\pscircle*[linecolor=\SpotColor](1,1){.3} +\pscircle*[linecolor=\SpotColor](3,3){.3} +\pscircle*[linecolor=\SpotColor](1,3){.3} +\pscircle*[linecolor=\SpotColor](3,1){.3} +\pscircle*[linecolor=\SpotColor](2,2){.3} +} +\def\DieSix{\DieFrame +\pscircle*[linecolor=\SpotColor](1,1){.3} +\pscircle*[linecolor=\SpotColor](1,2){.3} +\pscircle*[linecolor=\SpotColor](1,3){.3} +\pscircle*[linecolor=\SpotColor](3,1){.3} +\pscircle*[linecolor=\SpotColor](3,2){.3} +\pscircle*[linecolor=\SpotColor](3,3){.3} +} +\def\DieSide#1#2#3{\ThreeDput[normal=#1](#2){#3}} +\def\TheDie#1#2(#3)(#4){% +\begin{pspicture}(#3)(#4) +\ifcase #1 \relax +\or %1 + \psset{viewpoint=-1 -1 #2} + \DieSide{-1 0 0}{0,4,0}{\DieThree} + \DieSide{0 -1 0}{0,0,0}{\DieFive} +\or %2 + \psset{viewpoint=1 -1 #2} + \DieSide{0 -1 0}{0,0,0}{\DieFive} + \DieSide{1 0 0}{4,0,0}{\DieFour} +\or %3 + \psset{viewpoint=1 1 #2} + \DieSide{1 0 0}{4,0,0}{\DieFour} + \DieSide{0 1 0}{4,4,0}{\DieTwo} +\or %4 + \psset{viewpoint=-1 1 #2} + \DieSide{0 1 0}{4,4,0}{\DieTwo} + \DieSide{-1 0 0}{0,4,0}{\DieThree} +\fi +\ifnum#2<0 + \DieSide{0 0 -1}{0,4,0}{\DieSix} +\else + \DieSide{0 0 1}{0,0,4}{\DieOne} +\fi +\end{pspicture}} +\psset{unit=.35cm} +\framebox{% +\begin{tabular}{cccc} +\TheDie{1}{1}(-5,-2.5)(5,7.5)& +\TheDie{2}{1}(-2.5,-3.5)(7.5,6.5)& +\TheDie{3}{1}(-5,-5)(5,5)& +\TheDie{4}{1}(-7.5,-4)(2.5,6)\\ +\TheDie{1}{-1}(-5,-5)(5,5)& +\TheDie{2}{-1}(-2.5,-3.5)(7.5,6.5)& +\TheDie{3}{-1}(-5,-2.5)(5,7.5)& +\TheDie{4}{-1}(-7.5,-4)(2.5,6) +\end{tabular} +} +\end{Escape} +\caption{Different views of a dice cube}\label{PSTdice} +\end{figure*} + +The general macro is \Lcs{ThreeDPut}, which places any \PST\ object at +a point in 3D space. This will almost always set the \texttt{normal} +graphics parameter, which sets the vector which will be orthogonal to +the plane of the object. To take a simple example, suppose we want to +draw a house, with a reference origin at the left-hand end of the +front wall; the left side wall would be drawn as follows: +\begin{PSExample}(-3.5,-1.2)(4,2.5) + \psset{unit=.5cm} + \psset{viewpoint=-1 -1 1} + \ThreeDput[normal=0 0 1]{\psgrid(-3,-3)(6,6)} + \ThreeDput[normal=-1 0 0](0,4,0){ + \psframe*[linecolor=yellow](4,4)} +\end{PSExample} +The viewpoint is from `up, back and to the left'. When we draw a whole +cube, +it is important to realize that \PST\ does not check which side hides +which; the last side drawn will wipe out others drawn earlier, regardless +of the fact that it is `behind' them in 3D space. When drawing the +different views, we have to give the sides in different orders. +Fig.~\ref{PSTdice} shows this problem, since when we show the +`underneath' well, we have to be sure to draw all the six faces in the +right order for the viewpoint. The attempt to provide `lighting' on +the die is done simply by colouring three faces in a lighter +colour. To attempt formal ray-tracing from a light source would be +considerably beyond the scope of this package! + +Following another example by Denis Girou, we can use the +\Lcs{ThreeDPut} macro to generate the appearance of raised text: +% this one uses too much memory redefining colours +%%% Bounding box corrected by hand to +%%%%%%BoundingBox: 146 522 322 658 +\begin{Example*} +\begin{pspicture}(-3,0)(3,5.5) +\psset{unit=.5cm} +\font\bigfont=phvb8t at .8cm +\psset{viewpoint=-1 -1 1.5,normal=0 0 1} +\rput(0,0){\multido{\n=0+0.07}{12} + {\definecolor{AColor}{rgb}{1, \n, \n} + \ThreeDput(\n,\n,0){\pscircle[% + linestyle=none,fillstyle=solid, + fillcolor=AColor](5,5){6}}}} +\psset{linestyle=none} +\rput(0,0){\multido{\n=0+0.07}{12} + {\definecolor{AColor}{rgb}{1, \n, \n} + \ThreeDput(\n,\n,0){\bigfont + \pstextpath[c]{% + \psarcn(5.5,5.5){4}{180}{0}}{% + \color{AColor}Happy Christmas} + \pstextpath[c]{% + \psarc(5.5,5.5){4}{180}{0}}{% + \color{AColor}\TeX\ Lovers}}}} +\end{pspicture} +\end{Example*} + + +\DeleteShortVerb{\"} + +\begin{thebibliography}{99} +\bibitem[\protect\citename{Girou }1994]{Girou:1994} +{Girou, D.} 1994. +\newblock {Pr\'esentation de PSTricks}. {\em Cahiers GUTenberg}, {\bfseries + 16}, 21--70. + +\bibitem[\protect\citename{{van Zandt} }1993]{Zandt:1993a} +{{van Zandt}, T.} 1993. +\newblock PSTricks User's Guide. +\newblock Unpublished documentation with the software, version 0.93a. + +\bibitem[\protect\citename{{van Zandt} \& Girou }1994]{Zandt-Girou:1994} +{{van Zandt}, T. \& Girou, D} 1994. +\newblock Inside PSTricks. {\em TUGboat}, {\bfseries 15 (3)} September, + 239--246. +\end{thebibliography} +\end{Article} + |