% \iffalse meta-comment, etc.
%%
%% Package `pst-gr3d.dtx'
%%
%% Denis Girou (CNRS/IDRIS - France) <Denis.Girou@idris.fr>
%% Herbert Voss <voss@perce.de>
%%
%% This program can be redistributed and/or modified under the terms
%% of the LaTeX Project Public License Distributed from CTAN archives
%% in directory macros/latex/base/lppl.txt.
%%
%% DESCRIPTION:
%%   `pst-gr3d' is a PSTricks package to draw three dimensional grids
%%   with various customization
%%
% \fi
%
% \changes{v1.34}{2005/09/12}{(hv) switch to extended version of keyvalue interface}
% \changes{v1.33}{2005/01/14}{(hv) fixed introduced bug}
% \changes{v1.32}{2005/01/13}{(hv) new package wrapper for pst-gr3d.tex}
% \changes{v1.31}{2004/06/23}{(hv) delete the PstDebug option and use the one
%                             the one from pstricks, to prevent a clash with
%                             pst-fill}
% \changes{v1.3}{2001/02/19}{Changed conventions for units and updates
%                            in the example macros and the examples.}
% \changes{v1.2}{1998/09/16}{Standard packaging (.ins + .dtx files).}
% \changes{v1.1}{1998/03/27}{First public release.}
%
% \DoNotIndex{\!,\",\#,\$,\%,\&,\',\(,\+,\*,\,,\-,\.,\/,\:,\;,\<,\=,\>,\?}
% \DoNotIndex{\@,\@B,\@K,\@cTq,\@f,\@fPl,\@ifnextchar,\@nameuse,\@oVk}
% \DoNotIndex{\[,\\,\],\^,\_,\ }
% \DoNotIndex{\^,\\^,\\\^,$\^$,$\\^$,$\\^$}
% \DoNotIndex{\0,\2,\4,\5,\6,\7,\8,}
% \DoNotIndex{\A,\a}
% \DoNotIndex{\B,\b,\Bc,\begin,\Bq,\Bqc}
% \DoNotIndex{\C,\c,\catcode,\cJA,\CodelineIndex,\csname}
% \DoNotIndex{\D,\def,\define@key,\Df,\divide,\DocInput,\documentclass,\pst@addfams}
% \DoNotIndex{\eCN,\edef,\else,\eHd,\eMcj,\EnableCrossrefs,\end,\endcsname}
% \DoNotIndex{\endCenterExample,\endExample,\endinput,\endpsclip}
% \DoNotIndex{\PrintIndex,\PrintChanges,\ProvidesFile}
% \DoNotIndex{\endpspicture,\endSideBySideExample,\Example}
% \DoNotIndex{\F,\f,\FdUrr,\fi,\filedate,\fileversion,\FV@Environment}
% \DoNotIndex{\FV@UseKeyValues,\FV@XRightMargin,\FVB@Example,\fvset}
% \DoNotIndex{\G,\g,\GetFileInfo,\gr,\GradientLoaded,\gsFKrbK@o,\gsj,\gsOX}
% \DoNotIndex{\hbadness,\hfuzz,\HLEmphasize,\HLMacro,\HLMacro@i}
% \DoNotIndex{\HLReverse,\HLReverse@i,\hqcu,\HqY}
% \DoNotIndex{\I,\i,\ifx,\input,\Ir,\IU}
% \DoNotIndex{\j,\jl,\JT,\JVodH}
% \DoNotIndex{\K,\k,\kfSlL}
% \DoNotIndex{\L,\let}
% \DoNotIndex{\message,\mHNa,\mIU}
% \DoNotIndex{\N,\nB,\newcmykcolor,\newdimen,\newif,\nW}
% \DoNotIndex{\O,\oCDJDo,\ocQhVI,\OnlyDescription,\oRKJ}
% \DoNotIndex{\P,\p,\ProvidesPackage,\psframe,\pslinewidth,\psset}
% \DoNotIndex{\PstAtCode,\PSTricksLoaded}
% \DoNotIndex{\q,\Qr,\qssRXq,\qu,\qXjFQp,\qYL}
% \DoNotIndex{\R,\r,\RecordChanges,\relax,\RlaYI,\rN,\Rp,\rp,\RPDXNn,\rput}
% \DoNotIndex{\S,\scalebox,\SgY,\SideBySide@Example,\SideBySideExample}
% \DoNotIndex{\SgY,\sk,\Sp,\space,\sZb}
% \DoNotIndex{\T,\the,\tw@}
% \DoNotIndex{\u,\UiSWGEf@,\uJi,\usepackage,\uVQdMM,\UYj}
% \DoNotIndex{\VerbatimEnvironment,\VerbatimInput,\VrC@}
% \DoNotIndex{\WhZ,\WjKCYb,\WNs}
% \DoNotIndex{\XkN,\XW}
% \DoNotIndex{\Z,\ZCM,\Ze}
% \DoNotIndex{\addtocounter,\advance,\alph,\arabic,\AtBeginDocument,\AtEndDocument}
% \DoNotIndex{\AtEndOfPackage,\begingroup,\bfseries,\bgroup,\box,\csname}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\expandafter,\fi}
% \DoNotIndex{\TeX,\z@,\p@,\@one,\xdef,\thr@@,\string,\sixt@@n,\reset,\or,\multiply,\repeat,\RequirePackage}
% \DoNotIndex{\@cclvi,\@ne,\@ehpa,\@nil,\copy,\dp,\global,\hbox,\hss,\ht,\ifodd,\ifdim,\ifcase,\kern}
% \DoNotIndex{\chardef,\loop,\leavevmode,\ifnum,\lower}
% \setcounter{IndexColumns}{2}
%
% \setcounter{IndexColumns}{2}
%
% \newcommand{\PstGridThreeDPackage}{`\textsf{pst-gr3d}'}
% \newcommand{\PstGridThreeDMacro}{\cs{PstGridThreeD}}
%
% ^^A From ltugboat.cls
%
% ^^A Typeset the name of an environment
% \providecommand\env[1]{\textsf{#1}}
% \providecommand\clsname[1]{\textsf{#1}}
% \providecommand\pkgname[1]{\textsf{#1}}
% \providecommand\optname[1]{\textsf{#1}}
% \providecommand\progname[1]{\textsf{#1}}
%
% ^^A A list of options for a package/class
% \newenvironment{optlist}{\begin{description}%
%   \renewcommand\makelabel[1]{%
%     \descriptionlabel{\mdseries\optname{##1}}}%
%   \itemsep0.25\itemsep}%
%  {\end{description}}
%
% ^^A Utility macros
%
%
% ^^A Example macros - adapted from the `fvrb-ex' package
% ^^A ---------------------------------------------------
%
% ^^A Take care that we use here the four /?_W characters as escape
% ^^A characters, so we can't use these characters in the examples!
%
% \makeatletter
%
% ^^A To highlight some verbatim sequences (comments, macro names, etc.)
% \def\HLEmphasize#1{\textit{#1}}
% \newcommand{\BS}{\texttt{\symbol{`\\}}}
% \def\HLMacro#1{\BS{}def\HLMacro@i#1\@nil}
% \def\HLMacro@i#1def#2\@nil{\HLReverse{#2}}
% \def\HLReverse#1{{\setlength{\fboxsep}{1pt}\HLReverse@i{#1}}}
% \def\HLReverse@i#1{\colorbox{black}{\textcolor{white}{\textbf{#1}}}}
%
% \def\Example{\FV@Environment{}{Example}}
% \def\endExample{%
% \end{VerbatimOut}
% \Below@Example{\input{\jobname.tmp}}
% \endgroup}
%
% \def\CenterExample{\FV@Environment{}{Example}}
% \def\endCenterExample{%
% \end{VerbatimOut}
% \begin{center}
%   \Below@Example{\input{\jobname.tmp}}
% \end{center}
% \endgroup}
%
% \def\SideBySideExample{\FV@Environment{}{Example}}
% \def\endSideBySideExample{%
% \end{VerbatimOut}
% \SideBySide@Example{\input{\jobname.tmp}}
% \endgroup}
%
% \def\FVB@Example{%
% \begingroup
% \FV@UseKeyValues
% \parindent=0pt
% \multiply\topsep by 2
% \VerbatimEnvironment
% \begin{VerbatimOut}[gobble=4,codes={\catcode`\W=12}]{\jobname.tmp}}
%
% \def\Below@Example#1{%
% \VerbatimInput[gobble=0,commentchar=W,commandchars=/?_,frame=single,
%                numbers=left,numbersep=3pt]{\jobname.tmp}
% \catcode`\%=14\relax
% \catcode`\W=9\relax
% ^^A We suppress the effect of the highlighting macros
% \catcode`/=0\relax
% \catcode`?=1\relax
% \catcode`_=2\relax
% \def\HLEmphasize##1{##1}%
% \def\HLMacro##1{##1}%
% \def\HLReverse##1{##1}%
% #1
% \par}
%
% \def\SideBySide@Example#1{%
% \vskip 1mm
% \@tempdimb=\FV@XRightMargin
% \advance\@tempdimb -5mm
% \begin{minipage}[c]{\@tempdimb}
%   \fvset{xrightmargin=0pt}
%   \catcode`\%=14\relax
%   \catcode`\W=9\relax
%   ^^A We suppress the effect of the highlighting macros
%   \catcode`/=0\relax
%   \catcode`?=1\relax
%   \catcode`_=2\relax
%   \def\HLEmphasize##1{##1}%
%   \def\HLMacro##1{##1}%
%   \def\HLReverse##1{##1}%
%   #1
% \end{minipage}%
% \@tempdimb=\textwidth
% \advance\@tempdimb -\FV@XRightMargin
% \advance\@tempdimb 5mm
% \begin{minipage}[c]{\@tempdimb}
%   \VerbatimInput[gobble=0,commentchar=W,commandchars=/?_,
%                  frame=single,numbers=left,numbersep=3pt,
%                  xleftmargin=5mm,xrightmargin=0pt]{\jobname.tmp}
% \end{minipage}
% \vskip 1mm}
%
% \makeatother
%
% ^^A End of example macros from `fvrb-ex'
%
% ^^A For the possible index and changes log
% \setlength{\columnseprule}{0.6pt}
%
% ^^A Beginning of the documentation itself
%
% \title{The \PstGridThreeDPackage{} package\\
%        A PSTricks package for three dimensional grids}
% \author{Denis \textsc{Girou}\thanks{CNRS/IDRIS ---
%         Centre National de la Recherche Scientifique /
%         Institut du D\'eveloppement et des Ressources en Informatique
%         Scientifique --- Orsay --- France ---
%         \mbox{\texttt{<Denis.Girou@idris.fr>}}.}}
% \date{Version 1.34\\\ 2005-09-12\\
%       {\small Documentation revised \today\ by Herbert Voss}}
%
% \maketitle
%
% \begin{abstract}
%     This package allow to draw three dimensional grids using the macro
%   \PstGridThreeDMacro. We can also specify how nodes of the grid must look
%   like.
% \end{abstract}
%
% \tableofcontents
%
% \section{Introduction}
%
%   \PstGridThreeDPackage{} offer a main unique macro with few parameters to
% interact on it. But we can also use all the relevant PSTricks parameters to
% change the size, the characteristics of lines, etc.
%
% \vspace{1mm}
%   The syntax is simply:%
% \fbox{\PstGridThreeDMacro\texttt{[optional\_parameters](X,Y,Z)}}
%
% \vspace{1mm}
%   We can define a macro \PstGridThreeDMacro\texttt{HookNode} to specify how
% the nodes at the interconnections must look like, and there are also some
% other \emph{hooks} that can be used for special purposes.
%
%   The default viewpoint is (\texttt{1.2,-0.6,0.8}), but this can of course be
% changed using the standard way.
%
%   The package try to compute approximatively the size of the object (the
% \texttt{pspicture} parameter, PSTricks speaking), but for three dimensional
% grids it is an impossible task to found it accurately in the general case.
% So, if the exact size is needed or if we change the viewpoint for the
% graphic, the size must be computed \emph{by hand}, using the
% \cs{psframebox[framesep=0]\{...\}} construction to found the correct values
% by attempts and errors --- fortunately, in practice few attempts are often
% enough...
%
% \section{Usage}
%
% \subsection{Parameters and hooks}
%
%   The three required parameters specify the lengths in the X, Y and Z
% directions, respectively:
%
% \begin{CenterExample}
%   \PstGridThreeD(3,1,1)\hfill
%   \PstGridThreeD(1,3,1)\hfill
%   \PstGridThreeD(1,1,3)
% \end{CenterExample}
%
%   Of course, we can use all the relevant generic PSTricks parameters,
% specially those applying to grids:
%
% \begin{CenterExample}
%   \PstGridThreeD[unit=1.5](1,1,1)\hfill
%   \PstGridThreeD[viewpoint=1.2 -1.5 0.4,griddots=7](1,3,2)\hfill
%   \PstGridThreeD[gridwidth=0.08,gridcolor=red](3,2,2)\hfill
%   \begin{pspicture}(-1.7,0)(0.8,3.6)
%     \PstGridThreeD[viewpoint=-0.4 -0.6 0.8,PstPicture=false](1,3,2)
%   \end{pspicture}
% \end{CenterExample}
%
%   We can draw one and two dimensional grids, using degenerated cases:
%
% \begin{CenterExample}
%   \PstGridThreeD(0,4,0)\hfill
%   \PstGridThreeD[linewidth=0.05](0,3,1)\hfill
%   \PstGridThreeD[griddots=5](3,1,0)
% \end{CenterExample}
%
%   To change the way the grids are drawn, we can also use \textbf{nine}
% specific parameters and \textbf{five} specific \emph{hooks}:
%
% \begin{optlist}
%   \item [PstDebug (integer)]: to obtain some internal debugging informations
%   --- here, a framed box around the boundix box used (the \texttt{pspicture}
%   environment) could be drawn. It can take the  values 0 (no debug) or 1. 
%   (\emph{Default:~0} --- no debugging informations).
% \end{optlist}
%
% \begin{optlist}
%   \item [PstPicture (boolean)]: to define or not a \texttt{pspicture}
%   environment for the grid. We have to define this parameter to \emph{false}
%   mainly if we choose a viewpoint different than the  default one --- see
%   examples later
%   (\emph{Default:~true} --- which is not the case for basic PSTricks
%   objects).
% \end{optlist}
%
% \begin{optlist}
%   \item [GridThreeDXUnit (integer)]: unit coefficient in the X direction
%   (\emph{Default:~1} --- it must be an integer, not a real).
%   \item [GridThreeDYUnit (integer)]: unit coefficient in the Y direction
%   (\emph{Default:~1} --- it must be an integer, not a real).
%   \item [GridThreeDZUnit (integer)]: unit coefficient in the Z direction
%   (\emph{Default:~1} --- it must be an integer, not a real).
% \end{optlist}
%
% \begin{CenterExample}
%   \PstGridThreeD[/HLEmphasize?GridThreeDXUnit_=/HLReverse?2_](1,1,1)\hfill
%   \PstGridThreeD[/HLEmphasize?GridThreeDYUnit_=/HLReverse?3_](1,1,1)\hfill
%   \PstGridThreeD[unit=0.5,/HLEmphasize?GridThreeDZUnit_=/HLReverse?4_](4,3,1)
% \end{CenterExample}
%
% \begin{optlist}
%   \item [GridThreeDXPos (integer)]: position of the origin in the X direction
%   (\emph{Default:~0} --- it must be an integer, not a real).
%   \item [GridThreeDYPos (integer)]: position of the origin in the Y direction
%   (\emph{Default:~0} --- it must be an integer, not a real).
%   \item [GridThreeDZPos (integer)]: position of the origin in the Z direction
%   (\emph{Default:~0} --- it must be an integer, not a real).
% \end{optlist}
%
%   These parameters are in fact mainly useful if we want to superpose grids,
% which can be done easily using the \cs{PstGridThreeDHookEnd} macro (see
% description below):
%
% \begin{CenterExample}
%   % /HLEmphasize?First grid_
%   /HLMacro?\def\PstGridThreeDHookEnd_{%
%     \PstGridThreeD[/HLEmphasize?PstPicture_=/HLReverse?false_,gridwidth=0.1,
%                    /HLEmphasize?GridThreeDXPos_=/HLReverse?1_](0,2,1)}
%   \PstGridThreeD(1,3,2)\hfill
%   % /HLEmphasize?Second grid_
%   /HLMacro?\def\PstGridThreeDHookEnd_{%
%     \PstGridThreeD[/HLEmphasize?PstPicture_=/HLReverse?false_,gridwidth=0.1,
%                    /HLEmphasize?GridThreeDYPos_=/HLReverse?1_](1,2,1)}
%   \PstGridThreeD(1,3,2)\hfill
%   % /HLEmphasize?Third grid_
%   /HLMacro?\def\PstGridThreeDHookEnd_{%
%     \PstGridThreeD[/HLEmphasize?PstPicture_=/HLReverse?false_,gridwidth=0.1,
%                    gridcolor=green,
%                    /HLEmphasize?GridThreeDYPos_=/HLReverse?2_,
%                    /HLEmphasize?GridThreeDZPos_=/HLReverse?1_](1,1,1)}
%   \PstGridThreeD(1,3,2)
% \end{CenterExample}
%
% \begin{optlist}
%   \item [GridThreeDNodes (boolean)]: to define or not the nodes at
%   interconnection points of the grid. The nodes are named
%   \texttt{Gr3dNodeXYZ}. We can use the \texttt{Rx} and \texttt{Ry} parameters
%   to position the relevant material relatively to the nodes, specifying the
%   distance in cartesian coordinates. The parameter \texttt{angle} used with
%   \texttt{Rx} allow to use polar ones.
%   (\emph{Default:~false} --- no nodes defined).
% \end{optlist}
%
% \begin{SideBySideExample}[xrightmargin=4cm]
%   \PstGridThreeD[/HLEmphasize?GridThreeDNodes_=/HLReverse?true_](1,3,1)
%   \SpecialCoor
%   \rput*(/HLEmphasize?Gr3dNode130_){\footnotesize 130}
%   \rput*(/HLEmphasize?Gr3dNode131_){\footnotesize 131}
% \end{SideBySideExample}
%
% \begin{optlist}
%   \item [\cs{PstGridThreeDHookNode} (macro)]: this hook allow to define the
%   form of the nodes. A predefined \cs{PstGridThreeDNodeProcessor} macro
%   exist, which define a circle with a little white circle in it. We can also
%   use the \cs{iy} counter to differentiate the nodes according to the Y
%   faces --- but note that we can't do the same thing for the X or Z faces
%   (\emph{Default:~empty}).
% \end{optlist}
%
% \begin{CenterExample}
%   % /HLEmphasize?First grid_
%   /HLMacro?\def\PstGridThreeDHookNode_{%
%     \begin{pspicture}(-0.15,-0.15)(0.15,0.15)
%       \pscircle*[linecolor=magenta]{0.15}
%     \end{pspicture}}
%   \PstGridThreeD(1,2,2)\hfill
%   % /HLEmphasize?Second grid_
%   \definecolor{LightBlue}{rgb}{0.68,0.85,0.9}
%   /HLMacro?\def\PstGridThreeDHookNode_{%
%     \PstGridThreeDNodeProcessor{LightBlue}}
%   \PstGridThreeD[unit=0.7](2,3,3)\hfill
%   % /HLEmphasize?Third grid_
%   /HLMacro?\def\PstGridThreeDHookNode_{%
%     \ifcase\iy
%          \PstGridThreeDNodeProcessor{magenta}%
%       \or\PstGridThreeDNodeProcessor{yellow}%
%       \or\PstGridThreeDNodeProcessor{cyan}%
%       \else\PstGridThreeDNodeProcessor{green}%
%     \fi}
%   \PstGridThreeD(1,3,1)
% \end{CenterExample}
%
% \begin{optlist}
%   \item [\cs{PstGridThreeDHookEnd} (macro)]: this hook allow to execute a
%   macro at the end of the grid drawing, before the \texttt{pspicture}
%   environment closing. This is specially interesting for instance to
%   superpose grids, if we take care to define the \texttt{PstPicture}
%   parameter to false for them
%   (\emph{Default:~empty}).
% \end{optlist}
%
% \begin{CenterExample}
%   /HLMacro?\def\PstGridThreeDHookEnd_{{%
%     \psset{/HLEmphasize?PstPicture_=/HLReverse?false_,gridwidth=0.1}
%     {/HLMacro?\def\PstGridThreeDHookNode_{%
%        \PstGridThreeDNodeProcessor{blue}}%
%      \PstGridThreeD[gridcolor=blue,
%                     /HLEmphasize?GridThreeDZPos_=/HLReverse?3_](0,7,0)}%
%     {/HLMacro?\def\PstGridThreeDHookNode_{%
%        \PstGridThreeDNodeProcessor{red}}%
%      \PstGridThreeD[gridcolor=red,
%                     /HLEmphasize?GridThreeDXPos_=/HLReverse?1_,
%                     /HLEmphasize?GridThreeDZPos_=/HLReverse?1_](0,3,1)}%
%     {/HLMacro?\def\PstGridThreeDHookNode_{%
%        \PstGridThreeDNodeProcessor{green}}%
%      \PstGridThreeD[gridcolor=green,
%                     /HLEmphasize?GridThreeDYPos_=/HLReverse?6_](1,1,1)}}}
%   \PstGridThreeD(1,7,3)
% \end{CenterExample}
%
% \begin{optlist}
%   \item [\cs{PstGridThreeDHookXFace} (macro)]: this hook allow to execute
%   a macro before to draw the X faces
%   (\emph{Default:~empty}).
%   \item [\cs{PstGridThreeDHookYFace} (macro)]: this hook allow to execute
%   a macro before to draw the Y faces
%   (\emph{Default:~empty}).
%   \item [\cs{PstGridThreeDHookZFace} (macro)]: this hook allow to execute
%   a macro before to draw the Z faces
%   (\emph{Default:~empty}).
% \end{optlist}
%
%   In fact, these hooks are not very powerful, because we can't control the
% order of the faces drawing as we can dream... For instance, we can't use this
% technic to draw objects with only \emph{true} visible lines. Take care also
% that for the Y faces, the direction is negative in the horizontal direction,
% so the coordinates must take this fact in account.
%
% \begin{CenterExample}
%   {/HLMacro?\def\PstGridThreeDHookXFace_{%
%     \ifnum\multidocount=1\psframe*[linecolor=cyan](3,2)\fi}%
%    \PstGridThreeD(1,3,2)}\hfill
%   {/HLMacro?\def\PstGridThreeDHookYFace_{%
%     \ifnum\multidocount=2\psframe*[linecolor=yellow](-3,0)(0,2)\fi}%
%    \PstGridThreeD(3,1,2)}\hfill
%   {/HLMacro?\def\PstGridThreeDHookZFace_{%
%     \ifnum\multidocount=2
%     \else
%       \psframe*[linecolor=yellow](3,3)
%     \fi}%
%    \PstGridThreeD(3,3,2)}
% \end{CenterExample}
%
% \section{Examples}
%
%   We give here more advanced examples, most of them from technical drawings
% describing the architecture of a multiprocessors supercomputer.
%
% \begin{SideBySideExample}[xrightmargin=4cm]
%   \PstGridThreeD[/HLEmphasize?GridThreeDNodes_=/HLReverse?true_](2,2,2)
%   \SpecialCoor
%   \rput*(/HLEmphasize?Gr3dNode002_){\tiny 002}
%   \rput*(/HLEmphasize?Gr3dNode221_){\tiny 221}
%   \rput([Rx=0.3]/HLEmphasize?Gr3dNode222_){\tiny 222}
%   \multido{\i=0+1}{3}{%
%     \rput([Rx=0.3,Ry=-0.3]/HLEmphasize?Gr3dNode2\i0_){2\i0}}
% \end{SideBySideExample}
%
% \begin{SideBySideExample}[xrightmargin=4cm]
%   \definecolor{LightBlue}{rgb}{0.68,0.85,0.9}
%   /HLMacro?\def\PstGridThreeDHookNode_{%
%     \PstGridThreeDNodeProcessor{LightBlue}}
%   \PstGridThreeD[/HLEmphasize?GridThreeDNodes_=/HLReverse?true_](1,2,2)
%   \SpecialCoor
%   \rput([Rx=-0.15,Ry=0.3]/HLEmphasize?Gr3dNode122_){%
%     \psline{<-}(0.5;35)}
%   \rput([Rx=0.35,Ry=0.8]/HLEmphasize?Gr3dNode122_){Network}
%   \rput([Rx=0.15,angle=-40]/HLEmphasize?Gr3dNode110_){%
%     \psline{<-}(0.8;-60)}
%   \rput([Rx=0.25,angle=-100]/HLEmphasize?Gr3dNode120_){%
%     \psline{<-}(0.8;-100)}
%   \rput([Rx=1.5,angle=-55]/HLEmphasize?Gr3dNode010_){Nodes}
% \end{SideBySideExample}
%
% \begin{SideBySideExample}[xrightmargin=4cm]
%   \definecolor{Orange}{rgb}{1.,0.65,0.}
%   /HLMacro?\def\PstGridThreeDHookNode_{%
%     \PstGridThreeDNodeProcessor{Orange}}
%   \psset{unit=1.3}
%   \PstGridThreeD[/HLEmphasize?GridThreeDNodes_=/HLReverse?true_](1,2,2)
%   \SpecialCoor
%   \psset{arrows=<->,arrowscale=2}
%   \ThreeDput[normal=0 0 -1](0,0,0){%
%     \ncloop[linecolor=red,arm=0.35,
%             loopsize=0.6,angleA=-90,angleB=90]
%            {/HLEmphasize?Gr3dNode022_}{/HLEmphasize?Gr3dNode002_}
%     \ncloop[linecolor=green,arm=0.7,
%             nodesepA=0.18,nodesepB=0.12,
%             loopsize=-0.5,angleA=180]
%            {/HLEmphasize?Gr3dNode002_}{/HLEmphasize?Gr3dNode102_}}
% \end{SideBySideExample}
%
% \begin{CenterExample}
%   /HLMacro?\def\PstGridThreeDHookEnd_{{%
%     \psset{/HLEmphasize?PstPicture_=/HLReverse?false_,gridwidth=0.1}
%     {/HLMacro?\def\PstGridThreeDHookNode_{%
%        \PstGridThreeDNodeProcessor{blue}}%
%      \PstGridThreeD[gridcolor=blue,
%                     /HLEmphasize?GridThreeDZPos_=/HLReverse?3_](0,7,0)}%
%     {/HLMacro?\def\PstGridThreeDHookNode_{%
%        \PstGridThreeDNodeProcessor{red}}%
%      \PstGridThreeD[gridcolor=red,
%                     /HLEmphasize?GridThreeDXPos_=/HLReverse?1_,
%                     /HLEmphasize?GridThreeDZPos_=/HLReverse?1_](0,3,1)}%
%     {/HLMacro?\def\PstGridThreeDHookNode_{%
%        \PstGridThreeDNodeProcessor{green}}%
%      \PstGridThreeD[gridcolor=green,
%                     /HLEmphasize?GridThreeDYPos_=/HLReverse?6_](1,1,1)}}}
%   \PstGridThreeD[gridwidth=0.04,
%                  /HLEmphasize?GridThreeDNodes_=/HLReverse?true_](1,7,3)
%   \SpecialCoor
%   \rput([Rx=0.15,angle=140]/HLEmphasize?Gr3dNode033_){%
%     \psline[linecolor=blue]{<-}(0.8;150)}
%   \rput([Rx=0.95,angle=140]/HLEmphasize?Gr3dNode033_){%
%     \shortstack{1d grid\\\footnotesize (X=8,Y=1,Z=1)}}
%   \rput([Rx=0.15,angle=-50]/HLEmphasize?Gr3dNode121_){%
%     \psline[linecolor=red]{<-}(1.2;-50)}
%   \rput([Rx=1.5,angle=-55]/HLEmphasize?Gr3dNode121_){%
%     \shortstack{2d grid\\\footnotesize (X=4,Y=2,Z=1)}}
%   \rput([Rx=0.2,angle=-100]/HLEmphasize?Gr3dNode160_){%
%     \psline[linecolor=green]{<-}(0.8;-100)}
%   \rput([Rx=1.4,angle=-100]/HLEmphasize?Gr3dNode160_){%
%     \shortstack{3d grid\\\footnotesize (X=2,Y=2,Z=2)}}
% \end{CenterExample}
%
%
% \StopEventually{}
%
% ^^A .................... End of the documentation part ....................
%
% \section{Driver file}
%
%   The next bit of code contains the documentation driver file for \TeX{},
% i.e., the file that will produce the documentation you are currently
% reading. It will be extracted from this file by the \texttt{docstrip}
% program.
%
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
\GetFileInfo{pst-gr3d.dtx}
\usepackage{fancyvrb}
\usepackage{pstricks}
\usepackage[colorlinks,linktocpage]{hyperref}
\usepackage{pst-gr3d}
%
\AtBeginDocument{
%  \OnlyDescription % comment out for implementation details
  \EnableCrossrefs
  \CodelineIndex
  \RecordChanges}
\AtEndDocument{
  \PrintIndex
  \setcounter{IndexColumns}{1}
  \PrintChanges}
\hbadness=7000            % Over and under full box warnings
\hfuzz=3pt
\begin{document}
  \DocInput{pst-gr3d.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
% \section{\PstGridThreeDPackage{} \LaTeX{} wrapper}
%
%    \begin{macrocode}
%<*latex-wrapper>
\RequirePackage{pstricks}
\ProvidesPackage{pst-gr3d}[2005/01/13 package wrapper for 
  pst-gr3d.tex (hv)]
\input{pst-gr3d.tex}
\ProvidesFile{pst-gr3d.tex}
  [\filedate\space v\fileversion\space `PST-gr3d' (dg)]
