pst-3dplot 1.78 (23dec07)

git-svn-id: svn://tug.org/texlive/trunk@5827 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 120 insertions, 14 deletions

diff --git a/Master/texmf-dist/doc/generic/pst-3dplot/Changes b/Master/texmf-dist/doc/generic/pst-3dplot/Changes
index 43a46d7cf30..55fcfc45286 100644
--- a/Master/texmf-dist/doc/generic/pst-3dplot/Changes
+++ b/Master/texmf-dist/doc/generic/pst-3dplot/Changes
@@ -1,6 +1,7 @@
 pst-3dplot.pro --------
-0.24  2006-08-30 - add code for special node calculating
-0.23  2007-08-18 - add coorType 0,1,2 code for convertTo2D
+0.25  2007-12-22 - add code for special rotating (Darrell Lamm)
+0.24  2007-08-30 - add code for special node calculating
+0.23  2007-08-18 - add coorType 0,1,2,3 code for convertTo2D
 		 - add code IIIDCylinder and cylindrical coordinates
 		 - add code for \psBox and \psCylinder
 0.22  2006-01-11 add code for left-Handed coor (experimental)
@@ -10,6 +11,10 @@ pst-3dplot.pro --------
 
 
 pst-3dplot.tex --------
+1.78  2007-10-11  - fix bug in \parametricPlotThreeD
+		  - add option Debug=false|true for addtional
+		    comments written into the log file
+		  - add extended rotation stuff (Darrell Lamm)
 1.77  2007-10-03  - fix trailing spaces in \pstThreeDNode
 1.76  2007-08-30  - add optional argument nodeType for different setting
                     the node depending to a line and a plain
diff --git a/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.pdf b/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.pdf
index e391cc760c1..10560d50bad 100644
--- a/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.pdf
+++ b/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.pdf
diff --git a/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.tex b/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.tex
index dbc52557da2..d0113649230 100644
--- a/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.tex
+++ b/Master/texmf-dist/doc/generic/pst-3dplot/pst-3dplot-doc.tex
@@ -499,7 +499,7 @@
 
 %
 \begin{document}
-\author{Herbert Voß\thanks{voss@perce.de}}
+\author{Darrell Lamm\thanks{darrell.lamm@gtri.gatech.edu} \and Herbert Voß\thanks{hv@pstricks.de}}
 \date{\today}
 \title{3D plots: PST-3dplot v\myFV\\Documentation}
 
@@ -742,7 +742,13 @@ IIIDzticksep     & <value>  & 0.2\\
 RotX             & <angle>  & 0\\
 RotY             & <angle>  & 0\\
 RotZ             & <angle>  & 0\\
-RotSequence	 & xyz|xzy|yxz|yzx|zxy|zyx & xyz\\
+RotAngle         & <angle>  & 0\\
+xRotVec          & <angle>  & 0\\
+yRotVec          & <angle>  & 0\\
+zRotVec          & <angle>  & 0\\
+RotSequence	 & xyz|xzy|yxz|yzx|zxy|zyx|quaternion & xyz\\
+RotSet     	 & set|concat|keep & set\\
+eulerRotation    & true|false & false\\
 \end{longtable}
 }
 
@@ -917,7 +923,6 @@ The angle \texttt{Alpha} is only valid for placing the ticks, if any.  The angle
 \end{pspicture}
 \end{LTXexample}
 
-
 With \texttt{coorType=3} the y--z-axes are orthogonal and the angle between x- and y-axis
 is always 45 degrees and the x-axis is shortened by a factor of $1/\sqrt{2}$. 
 The angle \texttt{Alpha} is only valid for placing the ticks, if any.  The angle \texttt{Beta} is not valid.
@@ -931,7 +936,6 @@ The angle \texttt{Alpha} is only valid for placing the ticks, if any.  The angle
 \end{LTXexample}
 
 
-
 \clearpage
 \section{Rotation}
 
@@ -981,7 +985,87 @@ additional one for the rotating sequence, which can be any combination of the th
 \end{LTXexample}
 
 
