doc-en/par-plan-en.tex

   1 \section{The object \texttt{plan}}
   2
   3 \subsection{Presentation: type \texttt{plan\/} and type \texttt{solid} }
   4
   5 The  object
   6 \Lkeyval{plan} is special in
   7 \texttt{pst-solides3d}. However, all the objects presented until now have had a common structure:
   8  they are of type \verb+solid+: in other words, they are defined by a list of vertices, faces and colours.
   9
  10 For many applications, it is necessary to have some additional information for a \Index{plane}: an origin, an
  11 orientation, a reference base etc.
  12
  13 To fulfill all these requirements, another
  14 data structure of type \Lkeyval{plan} was created, which allows one to save all this necessary information. These manipulations of the plane will be controlled
  15 by such an object.
  16 Only when rendering takes place will an object of type \Lkeyval{plan} be converted to an object of type \verb+solid+ which conforms to the macro \Lcs{psSolid}.
  17
  18 An object of type \Lkeyval{plan} is used to describe an oriented affine plane.
  19 For a complete definition of such an object,
  20  an origin
  21 $I$, a basis $(\vec u, \vec v)$ for that plane, a scaling of the axis $(I, \vec u)$ and a scaling of the axis
  22 $(I, \vec v)$ are needed.
  23 In addition, we can specify the fineness of the grid---in other words, the number of faces---used to represent that portion of the affine plane
  24 while transforming in an object of the type \verb+solid+.%I'm confused by this last phrase.
  25
  26 This type of object can be used to define planes of section; it is then necessary to define a plane for projection.%check if this keeps your sense
  27
  28 Its usage is quite easy to understand for users of PSTricks.
  29 The only thing that you need to know is that, if we manipulate a
  30 \texttt{\Lkeyword{object}=\Lkeyval{plan}} with the macro \Lcs{psSolid}, we manipulate two objects at the same time: one of type \Lkeyval{plan} and
  31 the other of type \verb+solid+. When we select a backup
  32 of that object (see chapter ``\textit{Advanced usage}'') with the name $monplan$ for example with the option \texttt{\Lkeyword{name}=monplan}, there are
  33 in fact 2 backups that are effected.
  34 The first, with the name \texttt{monplan}, is an object of  type \Lkeyval{plan}, and the second, with the name \texttt{monplan\_s}, is an object of  type \verb+solid+.
  35
  36
  37 \subsection{Defining an oriented plane}
  38
  39 To generate such an object, one uses \texttt{\Lkeyword{object}=\Lkeyval{plan}} which comes with a few arguments:
  40
  41 \begin{itemize}
  42
  43 \item \Lkeyword{definition} which specifies the method to defining the plane.
  44
  45 \item \Lkeyword{args} which specifies the necessary arguments for the method chosen.
  46
  47 \item \texttt{\Lkeyword{base}=$xmin$ $xmax$ $ymin$ $ymax$} which specifies the dimensions of each axis.
  48
  49 \item \verb+[phi]+ (value $0$ by default) which specifies the angle of rotation (in degrees) of the plane around its normal.
  50
  51
  52
  53 \end{itemize}
  54
  55 \subsection{Special options}
  56
  57 The object \verb+plan+ comes with some special options for  viewing:
  58 \begin{itemize}
  59 \item \Lkeyword{planmarks} which shows axes and scaling (with ticks),
  60 \item \Lkeyword{plangrid} which shows the grid,
  61 \item \Lkeyword{showbase} which shows the basis vectors for the plane, and
  62 \item \Lkeyword{showBase} (note the capital letters) which shows the basis vectors of the plane
  63 and draws the associated normal vector.
  64 \end{itemize}
  65 These options apply regardless of the method of definition of the plane.
  66
  67 \begin{center}
  68 \psset{unit=0.4}
  69 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,fontsize=10}
  70 \begin{pspicture*}(-5,-4)(6,4)
  71 \psframe(-5,-4)(5,3)
  72 \psSolid[object=plan,
  73    definition=equation,
  74    args={[0 0 1 0]},
  75    fillcolor=Aquamarine,
  76    base=-2.2 2.2 -3.2 3.2]
  77 \end{pspicture*}
  78 %%
  79 \psset{unit=1}
  80 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,fontsize=10}
  81 \begin{pspicture*}(-5,-4)(6,4)
  82 \psframe(-5,-4)(5,3)
  83 \psSolid[object=plan,
  84    definition=equation,
  85    args={[0 0 1 0]},
  86    fillcolor=Aquamarine,
  87    base=-2.2 2.2 -3.2 3.2,
  88    planmarks]
  89 \end{pspicture*}
  90 %%
  91 \psset{unit=1}
  92 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,fontsize=10}
  93 \begin{pspicture*}(-5,-4)(6,4)
  94 \psframe(-5,-4)(5,3)
  95 \psSolid[object=plan,
  96    definition=equation,
  97    args={[0 0 1 0]},
  98    fillcolor=Aquamarine,
  99    base=-2.2 2.2 -3.2 3.2,
 100    plangrid]
 101 \end{pspicture*}
 102 %%
 103 \psset{unit=1}
 104 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,fontsize=10}
 105 \begin{pspicture*}(-5,-4)(6,4)
 106 \psframe(-5,-4)(5,3)
 107 \psSolid[object=plan,
 108    definition=equation,
 109    args={[0 0 1 0]},
 110    fillcolor=Aquamarine,
 111    base=-2.2 2.2 -3.2 3.2,
 112    showbase]
 113 \end{pspicture*}
 114 %%
 115 \psset{unit=1}
 116 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,fontsize=10}
 117 \begin{pspicture*}(-5,-4)(6,4)
 118 \psframe(-5,-4)(5,3)
 119 \psSolid[object=plan,
 120    definition=equation,
 121    args={[0 0 1 0]},
 122    fillcolor=Aquamarine,
 123    base=-2.2 2.2 -3.2 3.2,
 124    showBase]
 125 \end{pspicture*}
 126 %%
 127 \psset{unit=1}
 128 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,fontsize=10}
 129 \begin{pspicture*}(-5,-4)(6,4)
 130 \psframe(-5,-4)(5,3)
 131 \psSolid[object=plan,
 132    definition=equation,
 133    args={[0 0 1 0]},
 134    fillcolor=Aquamarine,
 135    base=-2.2 2.2 -3.2 3.2,
 136    plangrid,
 137    showBase,
 138    action=none
 139 ]
 140 \end{pspicture*}
 141 \end{center}
 142
 143 These options can be used, even if the plane is not drawn.
 144
 145 \subsection{Defining a plane with a cartesian equation}
 146
 147 The \textit{cartesian equation} of a plane is of the form
 148 \[
 149    ax+by+cz+d=0
 150 \]
 151 The coefficients $a$, $b$, $c$ and $d$ determine an affine plane.
 152
 153 \subsubsection{Usage with default orientation and origin}
 154
 155 To define an affine plane, we can use
 156 \texttt{\Lkeyword{definition}=\Lkeyval{equation}}, and \texttt{\Lkeyword{args}=\{[$a$ $b$ $c$
 157 $d$]\}}. The orientation and origin of the affine plane must be given.
 158
 159 For example, the quadruple $(a, b, c, d) = (0, 0, 1, 0)$ determines
 160 the plane with the equation $z=0$:
 161
 162 \begin{LTXexample}[width=6.5cm]
 163 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,
 164   fontsize=10,unit=0.65}
 165 \begin{pspicture*}(-5,-4)(5,4)
 166 \psSolid[object=plan,
 167    definition=equation,
 168    args={[0 0 1 0]},
 169    fillcolor=Aquamarine,
 170    planmarks,
 171    base=-2.2 2.2 -3.2 3.2,
 172    showbase]
 173 \axesIIID(0,0,0)(2.2,3.2,4)
 174 \end{pspicture*}
 175 \end{LTXexample}
 176
 177 The parameter \texttt{\Lkeyword{base}=$xmin$ $xmax$ $ymin$ $ymax$} specifies the extent along each axis.
 178
 179 \subsubsection{Specifying the origin}
 180
 181 The parameter \texttt{\Lkeyword{origine}=$x_0$ $y_0$ $z_0$} specifies
 182 the origin of the affine plane.
 183 If the chosen point $(x_0, y_0, z_0)$ doesn't fit the equation of the plane, it will be ignored.% The meaning of this is unclear to me.
 184
 185 For example, a plane with the equation $z=0$ for which $(1, 2, 0)$ has been chosen as a possible origin:%(finish the sentence---it does what?)
 186
 187
 188 \begin{LTXexample}[width=6.5cm]
 189 \psset{viewpoint=10 18 60 rtp2xyz,Decran=10,
 190   fontsize=10,unit=0.65cm}
 191 \begin{pspicture*}(-4,-5.5)(6,4)
 192 \psSolid[object=plan,
 193    definition=equation,
 194    args={[0 0 1 0]},
 195    fillcolor=Aquamarine,
 196    origine=1 2 0,
 197    base=-2.2 2.2 -3.2 3.2,
 198    planmarks]
 199 \axesIIID(0,0,0)(2.2,3.2,4)
 200 \end{pspicture*}
 201 \end{LTXexample}
 202
 203
 204 \subsubsection{Specifying the orientation}
 205
 206 If the chosen orientation is unsatisfactory,
 207 we can specify an angle of rotation $\alpha $ (in degrees) around the normal of the plane with the syntax
 208 \texttt{\Lkeyword{args}=\{[a b c d] $\alpha $\}}.
 209
 210
 211 \begin{LTXexample}[width=6.5cm]
 212 \psset{viewpoint=10 18 60 rtp2xyz,
 213   Decran=10,fontsize=10,unit=0.65cm}
 214 \begin{pspicture*}(-5,-4)(5,4)
 215 \psSolid[object=plan,
 216    definition=equation,
 217    args={[0 0 1 0] 90},
 218    fillcolor=Aquamarine,
 219    base=-2.2 2.2 -3.2 3.2,
 220    planmarks]
 221 \axesIIID(0,0,0)(3.2,2.2,4)
 222 \end{pspicture*}
 223 \end{LTXexample}
 224
 225
 226 \subsection{Defining a plane using a normal vector and a point}
 227
 228 It is also possible to define a plane by giving a point and a normal vector.
 229  In this case one uses the parameter \texttt{\Lkeyword{definition}=\Lkeyval{normalpoint}}.
 230
 231 If wanted, we can specify the orientation, but it can be omitted.
 232
 233 \subsubsection{First Method: orientation Unspecified}
 234
 235 We use \texttt{\Lkeyword{args}=\{$x_0$ $y_0$ $z_0$ [$a$ $b$ $c$]\}} where $(x_0,
 236 y_0, z_0)$ is the origin of the affine plane, and $(a, b, c)$ is a vector normal to that plane.
 237
 238
 239 \begin{LTXexample}[width=6.5cm]
 240 \psset{viewpoint=10 18 60 rtp2xyz,
 241   Decran=10,fontsize=10,unit=0.65cm}
 242 \begin{pspicture*}(-5,-4)(5,4)
 243 \psSolid[object=plan,
 244    definition=normalpoint,
 245    args={0 0 0 [0 0 1]},
 246    fillcolor=Aquamarine,
 247    planmarks,
 248    base=-2.2 2.2 -3.2 3.2,
 249    showbase]
 250 \axesIIID(0,0,0)(2.2,3.2,4)
 251 \end{pspicture*}
 252 \end{LTXexample}
 253
 254
 255 \subsubsection{Second Method: Specifying an angle of rotation}
 256
 257 We use \texttt{\Lkeyword{args}=\{$x_0$ $y_0$ $z_0$ [$a$ $b$ $c$ $\alpha
 258 $]\}} where $(x_0, y_0, z_0)$ is the origin of the affine plane, $(a, b,
 259 c)$ a normal vector of that plane, and $\alpha $ the angle of rotation (in
 260 degrees) around the normal vector of that plane.
 261
 262
 263
 264 \begin{LTXexample}[width=6.5cm]
 265 \psset{viewpoint=10 18 60 rtp2xyz,
 266   Decran=10,fontsize=10,unit=0.65}
 267 \begin{pspicture*}(-5,-4)(5,4)
 268 \psSolid[object=plan,
 269    definition=normalpoint,
 270    args={0 0 0 [0 0 1 45]},
 271    fillcolor=Aquamarine,
 272    planmarks,
 273    base=-2.2 2.2 -3.2 3.2,
 274    showbase]
 275 \axesIIID(0,0,0)(2.2,3.2,4)
 276 \end{pspicture*}
 277 \end{LTXexample}
 278
 279
 280 \subsubsection{Third Method: Specifying the first basis vector}
 281
 282 We use \texttt{\Lkeyword{args}=\{$x_0$ $y_0$ $z_0$ [$u_x$ $u_y$ $u_z$ $a$ $b$
 283 $c$ ]\}} where $(x_0, y_0, z_0)$ is the origin of the affine plane,
 284 $(a, b, c)$ a normal vector of that plane, and $(u_x, u_y, u_z)$ the first basis vector for that plane.
 285
 286
 287 \begin{LTXexample}[width=6.5cm]
 288 \psset{viewpoint=10 18 60 rtp2xyz,
 289   Decran=10,fontsize=10,unit=0.65cm}
 290 \begin{pspicture*}(-5,-4)(5,4)
 291 \psSolid[object=plan,
 292    definition=normalpoint,
 293    args={0 0 0 [1 1 0 0 0 1]},
 294    fillcolor=Aquamarine,
 295    planmarks,
 296    base=-2.2 2.2 -3.2 3.2,
 297    showbase,
 298 ]
 299 \axesIIID(0,0,0)(2.2,3.2,4)
 300 \end{pspicture*}
 301 \end{LTXexample}
 302
 303
 304 \subsubsection{Fourth Method: Specifying the first basis vector and an angle of rotation}
 305
 306 We use \texttt{\Lkeyword{args}=\{$x_0$ $y_0$ $z_0$ [$u_x$ $u_y$ $u_z$ $a$ $b$
 307 $c$ $\alpha $]\}} where $(x_0, y_0, z_0)$ is the origin of the affine plane,
 308 $(a, b, c)$ is a normal vector of that plane, $(u_x, u_y, u_z)$ is the first basis vector for that plane and $\alpha $ (in degrees) is a rotation around the axis of the normal vector.
 309
 310
 311 \begin{LTXexample}[width=6.5cm]
 312 \psset{viewpoint=10 18 60 rtp2xyz,
 313   Decran=10,fontsize=10,unit=0.65cm}
 314 \begin{pspicture*}(-5,-4)(5,4)
 315 \psSolid[object=plan,
 316    definition=normalpoint,
 317    args={0 0 0 [1 1 0 0 0 1 45]},
 318    fillcolor=Aquamarine,
 319    planmarks,
 320    base=-2.2 2.2 -3.2 3.2,
 321    showbase]
 322 \axesIIID(0,0,0)(2.2,3.2,4)
 323 \end{pspicture*}
 324 \end{LTXexample}
 325
 326
 327 \subsection{Defining a plane from a face of a solid}
 328
 329 We use \texttt{\texttt{\Lkeyword{definition}=\Lkeyval{solidface}}} with the arguments
 330 \texttt{\texttt{\Lkeyword{args}=$name$ $i$}} where $name$ is the name of the designated solid and
 331 $i$ is the index of the face. The origin is taken as the centre of the chosen face.
 332
 333 In the example below, the plane is defined through the face with the index 0 from the cube named $A$.
 334
 335
 336 \begin{LTXexample}[width=6.5cm]
 337 \psset{viewpoint=10 18 20 rtp2xyz,Decran=8}
 338 \begin{pspicture}(-3.5,-2)(3,2.5)
 339 \psset{solidmemory}
 340 \psSolid[object=cube,a=2,fontsize=20,numfaces=all,name=A]
 341 \psSolid[object=plan,
 342    definition=solidface,
 343    args=A 0,
 344    showBase]
 345 \end{pspicture}
 346 \end{LTXexample}
 347
 348 If the user specifies the coordinates $(x, y, z)$ within the macro
 349 \verb+\psSolid[...](+$x,y,z$\verb+)+, a plane is generated parallel to the face with  index $i$ of the solid $name$, and translated to the point $(x, y, z)$ which now is taken as the origin.
 350
 351
 352 \begin{LTXexample}[width=6.5cm]
 353 \psset{viewpoint=10 18 20 rtp2xyz,Decran=8}
 354 \begin{pspicture}(-3.5,-1.5)(3,3)
 355 \psset{solidmemory}
 356 \psSolid[object=cube,a=2,fontsize=20,numfaces=all,name=A]
 357 \psSolid[object=plan,
 358    definition=solidface,
 359    args=A 0,
 360    showBase](0,0,2)
 361 \end{pspicture}
 362 \end{LTXexample}
 363
 364 \endinput