%</latex-wrapper>
%    \end{macrocode}
%
% \section{\PstGridThreeDPackage{} code}
%
%    \begin{macrocode}
%<*pst-gr3d>
%    \end{macrocode}
%
% \subsection{Preambule}
%
%   Who we are.
%
%    \begin{macrocode}
\def\fileversion{1.34}
\def\filedate{2005/09/12}
\message{`PST-Grid3d' v\fileversion, \filedate\space (Denis Girou)}
\csname PSTGridThreeDLoaded\endcsname
\let\PSTGridThreeDLoaded\endinput
%    \end{macrocode}
%
%   Require the PSTricks, `\textsf{pst-node}', `\textsf{pst-3d}' and
% `\textsf{multido}' packages.
%
%    \begin{macrocode}
\ifx\PSTricksLoaded\endinput\else\input pstricks.tex\fi
\ifx\PSTnodesLoaded\endinput\else\input pst-node.tex\fi
\ifx\PSTthreeDLoaded\endinput\else\input pst-3d.tex\fi
\ifx\MultidoLoaded\endinput\else\input multido.tex\fi
%    \end{macrocode}
%
%   interface to the extended `\textsf{keyval}' package.
%
%    \begin{macrocode}
\ifx\PSTXKeyLoaded\endinput\else\input pst-xkey\fi
%%
%    \end{macrocode}
%
%   Catcodes changes and defining the family name for xkeyvalue.
%
%    \begin{macrocode}
\edef\PstAtCode{\the\catcode`\@}\catcode`\@=11\relax
\pst@addfams{pst-gr3d}
%%
%    \end{macrocode}
%
% \subsection{Definition of the parameters}
%
%   \texttt{PstDebug} is for internal debugging purposes --- here, a framed box
% around the grid is shown (to debug, set \texttt{PstDebug=1}).
%
%    \begin{macrocode}
%% change Pst@Debug to prevent a clash with pst-fill
%% which has the same option. Now pstricks defines Pst@Debug
%%\define@key[psset]{pst-gr3d}{PstDebug}{\pst@getint{#1}{\Pst@Debug}}
%% end hv 2004-06-22
%    \end{macrocode}
%
%   \texttt{PstPicture} allow to define a ``\texttt{pspicture}'' environment.
%
%    \begin{macrocode}
\newif\ifPst@PstPicture
\define@key[psset]{pst-gr3d}{PstPicture}[true]{\@nameuse{Pst@PstPicture#1}}
%    \end{macrocode}
%
%   \texttt{GridThreeDNodes} allow to define nodes on the grid.
%
%    \begin{macrocode}
\newif\ifPstGridThreeD@Nodes
\define@key[psset]{pst-gr3d}{GridThreeDNodes}[true]{%
   \@nameuse{PstGridThreeD@Nodes#1}}
%    \end{macrocode}
%
%   \texttt{GridThreeDXUnit}, \texttt{GridThreeDYUnit} and
% \texttt{GridThreeDZUnit} define the X, Y and Z units (must be integers).
%
%    \begin{macrocode}
\define@key[psset]{pst-gr3d}{GridThreeDXUnit}{%
  \pst@getint{#1}{\PstGridThreeD@XUnit}}
\define@key[psset]{pst-gr3d}{GridThreeDYUnit}{%
  \pst@getint{#1}{\PstGridThreeD@YUnit}}
\define@key[psset]{pst-gr3d}{GridThreeDZUnit}{%
  \pst@getint{#1}{\PstGridThreeD@ZUnit}}
%    \end{macrocode}
%
%   \texttt{GridThreeDXPos}, \texttt{GridThreeDYPos} and
% \texttt{GridThreeDZPos} define the X, Y and Z positions.
%
%    \begin{macrocode}
\define@key[psset]{pst-gr3d}{GridThreeDXPos}{%
  \pst@getint{#1}{\PstGridThreeD@XPos}}
\define@key[psset]{pst-gr3d}{GridThreeDYPos}{%
  \pst@getint{#1}{\PstGridThreeD@YPos}}
\define@key[psset]{pst-gr3d}{GridThreeDZPos}{%
  \pst@getint{#1}{\PstGridThreeD@ZPos}}
%    \end{macrocode}
%
%   \texttt{Rx} and \texttt{Ry} are aliases for relative moves from nodes.
%
%    \begin{macrocode}
\define@key[psset]{pst-gr3d}{Rx}{\psset{XnodesepA=#1}}
\define@key[psset]{pst-gr3d}{Ry}{\psset{offsetA=#1}}
%    \end{macrocode}
%
%   Default values (including \texttt{viewpoint} first).
%
%    \begin{macrocode}
\psset{viewpoint=1.2 -0.6 0.8}
\psset{%
PstDebug=0,PstPicture=true,GridThreeDNodes=false,
GridThreeDXPos=0,GridThreeDYPos=0,GridThreeDZPos=0,
GridThreeDXUnit=1,GridThreeDYUnit=1,GridThreeDZUnit=1}
%    \end{macrocode}
%
% \subsection{Main macro}
%
%   The general \cs{PstGridThreeD} macro to draw three dimensional grids.
%
% \begin{macro}{\PstGridThreeD}
%    \begin{macrocode}
\def\PstGridThreeD{\@ifnextchar[{\PstGridThreeD@i}{\PstGridThreeD@i[]}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\PstGridThreeD@i}
%    \begin{macrocode}
\def\PstGridThreeD@i[#1](#2,#3,#4){{%
\psset{dimen=middle}%
\psset{#1}%
%    \end{macrocode}
%
%   First, we try to compute rather accurate values for the
% ``\texttt{pspicture}'' environment (it is not possible to found them in the
% general case, so we must define our own ones, setting \texttt{PstPicture}
% to false before, if the ones automatically computed here are really wrong
% in our case...).
%
%   Ymin pspicture value.
%
%    \begin{macrocode}
\pst@cnth=#2
\multiply\pst@cnth\PstGridThreeD@XUnit
\divide\pst@cnth\tw@
\ifodd\pst@cnth
  \edef\PstGridThreeD@PictureYmin{-\the\pst@cnth}%
\else
  \edef\PstGridThreeD@PictureYmin{-\the\pst@cnth.5}%
\fi
%    \end{macrocode}
%
%   Xmax pspicture value (stored in \cs{pst@cntg}).
%
%    \begin{macrocode}
\pst@cntg=#3
\multiply\pst@cntg\PstGridThreeD@YUnit
\pst@cnth=#2
\divide\pst@cnth\tw@
\multiply\pst@cnth\PstGridThreeD@XUnit
\advance\pst@cntg\pst@cnth
%    \end{macrocode}
%
%   Ymax pspicture value.
%
%    \begin{macrocode}
\pst@cnth=#3
\advance\pst@cnth\m@ne
\multiply\pst@cnth\PstGridThreeD@YUnit
\divide\pst@cnth\tw@
\pst@cntd=#4
\multiply\pst@cntd\PstGridThreeD@ZUnit
\advance\pst@cntd\pst@cnth
\ifnum\pst@cnth=\z@
  \edef\PstGridThreeD@PictureYmax{\the\pst@cntd.5}%
\else
  \edef\PstGridThreeD@PictureYmax{\the\pst@cntd}%
\fi
%    \end{macrocode}
%
%   If required, the pspicture environment.
%
%    \begin{macrocode}
\ifPst@PstPicture
%    \end{macrocode}
%
%   If \texttt{PstDebug=1}, we draw a framed box around the grid.
%
%    \begin{macrocode}
  \ifnum\Pst@Debug=\@ne
    \psframebox[framesep=0]{%
  \fi
%    \end{macrocode}
%
%    \begin{macrocode}
  \pspicture(0,\PstGridThreeD@PictureYmin)
            (\the\pst@cntg,\PstGridThreeD@PictureYmax)
\fi
%    \end{macrocode}
%
%    \begin{macrocode}
\pst@cntd=\PstGridThreeD@XPos
\multiply\pst@cntd\PstGridThreeD@XUnit
\pst@cntg=\PstGridThreeD@YPos
\multiply\pst@cntg\PstGridThreeD@YUnit
\pst@cnth=\PstGridThreeD@ZPos
\multiply\pst@cnth\PstGridThreeD@ZUnit
%    \end{macrocode}
%
%   Z faces (only if \cs{PstGridThreeDHookZFace} is defined).
%
%    \begin{macrocode}
\ifx\PstGridThreeDHookZFace\empty
\else
  \pst@cntc=#4
  \advance\pst@cntc\@ne
  \multido{\iz=#4+-\PstGridThreeD@ZUnit}{\pst@cntc}{% Z face hook
    \ThreeDput[normal=0 0 1](\pst@cntd,\pst@cntg,\iz){\PstGridThreeDHookZFace}}
\fi
%    \end{macrocode}
%
%   X faces.
%
%    \begin{macrocode}
\pst@cntc=#2
\advance\pst@cntc\@ne
\multido{\ix=\pst@cntd+\PstGridThreeD@XUnit}{\pst@cntc}{%
  \ThreeDput[normal=1 0 0](\ix,\pst@cntg,\pst@cnth){%
%    \end{macrocode}
%
%   with an X face hook.
%
%    \begin{macrocode}
    \PstGridThreeDHookXFace
    \psgrid[xunit=\PstGridThreeD@YUnit,yunit=\PstGridThreeD@ZUnit,
            subgriddiv=0,gridlabels=0](#3,#4)}}
%    \end{macrocode}
%
%   Y faces.
%
%    \begin{macrocode}
\pst@cnta=#3
\multiply\pst@cnta\PstGridThreeD@YUnit
\advance\pst@cnta\pst@cntg
\pst@cntc=#3
\advance\pst@cntc\@ne
\multido{\iy=\pst@cnta+-\PstGridThreeD@YUnit}{\pst@cntc}{%
  \ThreeDput[normal=0 1 0](\pst@cntd,\iy,\pst@cnth){%
    \PstGridThreeDYFace{#2}{#4}{\iy}}}
%    \end{macrocode}
%
%   Hook at the end, if defined.
%
%    \begin{macrocode}
\PstGridThreeD@HookEnd
%    \end{macrocode}
%
%   Then we close the ``\texttt{pspicture}'' environment, if defined.
%
%    \begin{macrocode}
\ifPst@PstPicture
  \endpspicture
%    \end{macrocode}
%
%   If \texttt{PstDebug=1}, we close of the framed box.
%
%    \begin{macrocode}
  \ifnum\Pst@Debug=\@ne
}
  \fi
%    \end{macrocode}
%
%   And we close the \cs{PstGridThreeD@} macro.
%
%    \begin{macrocode}
\fi}}
%    \end{macrocode}
% \end{macro}
%
%   One face of the three dimensional grid.
%
% \begin{macro}{\PstGridThreeDYFace}
%    \begin{macrocode}
\def\PstGridThreeDYFace#1#2#3{%
%    \end{macrocode}
%
%   Vertical faces.
%
%   First, Y face hook.
%
%    \begin{macrocode}
\PstGridThreeDHookYFace%
\psgrid[xunit=\PstGridThreeD@XUnit,yunit=\PstGridThreeD@ZUnit,
        subgriddiv=0,gridlabels=0](-#1,#2)
\pst@cnta=#1
\advance\pst@cnta\@ne
\pst@cntb=#2
\advance\pst@cntb\@ne
\pst@cntg=#3
\multido{\ia=0+-\PstGridThreeD@XUnit}{\pst@cnta}{%
  \pst@cntc=\multidocount
  \advance\pst@cntc\m@ne
  \multido{\ib=0+\PstGridThreeD@ZUnit}{\pst@cntb}{%
%    \end{macrocode}
%
%   Nodes definition.
%
%    \begin{macrocode}
    \ifPstGridThreeD@Nodes
      \pst@cntd=\multidocount
      \advance\pst@cntd\m@ne
      \pnode(\ia,\ib){Gr3dNode\the\pst@cntc\the\pst@cntg\the\pst@cntd}
    \fi
    \ifx\PstGridThreeDHookNode\empty
    \else
%    \end{macrocode}
%
%   Nodes drawing.
%
%    \begin{macrocode}
      \rput(\ia,\ib){\PstGridThreeDHookNode}
    \fi}}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Default hooks (empty)}
%
% \begin{macro}{\PstGridThreeDHookNode}
%    \begin{macrocode}
\def\PstGridThreeDHookNode{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\PstGridThreeDHookXFace}
%    \begin{macrocode}
\def\PstGridThreeDHookXFace{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\PstGridThreeDHookYFace}
%    \begin{macrocode}
\def\PstGridThreeDHookYFace{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\PstGridThreeDHookZFace}
%    \begin{macrocode}
\def\PstGridThreeDHookZFace{}
%    \end{macrocode}
% \end{macro}
%
%   For the end hook, we must avoid infinite recursion if the hook contain
% a \cs{PstGridThreeD} macro!
%
% \begin{macro}{\PstGridThreeDHookEnd}
%    \begin{macrocode}
\def\PstGridThreeDHookEnd{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\PstGridThreeD@HookEnd}
%    \begin{macrocode}
\def\PstGridThreeD@HookEnd{%
\def\PstGridThreeD@HookEnd{}%
\PstGridThreeDHookEnd}
%    \end{macrocode}
% \end{macro}
%
%   Default definition of a processor node.
%
% \begin{macro}{\PstGridThreeDNodeProcessor}
%    \begin{macrocode}
\def\PstGridThreeDNodeProcessor#1{{%
\psset{unit=0.3}
\pspicture(-0.5,-0.5)(0.5,0.5)
  \pscircle*[linecolor=#1]{0.5}
  \pscircle*[linecolor=white]{0.2}
\endpspicture}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Closing}
%
%   Catcodes restoration.
%
%    \begin{macrocode}
\catcode`\@=\PstAtCode\relax
%    \end{macrocode}
%
%    \begin{macrocode}
%</pst-gr3d>
%    \end{macrocode}
%
% \Finale
%
\endinput
%%
%% End of file `pst-gr3d.dtx'