path: root/Master/texmf-dist/doc/generic/pst-geometrictools/pst-geometrictools-doc.tex

%%
%% This is file `pst-geometrictools-doc.tex',
%%
%% IMPORTANT NOTICE:
%%
%% Package `pst-geometrictools.tex'
%%
%% Thomas Söll
%%
%% This program can redistributed and/or modified under %%
%% the terms of the LaTeX Project Public License              %%
%% Distributed from CTAN archives in directory                %%
%% macros/latex/base/lppl.txt; either version 1.3c of       %%
%% the License, or (at your option) any later version.       %%
%%
%% DESCRIPTION:
%%   `pst-geometrictools' is a PSTricks package to draw a protractor, a ruler, a compass and pencils 
%%
%%


\listfiles

\documentclass[%
11pt,
english,
BCOR10mm,
DIV12,
bibliography=totoc,
parskip=false,
fleqn,
smallheadings,
headexclude,
footexclude,
oneside,
dvipsnames,
svgnames,
x11names,
distiller
]{pst-doc}

\usepackage[autostyle]{csquotes}
\usepackage{biblatex}
%\usepackage[style=dtk]{biblatex}
\addbibresource{pst-geometrictools-doc.bib}
\usepackage[utf8]{inputenc}
\let\pstpersFV\fileversion
\usepackage{pst-geometrictools,pst-node,pst-eucl,pst-pers,pstricks-add,animate}
\usepackage{etex} % increase the number of registers  (otherwise only 256)

\let\belowcaptionskip\abovecaptionskip

\parindent0pt

\psset{arrowlength=2.8,arrowinset=0.1}

\def\bgImage{%
\begin{pspicture}(-7,-3)(7,7)%
\psProtractor[ProScale=0.75]{-5}(-2,2)%
\psRuler[RulerFillCol=Blue!80,RulerScale=0.75]{190}(1,5)
\psPencil[pencilColA=Green,PenScale=0.75]{10}(-2,2)
\psPencil[PenLength=2,pencilColA=red,PenScale=0.75]{-20}(1,5)
\psCompass[PoCScale=1.25,PoCFillCol=Yellow,PoCAngle=0,PoCMineCol=Green]{5}(3.5,-3.5)(7.5,-3.5)
\end{pspicture}
}

\lstset{language=PSTricks,morekeywords={psdot,psIntersectionPoint,psProtractor,psCompass,psPencil,psRuler,psParallels,psGetAngleABC,pstGeonode,midAB,pstRightAngle,perspective,multiframe,psline}\footnotesize\ttfamily}

\newpsstyle{Parallelen}{country=G,ProScale=0.5,ProLineCol=cyan,ProFillCol=gray!50,OwnerTxt=Pythagoras,MadeTxt={Geodreieck},RulerFillCol=cyan!40}


\begin{document}

\title{pst-geometrictools v 1.1}
\subtitle{A PSTricks package to draw a protractor, a ruler, a compass and pencils}
\author{Thomas \textsc{Söll}}
\date{\today}

\maketitle

\tableofcontents
\psset{unit=1cm}


\clearpage


\begin{abstract}
The package \LPack{pst-geometrictools} offers some customizable options to setup a \emph{protractor}, a \emph{ruler}, a \emph{compass} and \emph{pencils} to the users'  wishes. Some geometric tools are predefined
 and ready-to-use for the customer to be able to present some pixel-free graphics showing the handling of some geometric tools.

The geometric tools can be scaled, rotated, positioned, colored as wanted, even labeled---if wanted.

These tools were already available since years within diverse examples---however not yet packaged together in pure PostScript. This was done within this package.

We recommend to use the package \LPack{pst-eucl} (by \textit{Dominique Rodriguez}) which makes it easy to position the tools precisely.

Have fun to use it!

\vfill
This program can redistributed and/or modified under the terms of the LaTeX Project Public License Distributed from CTAN archives in directory macros/latex/base/lppl.txt; 
either version 1.3c of the License, or (at your option) any later version.
\end{abstract}


\clearpage


\section{How to use the commands}

\subsection{\textbackslash psProtractor}

\begin{BDef}
\Lcs{psProtractor}\OptArgs\Largb{angle}\Largr{coordinates of the origin}
\\
\Lcs{psProtractor}\OptArgs\Largb{angle}\Largr{coordinates of the origin}\Largr{coordinates of a second point}
\end{BDef}

The command \Lcs{psProtractor} contains the options \nxLkeyword{ProScale=}, \nxLkeyword{ProLineCol=}, \nxLkeyword{ProFillCol=}, \nxLkeyword{OwnerTxt=}, 
\nxLkeyword{MadeTxt=}, \nxLkeyword{PSfontO=}, \nxLkeyword{fontsizeO=}, \nxLkeyword{PSfontM=}, \nxLkeyword{fontsizeM=}, \nxLkeyword{country=} and \nxLkeyword{Ghost=}.

\begin{quote}
\begin{tabularx}{\linewidth}{ @{} l >{\ttfamily}l X @{} }\toprule
\emph{Name}           & \emph{Default} & \emph{Meaning} \\\midrule
\Lkeyword{ProScale}     & 1          & scale factor\\
\Lkeyword{ProFillCol}     & gray!60          & transparent fill color of the protrace\\
\Lkeyword{ProLineCol}     & cyan          & linecolor of the protrace\\
\Lkeyword{OwnerTxt}    & T.S.             & Name of the owner\\
\Lkeyword{MadeTxt}  & Made in NES   & Made in wherever\\
\Lkeyword{PSfontO}  & Symbol   & PSfont for the owner\\
\Lkeyword{fontsizeO}  & 10pt   & fontsize for the owner\\
\Lkeyword{PSfontM}  &  Times-Roman  & PSfont for Made in wherever\\
\Lkeyword{fontsizeM}  & 6pt  &  fontsize for Made in wherever\\
\Lkeyword{country}  & Germany  & Permissible values: Germany, France\\
\Lkeyword{Ghost}  & false  & true: not showing the protrace itself, but getting the nodes of its verices\\
\bottomrule
\end{tabularx}
\end{quote}

This above introduced command \Lcs{psProtractor} automatically provides three nodes of the vertices of the protractor which are named as follows: \texttt{GeodrA}, \texttt{GeodrB}, \texttt{GeodrC}

These nodes maybe very helpful.

The command \Lcs{psProtractor} offers a positioning
\begin{itemize}
\item either by one point and an angle of rotation
\item or by two points (and an additional angle of rotation)
\end{itemize}


\subsection{\textbackslash psRuler}

\begin{BDef}
\Lcs{psRuler}\OptArgs\Largb{angle}\Largr{coordinates of origin}
\\
\Lcs{psRuler}\OptArgs\Largb{angle}\Largr{coordinates of origin}\Largr{coordinates of a second point}
\end{BDef}

The command \Lcs{psRuler} contains the options \nxLkeyword{RulerScale=} and \nxLkeyword{RulerFillCol=}.

\begin{quote}
\begin{tabularx}{\linewidth}{ @{} l >{\ttfamily}l X @{} }\toprule
\emph{Name}           & \emph{Default} & \emph{Meaning} \\\midrule
\Lkeyword{RulerScale}     & 1          & scale factor of the ruler\\
\Lkeyword{RulerFillCol}    & gray           & color of the ruler\\
\bottomrule
\end{tabularx}
\end{quote}

The command \Lcs{psRuler} offers a positioning

\begin{itemize}
\item either by one point and an angle of rotation
\item or by two points (and an additional angle of rotation)
\end{itemize}


\newpage


\subsection{\textbackslash psCompass}

\begin{BDef}
\Lcs{psCompass}\OptArgs\Largb{radius}\Largr{coordinates of  origin}
\\
\Lcs{psCompass}\OptArgs\Largb{radius}\Largr{coordinates of origin}\Largr{coordinates of a second point}
\end{BDef}

The command \Lcs{psCompass} contains the options \nxLkeyword{PoCAngle=}, \nxLkeyword{MCAngle=}, \nxLkeyword{PoCLength}, 
\nxLkeyword{PoCFillCol=}, \nxLkeyword{PoCMineCol=}, \nxLkeyword{RadVS=}, \nxLkeyword{AngleVS=}, \nxLkeyword{RadMul=} and \nxLkeyword{PoCScale=}.

\begin{quote}
\begin{tabularx}{\linewidth}{ @{} l >{\ttfamily}l X @{} }\toprule
\emph{Name}           & \emph{Default} & \emph{Meaning} \\\midrule
\Lkeyword{PoCAngle}     & 0          & angle of rotation\\
\Lkeyword{PoCLength}     & 5          & length of the compass\\
\Lkeyword{PoCFillCol}    & gray!60           & color of the compass\\
\Lkeyword{PoCMineCol}  & gray!60   & color of the mine\\
\Lkeyword{PoCScale}  & 1   & scaling factor \\
\Lkeyword{MCAngle} & false & suppresses the initial angle, when two points are given\\
\Lkeyword{RadVS} & RVS & PostScript value for the radius\\
\Lkeyword{AngleVS} & AVS & PostScript value for the angle\\
\Lkeyword{RadMul} & 1 & multiplication factor for the radius\\
\bottomrule
\end{tabularx}
\end{quote}

The command \Lcs{psCompass} offers a positioning
\begin{itemize}
\item either by one point and the radius---a rotation is set with \texttt{[PoCAngle=30]}.
\item or by two points (the radius and initial angle then are calculated automatically)---if one sets an additional rotation with \texttt{[PoCAngle=30]}, 
these two angles are automatically added. If one will suppress the initial rotation, then set \texttt{[MCAngle=false]}. 
Using \texttt{RadVS=<unique name>} and \texttt{AngleVS=<unique name>} you can use the values of the radius respectively the angle within some PostScript calculations. 
When you like to use a radius other than the distance between the two points that automatically calculates the radius, use \texttt{RadMul=<decimal number>} to multiply the initial radius with this factor.
\end{itemize}


\subsection{\textbackslash psPencil}

\begin{BDef}
\Lcs{psPencil}\OptArgs\Largb{angle}\Largr{coordinates of the cone end}
\end{BDef}

The command \Lcs{psPencil} contains the options \nxLkeyword{PenScale=}, \nxLkeyword{PenLength=}, \nxLkeyword{pencilColA=} and \nxLkeyword{pencilColB=}.

\begin{quote}
\begin{tabularx}{\linewidth}{ @{} l >{\ttfamily}l X @{} }\toprule
\emph{Name}           & \emph{Default} & \emph{Meaning} \\\midrule
\Lkeyword{PenScale}     & 1          & scale factor\\
\Lkeyword{PenLength}    & 5           & length of the pencil\\
\Lkeyword{pencilColA}  & red   & color of the pencil\\
\Lkeyword{pencilColB}  & HolzCol   & color of the wooden cone end \\
\bottomrule
\end{tabularx}
\end{quote}


\newpage


\subsection{\textbackslash psParallels (Idea and realization by \emph{Manuel Luque})}

\begin{BDef}
\Lcs{psParallels}\OptArgs\Largr{pointA}\Largr{pointB}\Largr{pointC}\Largb{angle}
\end{BDef}

The command \Lcs{psParallels} contains the option \nxLkeyword{DistCoeff=}.

\begin{quote}
\begin{tabularx}{\linewidth}{ @{} l >{\ttfamily}l X @{} }\toprule
\emph{Name}           & \emph{Default} & \emph{Meaning} \\\midrule
\Lkeyword{DistCoeff}     & 1          & relative disctance between (AB) and C\\
\bottomrule
\end{tabularx}
\end{quote}

This command is made to directly draw a line parallel to the line containing \texttt{pointA} and \texttt{pointB} intersecting at point \texttt{pointC}.

\begin{LTXexample}[pos=t,width=17cm]
\begin{pspicture}(-11,-10)(6,2.5)
\psParallels[DistCoeff=1](-6,-1)(1,2)(2,0)
\end{pspicture}
\end{LTXexample}

The command \verb+\psParallels[DistCoeff=1](A)(B)(C){angle}+ allows to draw a parallel through the point C with the help of a ruler and protractor. The angle is the one between the pencil and the vertical. 
The command uses the option [DistCoef=] as within pst-eucl. If [DistCoef=0] the hypotenuse of the protractor lays on the line (AB), the ruler automatically positions below the protractor.

For an animation, we vary [DistCoef=0..1], the protractor moves along the ruler letting the hypotenuse parallel to the line (AB). If [DistCoef=1], the protractor intersects with the point C. We can now draw the parallel to (AB) intersecting C.


\newpage


\section{Basic Examples}

\begin{LTXexample}[pos=t,width=16cm]
\begin{pspicture}*(-6,-5.5)(10,7)
\psProtractor{0}(0,0)% origin of the protractor
\psRuler{0}(0,0)% origin of the ruler
\psPencil{-30}(6,0)% origin of the pencil
\psCompass{3}(2,0)% origin of the compass
\end{pspicture}
\end{LTXexample}

We see, that the origins of the \emph{protractor} and \emph{ruler}, \emph{compass} and respectively the \emph{cone end of the pencil} are positioned at $(0|0)$, $(2|0)$, $(6|0)$. Adding an angle rotates the objects around their origins.

For the \emph{protractor} and \emph{ruler}, there are two ways to position them:

\begin{itemize}
\item one point and an angle, like:

\Lcs{psProtractor}\OptArgs\Largb{<angle>}\Largr{<point>}\\
\Lcs{psRuler}\OptArgs\Largb{<angle>}\Largr{<point>}

This is quite self-explanatory. The origin is positioned  at the point and the tool is rotated around this point by the chosen angle.
\item two points and an additional angle, like:

\Lcs{psProtractor}\OptArgs\Largb{<additional angle>}\Largr{<pointA>}\Largr{<pointB>}\\
\Lcs{psRuler}\OptArgs\Largb{<additional angle>}\Largr{<pointA>}\Largr{<pointB>}

The origin of the tool is set to pointA. The hypotenuse of the protractor is aligned to the line between pointA and pointB, when the additional angle is chosen to $0$.
\end{itemize}


\newpage


\begin{LTXexample}[pos=t,width=16cm]
\begin{pspicture}(-8,-6.5)(8,2)
\pnode(-2,-1){A}\psdot[linecolor=Green,dotsize=5pt](A)\uput[90](A){A}
\pnode(5,-2){B}\psdot[linecolor=Green,dotsize=5pt](B)\uput[180](B){B}
\psProtractor[ProScale=0.5]{30}(A)
\psProtractor[ProLineCol=Yellow,ProScale=0.5]{90}(B)
\end{pspicture}
\end{LTXexample}

\begin{LTXexample}[pos=t,width=13cm]
\begin{pspicture}(-8,-6.5)(5,2)
\pnode(-2,-2){A}\psdot[linecolor=Green,dotsize=5pt](A)\uput[45](A){A}
\pnode(5,-4){B}\psdot[linecolor=Green,dotsize=5pt](B)\uput[45](B){B}
\pcline[linecolor=Green](A)(B)
\psProtractor[ProScale=0.5]{0}(A)(B)
\psProtractor[ProLineCol=Yellow,ProScale=0.5]{190}(A)(B)
\end{pspicture}
\end{LTXexample}


\newpage


The predefined nodes of a protractor.

\begin{LTXexample}[pos=t,width=13cm]
\begin{pspicture}(-8,-6.5)(5,0.3)
\psProtractor[ProScale=0.75]{0}(0,0)
\psdot[linecolor=Green,dotsize=7pt](GeodrA)\uput[45](GeodrA){GeodrA}
\psdot[linecolor=Blue,dotsize=7pt](GeodrB)\uput[135](GeodrB){GeodrB}
\psdot[linecolor=BrickRed,dotsize=7pt](GeodrC)\uput[-90](GeodrC){GeodrC}
\end{pspicture}
\end{LTXexample}

Compass

\begin{LTXexample}[pos=t,width=12cm]
\begin{pspicture}(-6,-2)(6,6)%
\pnode(-1,0){A}\psdot[dotsize=3pt,linecolor=red](A)
\pnode(1,0){B}\psdot[dotsize=3pt,linecolor=Green](B)
\pscircle(A){2}
\pcline[linecolor=BrickRed,nodesepA=-9,nodesepB=-6](A)(B)
\psCompass[PoCAngle=70,PoCScale=0.8]{2}(A)
\pnode(2,0){A}\psdot[dotsize=3pt,linecolor=red](A)
\pnode(6,0){B}\psdot[dotsize=3pt,linecolor=Green](B)
\psCompass[PoCScale=1,PoCFillCol=Yellow,PoCAngle=0,PoCMineCol=Green]{5}(A)(B)
\end{pspicture}
\end{LTXexample}


\newpage


\section{Advanced examples}

Measuring the angles of a given triangle.

\begin{LTXexample}[pos=t,width=17cm]
\newpsstyle{WkMessung}{linestyle=none,AngleValue=true,ArcColor=Green,arrows=->,WedgeOpacity=0.6,WedgeColor=Green!30,LabelSep=1.6,MarkAngleRadius=2.8,linecolor=Green,decimals=1,comma,xShift=-6,yShift=9}
\newpsstyle{GeoDrG}{country=G,ProScale=1,ProLineCol=Green,ProFillCol=Green!50,OwnerTxt={Pythagoras},MadeTxt={Geodreieck}}
\begin{pspicture}(0,-1)(17,10)
\pnode(8,0){S}\uput[d](S){S}\psdot(S)
\pnode(17,0){B}
\rput(S){\pnode(7;35){C}}
\pcline[linecolor=blue,nodesepB=-0](S)(B)
\pcline[linecolor=red,nodesepB=-2](S)(C)
\psProtractor[style=GeoDrG]{0}(S)(B)
\psIntersectionPoint(S)(C)(GeodrB)(GeodrC){D}% pstricks-add
\pcline[linecolor=Green,arrowinset=0.1,arrowlength=2,linewidth=2pt]{->}([offset=1.5cm]D)(D)
\psGetAngleABC[style=WkMessung](B)(S)(C){\Large\color{Green}$\alpha$}% pst-eucl
\rput([offset=4.5]D){\psframebox[framesep=6pt,framearc=0.2]{
\begin{minipage}[t]{5.5cm}
Lege das Geodreieck auf den blauen Schenkel, so dass die  Null auf dem Scheitel S liegt. Lies nun am \"au\ss eren Rand den Winkel ab (gr\"uner Pfeil).
\end{minipage}
}}
\end{pspicture}
\end{LTXexample}

\begin{LTXexample}[pos=t,width=16cm]
\begin{pspicture}(-9,-6)(7,10)
\pnode(1,7){A}
\pnode(-5,0){B}
\pnode(5,-2){C}
\pspolygon[linecolor=red](A)(B)(C)
\psProtractor[ProScale=0.5]{0}(A)(B)
\psProtractor[ProScale=0.5]{0}(B)(C)
\psProtractor[ProScale=0.5]{0}(C)(A)
\end{pspicture}
\end{LTXexample}


\newpage


Constructing the height of a given triangle.

\begin{LTXexample}[pos=t,width=16cm]
\begin{pspicture}(-6,-4.5)(5,8)
\pnode(1,7){A}
\pnode(-5,1){B}
\pnode(3,2){C}
\uput[ur](A){A}
\uput[d](B){B}
\uput[d](C){C}
\pspolygon(A)(B)(C)
\pstProjection{B}{C}{A}[A']% pst-eucl
\psProtractor[ProScale=0.8,OwnerTxt={Height of a triangle},MadeTxt={Made in NES},PSfontO=Helvetica,PSfontM=Times-Roman,fontsizeO=8,fontsizeM=6]{0}(A')(A)
\pcline[linecolor=red,linestyle=dashed,linewidth=2pt](GeodrC)(A')
\pstRightAngle[RightAngleType=german]{C}{A'}{A}% pst-eucl
\end{pspicture}
\end{LTXexample}


\newpage


%Using the package \LPack{pst-pers} (by \emph{Manuel Luque} avec la collaboration de \emph{Thomas Söll} et \emph{Jürgen Gilg}), we have the full range to project objects into whatever planes we want.
%
%Here we present a little example, setting the protractor into the [$x,y$]-plane, whereas the compass is set into the [$y,z$]-plane.
%
%\begin{LTXexample}[pos=t,width=16cm]
%\begin{pspicture}(-8,-1.75)(9,7)
%\perspective[normal=0 90](0,0,0){% pst-pers
%\psarc[linecolor=green](0,0){2}{180}{0}
%\psProtractor{0}(0,0)(2,0)
%}
%\perspective[normal=0 0](0,0,0){% pst-pers
%\psCompass[PoCAngle=0,PoCScale=1,PoCMineCol=green]{2}(0,0)
%}
%\end{pspicture}
%\end{LTXexample}
%
%
%\newpage


%\section{Animations}
%
%\begin{LTXexample}[pos=t,width=17cm]
%\begin{animateinline}[% animate
%controls,
%palindrome,
%begin={\begin{pspicture}(-8,-1.75)(9,7)},
%end={\end{pspicture}}]{10}% 10 frames/s (velocity of the animation)
%\multiframe{73}{rB=0+2.5}{% number of frames
%\perspective[normal=0 90](0,0,0){% pst-pers
%    \psarc[linecolor=Green](0,0){2}{0}{\rB}
%    \psProtractor[ProLineCol=Yellow]{180}(0,0)(2,0)
%    }
%\perspective[normal=\rB\space 0](0,0,0){% pst-pers
%    \psCompass[PoCAngle=0,PoCScale=1,PoCMineCol=Green]{2}(0,0)
%    }
%}
%\end{animateinline}
%\end{LTXexample}
%
%
%\clearpage


\section{List of all optional arguments for \texttt{pst-geometrictools}}

\xkvview{family=pst-geometrictools,columns={key,type,default}}


\clearpage


\nocite{*}
\bgroup
\RaggedRight
\printbibliography
\egroup


\printindex
\end{document}