+It is sometimes more convenient to rotate the coordinate system by 
+specifying a \emph{single} angle of rotation \verb+RotAngle+ (in degrees) 
+about a vector whose coordinates are \verb+xRotVec+, \verb+yRotVec+, 
+and \verb+zRotVec+ using the \verb+quaternion+ option for \verb+RotSequence+.
+
+\begin{LTXexample}[pos=t]
+\begin{pspicture}(-3,-1.8)(3,3)
+\multido{\iA=0+10}{18}{%
+ \pstThreeDCoor[linecolor=red, RotSequence=quaternion, RotAngle=\iA, xRotVec=3,yRotVec=0,zRotVec=3,
+  xMin=0,xMax=3, yMin=0,yMax=3,  zMin=0,zMax=3]}
+\pstThreeDCoor[linecolor=blue, RotSequence=quaternion, RotAngle=0, xRotVec=0, yRotVec=0, zRotVec=1,
+ xMin=0,xMax=3, yMin=0,yMax=3, zMin=0,zMax=3]
+\pstThreeDLine[linecolor=blue, linewidth=2pt, arrows=->](0,0,0)(3,0,3)
+\uput[0](-2.28,1.2){$\vec{R}_\Phi$}
+\end{pspicture}
+\end{LTXexample}
+
+Rotations of the coordinate system may be ``accumulated'' by applying 
+successive rotation sequences using the \verb+RotSet+ variable, 
+which is set either as a \verb+pst-3dplot+ object's optional argument, or
+with a \verb+\psset[pst-3dplot]{RotSet=value}+
+command. The usual \TeX{} scoping rules for the value of \verb+RotSet+
+hold. The following are valid values of \verb+RotSet+:
+\begin{itemize}
+\item \verb+set+: Sets the rotation matrix using the rotation
+parameters. This is the default value for \verb+RotSet+ and is
+what is used if \verb+RotSet+ is not set as an option for the
+\verb+pst-3dplot+ object, or if not previously
+set within the object's scope by a \verb+\psset[pst-3dplot]{RotSet=val}+ 
+command.
+\item \verb+concat+: Concatenates the current rotation matrix with
+a the new rotation that is defined by the rotation parameters. This option
+is most useful when multiple \verb+\\pstThreeDCoor+ calls are made,
+with or without actual plotting of the axes,
+to accumulate rotations. A previous value of \verb+RotSet=set+
+must have been made!
+\item \verb+keep+: Keeps the current rotation matrix, ignoring the
+rotation parameters. Mostly used internally to eliminate redundant
+calculations.
+\end{itemize}
+
+\begin{LTXexample}[pos=t]
+\begin{pspicture}(-3,-3)(3.6,3)
+\pstThreeDCoor[linecolor=blue, RotSequence=quaternion, RotAngle=0, RotSet=set, xRotVec=0,yRotVec=0,zRotVec=1,
+ xMin=0,xMax=3, yMin=0,yMax=3, zMin=0,zMax=3]
+ \pstThreeDCoor[linecolor=green, RotSequence=quaternion, RotSet=concat, RotAngle=22.5, xRotVec=0,yRotVec=0,zRotVec=1,
+  xMin=0,xMax=3, yMin=0,yMax=3, zMin=-0.6,zMax=3]
+ \pstThreeDCoor[linecolor=yellow, RotSequence=quaternion, RotSet=concat, RotAngle=30, xRotVec=0,yRotVec=1,zRotVec=0,
+  xMin=0,xMax=3,yMin=-0.6,yMax=3, zMin=0,zMax=3]
+ \pstThreeDCoor[linecolor=red, RotSequence=quaternion, RotSet=concat, RotAngle=60, xRotVec=1,yRotVec=0,zRotVec=0,
+  xMin=-0.6,xMax=3, yMin=0,yMax=3, zMin=0,zMax=3]%
+\end{pspicture}
+\end{LTXexample}
+
+By default, the rotations defined by \verb+RotX+, \verb+RotY+, and
+\verb+RotZ+ are rotations about the \emph{original} coordinate system's, 
+$x$, $y$, or $z$
+axes, respectively. More traditionally, however, these rotation angles
+are defined as rotations about the rotated coordinate system's \emph{current},
+$x$, $y$, or $z$ axis. The \verb+pst-3dplot+ variable option
+\verb+eulerRotation+ can be set to \verb+true+ to activate Euler angle
+definitions; i.e., \verb+eulerRotation=true+. The default is
+\verb+eulerRotation=false+.
 
