The ‘pst-gr3d’ package

A PSTricks package for three dimensional grids

Denis Girou^{∗}

Version 1.3 February 19, 2001

Documentation revised February 19, 2001

Abstract

This package allow to draw three dimensional grids using the macro \PstGridThreeD. We can also specify how nodes of the grid must look like.

Contents

1 Introduction

‘pst-gr3d’ 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.

   The syntax is simply: \PstGridThreeD[optional parameters](X,Y,Z)

We can define a macro \PstGridThreeDHookNode to specify how the nodes at the interconnections must look like, and there are also some other hooks that can be used for special purposes.

The default viewpoint is (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 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 by hand, using the \psframebox[framesep=0]{...} construction to found the correct values by attempts and errors — fortunately, in practice few attempts are often enough...

∗CNRS/IDRIS — Centre National de la Recherche Scientifique / Institut du Développement et des Ressources en Informatique Scientifique — Orsay — France — <Denis.Girou@idris.fr>.

2 Usage

2.1 Parameters and hooks

The three required parameters specify the lengths in the X, Y and Z directions, respectively:

1 \PstGridThreeD(3,1,1)\hfill
2 \PstGridThreeD(1,3,1)\hfill
3 \PstGridThreeD(1,1,3)

Of course, we can use all the relevant generic PSTricks parameters, specially those applying to grids:

1 \PstGridThreeD[unit=1.5](1,1,1)\hfill
2 \PstGridThreeD[viewpoint=1.2 -1.5 0.4,griddots=7](1,3,2)\hfill
3 \PstGridThreeD[gridwidth=0.08,gridcolor=red](3,2,2)\hfill
4 \begin{pspicture}(-1.7,0)(0.8,3.6)
5 \PstGridThreeD[viewpoint=-0.4 -0.6 0.8,PstPicture=false](1,3,2)
6 \end{pspicture}

We can draw one and two dimensional grids, using degenerated cases:

1 \PstGridThreeD(0,4,0)\hfill
2 \PstGridThreeD[linewidth=0.05](0,3,1)\hfill
3 \PstGridThreeD[griddots=5](3,1,0)

To change the way the grids are drawn, we can also use nine specific parameters and five specific hooks:

PstDebug (integer) : to obtain some internal debugging informations — here, a framed box around the boundix box used (the pspicture environment) could be drawn. It can take the values 0 (no debug) or 1. (Default: 0 — no debugging informations).

PstPicture (boolean) : to define or not a pspicture environment for the grid. We have to define this parameter to false mainly if we choose a viewpoint different than the default one — see examples later (Default: true — which is not the case for basic PSTricks objects).

GridThreeDXUnit (integer) : unit coefficient in the X direction (Default: 1 — it must be an integer, not a real).

GridThreeDYUnit (integer) : unit coefficient in the Y direction (Default: 1 — it must be an integer, not a real).

GridThreeDZUnit (integer) : unit coefficient in the Z direction (Default: 1 — it must be an integer, not a real).

1 \PstGridThreeD[GridThreeDXUnit=2](1,1,1)\hfill
2 \PstGridThreeD[GridThreeDYUnit=3](1,1,1)\hfill
3 \PstGridThreeD[unit=0.5,GridThreeDZUnit=4](4,3,1)

GridThreeDXPos (integer) : position of the origin in the X direction (Default: 0 — it must be an integer, not a real).

GridThreeDYPos (integer) : position of the origin in the Y direction (Default: 0 — it must be an integer, not a real).

GridThreeDZPos (integer) : position of the origin in the Z direction (Default: 0 — it must be an integer, not a real).

These parameters are in fact mainly useful if we want to superpose grids, which can be done easily using the \PstGridThreeDHookEnd macro (see description below):

1 % First grid
2 \def\PstGridThreeDHookEnd{%
3 \PstGridThreeD[PstPicture=false,gridwidth=0.1,
4  GridThreeDXPos=1](0,2,1)}
5 \PstGridThreeD(1,3,2)\hfill
6 % Second grid
7 \def\PstGridThreeDHookEnd{%
8 \PstGridThreeD[PstPicture=false,gridwidth=0.1,
9  GridThreeDYPos=1](1,2,1)}
10 \PstGridThreeD(1,3,2)\hfill
11 % Third grid
12 \def\PstGridThreeDHookEnd{%
13 \PstGridThreeD[PstPicture=false,gridwidth=0.1,
14  gridcolor=green,
15  GridThreeDYPos=2,
16  GridThreeDZPos=1](1,1,1)}
17 \PstGridThreeD(1,3,2)

GridThreeDNodes (boolean) : to define or not the nodes at interconnection points of the grid. The nodes are named Gr3dNodeXYZ. We can use the Rx and Ry parameters to position the relevant material relatively to the nodes, specifying the distance in cartesian coordinates. The parameter angle used with Rx allow to use polar ones. (Default: false — no nodes defined).

{130 \atop 131}

                      1 \PstGridThreeD[GridThreeDNodes=true](1,3,1)
                      2 \SpecialCoor
                      3 \rput*(Gr3dNode130){\footnotesize 130}
                      4 \rput*(Gr3dNode131){\footnotesize 131}

\PstGridThreeDHookNode (macro) : this hook allow to define the form of the nodes. A predefined \PstGridThreeDNodeProcessor macro exist, which define a circle with a little white circle in it. We can also use the \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 (Default: empty).

1 % First grid
2 \def\PstGridThreeDHookNode{%
3 \begin{pspicture}(-0.15,-0.15)(0.15,0.15)
4  \pscircle*[linecolor=magenta]{0.15}
5 \end{pspicture}}
6 \PstGridThreeD(1,2,2)\hfill
7 % Second grid
8 \definecolor{LightBlue}{rgb}{0.68,0.85,0.9}
9 \def\PstGridThreeDHookNode{%
10 \PstGridThreeDNodeProcessor{LightBlue}}
11 \PstGridThreeD[unit=0.7](2,3,3)\hfill
12 % Third grid
13 \def\PstGridThreeDHookNode{%
14 \ifcase\iy
15  \PstGridThreeDNodeProcessor{magenta}%
16  \or\PstGridThreeDNodeProcessor{yellow}%
17  \or\PstGridThreeDNodeProcessor{cyan}%
18  \else\PstGridThreeDNodeProcessor{green}%
19 \fi}
20 \PstGridThreeD(1,3,1)

\PstGridThreeDHookEnd (macro) : this hook allow to execute a macro at the end of the grid drawing, before the pspicture environment closing. This is specially interesting for instance to superpose grids, if we take care to define the PstPicture parameter to false for them (Default: empty).

1 \def\PstGridThreeDHookEnd{{%
2 \psset{PstPicture=false,gridwidth=0.1}
3 {\def\PstGridThreeDHookNode{%
4  \PstGridThreeDNodeProcessor{blue}}%
5  \PstGridThreeD[gridcolor=blue,
6  GridThreeDZPos=3](0,7,0)}%
7 {\def\PstGridThreeDHookNode{%
8  \PstGridThreeDNodeProcessor{red}}%
9  \PstGridThreeD[gridcolor=red,
10  GridThreeDXPos=1,
11  GridThreeDZPos=1](0,3,1)}%
12 {\def\PstGridThreeDHookNode{%

13  \PstGridThreeDNodeProcessor{green}}%
14  \PstGridThreeD[gridcolor=green,
15  GridThreeDYPos=6](1,1,1)}}}
16 \PstGridThreeD(1,7,3)

\PstGridThreeDHookXFace (macro) : this hook allow to execute a macro before to draw the X faces (Default: empty).

\PstGridThreeDHookYFace (macro) : this hook allow to execute a macro before to draw the Y faces (Default: empty).

\PstGridThreeDHookZFace (macro) : this hook allow to execute a macro before to draw the Z faces (Default: empty).

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 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.

1 {\def\PstGridThreeDHookXFace{%
2 \ifnum\multidocount=1\psframe*[linecolor=cyan](3,2)\fi}%
3 \PstGridThreeD(1,3,2)}\hfill
4 {\def\PstGridThreeDHookYFace{%
5 \ifnum\multidocount=2\psframe*[linecolor=yellow](-3,0)(0,2)\fi}%
6 \PstGridThreeD(3,1,2)}\hfill
7 {\def\PstGridThreeDHookZFace{%
8 \ifnum\multidocount=2
9 \else
10  \psframe*[linecolor=yellow](3,3)
11 \fi}%
12 \PstGridThreeD(3,3,2)}

3 Examples

We give here more advanced examples, most of them from technical drawings describing the architecture of a multiprocessors supercomputer.

002 221 222 200 210 220

1 \PstGridThreeD[GridThreeDNodes=true](2,2,2)
2 \SpecialCoor
3 \rput*(Gr3dNode002){\tiny 002}
4 \rput*(Gr3dNode221){\tiny 221}
5 \rput([Rx=0.3]Gr3dNode222){\tiny 222}
6 \multido{\i=0+1}{3}{%
7 \rput([Rx=0.3,Ry=-0.3]Gr3dNode2\i0){2\i0}}

Network Nodes

1 \definecolor{LightBlue}{rgb}{0.68,0.85,0.9}
2 \def\PstGridThreeDHookNode{%
3 \PstGridThreeDNodeProcessor{LightBlue}}
4 \PstGridThreeD[GridThreeDNodes=true](1,2,2)
5 \SpecialCoor
6 \rput([Rx=-0.15,Ry=0.3]Gr3dNode122){%
7 \psline{<-}(0.5;35)}
8 \rput([Rx=0.35,Ry=0.8]Gr3dNode122){Network}
9 \rput([Rx=0.15,angle=-40]Gr3dNode110){%
10 \psline{<-}(0.8;-60)}
11 \rput([Rx=0.25,angle=-100]Gr3dNode120){%
12 \psline{<-}(0.8;-100)}
13 \rput([Rx=1.5,angle=-55]Gr3dNode010){Nodes}

                       1 \definecolor{Orange}{rgb}{1.,0.65,0.}
                       2 \def\PstGridThreeDHookNode{%
                       3 \PstGridThreeDNodeProcessor{Orange}}
                       4 \psset{unit=1.3}
                       5 \PstGridThreeD[GridThreeDNodes=true](1,2,2)
                       6 \SpecialCoor
                       7 \psset{arrows=<->,arrowscale=2}
                       8 \ThreeDput[normal=0 0 -1](0,0,0){%
                       9 \ncloop[linecolor=red,arm=0.35,
                      10  loopsize=0.6,angleA=-90,angleB=90]
                      11  {Gr3dNode022}{Gr3dNode002}
                      12 \ncloop[linecolor=green,arm=0.7,
                      13  nodesepA=0.18,nodesepB=0.12,
                      14  loopsize=-0.5,angleA=180]
                      15  {Gr3dNode002}{Gr3dNode102}}

 1 \def\PstGridThreeDHookEnd{{%
 2 \psset{PstPicture=false,gridwidth=0.1}
 3 {\def\PstGridThreeDHookNode{%
 4  \PstGridThreeDNodeProcessor{blue}}%
 5  \PstGridThreeD[gridcolor=blue,
 6  GridThreeDZPos=3](0,7,0)}%
 7 {\def\PstGridThreeDHookNode{%
 8  \PstGridThreeDNodeProcessor{red}}%
 9  \PstGridThreeD[gridcolor=red,
10  GridThreeDXPos=1,
11  GridThreeDZPos=1](0,3,1)}%
12 {\def\PstGridThreeDHookNode{%
13  \PstGridThreeDNodeProcessor{green}}%
14  \PstGridThreeD[gridcolor=green,
15  GridThreeDYPos=6](1,1,1)}}}
16 \PstGridThreeD[gridwidth=0.04,
17  GridThreeDNodes=true](1,7,3)
18 \SpecialCoor
19 \rput([Rx=0.15,angle=140]Gr3dNode033){%
20 \psline[linecolor=blue]{<-}(0.8;150)}
21 \rput([Rx=0.95,angle=140]Gr3dNode033){%
22 \shortstack{1d grid\\\footnotesize (X=8,Y=1,Z=1)}}
23 \rput([Rx=0.15,angle=-50]Gr3dNode121){%
24 \psline[linecolor=red]{<-}(1.2;-50)}
25 \rput([Rx=1.5,angle=-55]Gr3dNode121){%
26 \shortstack{2d grid\\\footnotesize (X=4,Y=2,Z=1)}}
27 \rput([Rx=0.2,angle=-100]Gr3dNode160){%
28 \psline[linecolor=green]{<-}(0.8;-100)}
29 \rput([Rx=1.4,angle=-100]Gr3dNode160){%
30 \shortstack{3d grid\\\footnotesize (X=2,Y=2,Z=2)}}

1d grid

(X=8,Y=1,Z=1)

2d grid

(X=4,Y=2,Z=1)

3d grid

(X=2,Y=2,Z=2)