diff options
Diffstat (limited to 'Master/texmf-dist/doc/metapost/featpost/doc/featpostdocsource.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/featpost/doc/featpostdocsource.tex | 2124 |
1 files changed, 2124 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/metapost/featpost/doc/featpostdocsource.tex b/Master/texmf-dist/doc/metapost/featpost/doc/featpostdocsource.tex new file mode 100644 index 00000000000..749dd7ac0cf --- /dev/null +++ b/Master/texmf-dist/doc/metapost/featpost/doc/featpostdocsource.tex @@ -0,0 +1,2124 @@ +\usepackage{amsmath,amssymb,graphicx} +\DeclareGraphicsRule{*}{mps}{*}{} +\graphicspath{{../allps/}} +\newfont{\normald}{logod10 scaled 1000} +\newcommand{\MF}{{\normald METAFONT}} +\newcommand{\MP}{{\normald METAPOST}} +\newcommand{\FP}{{\normald FEATPOST}} +\newcommand{\changeableframetitle}[1]{\mode<presentation>{\frametitle{#1}}} +\newcommand{\myem}[1]{\texttt{#1}} +\title{\FP\ manual} +\author{\href{mailto:lnobreg@gmail.com}{L. Nobre G.}} +\date{0.8.2} +\begin{document} +\mode<article>{\maketitle} +\frame{\titlepage} +\frame{ + \changeableframetitle{Abstract} + \FP\ is an extension of the \MP\ language that has a fairly large set of + \alert{feat}ures to facilitate the production of schematic diagrams, both in + three dimensions (3D) and two dimensions (2D). + + These schematic diagrams are vectorial and focus on the representation + of edges (unlike ray-traced raster images that focus on surfaces). +} + +\mode<article>{\tableofcontents} + +\section{Getting started} + +\frame{ + \changeableframetitle{Getting started} + \myem{input featpost3Dplus2D;} +} + +\section{Propaganda for \MP} + +\frame{ + \changeableframetitle{Propaganda} + \MP\ is based on mathematics and that is beautiful. + + \MP\ is also the realm og graphic parametrization and that is beyond + description. +} + +\subsection{A bit of history} + +\frame{ + \changeableframetitle{A bit of history} + Donald Knuth -- \textit{The Art of Computer Programming} + \begin{itemize} + \item Volume1, 1969, hot metal + \item Volume2, $2^{\mathrm{\underline{nd}}}$ ed., 1977, photographic + \item \TeX, v1, 1978, $\mathrm{v}\longrightarrow\pi$ + \item \MF, v1, 1979, $\mathrm{v}\longrightarrow e$ + \item AMS, 1983 + \item APS, AIP, OSA, AAS, Springer-Verlag + \item \MP, 1994, John Hobby + \end{itemize} +} + +\subsection{What is \MP ?} + +\frame{ + \changeableframetitle{Main features of \MP} + \begin{itemize} + \item It is easy to express geometry as \MP\ code + \item \MP\ outputs \myem{postscript} + \item Very good control of 2D B\'{e}zier splines + \item Special 2D operators + \item Many operators work the same way in 1, 2, 3 or 4D + \item Linear equations + \item May include \LaTeX + \item May be included in \LaTeX + \end{itemize} +} + +\subsubsection{Linear equations} + +\frame{ + \changeableframetitle{Linear equations} + \begin{center} + \includegraphics[height=40mm]{intersection2D.1} + \\ + \begin{itemize} + \item Constraints may be expressed as linear equations + \item No need to explicitly assign calculations to unknowns + \end{itemize} + \end{center} +} + +\subsubsection{Built-ins} + +\frame{ + \changeableframetitle{Other \MP\ built-ins} + \begin{itemize} + \item \myem{color} + \begin{tabular}[t]{cc} + \myem{(\textit{red,green,blue})}$\longrightarrow$\myem{(X,Y,Z)} \\ + \myem{black} & (0,0,0) \\ + \myem{red} & (1,0,0) \\ + \myem{green} & (0,1,0) \\ + \myem{blue} & (0,0,1) \\ + \myem{white} & (1,1,1) + \end{tabular} + + \item \myem{cmykcolor} + + \myem{(\textit{cyan,magenta,yellow,black})}$\longrightarrow$\myem{(X,Y,Z,W)} + (\href{http://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation}{quaternions}, + \href{http://en.wikipedia.org/wiki/Homogeneous_coordinates}{homogeneous + coordinates}, 4D splines, animation frames, straight line + segments, etc.) + + \item \myem{scantokens ``\textsl{string of commands}''} (allows + sorting of generic graphic elements) + \end{itemize} +} + +\subsection{Main reason} + +\frame{ + \changeableframetitle{Use \MP\ because} + \MP\ helps the user to experiment different + diagram layouts without changing specified geometric relationships + among diagram elements. +} + +\section{First taste of \FP} + +\frame{ + \changeableframetitle{First taste of \FP} +Each perspective depends on the point of view. \FP\ uses the global +variable \myem{f}, of \myem{color} type, to store the $(X,Y,Z)$ +space coordinates of the point of view. Also important is the aim of view +(global variable \myem{viewcentr}). Both define the line of +view. +} + +\frame{ +The perspective +consists of a projection from space coordinates into planar $(u,v)$ +coordinates on the projection plane. \FP\ uses a projection plane that +is perpendicular to the line of view and contains the +\myem{viewcentr}. Furthermore, one of the projection plane axes is +horizontal and the other is on the intersection of a vertical plane +with the projection plane. ``Horizontal'' means parallel to the +$XY$ plane. The projection plane axes are perpendicular to each other. +} + + +One consequence of this setup is that \myem{f} and \myem{viewcentr} +must not be on the same vertical line. The three kinds of projection known +to \FP\ are schematized in figures \ref{paraproj}, \ref{coniproj} and +\ref{spheproj}, which correspond to the diagrams presented in +\S\ref{perspectives}. The macro that actually does the projection is, in all +cases, \myem{rp}. + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{thethreekindsofperspec.1} + \end{center} + \caption{Parallel projection.} + \label{paraproj} +\end{figure} +} +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{thethreekindsofperspec.2} + \end{center} + \caption{Central projection.} + \label{coniproj} +\end{figure} +} +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{thethreekindsofperspec.3} + \end{center} + \caption{Spherical projection. The + spherical projection is the composition of two operations: (i)~there + is a projection onto a sphere and (ii)~the sphere is plaited + onto the projection plane.} + \label{spheproj} +\end{figure} +} + +\frame{ +Some problems often require defining angles, and diagrams are +needed to visualize their meanings. The \myem{angline} and +\myem{squareangline} macros support this (see figure \ref{figcartaxes2}). +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{cartaxes.2} + \end{center} + \caption{Example that uses \myem{cartaxes}, \myem{squareangline}, + \myem{angline} and \myem{getangle}.} + \label{figcartaxes2} +\end{figure} +} + +\frame{ +Visualizing parametric lines is another need. When two +lines cross, one should be able to see which line is in front of the +other. The macro \myem{emptyline} can help here (see figure +\ref{induction}). +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{parafuso.1} + \end{center} + \caption{\FP\ diagram using \myem{emptyline}.} + \label{induction} +\end{figure} +} + +\frame{ +Cuboids and labels are always needed. The macros \myem{kindofcube} +and \myem{labelinspace} fulfill this need (see figure +\ref{cublab}). The macro \myem{labelinspace} does +not project labels from 3D into 2D. It only \myem{Transform}s the +label in the same +way as its bounding box, that is, the same way as two perpendicular sides +of its bounding box. This is only exact for parallel perspectives. +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{labelconstruct.1} + \end{center} + \caption{\FP\ diagram using the macros \myem{kindofcube} + and \myem{labelinspace}.} + \label{cublab} +\end{figure} +} + +\frame{ +\begin{sloppypar} +Some curved surface solid objects can be drawn with \FP. Among them +are cones (\myem{very\-good\-cone}), cylinders (\myem{rigorous\-disc}) +and globes (\myem{trop\-ical\-globe}). These can also cast their shadows +on a horizontal plane (see figure +\ref{anddisc}). The production of shadows +involves the global variables \myem{LightSource}, \myem{ShadowOn} +and \myem{HoriZon}. +\end{sloppypar} +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{stageforthree.3} + \end{center} + \caption{\FP\ diagram using + the macros \myem{rigorousdisc}, \myem{verygoodcone}, + \myem{tropicalglobe} and \myem{setthestage}.} + \label{anddisc} +\end{figure} +} + +\frame{ +Another very common need is the plotting of functions, usually satisfied +by software such as Gnuplot (\url{http://www.gnuplot.info/}) or Gri +(\url{http://gri.sourceforge.net/}). +Nevertheless, there are always new plots to draw. One specific \FP\ +kind of plot is the ``triangular grid triangular domain +surface'' (see figure \ref{triangulartrimesh}). +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{triangulartrimesh.1} + \end{center} + \caption{\FP\ surface plot using + the macro \myem{hexagonaltrimesh}.} + \label{triangulartrimesh} +\end{figure} +} + +\frame{ +One feature that merges 2D and 3D involves what might be called +``fat sticks''. A fat stick resembles the Teflon magnets used to mix +chemicals. They have volume but can be drawn like a small straight +line segment stroked with a \myem{pencircle}. Fat sticks may be used +to represent direction fields (unitary vector fields without arrows). +See figure \ref{nsmetica}. +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{nsmetica.1} + \end{center} + \caption{\FP\ direction field macro \myem{director\_invisible} was + used to produce this representation of the molecular structure of + a Smectic A liquid crystal.} + \label{nsmetica} +\end{figure} +} + +\frame{ +Finaly, it is important to remember that some capabilities of \FP, +although usable, may be considered ``buggy'' or only partially +implemented. These include the +calculation of intersections between polygons, as in figure +\ref{figsharpraytrace}, and the drawing of cylinders with axial holes, as +in figure \ref{smoothtorus}. +} + +\frame{ +\begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.65\columnwidth]{twoholes.1} + \end{center} + \caption{\FP\ example containing a \myem{smoothtorus} and a + \myem{rigorousdisc} with a hole.} + \label{smoothtorus} +\end{figure} +} + +\subsection{Moving on, slowly} + +\frame{ +It is highly beneficial to +be able to understand and cope with \MP\ error messages as +\FP\ has no protection against mistaken inputs. One +probable cause of errors is the use of variables with the name of +procedures (macros), like +\begin{quote} +\begin{verbatim} +X, Y, Z, W, N, rp, cb, ps +\end{verbatim} +\end{quote} +All other procedure names have six or more characters. +} + +\frame{ +The user must be aware that \MP\ has a limited arithmetic power +and that the author has limited programming skills, +which may lead to unperfect 3D figures, very long processing +time or shear bugs. +It's advisable not to try very complex diagrams at first +and it's recommended to +keep 3D coordinates near order 1 (default \MP\ units). +} + +\frame{ +All three-dimensional \FP\ macros are build apon +the \MP\ +\myem{color} variable type. It looks like this: +\begin{quote} +\begin{verbatim} +(red,green,blue) +\end{verbatim} +\end{quote} +Its components may, nevertheless, +be arbtitrary numbers, like: +\begin{quote} +\begin{verbatim} +(X,Y,Z) +\end{verbatim} +\end{quote} +So, the +\myem{color} type is adequate to define not only colors but +also 3D points and vectors. +} + +\frame{ +One very minimalistic example program could be: +\begin{quote} +\begin{verbatim} +input featpost3Dplus2D; +beginfig(1); + cartaxes(1,1,1); +endfig; +end; +\end{verbatim} +\end{quote} +where \myem{cartaxes} is a +\FP\ macro that produces +the Cartesian referential. +} + +One small example program may be: +\begin{quote} +\begin{verbatim} +input featpost3Dplus2D; +f := 5.4*(1.5,0.5,1); +Spread := 30; +beginfig(1); + numeric gridstep, sidenumber, i, j, coord, aa, ab, ac; + color pa; + gridstep = 0.9; + sidenumber = 10; + coord = 0.5*sidenumber*gridstep; + for i=0 upto sidenumber: + for j=0 upto sidenumber: + pa := (-coord+j*gridstep,-coord+i*gridstep,0); + aa := uniformdeviate(360); + ab := uniformdeviate(180); + ac := uniformdeviate(90); + kindofcube( false, false, pa, aa, ab, ac, 0.4, 0.4, 0.9 ); + endfor; + endfor; +endfig; +end. +\end{verbatim} +\end{quote} +where \myem{kindofcube} +is a \FP\ macro that produces +a rectangular prism (cuboid). See figure \ref{figkindofcube1}. + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{kindofcube.1} +\end{center} + \caption{Example that uses \myem{kindofcube}.} +\label{figkindofcube1} +\end{figure}} + +\frame{ +The main variable of any three-dimensional figure is the +point of view. \FP\ uses the variable \myem{f} +as the point of view. \myem{Spread} is another global +variable that controls the size of the projection. +} + +Another example may be: +\begin{quote} +\begin{verbatim} +input featpost3Dplus2D; +f := (13,7,3.5); +Spread := 35; +beginfig(1); + numeric i, len, wang, reflen, frac, coordg; + numeric fws, NumLines, inray, outay; + path conepath, cira, cirb, ella, ellb, tuba, tubb, tubc; + color axe, aroc, cubevertex, conecenter, conevertex; + color allellaxe, ellaaxe, ellbaxe, pca, pea, pcb, peb; + frac := 0.5; + len := 0.6; + wang := 60; + axe := (0,cosd(90-wang),sind(90-wang)); + fws := 4; + reflen := 0.2*fws; + outay := 0.45*fws; + inray := 0.7*outay; + coordg := frac*fws; + NumLines := 30; + HoriZon := -0.5*fws; + setthestage( 0.5*NumLines, 2*fws ); + cubevertex = (0.12*fws,-0.5*fws,-0.5*fws); + kindofcube(false,true,cubevertex,180,0,0,0.65*fws,0.2*fws,fws); + aroc := outay*(0,cosd(wang),sind(wang))-0.5*(0,fws,fws); + rigorousdisc( inray, true, aroc, outay, axe*len ); + allellaxe := reflen*( 0.707, 0.707, 0 ); + ellaaxe := reflen*( 0.707, -0.707, 1.0 ); + ellbaxe := reflen*( -0.707, 0.707, 1.0 ); + conecenter = ( coordg, coordg, -0.5*fws ); + pca := ( coordg, -coordg, -0.5*fws ); + pcb := ( -coordg, coordg, -0.5*fws ); + pea := ( coordg, -coordg, 0.9*fws ); + peb := ( -coordg, coordg, 0.9*fws ); + cira := goodcirclepath( pca, blue, reflen ); + cirb := goodcirclepath( pcb, blue, reflen ); + ella := ellipticpath( pea, allellaxe, ellaaxe ); + ellb := ellipticpath( peb, allellaxe, ellbaxe ); + tuba := twocyclestogether( cira, ella ); + tubb := twocyclestogether( cirb, ellb ); + tubc := twocyclestogether( ella, ellb ); + unfill tubb; draw tubb; + unfill tubc; draw tubc; + unfill tuba; draw tuba; + conevertex = conecenter + ( -3.5*reflen, 0, 0.8*fws ); + verygoodcone(false,conecenter,blue,reflen,conevertex); +endfig; +end. +\end{verbatim} +\end{quote} +where we find a \myem{rigorousdisc} +and a \myem{verygoodcone} +in addition to +\myem{setthestage}, \myem{ellipticpath}, +\myem{twocyclestogether} and +\myem{kindofcube}. See figure \ref{figstageforthree}. + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{stageforthree.1} +\end{center} + \caption{Example that uses \myem{rigorousdisc} and + \myem{verygoodcone}.} +\label{figstageforthree} +\end{figure}} + +\subsection{Main reason} + +\frame{ + \changeableframetitle{Use \FP\ because} +\FP\ has already been used in scientific publications: +\begin{itemize} +\item Figure 1 of + \href{http://pre.aps.org/abstract/PRE/v60/i3/p2985_1}{\textit{Phys. Rev. E}, + \textbf{60}, 2985-2989 (1999)}. +\item Figures 4, 6 and 8 of + \href{http://www.springerlink.com/content/pmwu8a2y9pkxr5rq/}{\textit{Eur. + Phys. J. E}, \textbf{2}, 351-358 (2000)}. +\item Figures 8 and 12 of + \href{http://www.springerlink.com/content/w41308176vnk7408/}{\textit{Eur. + Phys. J. E}, \textbf{20}, 55-61 (2006)}. +\end{itemize} +} + +\section{\FP\ in detail} + +\frame{ + \changeableframetitle{List of features} + 3D dots, vectors, flat arrows, angles, parametric + lines, circles and ellipses, cuboids, + cones, cylinders, cylindric holes, parts of cylindrical surfaces, + spheres and spheroids, globes, hemispheres, torus, + elliptical frusta, + polygons, polyhedra and their planifications, functional and + parametric surfaces, direction fields, field lines + and trajectories in vector fields (differential equations), + schematic automobiles, schematic electric charges, automatic + perspective tuning, 2D representation of ropes, reference horizontal + surfaces, hexagonal plots, schematic 2D springs, zig--zag lines, + irregular circles, selective intersection of two circles, detection + of tangency, paths for CNC machines, intersection of 2D areas, + intersection of three spheres. +} + +\subsection{Perspectives}\label{perspectives} + +\FP\ can do three kinds of perspective. +\begin{quote} +\begin{verbatim} +input featpost3Dplus2D; +f := ( 1.2 , 2.0 , 1.6 ); +Spread := 75; + +V1 := (1,1,1); +V2 := (-1,1,1); +V3 := (-1,-1,1); +V4 := (1,-1,1); +V5 := (1,1,-1); +V6 := (-1,1,-1); +V7 := (-1,-1,-1); +V8 := (1,-1,-1); +makeface1(1,2,3,4);makeface2(5,6,7,8); +makeface3(1,2,6,5);makeface4(2,3,7,6); +makeface5(3,4,8,7);makeface6(4,1,5,8); +makeline1(1,7);makeline2(2,8); +makeline3(3,5);makeline4(4,6); + +beginfig(1); + ParallelProj := true; + SphericalDistortion := false; + draw_all_test(red,true); +endfig; + +beginfig(2); + ParallelProj := false; + SphericalDistortion := false; + draw_all_test(green,true); +endfig; + +beginfig(3); + ParallelProj := false; + SphericalDistortion := true; + PrintStep := 5; + draw_all_test(blue,true); +endfig; + +end; +\end{verbatim} +\end{quote} + + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{cubicfigures.1} +\end{center} + \caption{Orthogonal perspective.} +\label{figcubicfigures1} +\end{figure}} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{cubicfigures.2} +\end{center} + \caption{Rigorous perspective.} +\label{figcubicfigures2} +\end{figure}} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{cubicfigures.3} +\end{center} + \caption{Fish-eye perspective.} +\label{figcubicfigures3} +\end{figure}} + +\subsubsection{From 3D to 2D} + +\frame{ + \changeableframetitle{From 3D to 2D} +The most important macro is \myem{rp} that converts 3D points +to two-dimensional (2D) rigorous, orthogonal +or fish-eye projections. To draw a line in +3D-space try +\begin{quote} +\begin{verbatim} +draw rp(a)--rp(b); +\end{verbatim} +\end{quote} +where +\myem{a} and \myem{b} are points in space +(of \myem{color} type). +} + +\frame{ + \changeableframetitle{``straight lines''} +But if you're going for fish-eye it's better to +\begin{quote} +\begin{verbatim} +draw pathofstraightline(a,b); +\end{verbatim} +\end{quote} +If +you don't know, leave it as +\begin{quote} +\begin{verbatim} +drawsegment(a,b); +\end{verbatim} +\end{quote} +} + +\subsection{Angles} + +When \FP\ was created its main ability was +to mark and to calculate angles. This is done with the +macros \myem{angline} and \myem{getangle} as in the +following program (see figure \ref{figcartaxes2}). +\begin{quote} +\begin{verbatim} +input featpost3Dplus2D; +f := (5,3.5,1); +beginfig(2); + cartaxes(1,1,1); + color va, vb, vc, vd; + va = (0.29,0.7,1.0); + vb = (X(va),Y(va),0); + vc = N((-Y(va),X(va),0)); + vd = (0,Y(vc),0); + drawarrow rp(black)--rp(va); + draw rp(black)--rp(vb)--rp(va) dashed evenly; + draw rp(vc)--rp(vd) dashed evenly; + drawarrow rp(black)--rp(vc); + squareangline( va, vc, black, 0.15 ); + angline(va,red,black,0.75,decimal getangle(va,red),lft); +endfig; +\end{verbatim} +\end{quote} + +\subsection{Intersections} + +The most advanced feature of \FP\ is the +ability to calculate the intersections of planar and +convex polygons\footnote{Unfortunately, this is also the +most "bugged" feature.}. It can draw the visible +part of arbitrary sets of polygons as in +the following program: +\begin{quote} +\begin{verbatim} +input featpost3Dplus2D; +numeric phi; +phi = 0.5*(1+sqrt(5)); +V1 := ( 1, phi,0);V2 := (-1, phi,0); +V3 := (-1,-phi,0);V4 := ( 1,-phi,0); +V5 := (0, 1, phi);V6 := (0,-1, phi); +V7 := (0,-1,-phi);V8 := (0, 1,-phi); +V9 := ( phi,0, 1);V10:= ( phi,0,-1); +V11:= (-phi,0,-1);V12:= (-phi,0, 1); +makeface1(1,2,3,4);makeface2(5,6,7,8); +makeface3(9,10,11,12); +beginfig(1); + sharpraytrace; +endfig; +end +\end{verbatim} +\end{quote} +See figure \ref{figsharpraytrace}. + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{sharpraytrace.1} +\end{center} + \caption{Intersecting polygons drawn with the macro \myem{sharpraytrace}.} +\label{figsharpraytrace} +\end{figure}} + +\subsection{Coming back to 3D from 2D} + +\frame{ + \changeableframetitle{Coming back to 3D from 2D} +It is possible to do an "automatic perspective tuning" +with the aid of macro \myem{photoreverse}. Please, refer both to example +\myem{photoreverse.mp} (see figure \ref{figphotoreverse}) and to the +following web page: +\href{http://matagalatlante.org/nobre/hyt/technicaldrawfromphoto.html}{FeatPost + Deeper Technicalities}. +} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.45\columnwidth]{photoreverse.1} +\end{center} + \caption{Example that uses \myem{photoreverse}. It may + not work when vertical lines are not vertical in + average on the photo.} +\label{figphotoreverse} +\end{figure}} + +The idea here is to: (i) have a \MP-coded vectorized image; (ii) associate 3D +coordinates to a few specific points of the vectorized image; (iii) +use \myem{photoreverse} to obtain the perspective parameters +corresponding to the image; and (iv) use those perspective parameters to +draw 3D matching schematic diagrams on the image. + +\subsection{Coming back to 3D from 1D} + +\frame{ + \changeableframetitle{Coming back to 3D from 1D} +Using the same algorithm of \myem{photoreverse}, the +macro \myem{improvertex} allows one to approximate a +point in 3D-space with given distances from three other +points (an initial guess is required). +} + +\section{Reference Manual} + +Some words about notation. +The meaning of macro, function, procedure and routine is the same. +Global variables are presented like this: +\begin{quote} +\begin{verbatim} +vartype var, anothervar +anothervartype yetanothervar +\end{verbatim} +\end{quote} +Explanation of \myem{var}, \myem{anothervar} and +\myem{yetanothervar}. \myem{vartype} can be any one of +\MP\ types but the meaning +of \myem{color} is a three-dimensional point or vector, not an +actual color like yellow, black or white. If the meaning is +an actual color then the type will be \myem{colour}. +Most of the global variables have default values. + +Functions are presented like this: +\begin{itemize} +\item returntype {\bfseries function()} +Explanation of this function. ``returntype'' can be any one of \MP\ +types plus global, draw, drawlabel or MD. +``global'' means that the function +changes some of the global variables. ``draw'' means that +the function +changes the currentpicture. ``drawlabel'' means that the +function changes +the currentpicture and adds text to it. ``MD'' means that the +returntype is the same as the type of the arguments (1, 2, 3 or 4D, +that is \myem{numeric}, \myem{pair}, \myem{color} or \myem{cmykcolor}). +\begin{enumerate} +\item \myem{type1} +Explanation of the first argument. The type of +one argument can be any one +of \MP\ types plus \myem{suffix} or +\myem{text}. +\item \myem{type2} +Explanation of the second argument. +There is the possibility that the +function has no arguments. In that case the +function is presented like +"\myem{returntype} {\bfseries function}". +\item Etc. +\end{enumerate} +\end{itemize} + +\subsection{Global variables} + +\begin{quote} +\begin{verbatim} +boolean ParallelProj +boolean SphericalDistortion +boolean MalcomX +\end{verbatim} +\end{quote} +Kind of projection calculated by \myem{rp}. +By default projections +are rigorous but if \myem{ParallelProj} is set +\myem{true} then +parallel lines remain parallel in the projection. +It is the same as +placing the point of view infinitely far without loosing +sight. +If \myem{SphericalDistortion} is set \myem{true} +there will be a +distortion coming from: (i) the projection being done +on a sphere of +center \myem{f} and (ii) this sphere being plaited +onto the paper page. +When \myem{MalcomX} is set \myem{true}, perspectives are calculated +with the x coordinate (first coordinate) replaced by the fourth +coordinate. The idea here is to use the fourth coordinate as ``time'' +and visualize yz projections of an animation in a single +figure\footnote{To be developed in future versions.}. + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{rigorousdiscSD.1} +\end{center} + \caption{Figure that uses \myem{SphericalDistortion:=true} + and \myem{rigorousdisc}.} +\label{sphericaldisc} +\end{figure}} + +\begin{quote} +\begin{verbatim} +color f, viewcentr +\end{verbatim} +\end{quote} +The point of view is \myem{f}. The plane or sphere +of projection contains +the center of view \myem{viewcentr}. +The axis, parallel to zz, that contains the +\myem{viewcentr} is projected on a vertical line. +\begin{quote} +\begin{verbatim} +numeric MaxFearLimit +\end{verbatim} +\end{quote} +The above variable defines the maximum allowed 3D distance between +\myem{viewcentr} and the projection of a point as calculated by +\myem{rp} (remember that 3D distances have no units). Everything +located beyond this maximum is compressed into a circumference. +\begin{quote} +\begin{verbatim} +numeric Spread +pair ShiftV, OriginProjPagePos +numeric PageWidth +numeric PageHeight +\end{verbatim} +\end{quote} +These variables control +the placement of the projection on the +paper. \myem{Spread} is the magnification +and \myem{ShiftV} is the position of the +\myem{viewcentr} projection on the +paper. But, if at some point in your program you introduce +\myem{produce\_auto\_scale} then the +\myem{currentpicture} will be +centered at \myem{OriginProjPagePos} +and scaled to fit inside a rectangle of +\myem{PageWidth} by \myem{PageHeight}. +\begin{quote} +\begin{verbatim} +color V[] +color L[]p[] +color F[]p[] +\end{verbatim} +\end{quote} +Vertexes, lines and faces. +The idea here is to draw +polygons and/or arbitrary lines in 3D space. +Defining the polygons and +the lines can be a bit tedious as \FP\ is not +interactive\footnote{The lines will, in future versions, be the skeleton of +NURBS.}. First, one defines a list of the +vertexes (\myem{V[]}) that define the +polygons and/or the lines. +There is a list of polygons and a list of +lines. Each polygon (\myem{F[]p[]}) or +line (\myem{L[]p[]}) is itself a list of vertexes. +All vertexes of the same poligon should belong +to the same plane. +\begin{quote} +\begin{verbatim} +numeric NL +numeric npl[] +numeric NF +numeric npf[] +\end{verbatim} +\end{quote} +Number of lines, number of vertexes of each line, +number of faces, number of vertexes of each face. +\begin{quote} +\begin{verbatim} +numeric PrintStep +\end{verbatim} +\end{quote} +\myem{Printstep} is the size of iterative jumps +along lines. Used by +\myem{lineraytrace}, \myem{faceraytrace} and +\myem{pathofstraightline}. +Big \myem{Printstep}s make fast \myem{lineraytrace}ings. +\begin{quote} +\begin{verbatim} +boolean FCD[] +colour TableC[] +numeric TableColors +numeric FC[] +colour HigColor +colour SubColor +color LightSource +\end{verbatim} +\end{quote} +\myem{FCD} means "face color defined". The +\myem{draw\_invisible} macro draws +polygons in colour, if it is defined. The colour must be +selected from the table of colours \myem{TableC} that has +as many as \myem{TableColors}. The colour \myem{FC} +of each polygon will depend on its position relatively to +\myem{LightSource} where we suppose there is a lamp that +emits light coloured \myem{HigColor}. Furthermore the +colour of each polygon may be modified if it belongs to a +functional or parametric surface. In this case, if we are +looking at the polygon from below than \myem{SubColor} is +subtracted from its colour. +\begin{quote} +\begin{verbatim} +numeric RopeColorSeq[] +numeric RopeColors +\end{verbatim} +\end{quote} +The above variables are used by \myem{ropepattern}. + +\begin{quote} +\begin{verbatim} +numeric TDAtiplen +numeric TDAhalftipbase +numeric TDAhalfthick +\end{verbatim} +\end{quote} +The above variables control the shape of Three-Dimensional Arrows. + +\begin{quote} +\begin{verbatim} +boolean ShadowOn +numeric HoriZon +\end{verbatim} +\end{quote} +When \myem{ShadowOn} is set \myem{true}, some objects can +cast a black shadow on a horizontal plane of \myem{Z} +coordinate equal to \myem{HoriZon} (an area from +this plane may be drawn with \myem{setthestage} or with \myem{setthearena}) as if +there is a punctual source of light at +\myem{LightSource}. +The macros that can produce shadows, in addition to their +specific production, are +\begin{itemize} +\item \myem{emptyline} +\item \myem{rigorousdisc} +\item \myem{verygoodcone} +\item \myem{tropicalglobe} +\item \myem{positivecharge} +\item \myem{whatisthis} +\item \myem{spheroid} +\item \myem{kindofcube} +\item \myem{draw\_all\_test} +\item \myem{fill\_faces} +\end{itemize} +All macros that contain {\bfseries shadow} in their name +calculate the location of shadows using \myem{cb}. These are +\begin{itemize} +\item \myem{circleshadowpath} +\item \myem{signalshadowvertex} +\item \myem{ellipticshadowpath} +\item \myem{circleshadowpath} +\item \myem{rigorousfearshadowpath} +\item \myem{faceshadowpath} +\end{itemize} + + + + +\begin{quote} +\begin{verbatim} +path VGAborder +\end{verbatim} +\end{quote} +This path and the macro \myem{produce\_vga\_border} are +meant to help you clip the \myem{currentpicture} to a 4:3 +rectangle as in a (old) movie frame. + +\begin{quote} +\begin{verbatim} +pair PhotoPair[] +color PhotoPoint[] +numeric PhotoMarks +\end{verbatim} +\end{quote} +The above variables are used by \myem{photoreverse}. + +\begin{quote} +\begin{verbatim} +pen ForePen, BackPen +path CLPath +numeric NCL +\end{verbatim} +\end{quote} +The above variables are used by \myem{closedline}. + +\begin{quote} +\begin{verbatim} +boolean OverRidePolyhedricColor +string ostr[] +numeric ActuC, Nobjects, RefDist[] +\end{verbatim} +\end{quote} +\myem{OverRidePolyhedricColor} is used by \myem{fillfacewithlight}. +\myem{Nobjects}, \myem{ostr} and \myem{RefDist[]} are auxiliary +variables used by \myem{getready} and \myem{doitnow}. +\myem{Actuc} is used both by \myem{hexagonaltrimesh} and +by \myem{partrimesh}. + + + + +\subsection{Definitions} + +\begin{itemize} +\item global makeline@\#( text1) +\item global makeface@\#( text1) +\end{itemize} +Both of these functions ease the task of +defining lines and polygons. Just +provide a list of vertexes in a correct +sequence for each polygon and/or +line. Suppose a tetrahedron +\begin{quote} +\begin{verbatim} +V3:=(+1,-1,-1);V2:=(-1,+1,-1); +V4:=(+1,+1,+1);V1:=(-1,-1,+1); +makeface2(1,2,3);makeface3(1,2,4); +makeface1(3,4,1);makeface4(3,4,2); +\end{verbatim} +\end{quote} +The +number in the last makeface or last +makeline procedure name must be the +number of polygons or lines. All polygons and lines from 1 upto this +number must be defined but the sorting may be any of your liking. + +\subsection{Macros} + +\subsubsection{Very Basic Macros} + +\begin{itemize} +\item numeric {\bfseries X()} +Returns the first coordinate of a point or vector (of +color type). Replaces \myem{redpart}. +\item numeric {\bfseries Y()} +Returns the second coordinate of a point or vector. +Replaces \myem{greenpart}. +\item numeric {\bfseries Z()} +Returns the third coordinate of a point or vector. +Replaces \myem{bluepart}. +\item numeric {\bfseries W()} +Returns the fourth coordinate of a 4D point or vector. +Replaces \myem{blackpart}. +\item cmykcolor {\bfseries makecmyk()} +\item color {\bfseries maketrio()} +\item draw {\bfseries produce\_auto\_scale} +The currentpicture is centered in, and adjusted +to the size of, an A4 +paper page. This avoids the control of \myem{Spread} and +\myem{ShiftV}. +\item string {\bfseries cstr()} Converts a color into its +string. Usefull in combination with \myem{getready}. +\item string {\bfseries bstr()} Converts a boolean +expression into its +string. Usefull in combination with \myem{getready}. +\end{itemize} + +\subsubsection{Vector Calculus} + +\begin{itemize} +\item color {\bfseries N()} Unit vector. Returns +\myem{black} (the null vector) when the argument has +null norm. The "N" means "normalized". +\item numeric {\bfseries cdotprod()} Dot product of two +vectors. +\item color {\bfseries ccrossprod()} Cross product of two +vectors. +\item numeric {\bfseries ndotprod()} Cossine of the angle +beetween two vectors. +\item color {\bfseries ncrossprod()} Normalized cross product +of twovectors. +\item numeric {\bfseries conorm()} Euclidean norm of a +vector. +\item numeric {\bfseries cmyknorm()} Euclidean norm of a +4D vector. Should not be used when \myem{MalcomX} is \myem{true}. +\item numeric {\bfseries getangle()} Angle beetween two +vectors. +\item numeric {\bfseries getcossine()} Cossine of the angle between + segment A and segment B, where A connects \myem{f} and the center of + a sphere, and where B contains \myem{f} and is tangent to that sphere. +\item pair {\bfseries getanglepair()} Orientation angles +of a vector. The first angle (\myem{xpart}) is +measured beetween the vector projection on the \myem{XY} +plane and the \myem{X} axis. The second angle +(\myem{ypart})is measured +beetween the vector and its projection on the \myem{XY} +plane. This may be usefull to find the arguments of +\myem{kindofcube} +\item color {\bfseries eulerrotation()} Three-dimensional +rotation of a vector. See the figure \ref{kindofcube2} to visualize +the following movement: (i) grab the \myem{X} component of the +vector; (ii) rotate it on the \myem{XY} plane as +much as the first argument; +(iii) raise it up as much as the second argument; and +(iv) turn it around as much as the third argument. +\begin{enumerate} +\item \myem{numeric} Angle of rotation around the +\myem{Z} component. +\item \myem{numeric} Angle of rotation around the +rotated \myem{Y} component. +\item \myem{numeric} Angle of rotation around the +two times rotated \myem{X} component. +\item \myem{color} Vector to be rotated. +\end{enumerate} +\item color {\bfseries randomfear} Generates a randomly +oriented unit vector. +\item MD {\bfseries planarrotation} +\item color {\bfseries rotvecaroundanother} +\end{itemize} + + + +\subsubsection{Projection Macros} + +\begin{itemize} +\item pair {\bfseries rp()} Converts spatial positions into +planar positions on the paper page. The conversion +considers the values of the following global +variables: \myem{viewcentr}, +\myem{ParallelProj}, \myem{SphericalDistortion}, +\myem{Spread}, \myem{ShiftV} and \myem{MaxFearLimit}. When both +\myem{ParallelProj} and \myem{SphericalDistortion} +are \myem{false} it won't work if either (i) the +vectors \myem{f-viewcentr} and \myem{f-R} are +perpendicular (\myem{R} is the argument) or (ii) +\myem{f} and \myem{viewcentr} share the same +\myem{X} and \myem{Y} coordinates. +\begin{enumerate} +\item \myem{color} Spatial position. +\end{enumerate} +\item color {\bfseries cb()} Calculates the position of the +shadow of a point. Uses \myem{HoriZon} and +\myem{LightSource}. +\begin{enumerate} +\item \myem{color} Point position. +\end{enumerate} +\item color {\bfseries projectpoint()} Calculates the +intersection beetween a plane and a straight +line. The plane contains a given point and is +perpendicular to the line connecting the +\myem{LightSource} and this same point. +The line is defined by another given point and the +\myem{LightSource}. Summary: \myem{projectpoint} +returns the projection of the second argument on a +plane that contains the first argument. Can be used to +draw shadows cast on generic planes. +\begin{enumerate} +\item \myem{color} Origin of the projection plane. +\item \myem{color} Point to be projected. +\end{enumerate} +\item color {\bfseries lineintersectplan()} Calculates the +intersection beetween a generic plane and a straight +line. The plane contains a given point and is +perpendicular to a given vector. +The line contains a given point and is parallel to +a given vector. +\begin{enumerate} +\item \myem{color} Point of the line. +\item \myem{color} Vector parallel to the line. +\item \myem{color} Point of the projection plane. +\item \myem{color} Vector perpendicular to the +projection plane. +\end{enumerate} +\item numeric {\bfseries ps()} Used by \myem{signalvertex}. +\end{itemize} + + + +\subsubsection{Plain Basic Macros} + +\begin{itemize} +\item draw {\bfseries signalvertex()} Draws a dot +sized inversely proportional to its distance from +the viewpoint \myem{f}. +\begin{enumerate} +\item \myem{color} Location. +\item \myem{numeric} Factor of proportionality +("size of the dot"). +\item \myem{colour} Colour of the dot. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{torus.1} +\end{center} + \caption{Figure that uses \myem{signalvertex}.} +\end{figure}} +\item path {\bfseries pathofstraightline()} When using +\myem{SphericalDistortion:=true}, straight lines +look like curves. This macro returns the curved path +of a straight line beetween two points. This path will +have a greater \myem{length} ("time") when +\myem{PrintStep} is made smaller. +\item draw {\bfseries drawsegment()} Alternative +\myem{pathofstraightline} that avoids the +calculation of all the intermediate points when +\myem{SphericalDistortion:=false}. +\item drawlabel {\bfseries cartaxes()} +Cartesean axis with prescribed lenghtes and apropriate labels. +\begin{enumerate} +\item \myem{numeric} Length of the \myem{X} axis. +\item \myem{numeric} Length of the \myem{Y} axis. +\item \myem{numeric} Length of the \myem{Z} axis. +\end{enumerate} +\item drawlabel {\bfseries orthaxes()} +Cartesean axis with prescribed lenghtes and prescribed labels. +\begin{enumerate} +\item \myem{numeric} Length of the \myem{X} axis. +\item \myem{label} Label of the \myem{X} axis. +\item \myem{numeric} Length of the \myem{Y} axis. +\item \myem{label} Label of the \myem{Y} axis. +\item \myem{numeric} Length of the \myem{Z} axis. +\item \myem{label} Label of the \myem{Z} axis. +\end{enumerate} +\item draw {\bfseries emptyline()} This procedure produces +a sort of a tube that can cross over itself. It +facilitates the drawing of, for instance, thick +helical curves but it won't +look right if the curves are drawn getting apart from +the point of view. Please, accept this inconveniance. +As like many other \FP\ macros this one +can produce visually correct diagrams only in limited +conditions. Can cast a shadow. +\begin{enumerate} +\item \myem{boolean} Choose \myem{true} to join +this line with a previously drawn line. +\item \myem{numeric} Factor of proportionality +("diameter of the tube"). The tubes are just +sequences of dots drawn by \myem{signalvertex}. +\item \myem{colour} Colour of the tube border. +\item \myem{colour} Colour of the tube. +\item \myem{numeric} Total number of dots on the +tube line. +\item \myem{numeric} Fraction of the tube diameter +that is drawn with the tube colour. +\item \myem{numeric} This is the number of dots +that are redrawn with the colour of the tube for +each drawn dot with the color of the tube +border. Usually 1 or 2 are enough. +\item \myem{text} This is the name a function +that returns a 3D point of the line for each value +of a parameter in beetween 0 and 1. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{joinedemptylines.1} +\end{center} + \caption{Figure that uses \myem{emptyline}. + The junction point of two different lines is indicated + by an arrow. } +\label{joinedemptylines} +\end{figure}} +\item draw {\bfseries closedline()} This procedure produces +a tube that can cross over itself. It +facilitates the drawing of, for instance, thick +helical curves but it won't +look right as its thickness does not change with the +distance from the point of view. The drawing is +entirely done in two dimensions, so the tube diameter +depends on the global variables \myem{ForePen} and +\myem{BackPen}. There can be more than one +line in a figure but all get the same diameter. +When calling \myem{closedline()} in different +figures of the same program you must reinitialize both +\myem{NCL} and \myem{Nobjects} (because +\myem{closedline()} uses \myem{getready()}). +\begin{enumerate} +\item \myem{boolean} Value of "the line is closed". +\item \myem{numeric} Total number of path segments +on the tube line. +\item \myem{numeric} Use 0.5 or more. +\item \myem{numeric} Use 0.75 or more. +\item \myem{text} This is the name of a function +that returns a 3D point of the line for each value +of a parameter in beetween 0 and 1. +\end{enumerate} +\item drawlabel {\bfseries angline()} +Draws an arch beetween two straight lines with a +common point and places a label +near the middle of the arch (marks an +angle). Note that the arch is not circular. +\begin{enumerate} +\item \myem{color} Point of one line. +\item \myem{color} Point ot the other line. +\item \myem{color} Common point. +\item \myem{numeric} Distance beetween the arch and +the common point. +\item \myem{picture} Label. +\item \myem{suffix} Position of the label relatively +to the middle of the arch. May +be one of \myem{lft, rt, top, bot, ulft, urt, +llft} and \myem{lrt}. +\end{enumerate} +\item drawlabel {\bfseries anglinen()} +The same as the previous function but the +sixth argument is numeric: +0=\myem{rt}; +1=\myem{urt}; +2=\myem{top}; +3=\myem{ulft}; +4=\myem{lft}; +5=\myem{llft}; +6=\myem{bot}; +7=\myem{lrt}; +any other number places the label +on the middle of the arch. +\item draw {\bfseries squareangline()} +This is supposed to mark 90 degree angles +but works for any angle value. +\begin{enumerate} +\item \myem{color} Point of one line. +\item \myem{color} Point ot the other line. +\item \myem{color} Common point. +\item \myem{numeric} Distance beetween the "arch" +and the common point. +\end{enumerate} +\item path {\bfseries rigorouscircle()} +3D circle. The total "time" of this path is 8. This +small number makes it easy to select parts of the +path. The circle is drawn using the +"left-hand-rule". If you put your left-hand thumb +parallel the circle axis then the other left-hand +fingers curl in the same sense as the circle +path. This path allways starts, approching the view +point, from a point on a diameter of the +circle that projects orthogonaly to its axis, and +rotating around the axis in the way of the left-hand-rule. +\begin{enumerate} +\item \myem{color} Center of the circle. +\item \myem{color} Direction orthogonal to the +circle (circle axis). +\item \myem{numeric} Radius of the circle. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.45\columnwidth]{anglinerigorouscircle.1} +\end{center} + \caption{Figure that uses \myem{anglinen} + and \myem{rigorouscircle}.} +\end{figure}} +\item draw {\bfseries tdarrow()} Draws a flat arrow that +begins at the first argument and ends at the second. +The shape of the arrow is controled by the global +variables \myem{TDAtiplen, TDAhalftipbase, TDAhalfthick}. +\item path {\bfseries twocyclestogether()} This macro +allows you to draw any solid that has no vertexes +and that has two, exactly two, planar cyclic edges. +In fact, it doesn't need to be a solid. Just +provide the pathes of both cyclic edges as arguments +but note that the returned path is polygonal. +In order to complete +the drawing of this solid you have to choose one of +the edges to be drawn immediatly afterwards. This is +done automatically by the \myem{whatisthis} macro +for the case of two parallel and concentric ellipses. +\item path {\bfseries ellipticpath()} Produces an elliptic +path in 3D space. +\begin{enumerate} +\item \myem{color} Position of the center. +\item \myem{color} Major or minor axis. +\item \myem{color} The other axis. +\end{enumerate} +\item drawlabel {\bfseries labelinspace()} Draw some 2D +\myem{picture} on some 3D plane (only when +\myem{ParallelProj:=true}). +\begin{enumerate} +\item \myem{color} Position for the lower-left +corner. +\item \myem{color} Orientation of the picture's +bottom edge. +\item \myem{color} Orientation of the picture's +letf edge. +\item \myem{text} 2D picture's name. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{labelinspace.1} +\end{center} + \caption{Example that uses \myem{labelinspace}.} +\end{figure}} +\end{itemize} + + + +\subsubsection{Standard Objects} + +\begin{itemize} +\item path {\bfseries goodcirclepath()} +Another 3D circle macro. More rigorous +than \myem{rigorouscircle} but when +the direction ortogonal to the circle is almost +orthogonal to the line \myem{viewpoint--center} +it doesn't work correctly. +The total "time" of this path is 36. +\begin{enumerate} +\item \myem{color} Center of the circle. +\item \myem{color} Direction ortogonal to +the circle. +\item \myem{numeric} Radius of the +circle. +\end{enumerate} +\item draw {\bfseries spatialhalfsfear()} An +hemisphere. Doesn't work with \myem{f} inside it. +\begin{enumerate} +\item \myem{color} Center. +\item \myem{color} Vector ortogonal to +the frontier circle and pointing +out of the concavity. +\item \myem{numeric} Radius of the +(hemi)sphere. +\end{enumerate} +\item path {\bfseries spatialhalfcircle()} +And yet another 3D circle macro. Only the visible or the hidden +part. This is usefull to mark sections of +cylinders or spherical major circles. +\begin{enumerate} +\item \myem{color} Center of the circle. +\item \myem{color} Direction ortogonal to the +circle. +\item \myem{numeric} Radius of the circle. +\item \myem{boolean} The visible part is selected with +\myem{true} and the hidden +with \myem{false}. +\end{enumerate} +\item draw {\bfseries rigorousdisc()} +3D opaque cylinder with/without a hole. Can cast a +shadow (without the hole). +\begin{enumerate} +\item \myem{numeric} Ray of an axial hole. +\item \myem{boolean} Option for completly opaque cylinder +(\myem{true}) or partial +pipe (\myem{false}) when there is no hole. When +the cylinder has an hole this option should be +\myem{true}. +\item \myem{color} Center of one circular base. +\item \myem{numeric} Radius of both circular bases. +\item \myem{color} Vector that defines the length and +orientation of the +cylinder. The addition the third and fifth +arguments should give the +position of the center of the other circular base. +\end{enumerate} +\item draw {\bfseries verygoodcone()} 3D cone. Can cast a shadow. +\begin{enumerate} +\item \myem{bolean} Option to draw dashed evenly +the invisible edge (\myem{true}) or not +(\myem{false}). +\item \myem{color} Center of the circular base. +\item \myem{color} Direction ortogonal to the +circular base. +\item \myem{numeric} Radius of the circular base. +\item \myem{color} Position of the vertex +\end{enumerate} +\item path {\bfseries rigorousfearpath()} +3D sphere. Simple but hard. +\begin{enumerate} +\item \myem{color} Center position. +\item \myem{numeric} Radius. +\end{enumerate} +\item draw {\bfseries tropicalglobe()} Globe with +minor circles. Can cast a shadow. +\begin{enumerate} +\item \myem{numeric} Number of marked latitudes. +\item \myem{color} Center position. +\item \myem{numeric} Radius +\item \myem{color} Axis orientation. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{tropicalglobe.1} +\end{center} + \caption{Figure that uses \myem{tropicalglobe}. + } +\end{figure}} +\item draw {\bfseries whatisthis()} An elliptic +frustum. Both edges are elliptic an have the same +orientation but one may be greater than the other. +Can cast a shadow. +\begin{enumerate} +\item \myem{color} Reference edge center. +\item \myem{color} Major or minor axis. +\item \myem{color} The other axis. +\item \myem{numeric} Length of the original +cylinder. +\item \myem{numeric} Edges axis length ratio. +\end{enumerate} +\item draw {\bfseries kindofcube()} Polyhedron with six +orthogonal faces (cuboid). +\begin{enumerate} +\item \myem{boolean} Also draw the invisible edges +\myem{dashed evenly} (\myem{true}) or do not. +\item \myem{boolean} The reference point may be a +vertex (\myem{true}) or the center(\myem{false}). +\item \myem{color} Reference point. +\item \myem{numeric} Alpha1. +\item \myem{numeric} Alpha2. +\item \myem{numeric} Alpha3. +\item \myem{numeric} L1. Length of the first side. +\item \myem{numeric} L2. Length of the second side. +\item \myem{numeric} L3. Length of the third side. +\end{enumerate} +These arguments are represented in figure \ref{kindofcube2}. + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{kindofcube.2} +\end{center} + \caption{Figure that uses and explains + \myem{kindofcube}. Note that the three indicated + angles may be used as arguments of \myem{eulerrotation}.} +\label{kindofcube2} +\end{figure}} +\item draw {\bfseries setthestage()} Produces an horizontal +square made of squares. Its \myem{Z} coordinate is defined by +\myem{HoriZon}. +\begin{enumerate} +\item \myem{numeric} Number of squares in each side. +\item \myem{numeric} Size of each side. +\end{enumerate} +\item draw {\bfseries setthearena()} Produces an horizontal +circle made of circles. Its \myem{Z} coordinate is defined by +\myem{HoriZon}. Due to the fact that the center of a +circle is not on the center of its central perspective +projection, this may look a bit strange. +\begin{enumerate} +\item \myem{numeric} Number of circles on a +diameter. +\item \myem{numeric} Diameter. +\end{enumerate} +\item draw {\bfseries smoothtorus()} Toxic donut (not to be +eaten). Produces an error message when \myem{f} is +close to the table. +\begin{enumerate} +\item \myem{color} Center. +\item \myem{color} Direction orthogonal to the +torus plane. +\item \myem{numeric} Big ray. +\item \myem{numeric} Small ray. +\end{enumerate} +\end{itemize} + + + +\subsubsection{Composed Objects} + +\begin{itemize} +\item draw {\bfseries positivecharge()} Draws a sphere with a +plus or minus sign on the surface. The horizontal +segment of the sign is drawn on the horizontal plane +that contains the sphere center. The middle point of +this segment is on a vertical plane containing the +viewpoint. +\begin{enumerate} +\item \myem{boolean} Selects the sign (\myem{true} +means positive). +\item \myem{color} Position of the center. +\item \myem{numeric} Sphere ray. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.55\columnwidth]{positivecharge.1} +\end{center} + \caption{Figure that uses \myem{positivecharge}, + \myem{getready} and \myem{doitnow}. + } +\end{figure}} +\item draw {\bfseries simplecar()} Draws a cuboid and four +discs in a configuration ressembling an automobile. The +first three arguments of \myem{simplecar} are the same +as the the last seven arguments of \myem{kindofcube} +but grouped in colors. +\begin{enumerate} +\item \myem{color} Center of the cuboid that +constitutes the body of the car.. +\item \myem{color} Angles defining the orientation +of the car (see \myem{kindofcube}). +\item \myem{color} Dimensions of the car. +\item \myem{color} Characteristics of the front +wheels. \myem{redpart}-distance from the +front. \myem{greenpart}-width of the front wheels (length +of the cylinders). \myem{bluepart}-wheel ray. +\item \myem{color} Same as above for the rear wheels +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{simplecar.1} +\end{center} + \caption{Figure that uses \myem{setthearena} and + \myem{simplecar}. + } +\end{figure}} + +\item draw {\bfseries banana()} Draws a cylindrical strip with a mark in + the middle angle. + \begin{enumerate} + \item \myem{color} Center of the base circle. + \item \myem{numeric} Radius. + \item \myem{color} Euler angles for the orientation of the strip + (uses \myem{eulerrotation} as if the cylindrical strip axis is the rotation + of $\hat{z}$). + \item \myem{numeric} Length of the cylindrical strip. + \item \myem{numeric} Angular amplitude of the cylindrical strip. + \end{enumerate} +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{bananadimmer.1} +\end{center} + \caption{Figure that uses \myem{banana}.} +\end{figure}} + + + +\end{itemize} + + + +\subsubsection{Shadow Pathes} + +\begin{itemize} +\item draw {\bfseries signalshadowvertex()} Draws the +shadow of a \myem{signalvertex} dot. Used by \myem{emptyline}. +\begin{enumerate} +\item \myem{color} Location of the light-blocking dot. +\item \myem{numeric} Factor of proportionality +("size of the dot"). +\item \myem{colour} Colour of the dot. +\end{enumerate} +\item path {\bfseries ellipticshadowpath()} Produces the +shadow of an elliptic path. +\begin{enumerate} +\item \myem{color} Position of the center. +\item \myem{color} Major or minor axis. +\item \myem{color} The other axis. +\end{enumerate} +\item path {\bfseries circleshadowpath()} Produces the +shadow of a circle. +\begin{enumerate} +\item \myem{color} Center of the circle. +\item \myem{color} Direction ortogonal to +the circle. +\item \myem{numeric} Radius of the +circle. +\end{enumerate} +\item path {\bfseries rigorousfearshadowpath()} +3D sphere shadow. +\begin{enumerate} +\item \myem{color} Center position. +\item \myem{numeric} Radius. +\end{enumerate} +\end{itemize} + + + +\subsubsection{Differential Equations} + +Before we proceed, be aware that solving differential +equations (DE) is mainly an experimental activity. The most +probable result of a procedure that atempts to solve a DE +is garbage. The procedure may be unstable, the solution +may be littered with singularities or something may go +wrong. If you don't have a basic understanding of +differential equations then skip this section, please. + +\begin{itemize} +\item path {\bfseries fieldlinepath()} A vectorial field line is +everywhere tangent to the field vectors. +Two different parallel fields +have the same field lines. So the field only +constrains the direction of the field lines, not any kind +of "speed" and, therefore, it is recommended to +normalize the field before using this macro that +contains a second-order Runge-Kutta method +implementation. +\begin{enumerate} +\item \myem{numeric} Total number of steps. +\item \myem{color} Initial position. +\item \myem{numeric} Step (arc)length. +\item \myem{text} Name of the function that +returns a field vector for each 3D position. +\end{enumerate} +\item path {\bfseries trajectorypath()} The acceleration of a +particle in a conservative force field is equal to the +ratio (conservative force)/(particle mass). The +acceleration is also equal to the second order time +derivative of the particle position. This produces a +second order differential equation that we solve using a +second-order Runge-Kutta method implementation. +\begin{enumerate} +\item \myem{numeric} Total number of steps. +\item \myem{color} Initial position. +\item \myem{color} Initial velocity. +\item \myem{numeric} Time step. +\item \myem{text} Name of the function that +returns a (force/mass) vector for each 3D position. +\end{enumerate} +\item path {\bfseries magnetictrajectorypath()} The +acceleration of a +charged particle in a magnetic field is equal to the +ratio (magnetic force)/(particle mass) but the magnetic +force depends on both the velocity and the magnetic field. The +acceleration is also equal to the second order time +derivative of the particle position. This produces a +second order differential equation that we solve using a +fourth-order Runge-Kutta method implementation. +\begin{enumerate} +\item \myem{numeric} Total number of steps. +\item \myem{color} Initial position. +\item \myem{color} Initial velocity. +\item \myem{numeric} Time step. +\item \myem{text} Name of the function that +returns a (charge)*(magnetic field)/(partcle mass) +vector for each 3D position. +\end{enumerate} +\end{itemize} + +\subsubsection{Renderers} + +\begin{itemize} +\item draw {\bfseries sharpraytrace} Heavy procedure that +draws only the visible part of all edges of all defined +faces. There's no point in using this procedure when +there are no intersections beetween faces. Any how +this will not work for non-convex faces nor when +\myem{SphericalDistortion:=true}. +\item draw {\bfseries lineraytrace()} Draws only the +visible part of all defined lines using sequences of dots +(\myem{signalvertex} and \myem{PrintStep}). +\begin{enumerate} +\item \myem{numeric} Dot size. +\item \myem{colour} Dot colour. +\end{enumerate} +\item draw {\bfseries faceraytrace()} Draws only the +visible part of all edges of all defined faces +using sequences of dots +(\myem{signalvertex} and \myem{PrintStep}). +\begin{enumerate} +\item \myem{numeric} Dot size. +\item \myem{colour} Dot colour. +\end{enumerate} +\item draw {\bfseries draw\_all\_test()} Draws all defined +edges (and lines) in a correct way independently of +the kind of projection used. Can cast a shadow (but +the shadow is not correct when +\myem{SphericalDistortion:=true}). +\begin{enumerate} +\item \myem{boolean} If \myem{true} the lines +are also drawn. +\end{enumerate} +\item draw {\bfseries fill\_faces()} Unfills and draws all +faces in the order they were defined (without +sorting). Can cast a shadow. +\begin{enumerate} +\item \myem{text} Like the argument of +\myem{drawoptions} but used only inside this +macro and only for the edges. +\end{enumerate} +\item draw {\bfseries draw\_invisible()} This is a fast way +of removing hidden lines that doesn't +allow for intersecting polygons nor +polygons of very different area. It works by ++sorting all polygons by +distance to \myem{f} and then by "filling" the +polygons. This routine may be used to draw graphs +of 3D surfaces. +\begin{enumerate} +\item \myem{boolean} If \myem{true} polygons are +sorted relatively to +nearest vertex and, if \myem{false}, relatively to their +mass center. Choose \myem{false} for surface +plots. +\item \myem{boolean} If \myem{false} then the +polygons are painted with their \myem{FC} colour +modified by \myem{LightSource}. If \myem{true} +then the next two arguments are used and the +polygons are darkened proportionaly to their +distance from \myem{f}. +\item \myem{colour} Colour of faces. +\item \myem{colour} Colour of the edges. +\end{enumerate} +\item global {\bfseries getready()} When you don't want to +edit the source of the \MP\ program, to resort the +objects so they'll be drawn correctly, use this macro +and the next. +\begin{enumerate} +\item \myem{string} Command line that would draw +some object. + +For instance: ``\myem{draw rigorousfearpath(black,1);}''. +\item \myem{color} Reference position of that +object. +\end{enumerate} +\item draw {\bfseries doitnow} The reference positions +given as arguments of previous \myem{getready} calls +are used to sort and draw the objects also given as +string arguments to previous \myem{getready} +calls. Remember to initialize \myem{Nobjects:=0;} +before a second figure. +\end{itemize} + + + +\subsubsection{Nematics (Direction Fields)} + +Nematics are the least ordered liquid crystals. Their +configurations can be described by direction fields +(vector fields without arrows). The two following routines +ease the task of representing their configurations. + +\begin{itemize} +\item global {\bfseries generatedirline()} Defines a single +straight line segment in a given position and with a +given orientation. +\begin{enumerate} +\item \myem{numeric} Line index number. +\item \myem{numeric} Angle beetween the \myem{X} +axis and the projection of the line on the +\myem{XY} plane. +\item \myem{numeric} Angle beetween the line +and the \myem{XY} plane. +\item \myem{numeric} Line (arc)length. +\item \myem{color} Position of the line middle +point. +\end{enumerate} +\item draw {\bfseries director\_invisible()} This is a +direction field renderer that can sort direction +lines. This routine +draws straight lines of given "thickness" beetween the +first all the points +of all the \myem{L[]p[]} lines. It is supposed to +help you draw vector fields +without arrows but taking care of invisibility. +The lines may be +generated by \myem{generatedirline} or by other macros. +\begin{enumerate} +\item \myem{boolean} When there is no need to sort +lines you may use \myem{false} here. +\item \myem{numeric} "Thickness" of the +direction lines +\item \myem{boolean} Use \myem{true} for cyclic +"direction" lines. +\end{enumerate} +\end{itemize} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{twistflat.1} +\end{center} + \caption{Figure that uses \myem{director\_invisible} + and \myem{generatedirline}.} +\end{figure}} + + + +\subsubsection{Surface Plots} + +\FP\ surface plots are geared towards unusual features like +equilateral triangular grid, hexagonal domain and merging +together functional and parametric surface descriptions. +\begin{itemize} +\item draw {\bfseries hexagonaltrimesh()} Plots a +functional surface on a triangular or hexagonal +domain. Uses the \myem{LightSource}. +\begin{enumerate} +\item \myem{boolean} Select the kind of +domain. \myem{true} for hexagonal and +\myem{false} for triangular. The domain is +centered on the origin (\myem{black}). When the +domain is hexagonal two of its corners are on the +\myem{-YY} axis. When the +domain is triangular one of its corners is on the +\myem{X} axis. +\item \myem{numeric} Number of small triangles on +each side of the triangular domain or three times +the number of small triangles on +each side of the hexagonal domain. +\item \myem{numeric} Length of the triangular +domain side or three times the hexagonal domain +side. +\item \myem{text} Name of the function that +returns the \myem{Z} coordinate of a surface +point of coordinates \myem{X} and \myem{Y}. +\end{enumerate} + +\frame{\begin{figure}[bpt] +\begin{center} + \includegraphics[width=0.65\columnwidth]{hexagonaltrimesh.1} +\end{center} + \caption{Figure that uses \myem{hexagonaltrimesh}. + } +\end{figure}} +\item global {\bfseries partrimesh()} Defines a parametric +surface that can be drawn with +\myem{draw\_invisible}. In the following descriptions +\myem{S} and \myem{T} are the parameters. Remember +to initialize \myem{NF}. The surface is defined so +that quadrangles are used whenever possible. If +impossible, two triangles are used but their +orientation is selected to maximize the surface +smoothness. Also note that, unlike +\myem{hexagonaltrimesh()}, the spatial range you +require to be visible is always first reshaped into a +cube and second compressed or extended vertically. How +much the cube is compressed or extended depends on the +last \myem{numeric} argument, the compression factor +for \myem{Z}, meaning that the final height of the +cube is 2/(compression factor). Thanks to Sebastian +Sturm for pointing the need to explain this. +\begin{enumerate} +\item \myem{numeric} Number of \myem{T} steps. +\item \myem{numeric} Number of \myem{S} steps. +\item \myem{numeric} Minimal \myem{T} value. +\item \myem{numeric} Maximal \myem{T} value. +\item \myem{numeric} Minimal \myem{S} value. +\item \myem{numeric} Maximal \myem{S} value. +\item \myem{numeric} Minimal \myem{X} value. +\item \myem{numeric} Maximal \myem{X} value. +\item \myem{numeric} Minimal \myem{Y} value. +\item \myem{numeric} Maximal \myem{Y} value. +\item \myem{numeric} Minimal \myem{Z} value. +\item \myem{numeric} Maximal \myem{Z} value. +\item \myem{numeric} Compression factor for \myem{Z} +values. +\item \myem{text} Name of the function that +returns a surface point (of \myem{color} type) +for each pair (\myem{S},\myem{T}). +\end{enumerate} +\end{itemize} + + +\subsubsection{Strictly 2D} +\begin{itemize} +\item path {\bfseries springpath()} +\item path+draw {\bfseries zigzagfrontier()} +\item path {\bfseries randomcirc()} +\item pair {\bfseries radialcross()} +\item draw {\bfseries ropepattern()} +\item pair {\bfseries firsttangencypoint()} +\item path {\bfseries lasermachine()} +\item path {\bfseries crossingline()} +\end{itemize} + +\subsubsection{Planification wise} + +Lots of things to write here\ldots + +\mode<article>{\newpage} + +\section{Reference-at-a-glance} + +\subsection{Sphere} + +\frame{ + \frametitle{\myem{tropicalglobe}( $N$, $\vec{c}$, $R$, $\vec{A}$ )} + \begin{center} + \includegraphics[width=65mm]{revolvers.1} \\ + + \myem{tropicalglobe( 5, black, 1, blue );} + \end{center} +} + +\subsection{Disc} + +\frame{ + \frametitle{\myem{rigorousdisc}( $R_i$, + \myem{bool}, $\vec{c}$, $R_o$, $\vec{A}$ )} + \begin{center} + \includegraphics[width=65mm]{revolvers.2} \\ + + \myem{rigorousdisc( 0.5, true, black, 1, 0.85blue );} + \end{center} +} + +\subsection{Torus} + +\frame{ + \frametitle{\myem{smoothtorus}( $\vec{c}$, $\vec{A}$, $R_b$, $R_s$ )} + \begin{center} + \includegraphics[width=65mm]{revolvers.3} \\ + + \myem{smoothtorus( black, blue, 0.7, 0.4 );} + \end{center} +} + +\subsection{Bowl} + +\frame{ + \frametitle{\myem{spatialhalfsfear}( $\vec{c}$, $\vec{A}$, $R$ )} + \begin{center} + \includegraphics[width=65mm]{revolvers.4} \\ + + \myem{spatialhalfsfear( black, blue, 1 );} + \end{center} +} + +\subsection{Cuboid} + +\frame{ + \frametitle{\myem{kindofcube}(\myem{bool,bool},$\vec{o},\alpha_1,\alpha_2,\alpha_3,l_1,l_2,l_3$)} + \begin{center} + \includegraphics[width=65mm]{kindofcuber.1} \\ + + \myem{kindofcube( false, true, black, 130, 32, 67, 0.3, 0.6, 0.9 );} + \end{center} +} + +\subsection{Simple car} + +\frame{ + \frametitle{\myem{simplecar}( $\vec{o}$,($\alpha_1,\alpha_2,\alpha_3$), + ($l_1,l_2,l_3$), (Xf,Yf,Zf), (Xr,Yr,Zr) )} + \begin{center} + \includegraphics[width=65mm]{simplecarparam.1} \\ + +\myem{simplecar( black, black, (0.8,0.35,0.18), (0.1,0.2,0.132), + (0.06,0.06,0.1) );} + \end{center} +} + +\subsection{Cone} + +\frame{ + \frametitle{\myem{verygoodcone}( \myem{bool}, $\vec{c}$, + $\vec{A}$, $R$, $\vec{v}$ )} + \begin{center} + \includegraphics[width=65mm]{cone.1} \\ + + \myem{verygoodcone( true, black, blue, 0.8, blue+green );} + \end{center} +} + +\subsection{Elliptic prism} + +\frame{ + \frametitle{\myem{whatisthis}( $\vec{c}$, $\vec{S}_1$, + $\vec{B}_1$, $D$, $||\vec{S}_2||/||\vec{S}_1||$ )} + \begin{center} + \includegraphics[width=65mm]{ellipticprism.1} \\ + + \myem{whatisthis( black, 0.5red, green, 0.85, 0.8 );} + \end{center} +} + +\subsection{Spheroid} + +\frame{ + \frametitle{\myem{spheroid}( $\vec{c}$, $\vec{S}$, $R$ )} + \begin{center} + \includegraphics[width=40mm]{revolvers.5} \\ + + \myem{spheroid( black, 2*blue, 1 );} + \end{center} +} + +\subsection{Cylindrical strip} + +\frame{ + \frametitle{\myem{banana}( $\vec{c}$, $R$, + $(\alpha_M,\beta_M,\gamma_M)$, $L$, $\theta$ )} + \begin{center} + \includegraphics[width=70mm]{revolvers.6} \\ + + \myem{banana( black, 1, black, 0.3, 145 );} + \end{center} +} + +\section{Acknowledgements} + +\frame{ + \changeableframetitle{Acknowledgements} + Many people have contributed to make \FP\ what it is today. + Perhaps it would have never come into being without the early + intervention of Jorge B\'arrios, providing access to his father's + computer in 1986. Another important moment happened when Jos\'e Esteves + first spoke about \MP\ sometime in the late nineties. + + Also, the very accurate criticism of Cristian Barbarosie has + significantly contributed to fundamental improvements. Jens + Schwai\-ger contributed new macros. Pedro Sebas\-ti\~ao, Jo\~ao Dinis and + Gon\-\c{c}alo Mo\-rais proposed challenging new features. +} +\end{document} + |