+\begin{LTXexample}[pos=t]
+\begin{pspicture}(-4,-5)(6,5)
+ \pstThreeDCoor[linecolor=red, RotSequence=zyx, RotZ=90,RotY=90,RotX=0, 
+  xMin=0,xMax=5, yMin=0,yMax=5, zMin=0,zMax=5]
+ \pstThreeDCoor[linecolor=blue, RotSequence=zyx, RotZ=0,RotY=0,RotX=0,
+  xMin=0,xMax=2.5, yMin=0,yMax=2.5, zMin=0,zMax=2.5]
+\end{pspicture}
+\end{LTXexample}
+
+\begin{LTXexample}[pos=t]
+\begin{pspicture}(-3,-5)(7,5)
+ \pstThreeDCoor[eulerRotation=true, linecolor=red, RotSequence=zyx, RotZ=90, RotY=90, RotX=0,
+  xMin=0,xMax=5, yMin=0,yMax=5, zMin=0,zMax=5] 
+ \pstThreeDCoor[linecolor=blue, RotSequence=zyx, RotZ=0,RotY=0,RotX=0,
+  xMin=0,xMax=2.5, yMin=0,yMax=2.5, zMin=0,zMax=2.5]
+\end{pspicture}
+\end{LTXexample}
 
 \clearpage
 \psset{unit=1cm,gridlabels=7pt}
@@ -2171,9 +2255,16 @@ values for the option \verb|drawStyle| :
 \item \verb|yxLines| Curves are first drawn in y and then in x direction
 \end{itemize}
 
-In fact of the inner loop it is only possible to get a closed curve in the defined direction. For lines in x direction less \verb|yPlotpoints| are no problem, in difference to \verb|xPlotpoints|, especially for the plotstyle options \verb|line| and \verb|dots|.
+In fact of the inner loop it is only possible to get a closed curve in the defined direction. 
+For lines in x direction less \verb|yPlotpoints| are no problem, in difference to 
+\verb|xPlotpoints|, especially for the plotstyle options \verb|line| and \verb|dots|.
 
-Drawing three dimensional functions with curves which are transparent makes it difficult to see if a point is before or behind another one. \verb|\psplotThreeD| has an option \verb|hiddenLine| for a primitive hidden line mode, which only works when the y-intervall is defined in a way that $y_2>y_1$. Then every new curve is plotted over the forgoing one and filled with the color white. Figure  \ref{fig:3dfunc-hidden} is the same as figure \ref{fig:3dfunc}, only with the option \verb|hiddenLine=true|.
+Drawing three dimensional functions with curves which are transparent makes it difficult 
+to see if a point is before or behind another one. \verb|\psplotThreeD| has an option 
+\verb|hiddenLine| for a primitive hidden line mode, which only works when the y-intervall 
+is defined in a way that $y_2>y_1$. Then every new curve is plotted over the forgoing one 
+and filled with the color white. Figure~\ref{fig:3dfunc-hidden} is the same as 
+figure~\ref{fig:3dfunc}, only with the option \verb|hiddenLine=true|.
 
 \begin{lstlisting}
 \begin{pspicture}(-6,-4)(6,5)
@@ -2331,7 +2422,9 @@ Parametric plots are only possible for  drawing curves or areas.  The syntax for
 \parametricplotThreeD(t1,t2)(u1,u2){<three parametric functions x y z}
 \end{verbatim}
 
-The only possible variables are \verb|t| and \verb|u| with \verb|t1,t2| and  \verb|u1,u2| as the range for the parameters.  The order for the functions is not important and \verb|u| may be optional when having only a three dimensional curve and not an area.
+The only possible variables are \verb|t| and \verb|u| with \verb|t1,t2| and  \verb|u1,u2| as the 
+range for the parameters.  The order for the functions is not important and \verb|u| may be 
+optional when having only a three dimensional curve and not an area.
 \begin{align}
 \begin{array}{rl}
 	x & =f(t,u)\\
@@ -2348,7 +2441,10 @@ To draw a spiral we have the parametric functions:
 \end{array}
 \end{align}
 
-In the example the $t$ value is divided by $600$ for the \verb|z| coordinate, because we have the values for $t$ in degrees, here with a range of $0\mbox{°}\ldots 2160\mbox{°}$. Drawing a curve in a three dimensional coordinate system does only require one parameter, which has to be by default \verb|t|. In this case we do not need all parameters, so that one can write
+In the example the $t$ value is divided by $600$ for the \verb|z| coordinate, because we have the 
+values for $t$ in degrees, here with a range of $0\mbox{°}\ldots 2160\mbox{°}$. Drawing a curve in 
+a three dimensional coordinate system does only require one parameter, which has to be by default 
+\verb|t|. In this case we do not need all parameters, so that one can write
 
 \begin{verbatim}
 \parametricplotThreeD(t1,t2){<three parametric functions x y z}
@@ -2366,7 +2462,9 @@ which is the same as \verb|(0,0)| for the parameter \verb|u|.
 \end{LTXexample}
 
 
-Instead of using the \verb|\pstThreeDSphere| macro (see section \ref{sec:spheres}) it is  also possible to use parametric functions for a sphere. The macro plots continous lines only for the \verb|t| parameter, so a sphere plotted with the longitudes need the parameter equations as
+Instead of using the \verb|\pstThreeDSphere| macro (see section \ref{sec:spheres}) it is  also 
+possible to use parametric functions for a sphere. The macro plots continous lines only for 
+the \verb|t| parameter, so a sphere plotted with the longitudes need the parameter equations as
 \begin{align}
 \begin{array}{l}
 x = \cos t \cdot \sin u\\
@@ -2505,7 +2603,9 @@ The syntax is
 \dataplotThreeD[<options>]{<data object>}
 \end{verbatim}
 
-In difference to the macro \CMD{fileplotThreeD} the \CMD{dataplotThreeD} cannot plot any external data without reading this with the macro \CMD{readdata} which reads external data and save it in a macro, f.ex.: \CMD{dataThreeD}.\cite{dtk02.2:jackson.voss:plot-funktionen}
+In difference to the macro \CMD{fileplotThreeD} the \CMD{dataplotThreeD} cannot plot any external data 
+without reading this with the macro \CMD{readdata} which reads external data and save it in a macro, 
+f.ex.: \CMD{dataThreeD}.\cite{dtk02.2:jackson.voss:plot-funktionen}
 
 \begin{verbatim}
 \readdata{<data object>}{<datafile>}
@@ -2520,7 +2620,8 @@ In difference to the macro \CMD{fileplotThreeD} the \CMD{dataplotThreeD} cannot
   \dataplotThreeD[plotstyle=line]{\dataThreeD}
 \end{pspicture}%
 \end{LTXexample}
-\caption{Demonstration of \texttt{\textbackslash dataplotThreeD} with \texttt{Alpha=-30} and \texttt{Beta=30}}\label{fig:fileplot}
+\caption{Demonstration of \texttt{\textbackslash dataplotThreeD} with \texttt{Alpha=-30} and 
+\texttt{Beta=30}}\label{fig:fileplot}
 \end{figure}
 
 
@@ -2709,7 +2810,7 @@ error. In this case save prevent expanding with e.g.: \verb+\psset{nameX=$\noexp
 
 
 \section{Credits}
-Bruce Burlton | Christophe Jorssen | Chris Kuklewicz | Thorsten Suhling
+Bruce Burlton | Christophe Jorssen | Chris Kuklewicz | Thorsten Suhling 
 
 \bgroup
 \nocite{*}