% !TEX TS-program = pdflatex
% !TEX encoding = UTF-8 Unicode
\documentclass[a4paper]{article}\errorcontextlines=100
\ProvidesFile{curve2e-manual.tex}[2024-11-13 v.2.6.0 curve2e user manual]
\hfuzz 10pt
%\usepackage[utf8]{inputenc}
\usepackage{lmodern,textcomp}
\usepackage{mflogo}
\usepackage{multicol,amsmath,fancyvrb,graphics,shortvrb}
\usepackage{xcolor,verbatim,enumitem,FramedSyntax,trace}
\usepackage{curve2e}
\MakeShortVerb{\|}
\providecommand*\diff{\mathop{}\!\mathrm{d}}
\providecommand\meta{}\providecommand\marg{}
\renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}}
\renewcommand\marg[1]{\texttt{\{\meta{#1}\}}}
\providecommand\Marg{}
\renewcommand\Marg[1]{\texttt{\{#1\}}}
\providecommand\oarg{}
\renewcommand\oarg[1]{\texttt{[\meta{#1}]}}
\providecommand\Oarg{}
\renewcommand\Oarg[1]{\texttt{[#1]}}
\providecommand\aarg{}
\renewcommand*\aarg[1]{\texttt{<\meta{#1}>}}
\providecommand\Aarg{}
\renewcommand\Aarg[1]{\texttt{<#1>}}
\providecommand\parg{}
\renewcommand\parg[1]{\texttt{(\meta{#1})}}
\providecommand\Parg{}
\renewcommand\Parg[1]{\texttt{(#1)}}
\providecommand\pack{}
\renewcommand\pack[1]{{\normalfont\textsf{#1}}}
\providecommand\file{}
\renewcommand\file[1]{{\normalfont\texttt{#1}}}
\providecommand\env{}
\renewcommand\env[1]{{\normalfont\textsf{\slshape#1}}}\let\amb\env
\providecommand\cs{}
\renewcommand\cs[1]{{\normalfont\texttt{\char92#1}}}
\def\LissajousCoefs#1,#2,#3,#4,#5,#6!{%
\edef\LAu{#1}\edef\LNu{#2}\edef\LFu{#3}%
\edef\LAd{#4}\edef\LNd{#5}\edef\LFd{#6}}
\def\LissajousCode#1#2{%
\edef\X{\fpeval{\LAu*cosd(\LNu*#1+\LFu)}}%
\edef\Y{\fpeval{\LAd*cosd(\LNd*#1+\LFd)}}%
\CopyVect\X,\Y to#2\ignorespaces}
\NewDocumentCommand\Lissajous{m o m}{%
\IfValueTF{#2}{\LissajousCoefs#2!\relax
\LissajousCode{#1}{#3}}%
{\ifcsname LAu\endcsname
\LissajousCode{#1}{#3}%
\else\PackageError{Lissajous}%
{I parametri di questa curva di Lissajous\MessageBreak
Non sono mai stati definiti}{Non faccio nulla}\fi}%
\ignorespaces}
\makeatletter
\NewDocumentCommand\Pall{O{1.5} R(){0,0}}{\put(#2){\circle*{#1}}}
\providecommand\setfontsize{}
\DeclareRobustCommand\setfontsize[2][1.2]{%
\linespread{#1}\fontsize{#2}{#2}\selectfont}
\newwrite\example@out
\ProvideDocumentEnvironment{Esempio}{ O{\footnotesize} D(){0.50}}
% All definitions and assignments are local
% #1 := Latex font size command or \setfontsize{<size>}
% %2 := \textwidth percentage for the code box; the
% complement, less the column gap for the compiled
% result
%
% Syntax: \begin{Esempio}[<size command>](<code box
% percentage width>)
%
% Warning: No extra space is put before and/or after the
% display; this environment is assumed to be used
% within a figure environment that already provides
% its own vertical spaces. Should this environment
% be used between paragraphs, the user should
% manually provide a convenient amount of space
% above and below it.
% Remember: This environment sets itself in vertical mode
{\par\dimendef\Wboxu=2570 \dimendef\Wboxd=2572
\Wboxu=#2\linewidth\relax
\Wboxd=\dimexpr\linewidth-\columnsep-\Wboxu\relax
\begingroup
\@bsphack
\immediate\openout\example@out\jobname-temp.tex
\let\do\@makeother\dospecials\catcode`\^^M\active
\def\verbatim@processline{%
\immediate\write\example@out{\the\verbatim@line}}%
\verbatim@start\relax}%
{\immediate\closeout\example@out\@esphack\endgroup
\begin{lrbox}{0}%
\begin{minipage}{\linewidth}%
\begin{minipage}{\Wboxu}#1\relax
\verbatiminput{\jobname-temp.tex}
\end{minipage}%
\hfill
\begin{minipage}{\Wboxd}\raggedleft
\input{\jobname-temp}%
\end{minipage}
\end{minipage}%
\end{lrbox}\par\medskip
\noindent\makebox[\linewidth]{\box0}\par}
\providecommand\GetFileInfo[1]{%
\def\filename{#1}%
\def\@tempb##1 v.##2 ##3\relax##4\relax{%
\def\filedate{##1}%
\def\fileversion{##2}%
\def\fileinfo{##3}}%
\edef\@tempa{\csname ver@#1\endcsname}%
\expandafter\@tempb\@tempa\relax? ? \relax\relax}
%%%%%%%%%%%%%%%%
\newenvironment{medaglione}[1][\linewidth]{%
\begin{lrbox}{0}%
\begin{minipage}{\dimexpr#1-2\fboxsep-2\fboxrule}
}{%
\end{minipage}\end{lrbox}\fbox{\usebox{0}}\relax
}
\newenvironment{sintassi}{\flushleft\medaglione\obeylines}%
{\endmedaglione\endflushleft}
\providecommand\eu{}
\renewcommand\eu{\ensuremath{\mathrm{e}}}
%%%%%%%%%%%%%%%%
\makeatletter
\NewDocumentCommand\Tbox{D(){0,0} O{cc} m O{0pt} D<>{Z}}{\bgroup
\edef\TBoxCode{#5}\dimen0=#4\relax %
\edef\tempE{\fpeval{round(#4/\unitlength,3)}}%
\put(#1){%
\ifdim\dimen0=\z@
\Zbox(0,0)[#2]{#3}[\z@]%
\else
\if\TBoxCode V\relax
\let\tempC=b\relax
\if\tempC #2\edef\tempD{0,-\tempE}\else\edef\tempD{0,\tempE}\fi%
\segment(0,0)(\tempD)\Zbox(0,0)[#2]{#3}[\z@]%
\else
\if\TBoxCode H\relax
\let\tempC=l\relax%
\if\tempC #2\edef\tempD{-\tempE,0}\else\edef\tempD{\tempE,0}\fi%
\segment(0,0)(\tempD)\Zbox(0,0)[#2]{#3}[\z@]%
\else
\typeout{The specified code\space #5\space is invalid!}%
\typeout{\string\Tbox\space ignored}%
\fi
\fi
\fi
}\egroup\ignorespaces}%
\begin{document}
\author{Claudio Beccari\\{\small\texttt{claudio(dot)beccari(at)gmail(dot)com}}}
\title{Package \pack{curve2e} user manual}
\GetFileInfo{curve2e.sty}
\date{Version \fileversion~--~Last revised \filedate}
\maketitle
\columnseprule=0.4pt
\begin{multicols}{2}
\tableofcontents
\end{multicols}
\begin{abstract}\setfontsize{9.5}
This file contains the user manual of the \pack{curve2e} extension package to the \pack{pict2e} bundle; the latter was described by Lamport himself in the 1994 second edition of his \LaTeX\ handbook.
Please take notice that on April 2011 a package \pack{pict2e} upgraded version has been released that incorporates some of the commands defined in early versions of this package \pack{curve2e}; apparently there are no conflicts, because this package contains only the advanced features that extend the above package.
Since this extension redefines some commands and introduces some more drawing facilities (that allow to draw circular arcs and arbitrary curves with the minimum of user intervention) users need a user manual that contains several actual examples; this auxiliary manual is contained in file
|curve2e-manual.pdf|. The software available to show the drawing code and its result after compilation is incompatible with the usual \LaTeX\ |ltxdoc| class for code documentation, therefore a separate user manual has been made available. If users want to explore the \pack{curve2e} code and its documentation they have available the |curve2e.pdf| file. Either file is readable by entering in a terminal window the command |texdoc curve2e-manual| or |texdoc curve2e.pdf|; please do not forget the extension when you want to read the code documentation.
\end{abstract}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Installation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
If \TeX\ system was installed with a \TeX~Live or a MiK\TeX\ complete and updated distribution this package is already installed; in order to verify open a terminal or command prompt window and use it to enter the \texttt{texdoc curve2e-manual} command; as soon as the command is executed a screen window should open displaying this manual. If this does not happen, either you misspelt the command (it happens more often than not), or your installation is not complete and updated.
I suggest you to use your computer installation facilities to install this bundle. Otherwise, download this curve2e.zip package from one of the CTAN (Comprehensive TeX Archive Network) archives, to your downloads folder.
Before doing anything else verify if you have a \emph{personal} \texttt{texmf} tree; if not, create one reading you distribution instruction; let us assume that your personal |texmf| archive is in |HOME/texmf| (on Windows change the slash with a backslash) and |HOME| is a path starting from the root of you hard disk and going though several other folders. On Windows~10 it might be |C:\Users\YourName|; on Linux it might simply be |~|; on Mac it would be |~/\Library|, but sometimes the |HOME| might be different, especially on Windows platforms. Create the following subfolders:
\begin{enumerate}[noitemsep]
\item |HOME/texmf/source/latex/curve2e/|
\item |HOME/texmf/doc/latex/curve2e/|
\item |HOME/texmf/tex/latex/curve2e/|
\end{enumerate}
Now move file \file{curve2e.zip} to the |.../source/latex/curve2e/| folder; then decompress the |.zip| file with the software you have available on your platform. Run |pdflatex| on the |.dtx| file; then compile the |curve2e-manual.tex| file. You might need to repeat these compilations two or three times in order to have the table of contents and all the references correctly connected.
This done, move the |.pdf| files to the |.../doc/latex/curve2e/| folder. and move the |.sty| files to the |.../tex/latex/curve2e/| folder.
Clear the |.../source/latex/curve2e/| folder from the auxiliary files, all those remaining in the folder except those that have the extensions |.zip|, |.dtx|, |.tex|, and |.txt|. Read the \file{README.txt} file.
If your \TeX\ system is correctly set up, your files in your personal tree should be immediately usable; probably you have to create or update the file-name database with MiK\TeX; in this case read the documentation of your MiK\TeX\ installation to discover how to~do~it.
Remember to delete all these subfolders if you decide to install a complete updated version of your favourite distribution, and you'd better keep it updated approximately once every 7 or 10 days. This is much simpler than to struggle with these manual operations.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Package \pack{pict2e} and this extension \pack{curve2e}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Package \pack{pict2e} was announced in issue 15 of
\file{latexnews} around December 2003; it was declared that
the new package would replace the dummy one that had been
accompanying every release of \LaTeXe\ since its beginnings
in 1994. The dummy package was just issuing an info message
that simply announced the temporary unavailability of the
real package.
Eventually Gäßlein and Niepraschk implemented what Lamport
himself had already documented in the second edition of his
\LaTeX\ handbook, it was a \LaTeX\ package that contained
the macros capable of removing all the limitations contained
in the standard commands of the original \texttt{picture}
environment; specifically what follows.
\begin{enumerate}[noitemsep]
\item The line and vector slopes were limited to the ratios of relative
prime one-digit integers of magnitude not exceeding 6 for lines and 4
for vectors.
%
\item Filled and unfilled full circles were limited by the necessarily
limited number of specific glyphs contained in the special \LaTeX\
\texttt{picture} fonts.
%
\item Quarter circles radii were also limited for the same reason.
%
\item Ovals (rectangles with rounded corners) could not be too small
because of the unavailability of small radius quarter circles, nor
could be too large, in the sense that after a certain radius the
rounded corners remained the same curvature and would not increase proportionally to the oval size.
%
\item Vector tips had only one possible shape and matched the limited
number of vector slopes.
%
\item For circles and inclined lines and vectors just two possible
thicknesses were available.
\end{enumerate}
Package \pack{pict2e} removes most if not all the above
limitations.
\begin{enumerate}[noitemsep]
\item Line and vector slopes are virtually unlimited; the only
remaining limitation is that the direction coefficients must be
three-digit integer numbers; they need not be relatively prime; with
the 2009 upgrade even this limitation was removed and now slope
coefficients can be any fractional number whose magnitude does not
exceed 16\,384, the maximum dimension in points that \TeX\ can handle.
%
\item Filled and unfilled circles can be of any size.
%
\item Ovals can be designed with any specified corner curvature and
there is virtually no limitation to such curvatures; of course corner
radii should not exceed half the lower value between the base and the
height of the oval.
%
\item There are two shapes for the arrow tips; the triangular one
traditional with \LaTeX\ vectors, or the arrow tip with PostScript
style.
%
\item The |\linethickness| command changes the thickness of all lines,
straight, curved, vertical, horizontal, arrow tipped, et cetera.
\end{enumerate}
This specific extension package \pack{curve2e} adds the following
features.
\begin{enumerate}[noitemsep]
%
\item Point coordinates can be specified with macros; this is similar
to “naming†points; it eases editing the user's graphic work, because
points that are used several times are specified with a single macro;
it also eases the transmission of coordinates between different macros
and environments. It is also important for the following feature, described in the following entry..
%
\item Point coordinates my be specified in both cartesian and polar
form: internally they are handled as cartesian coordinates, but the
user can specify his/her points also in polar form. In order to avoid
confusion with other graphic packages, \pack{curve2e} uses the usual
comma separated couple \meta{$x,y$} of integer or fractional numbers for
cartesian coordinates, and the couple \meta{$\theta$}:\meta{$\rho$} for
polar coordinates (the angle preceding the radius).
All graphic object commands accept polar or cartesian coordinates at
the choice of the user who may use for each object the formalism s/he
prefers. Also the |\put| and |\multiput| commands have been redefined so
as to accept cartesian or polar coordinates.
Of course the user should pay attention to the meaning of cartesian
vs.~polar coordinates. Both imply a displacement with respect to the
actual origin of the axes. So when a circle center is placed at
coordinates $a,b$ with a normal |\put| command, the circle is placed
exactly in that point; with a normal |\put| command the same happens if
coordinates $\alpha{:}\rho$ are specified.
But if the |\put| command is nested into another |\put| command, the
current origin of the axes is displaced — this is obvious and the
purpose of nesting |\put| commands is exactly that. But if a segment
is specified so that its ending point is at a specific distance and in
specific direction from its starting point, polar coordinates appear to
be the most convenient to use; in this case, though, the origin of the
axes becomes the starting point of the segment, therefore the segment
might be drawn in a strange way. Attention has been paid to avoid such
misinterpretation, but maybe some unusual situation may not have come to
my mind; feedback is very welcome. Meanwhile pay attention when you use
polar coordinates.
%
\item At user level most if not all coordinate pairs and slope pairs are
treated as \emph{ordered pairs}, that is \emph{complex numbers}; in
practice the user does not notice any difference from what s/he was
used to, but all the mathematical treatment to be applied to these
entities is coded as complex number operations, since complex numbers
may be viewed non only as ordered pairs, but also as vectors or as
roto-amplification operators.
%
\item Commands for setting the line terminations were introduced; the
user can chose between square or rounded caps; the default is set to
rounded caps; now this feature is directly available with \pack{pict2e}.
%
\item Commands for specifying the way two straight or curves lines
join to one another.
%
\item Originally the |\line| macro was redefined so as to allow large
(up to three digits) integer direction coefficients, but maintaining
the same syntax as in the original \texttt{picture} environment; now
\pack{pict2e} removes the integer number limitations and allows
fractional values, initially implemented by \pack{curve2e}; now direction
coefficients may be specified in polar form.
%
\item A new macro |\Line| was originally defined by \pack{curve2e} so
as to avoid the need to specify the horizontal projection of inclined
lines; now this functionality is available directly with \pack{pict2e};
but this \pack{curve2e} macro name now conflicts with the \pack{pict2e}
2009 version; therefore its name is changed to |\LIne| and supposedly it
will not be used very often, if ever, by the end user (but it is used
within this package macros).
%
\item A new macro |\LINE| was defined in order to join two points
specified with their coordinates; this is now the normal behaviour of
the |\Line| macro of \pack{pict2e}, so that in this package |\LINE| is
now renamed |\segment|; there is no need to use the |\put| command with
this segment specification.
%
\item A new macro |\DashLine| (alias: |\Dline|) is defined in order to
draw dashed lines joining any two given points; the dash length and
gap (equal to one another) get specified through one of the macro
arguments. The starting point may be specified in cartesiano or polar
form; the end point in cartesian format specifies the desired end
point; but, if the second point is in polar form, it is meant
\emph{relative to the starting point}, not as an absolute end point.
See the examples further on.
%
\item A similar new macro |\Dotline| is defined in order to draw dotted
straight lines as a sequence of equally spaced dots, where the gap can
be specified by the user; such straight line may have any inclination,
as well as the above dashed lines. Polar coordinates for the second
point have the same relative meaning as specified for the |\Dashline|
macro. The dot diameter may be specified with an optional argument; by
default this diameter equals the |1pt| width.
%
\item Similar macros are redefined for vectors; |\vector| redefines the
original macro but with the vector slope limitations removed and the
vector direction may be given in polar form; |\Vector|
gets specified with its two horizontal and vertical components in
analogy with |\LIne|; |\VECTOR| joins two specified points (without
using the |\put| command) with the arrow pointing to the second point.
|\VVECTOR| may be available if used with a sufficiently recent \LaTeX\
kernel version; it draws a vector between two given points, with arrow
tips at both ends.
%
\item A new macro |\polyline| for drawing polygonal lines is defined
that accepts from two vertices up to an arbitrary (reasonably limited)
number of them (available now also in \pack{pict2e}); here it is
redefined so as to allow an optional specification of the way segments
for the polyline are joined to one another. Vertices may be specified
with polar coordinates and are always relative to the preceding point.
%
\item The \pack{pict2e} |\polygon| macro draws closed polylines (in
practice general polygons) has been redefined in such a way that it
can accept the various vertices specified with (relative) polar
coordinates. The |polygon*| macro produces a color filled polygon; the
default color is black, but a different color may be specified with the
usual |\color| command given within the same group where |\polygon*| is
enclosed.
%
\item A new macro |\Arc| is defined in order to draw an arc with
arbitrary radius and arbitrary aperture (angle amplitude); this
amplitude is specified in sexagesimal degrees, not in radians; a
similar functionality is now achieved with the |\arc| macro of
\pack{pict2e}, which provides also the starred version |\arc*| that
fills up with the current color the sector generated by a circular arc.
It must be noticed that the syntax is slightly different, so that it's
reasonable that these commands, in spite of producing identical arcs,
might be more comfortable with this or that syntax.
%
\item Two new macros |\VectorArc| and |\VectorARC| (alias |\VVectorArc|)
are defined in order to draw circular arcs with an arrow at one or both
ends.
%
\item A new macro |\Curve| is defined so as to draw arbitrary curved
lines by means of cubic Bézier splines; the |\Curve| macro requires
only the curve nodes and the directions of the tangents at each
node. The starred version fills up the interior of the curve with the
current color.
%
\item The above |\Curve| macro is a recursive macro that can draw an
unlimited (reasonably limited) number of connected Bézier spline arcs
with specification of the tangent direction at the interpolation nodes.
It is possible to use a lower level macro |\CbezierTo| that does the
same but lets the user specify the control points of each arc; it is
more difficult to use but it is more performant.|\Curve| recognises also
an optional argument to set a direction change, that is a cusp.
%
\item The basic macros used within the cumulative |\Curve| macro can be
used individually in order to draw any curve, one cubic arc at the
time; but they are intended for internal use, even if it is not
prohibited to use them; by themselves such arcs are not different form
those used by |Curve|, but the final command, |\FillCurve|, should be
used in place of |\CurveFinish|, so as to fill up the closed path with
the locally specified color; see figure~\ref{fig:colored-curve}.
It is much more convenient to use the starred version of the |\Curve|
macro.
\end{enumerate}
The \pack{pict2e} package already defines macros such as |\moveto|,
|\lineto|, |\curveto|, |\closepath|, |\fillpath|, and |\strokepath|;
|curve2e| just redefines them so as to accept also polar coordinates;
of course these macros can be used by the end user, and sometimes they
perform better than the macros defined in this package, because the
user has a better control on the position of the Bézier splines
control points; in this case the control points are sort of rigid. It
would be very useful to resort to the \pack{hobby} package, but its
macros are compatible with those of the \pack{tikz} and \pack{pgf}
packages, not with\pack{curve2e}; an interface should be created in
order to deal with the \pack{hobby} package, but this has not been
done yet.
In order to make the necessary calculations many macros have been
defined so as to use complex number arithmetics to manipulate point
coordinates, directions (unit vectors, also known as ‘versors’),
rotations and the like. In the first versions of this package the
trigonometric functions were also defined in a way that the author
believed to be more efficient than those defined by the \texttt{trig}
package; in any case the macro names were sufficiently different to
accommodate both definition sets in the same \LaTeX\ run. With the
progress of the \LaTeX3 language, package \pack{xfp} functionalities
have become available, and any sort of calculations can be done floating
point decimal numbers; therefore the most common algebraic, irrational
and transcendental functions can be computed in the background with the
stable internal floating point facilities. We maintain some computation
with complex number algebra, but use the |xfp| functionalities for
other computations.
Many aspects of this extension could be fine tuned for better
performance; many new commands could be defined in order to further
extend this extension. If the new service macros are accepted by other
\TeX\ and \LaTeX\ programmers, this version could become the start for
a real extension of the \pack{pict2e} package or even become a part of
it. Actually some macros have already been included in the \pack{pict2e}
package. The |\Curve| algorithm, as said before, might be redefined
so as to use the macros introduced by the \pack{hobby} package, that
implements for the \pack{tikz} and \pack{pgf} packages the same
functionalities that John Hobby implemented for the \MF\ and \MP\
programs.
For these reasons I suppose that every enhancement should be submitted
to Gäßlein, Niepraschk, and Tkadlec who are the prime maintainers of
\pack{pict2e}; they are the only ones who can decide whether or not
to incorporate new macros in their package.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Summary and examples of new commands}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
This package \pack{curve2e} extends the power of \pack{pict2e} with
the following modifications and the following new commands.
\begin{enumerate}[noitemsep]
\item This package \pack{curve2e} calls directly the \LaTeX\ packages
|color| and \pack{pict2e}; it passes to the latter one any possible
option that it can receive; actually the only options that make sense
for \pack{pict2e} are those concerning the arrow tip shapes, either
\LaTeX\ (default) or PostScript styled, because it is assumed that if
this package is used, the original \LaTeX\ commands are of no interest:
see the \pack{pict2e} documentation in order to find the correct options
\pack{pict2e} can receive. If the user wants to use the \pack{xcolor}
package, it has to load it \emph{before} \pack{curve2e}.
%%
\item Since they are used very much in the following examples, we recall some commands to label certain drawing elements, such as points, lines, arcs, and similar lines, and to insert legends in some figures. They are \cs{legenda}, \cs{Zbox} and \cs{Pbox}; their syntax is the following:
\begin{Sintassi}[9.75]\ttfamily
|\legenda|\parg{coordinates}\marg{formula}
|\Zbox|\parg{coordinates}\oarg{position}\marg{formula}\oarg{dot diameter}
|\Pbox|\parg{coordinates}\oarg{position}\marg{text}\oarg{dot diameter}\meta{\texttt{*}}\aarg{angle}
\end{Sintassi}
They are described in any up to date documentation of \pack{curve2e}.
%%
\item The user is offered new commands in order to control the line
terminators and the line joins; specifically:
\begin{itemize}
\item |\roundcap|: the line is terminated with a semicircle;
\item |\squarecap|: the line is terminated with a half square;
\item |\roundjoin|: two lines are joined with a rounded join;
\item |\beveljoin|: two lines are joined with a bevel join;
\item |\miterjoin|: two lines are joined with a miter join.
\end{itemize}
All the above commands should respect the intended range; but since
they act at the PostScript or PDF level, not at \TeX\ level, it might
be necessary to issue the necessary commands in order to restore the
previous terminator or join; in other words, groups and environments do
not have any influence on these commands.
%%
\item The commands
\begin{Sintassi}
|\linethickness|\marg{thickness}
|\thicklines|
|\thinlines|
|\defaultlinethickness|\marg{thickness}
\end{Sintassi}
always redefine the internal |\@wholewidth| and |\@halfwidth| so that the
latter ones always refer to a full width and to a half of it in this way
if you issue the command {\setfontsize{8.75}|\defaultlinethickness{2pt}|}
all thin lines will be drawn with a thickness of 1\,pt while, if a
drawing command directly refers to the internal value |\@wholewidth|,
its line will be drawn with a thickness of 2\,pt. If one issues the
declaration |\thinlines| all lines will be drawn with
a 1\,pt width, but if a command refers to the internal value
|\@halfwidth| the line will be drawn with a thickness of 0.5\,pt.
The command |\linethickness| redefines the above internals but does not
change the default width value; all these width specifications apply to
all lines, straight ones, curved ones, circles, ovals, vectors, dashed
lines, and so on. It's better to recall that |\thinlines| and
|\thicklines| are declarations that do not take arguments; on the pposite
the other commands, as shown in the above syntax medallion, accept a
specific thickness value, that is either a length specification complete
of its units, or a dimensional expression.
%%
\item Straight lines and vectors are redefined in such a way that
fractional slope coefficients may be specified; the zero length line and
vector does not produce errors and is ignored; the zero length vectors
draw only the arrow tips.
%%
\item New line and vector macros are defined that avoid the necessity
of specifying the horizontal component; |\put(3,4){\LIne(25,15)}|
specifies a segment that starts at point $(3,4)$ and goes to point
$(3+25,4+15)$; the command |\segment(3,4)(28,19)| achieves the same
result without the need of using the |\put| command. Therefore |\LIne|
is just for internal usage, rather than a user command. Now
\pack{curve2e} has available also the “arc vectors†with the arrow tips
at one or at both ends. The |\segment| syntax is
\begin{Sintassi}
\cs{segment}\parg{starting point}\parg{ending point}
\end{Sintassi}
The same applies to the vector commands |\Vector| and |\VECTOR| and
|\VVECTOR|; the latter command behaves as |\VECTOR| but draws a vector
with arrow tips at both ends; furthermore this command is available
only with main versions~2 or higher of \pack{curve2e}.
\begin{Sintassi}\small
|\put|\parg{starting point}\Marg{\cs{Vector}\parg{vector cartesian or polar components}}
|\VECTOR|\parg{starting point}\parg{ending point}
|\VVECTOR|\parg{starting point}\parg{ending point}
\end{Sintassi}
Experience has shown that the commands intended
to join two specified points are particularly
useful; see figure~\ref{fig:vectors}.
\begin{figure}[!hb]
\begin{Esempio}[\small](0.60)
\unitlength=0.01\linewidth
\begin{picture}(80,20)
\AutoGrid[red]
\put(0,0){\vector(1.5,2.3){10}}
\put(20,0){\Vector(10,15.33333)}
\VECTOR(40,0)(50,15.33333)
\ifdefined\VVECTOR \VVECTOR(60,0)(80,10)\fi
\end{picture}
\end{Esempio}
\caption{Three (displaced) identical vectors
obtained with the three
vector macros\ifdefined\VVECTOR; a double
tipped vector is also shown\fi. The darker
cyan color is an usage example optional grid
coloring }\label{fig:vectors}
\end{figure}
%
\item The |\polyline| command has already been introduced in \pack{pict2e}: in \pack{curve2e} it is redefined so as to accept also polar coordinates; this new version of |\polyline| accepts also an optional argument to specify how two consecutive segments join together; it accepts an unlimited list of point coordinates, possibly stored in macros, enclosed within round parentheses; the command draws a sequence of connected segments that join in order the specified points; the syntax is:
\begin{Sintassi}
\cs{polyline}\oarg{optional join style}\parg{$P_1$}\parg{$P_2$}\texttt{...}\parg{$P_n$}
\end{Sintassi}
See figure~\ref{fig:polyline} where a regular pentagon is drawn; usage
of polar coordinates is also shown; please notice how polar
coordinates act in this figure.
\begin{figure}[!ht]
\begin{Esempio}[\small](0.55)
\unitlength=0.5mm
\begin{picture}(40,32)(-20,-17)
\polyline(90:20)(162:20)(234:20)(306:20)(378:20)(90:20)
\end{picture}
\end{Esempio}
\caption{Polygonal line obtained by means of the \texttt{\string\polyline}
command; vertex coordinates are in polar form.}
\label{fig:polyline}
\end{figure}
Examples of using polar and cartesian coordinates are shown in figure~\ref{fig:polar}. Notice the
|\AutoGrid| macro that draws the grid of mesh lines that are very useful to set objects at the right positions. The main lines are
\verb|10\unitlength| apart so that the main squares are clearly visible; if the squares are too small only the median lines are traced with thinner lines; if the squares are not so small thin lines are traced \verb|2\unitlength| apart; otherwise the thin median lines and the thinner \verb|1\unitlength| apart are traced as in regular millimetre drawing paper. The rendering on the screen depends very much on its pixel density, nevertheless we think that e nicely thick grid is very helpful while drawing geometric graphs. When the drawing is completed the \verb|\AutoGrid| command may be commented out so that the grid does not appear in the final document.
\begin{figure}[htb]
\begin{Esempio}[\normalsize]%
\unitlength=0.02\textwidth
\begin{picture}(40,30)
\AutoGrid
\Zbox(40,0)[l]{40,0}[1]
\Zbox(90:30)[bc]{90{:}30}[1]
\Zbox(45:30)[bc]{45{:}30}[1]
\Zbox(30,30)[bc]{30,30}[1]
\multiput(0,0)(20:10){5}%
{\makebox(0,0){\rule{1.5mm}{1.5mm}}}
\end{picture}
\end{Esempio}
\caption[Use of cartesian and absolute polar coordinates]{Use of
cartesian and absolute polar coordinates. The \texttt{\string\Zbox}
macro is just a shortcut to set a small dot with a (math) legend close
to it.}
\label{fig:polar}
\end{figure}
A similar example may be obtained with the |\polygon| macro that does
not require to terminate the polyline at the starting point.
Figure~\ref{fig:polygon} shows how to get a coloured filled pentagon.
\begin{figure}[!ht]
\begin{Esempio}[\normalsize]%
\unitlength=.5mm
\begin{picture}(40,32)(-20,-20)
\color{magenta}
\polygon*(90:20)(162:20)(234:20)(306:20)(378:20)
\end{picture}
\end{Esempio}
\caption{A pentagon obtained by means of the \texttt{\string\polygon*}
command; vertex coordinates are in relative polar form.}
\label{fig:polygon}
\end{figure}
%
\item The new command |\Dashline| (alias: |\Dline| for backwards
compatibility):
\begin{Sintassi}
|\Dashline|\parg{first point}\parg{second point}\marg{dash and gap length}
\end{Sintassi}
draws a dashed line containing as many dashes as possible, just as long
as specified, and separated by a gap exactly the same size; actually,
in order to make an even gap-dash sequence, the desired dash length is
used to do some computations in order to find a suitable length, close
to the one specified, such that the distance of the end points is
evenly divided in equally sized dashes and gaps.
The end points may be anywhere in the drawing area, without any
constraint on the slope of the joining segment. The desired dash length
is specified as a fractional multiple of |\unitlength|; see
figure~\ref{fig:dashline}.
\begin{figure}[!ht]
\begin{Esempio}[\normalsize]%
\unitlength=1mm
\begin{picture}(40,40)
\AutoGrid(40,40)
\Dashline(0,0)(40,10){4}
\put(0,0){\circle*{2}}
\Dashline(40,10)(0,25){4}
\put(40,10){\circle*{2}}
\Dashline(0,25)(20,40){4}
\put(0,25){\circle*{2}}
\put(20,40){\circle*{2}}
\Dotline(0,0)(40,40){2}[0.75mm]
\put(40,40){\circle*{2}}
\end{picture}
\end{Esempio}
\caption{Dashed lines and graph grid}\label{fig:dashline}
\end{figure}
Another example of usage of cartesian and polar coordinates usage is
shown in figure~\ref{fig:polar} together with its code.
\begin{figure}
\begin{Esempio}[\normalsize]%
\unitlength=0.025\textwidth
\begin{picture}(40,30)
\noinnerlines % <-------- !
\AutoGrid(40,30)\thicklines
\color{red}%
\Dashline(0,0)(40,10){2}
\Dashline(0,0)(40,20){2}
\Dashline(0,0)(40,30){2}
\Dashline(0,0)(30,30){2}
\Dashline(0,0)(20,30){2}
\Dashline(0,0)(10,30){2}
\Dashline(40,0)(108:30){2}
\Dashline(40,0)(126:30){2}
\Dashline(40,0)(144:30){2}
\Dashline(40,0)(162:30){2}
\end{picture}
\end{Esempio}
\caption{Different length dashed lines with the same nominal dash
length; notice the relative polar coordinates used for the dashed
lines starting at the grid lower right vertex.}
\label{fig:dashedlines}
\end{figure}
%%
\item Analogous to |\Dashline|, a new command |\Dotline| draws a dotted
line with the syntax:
\begin{flushleft}
|\Dotline|\parg{first point}\parg{end point}\marg{dot gap}
\end{flushleft}
See figures~\ref{fig:dashline} and~\ref{fig:dottedlines} for examples.
\begin{figure}[htb]
\begin{Esempio}[\normalsize]%
\unitlength=0.025\textwidth
\begin{picture}(40,30)
\AutoGrid(40,30)
\Dotline(0,0)(40,10){1.5}[2pt]
\Dotline(0,0)(40,20){1.5}[2pt]
\Dotline(0,0)(40,30){1.5}[2pt]
\Dotline(0,0)(30,30){1.5}[2pt]
\Dotline(0,0)(20,30){1.5}[2pt]
\Dotline(0,0)(10,30){1.5}[2pt]
{\color{red}\relax
\Dotline(40,0)(108:30){1.5}
\Dotline(40,0)(126:30){1.5}[2pt]
\Dotline(40,0)(144:30){1.5}[2pt]
\Dotline(40,0)(162:30){1.5}[2pt]}%
\end{picture}
\end{Esempio}
\caption{Different length dotted lines with the same nominal dot gap;
again notice the relative polar coordinates for the dotted lines
starting at the grid lower right vertex.}
\label{fig:dottedlines}
\end{figure}
%%
\item |\GraphGrid| and |\AutoGrid| are commands that draw a red grid
under the drawing with lines separated |10\unitlength|s apart; it is
described only with a comma separated couple of numbers, representing
the base and the height of the grid, see figure~\ref{fig:dashline}; it's
better to specify multiples of ten and the grid can be placed anywhere
in the drawing canvas by means of |\put|, whose cartesian coordinates
are multiples of 10; nevertheless the grid line distance is rounded to
the nearest multiple of 10, while the point coordinates specified to
|\put| are not rounded at all; therefore some care should be used to
place the working grid on the drawing canvas.
\begin{Sintassi}
|\GraphicGrid|\parg{grad base, grid height}
|\AutoGrid|
\end{Sintassi}
This grid is intended as an aid while drawing; even if you sketch your
drawing on millimetre paper, the drawing grid turns out to be very
useful; one must only delete or comment out the command when the drawing
is finished. Several examples of usage of such grid are shown in several
figures.
|\Autogrid| does not require arguments, but requires the canvas
dimensions and offsets to be specified as multiples of~10; if the latter
are specified they are simply ignored.
%%
\item New trigonometric function macros have been computed by means of
the functionalities of the |xfp| included in the \LaTeX\ kernel. The
difference with the other existing macros is that angles are specified
in sexagesimal degrees, so that the users need not transform to radians.
The computations are done taking into account that “abnormal†values that
can occasionally be avoided, for example $\tan 90^\circ$ must be avoided
and replaced with a suitably large number, because the \TeX\ system does
not handle “infinityâ€.
These trigonometric functions are used within the complex number
macros; but if the user wants to use them the syntax is the following:
\begin{Sintassi}
\cs{SinOf}\meta{angle}\texttt{to}\meta{control sequence}
\cs{CosOf}\meta{angle}\texttt{to}\meta{control sequence}
\cs{TanOf}\meta{angle}\texttt{to}\meta{control sequence}
\end{Sintassi}
The \meta{control sequence} may then be used, for example, as a
multiplying factor of a length.
%%
\item Arcs can be drawn as simple circular arcs, or with one or two
arrows at their ends (curved vectors); the syntax is:
\begin{Sintassi}
\cs{Arc}\parg{center}\parg{starting point}\marg{angle}
\cs{VectorArc}\parg{center}\parg{starting point}\marg{angle}
\cs{VectorARC}\parg{center}\parg{starting point}\marg{angle}
\cs{VVectorArc}\parg{center}\parg{starting point}\marg{angle}
\end{Sintassi}
If the angle is specified numerically it must be enclosed in braces,
while if it is specified with a control sequence the braces (curly
brackets) are not necessary. The above macro |\Arc| draws a simple
circular arc without arrows; |\VectorArc| draws an arc with an arrow
tip at the ending point; |\VectorARC| (alias |\VVectorArc|) draws an
arc with arrow tips at both ends; see figure~\ref{fig:arcs}.
Notice that the starting point may be specified with polar coordinates; differently to cartesian coordinates, that are absolute with respect with the drawing axes, the polar ones are relative to the center of the arcs with or without vector tips.
\begin{figure}
\begin{Esempio}[\small]%
\unitlength=0.5mm
\begin{picture}(60,40)
\GraphGrid(60,40)
\Arc(0,20)(30,0){60}
\VECTOR(0,20)(30,0)\VECTOR(0,20)(32.5,36)
\VectorArc(0,20)(15,10){60}
\put(20,20){\makebox(0,0)[l]{$60^\circ$}}
\VectorARC(60,20)(60,0){-180}
\VVectorArc(60,20)(135:10){90}
\end{picture}
\end{Esempio}
\caption{Arcs and curved vectors}\label{fig:arcs}
\end{figure}
%%
\item The available commands allow to create the drawings necessary to prove some geometrical theorems; for example let us prove the Pitagora's theorem. Figure~\ref{fig:pitagora} displays a right triangle with its hypothenuse laying horizontally; its vertices are labeled \textsf{A}, \textsf{B}, and \textsf{C}, being \textsf{A} the right angle vertex. The height relative to the hypothenuse intersects this side in point \textsf{H}, and divides the whole triangle \textsf{ABC}, in two similar smaller ones \textsf{AHC}, and\textsf{ABH}. Segments \textsf{CH}, and\textsf{HB}, add to the whole hypothenuse length. Figure~\ref{fig:pitagora} displays also the square \textsf{CBDE}, built on the hypothenuse and divided in two rectangles \textsf{CHFE}, and \textsf{HBDF}, where \textsf{HF} is the continuation of the height line.
The lengths of the original right triangle sides are $a, b, c$ as marked on the figure; Point \textsf{H} divides the hypothenuse of length $c$ in two shorter segments of lengths $d, e$, respectively, as marked in the figure
Since the three triangles are similar, we can set up the relationships between their sides:
\begin{align*}
d : a = a : c &\Longrightarrow d = a^2/c\\
e : b = b : c &\Longrightarrow e = b^2/c
\end{align*}
Therefore rectangle \textsf{CHFE} area equals $ c\cdot d = c\cdot a^2/c = a^2$. Similarly rectangle \textsf{HBDF} area equals $ c\cdot e = c\cdot b^2/c = b^2$. The square built on the hypothenuse has an area equal to $c^2$; therefore it is
\begin{equation*}
c^2 = a^2 + b^2
\end{equation*}
which proves the Pitagora's theorem.
\begin{figure}
\centering
\begin{Esempio}
\unitlength=1mm
\begin{picture}(70,80)(-10,-50)
\AutoGrid
\thicklines
\polygon(0,0)(50,0)(18,24)
\thinlines
\polyline(0,0)(0,-50)(50,-50)(50,0)
\Pbox(0,0)[r]{C}[0.75ex]
\Pbox(18,0)[bl]{H}[0.75ex]
\Pbox(50,0)[l]{B}[0.75ex]
\Pbox(18,24)[b]{A}[0.75ex]
\Pbox(0,-50)[br]{E}[0.75ex]
\Pbox(50,-50)[bl]{D}[0.75ex]
\Pbox(18,-50)[br]{F}[0.75ex]
\Zbox(10,12)[br]{a}[0]
\Zbox(33,12)[bl]{b}[0]
\Zbox(25,0)[t]{c}[0]
\Zbox(9,0)[b]{d}[0]
\Zbox(30,0)[b]{e}[0]
\Zbox(50,-25)[r]{c}[0]
\Zbox(25,-50)[b]{c}[0]
\Zbox(0,-25)[l]{c}[0]
\Dashline(18,24)(18,-50){1.5}
\end{picture}
\end{Esempio}
\caption{Geometrical construction to prove Pitagora's theorem}
\label{fig:pitagora}
\end{figure}
%%
\item A multitude of commands have been defined in order to manage
complex numbers; actually complex numbers are represented as a comma
separated pair of fractional numbers; internally these macros use
only the cartesian form, and output, unless
differently specified is also in cartesian form; but input can be in
polar form. They are used to address specific points in the drawing
plane, but also as operators so as to scale and rotate other objects.
In the following \meta{vector} means a comma separated pair of
fractional numbers, \meta{vector macro} means a macro that contains a
comma separated pair of fractional numbers; \meta{angle macro} means a
macro that contains the angle of a vector in sexagesimal degrees;
\meta{argument} means a brace delimited numeric value, even a macro;
\meta{numeric macro} means a macro that contains a fractional number;
\textit{macro} is a valid macro name, i.e.~a backslash followed by
letters, or anything else that can receive a definition. A
\emph{direction} of a vector is its versor; the angle of a vector is
the angle between the vector and the positive $x$ axis in
counterclockwise direction, as it is used in the
Euler formula $ \vec{v} = M\eu^{\mathrm{j}\varphi}$.
\begin{Sintassi}
|\MakeVectorFrom|\meta{numeric macro}\meta{numeric macro}|to|\meta{vector macro}
|\CopyVect|\meta{first vector}|to|\meta{second vector macro}
|\ModOfVect|\meta{vector}|to|\meta{modulus macro}
|\DirOfvect|\meta{vector}|to|\meta{versor macro}
|\ModAndDirOfVect|\meta{vector}|to|\meta{modulus macro}|and|\meta{versor macro}
|\ModAndAngleOfVect|\meta{vector}|to|\meta{modulus macro}|and|\meta{angle macro}
{\setfontsize{10}|\DistanceAndDirOfVect|\meta{1st vector} |minus|\meta{2nd vector}
\qquad\qquad|to|\meta{distance macro} |and|\meta{versor macro}}
|\XpartOfVect|\meta{vector}|to|\meta{macro}
|\YpartOfVect|\meta{vector}|to|\meta{macro}
\end{Sintassi}
\begin{Sintassi}
|\DirFromAngle|\meta{angle}|to|\meta{versor macro}
|\ArgOfVect|\meta{vector}|to|\meta{angle macro}
|\ScaleVect|\meta{vector}|by|\meta{scaling factor}|to|\meta{vector macro}
|\ConjVect|\meta{vector}|to|\meta{conjugate vector macro}
|\SubVect|\meta{subtrahend vector}|from|\meta{minuend vector}|to|\meta{vector macro}
|\AddVect|\meta{first vector}|and|\meta{second vector}|to|\meta{vector macro}
|\Multvect|\marg{first vector}*\marg{second vector}*\marg{vector macro} (\textcolor{blue}{the
\qquad\qquad asterisks are optional; either one changes the second vector
\qquad\qquad into its complex conjugate})
|\MultVect|\meta{first vector}|by|\meta{second vector}|to|\meta{vector macro}
\qquad\qquad (\textcolor{red}{discouraged; maintained for backwards compatibility})
|\MultVect|\meta{first vector}|by*|\meta{second vector}|to|\meta{vector macro}
\qquad\qquad (\textcolor{red}{discouraged; maintained for backwards compatibility})
|\Divvect|\marg{dividend vector}\marg{divisor vector}\marg{vector macro} {\color{blue}notice
\qquad\qquad that this new command warns the user if the divisor is zero}
|\DivVect|\meta{dividend vector}|by|\meta{divisor vector}|to|\meta{vector macro}
\qquad\qquad (\textcolor{red}{discouraged: maintained for backwards compatibility})
\end{Sintassi}
%%
\item General curves can be drawn with the \pack{pict2e} macro
|\curve| but it requires the specification of the third-order
Bézier-spline control points; sometimes it's better to be very
specific with the control points and there is no other means to
do a decent graph; sometimes the curves to be drawn are not so
tricky and a general set of macros can be defined so as to
compute the control points, while letting the user specify only
the nodes through which the curve must pass, and the tangent
direction of the curve in such nodes. Such commands are the following:
\begin{itemize}[noitemsep]
\item \cs{Curve} draws a sequence of arcs as explained above, using
third order (cubic) Bézier splines. The starred version of this command
fills the internal part of the curve with the current color; if the
last arc finishes where the fist arc starts, it is clear what is the
interior; if it does not, the driver (not the code of this package,
but the driver between this code and the physical representation on
paper or screen) assumes a straight line closure of the whole path.
The syntax offers several variants but it is substantially the following:
\begin{Sintassi}
|\Curve|\parg{node}\aarg{direction}\dots\parg{node}\aarg{direction}
|\Curve*|\parg{node}\aarg{direction}\dots\parg{node}\aarg{direction}
\qquad\qquad\dots\aarg{direction}\oarg{new direction}\parg{node}\dots
\end{Sintassi}
See some more explanation below.
\item \cs{Qurve} is similar to |\Curve|, but with second order
(quadratic) Bézier splines. The starred version fills the interior
with the current color. Its syntax si similar to that of |\Curve|.
\item \cs{CurveBetween} draws a single cubic Bézier spline between two
given nodes and with two given direction vectors. This macro is similar to |\Curve|, but it is used to draw a third order Bézier curve between just two nodes and require just two directions
\item \cs{CBezierBetween} draws a single cubic Bézier spline between
two given nodes, with two given direction versors along which the
control node distances are specified. This is the most general macro
(rather difficult to use) with which not only the arc end points are
specified but also the control nodes coordinates are given. It is similar to |\CurveBetween| but the contol points of the single arc can be specified; the arc is perfect, but the syntax is more complicated. See below for examples.
\end{itemize}
% le equazioni parametriche del cuore, da stackexchange, sono
%\def\x(#1){sin(#1)^3}
%\def\y(#1){(13*cos(#1)-5*cos(2*#1)-2*cos(3*#1)-cos(4*#1))/16}
% Varrebbe a penda di provarle con curve2e
%
\begin{figure}[!ht]
\begin{Esempio}[\small]%
\unitlength=8mm\relax
\begin{picture}(5,5)
\put(0,0){\framebox(5,5){}}\thicklines\roundcap
\Curve(2.5,0)<0.1,1>(5,3.5)<0,1>%
(4,5)<-1,0>(2.5,3.5)<-0.1,-1.2>[-0.1,1.2]%
(1,5)<-1,0>(0,3.5)<0,-1>(2.5,0)<0.1,-1>
\end{picture}
\end{Esempio}
\caption{A heart shaped curve with cusps drawn with \texttt{\string\Curve}}
\label{fig:curve}
\vspace*{2\baselineskip}
\begin{Esempio}[\small]%
\unitlength=8mm\relax
\begin{picture}(5,5)
\put(0,0){\framebox(5,5){}}\thicklines\roundcap
\color{green}\relax
\Curve*(2.5,0)<0.1,1>(5,3.5)<0,1>%
(4,5)<-1,0>(2.5,3.5)<-0.1,-1.2>[-0.1,1.2]%
(1,5)<-1,0>(0,3.5)<0,-1>(2.5,0)<0.1,-1>
\end{picture}
\end{Esempio}
\caption{Coloring the inside of a closed path drawn with \texttt{\string\Curve*}}
\label{fig:colored-curve}
\end{figure}
The main macro is |\Curve| and must be followed by an “unlimitedâ€
sequence of node-direction coordinates as a quadruple
defined as
\[
\parg{node coordinates}\aarg{direction vector}
\]
Possibly if a sudden change of direction has to be performed (cusp)
another item can be inserted after one of those quadruples in the form
\[
\mbox{\dots\parg{...}\aarg{...}\oarg{new direction vector}\parg{...}\aarg{...}\dots}
\]
Sometimes it is necessary to specify the “tension†or the “loosenessâ€
of a specific Bézier arc; such tension parameters range from 0 (zero)
to~4; the zero value implies a very stiff arc, as if it was a string
subject to a high tension (i.e. with zero looseness); a value of~4
implies a very low tension (very high looseness), almost as if the
string was not subject to any tension. In \MF\ or \MP\ language such a
concept is used very often; in this package, where the Hobby
algorithms are not used, the parameter value appears to mean the
opposite of tension.
A couple of comma separated tension values may be optionally used, they
are separated with a semicolon from the direction vector,
and they apply to the arc terminating with the last node; their
specification must precede any possible change of tangent according to
this syntax\footnote{The tension may be specified only for cubic
splines, because the quadratic ones do not use enough parameters to
control the tension; not all commands for drawing cubic splines accept
this optional tension specification.}:
\[
\makebox[\linewidth]{\small\dots\parg{node}\Aarg{\meta{direction vector};\meta{start tension},\meta{end tension}}\parg{node}\aarg{dirextion}\dots}
\]
The |\Curve| macro does not (still) have facilities for cycling the
path, that is to close the path from the last specified node-direction
to the first specified node-direction; but, as already mentioned, if
the ending node of the last arc does not coincide with the starting
node of the first arc, a straight line is assumed to join such nodes;
this line does not get drawn, but with starred commands no lines are
drawn because only the interior is coloured.
The tangent direction need not be specified with a unit vector,
although only its direction is relevant; the scaling of the specified
direction vector to a unit vector is performed by the macro itself.
Therefore one cannot specify the fine tuning of the curve convexity as
it can be done with other programs or commands, as, for example, with
\MF\ or the |pgf/tikz| package and environment.
See figure~\ref{fig:curve} for an example.
With the starred version of |\Curve|, instead of stroking the contour,
the macro fills up the contour with the selected current color, see
figure~\ref{fig:colored-curve}.
Figure~\ref{fig:arcspline} shows a geometric construction that
contains the geometric elements and symbols used to determine the
parameters of a cubic spline required to draw a quarter circle. This
construction contains many of the commands described so far.
\begin{figure}[p]
\begin{minipage}{\linewidth}\small
\begin{verbatim}
\unitlength=0.007\textwidth
\begin{picture}(100,90)(-50,-50)
\put(-50,0){\vector(1,0){100}}\put(50,1){\makebox(0,0)[br]{$x$}}%
\put(20,-1){\makebox(0,0)[t]{$s$}}%
\put(0,0){\circle*{2}}\put(-1,-1){\makebox(0,0)[tr]{$M$}}%
\legenda(12,-45){s=\overline{MP_2}=R\sin\theta}%
\put(0,-50){\vector(0,1){90}}%
\put(1,40){\makebox(0,0)[tl]{$y$}}%
\put(0,-40){\circle*{2}}\put(1,-41){\makebox(0,0)[lt]{$C$}}%
\segment(0,-40)(-40,0)\segment(0,-40)(40,0)%
\put(-41,1){\makebox(0,0)[br]{$P_1$}}\put(-40,0){\circle*{2}}%
\put(41,1){\makebox(0,0)[bl]{$P_2$}}\put(40,0){\circle*{2}}%
\put(0,0){\linethickness{1pt}\Arc(0,-40)(40,0){90}}%
\segment(-40,0)(-20,20)\put(-20,20){\circle*{2}}%
\put(-20,21.5){\makebox(0,0)[b]{$C_1$}}%
\segment(40,0)(20,20)\put(20,20){\circle*{2}}%
\put(20,21.5){\makebox(0,0)[b]{$C_2$}}%
\put(0,-40){\put(0,56.5685){\circle*{2}}%
\put(1,58){\makebox(0,0)[bl]{$P$}}}%
\VectorARC(0,-40)(15,-25){45}\put(10,-18){\makebox(0,0)[c]{$\theta$}}%
\VectorARC(40,0)(20,0){-45}\put(19,5){\makebox(0,0)[r]{$\theta$}}%
\VectorARC(-40,0)(-20,0){45}\put(-19,5){\makebox(0,0)[l]{$\theta$}}%
\put(-20,-18){\makebox(0,0)[bl]{$R$}}%
\put(-32,13){\makebox(0,0)[bl]{$K$}}%
\put(32,13){\makebox(0,0)[br]{$K$}}%
\end{picture}
\end{verbatim}
\end{minipage}
\par
\vspace*{\stretch{1}}
\par
\begin{minipage}{\linewidth}\centering
% \unitlength=0.007\textwidth
% \begin{picture}(100,90)(-50,-50)
% \put(-50,0){\vector(1,0){100}}\put(50,1){\makebox(0,0)[br]{$x$}}%
% \put(20,-1){\makebox(0,0)[t]{$s$}}%
% \put(0,0){\circle*{2}}\put(-1,-1){\makebox(0,0)[tr]{$M$}}%
% \legenda(12,-45){s=\overline{MP_2}=R\sin\theta}%
% \put(0,-50){\vector(0,1){90}}%
% \put(1,40){\makebox(0,0)[tl]{$y$}}%
% \put(0,-40){\circle*{2}}\put(1,-41){\makebox(0,0)[lt]{$C$}}%
% \segment(0,-40)(-40,0)\segment(0,-40)(40,0)%
% \put(-41,1){\makebox(0,0)[br]{$P_1$}}\put(-40,0){\circle*{2}}%
% \put(41,1){\makebox(0,0)[bl]{$P_2$}}\put(40,0){\circle*{2}}%
% \put(0,0){\linethickness{1pt}\Arc(0,-40)(40,0){90}}%
% \segment(-40,0)(-20,20)\put(-20,20){\circle*{2}}%
% \put(-20,21.5){\makebox(0,0)[b]{$C_1$}}%
% \segment(40,0)(20,20)\put(20,20){\circle*{2}}%
% \put(20,21.5){\makebox(0,0)[b]{$C_2$}}%
% \put(0,-40){\put(0,56.5685){\circle*{2}}%
% \put(1,58){\makebox(0,0)[bl]{$P$}}}%
% \VectorARC(0,-40)(15,-25){45}
% \put(10,-18){\makebox(0,0)[c]{$\theta$}}%
% \VectorARC(40,0)(20,0){-45}
% \put(19,5){\makebox(0,0)[r]{$\theta$}}%
% \VectorARC(-40,0)(-20,0){45}
% \put(-19,5){\makebox(0,0)[l]{$\theta$}}%
% \put(-20,-18){\makebox(0,0)[bl]{$R$}}%
% \put(-32,13){\makebox(0,0)[bl]{$K$}}%
% \put(32,13){\makebox(0,0)[br]{$K$}}%
% \end{picture}
\end{minipage}
\caption{The code to display the nodes and
control points for an arc to be approximated
with a cubic Bézier spline}
\label{fig:arcspline}
\end{figure}
To show what you can do with |\CurveBetween| see the code and result
shown in figure~\ref{fig:curva-due-punti}. Notice the effect of
changing the directions at both or at the end nodes of a single cubic
spline. The directions are conveniently expressed with unit vectors
described by polar coordinates. The |\CurveBetween| macro is built on
|\CBezierBetween|; this latter command is very complicated to describe and its use is reserved to experienced users; its syntax is described in the code documentation file |cureve2e.pdf|; the reader is encouraged to examine it in case s/he is willing to use it.
\begin{figure}\centering\unitlength=0.004\textwidth
\begin{picture}(220,120)(-50,-20)
\put(0,60){\Line(-50,0)(50,0)
\CurveBetween-50,0and50,0WithDirs15:1and{-15:1}
\CurveBetween-50,0and50,0WithDirs30:1and{-30:1}
\CurveBetween-50,0and50,0WithDirs45:1and{-45:1}
\CurveBetween-50,0and50,0WithDirs60:1and{-60:1}
\CurveBetween-50,0and50,0WithDirs75:1and{-75:1}
\CurveBetween-50,0and50,0WithDirs90:1and{-90:1}}
\put(120,60){%
\Line(-50,0)(50,0)
\CurveBetween-50,0and50,0WithDirs15:1and{15:1}
\CurveBetween-50,0and50,0WithDirs30:1and{30:1}
\CurveBetween-50,0and50,0WithDirs45:1and{45:1}
\CurveBetween-50,0and50,0WithDirs60:1and{60:1}
\CurveBetween-50,0and50,0WithDirs75:1and{75:1}
\CurveBetween-50,0and50,0WithDirs90:1and{90:1}}
\put(0,0){%
\Line(-50,0)(50,0)
\CurveBetween-50,0and50,0WithDirs45:1and{-15:1}
\CurveBetween-50,0and50,0WithDirs45:1and{-30:1}
\CurveBetween-50,0and50,0WithDirs45:1and{-45:1}
\CurveBetween-50,0and50,0WithDirs45:1and{-60:1}
\CurveBetween-50,0and50,0WithDirs45:1and{-75:1}
\CurveBetween-50,0and50,0WithDirs45:1and{-90:1}}
\put(120,0){%
\Line(-50,0)(50,0)
\CurveBetween-50,0and50,0WithDirs45:1and{15:1}
\CurveBetween-50,0and50,0WithDirs45:1and{30:1}
\CurveBetween-50,0and50,0WithDirs45:1and{45:1}
\CurveBetween-50,0and50,0WithDirs45:1and{60:1}
\CurveBetween-50,0and50,0WithDirs45:1and{75:1}
\CurveBetween-50,0and50,0WithDirs45:1and{90:1}}
\end{picture}
\caption{Curves between two points with different start and end slopes}\label{fig:curva-due-punti}
\end{figure}
A little more complicated is the use of the
|\CBezierBetween| macro, figure~\ref{fig:Cbezier}. The
directions are specified with unit vectors in polar form;
the control points are specified by adding their distances
from their neighbouring nodes; actually the right distance
is maintained to the value~1, while the left one increases
from~4 to~10.
The black line corresponds to the standard |\CurveBetween|
where the default distance is computed to trace an arc of a
circle and is approximately~3.5.
\begin{figure}[!tb]
\begin{minipage}[t]{0.52\textwidth}\small
\begin{verbatim}
\unitlength=0.1\textwidth
\begin{picture}(10,3)
\CurveBetween0,0and10,0WithDirs1,1and{1,-1}
\color{red}%
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists4And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists6And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists8And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists10And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists12And{1}
\end{picture}
\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}{0.40\textwidth}\raggedleft
\unitlength=0.1\textwidth
\begin{picture}(10,3)(0,1.25)
\CurveBetween0,0and10,0WithDirs1,1and{1,-1}
\color{red}%
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists4And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists6And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists8And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists10And{1}
\CbezierBetween0,0And10,0 WithDirs45:1And-45:1UsingDists12And{1}
\end{picture}
\end{minipage}
\caption{Comparison between similar arcs drawn with \cs{CurveBetween} with the default tension values (black)
and with several tension values specified (red)}
\label{fig:Cbezier}
\end{figure}
In figure~\ref{fig:tensions} the effect of tension
specification is shown. The red line corresponds to the
default tension, since the tension values are not specified.
The black lines correspond to the various values used in the
various commands to the |\Curve| macro.
With a tension of zero, the spline is almost coincident
with the horizontal base line of the frame. Increasing the
parameter value to~4.5, the curved becomes taller and
taller, until it wraps itself displaying an evident loop.
We would say that the value of ~2 is a reasonable maximum
one and that increasing that value is just to obtain special
effects.
\begin{figure}[!htb]\centering
\begin{Esempio}[\setfontsize{8.5}]%
\unitlength=0.01\textwidth
\begin{picture}(70,70)
\put(0,0){\color{black}\framebox(70,70){}}
\put(0,0){\color{red}%
\Curve(0,0)<1,1>(70,0)<1,-1>}
\Curve(0,0)<1,1>(70,0)<1,-1;0,0>
\Curve(0,0)<1,1>(70,0)<1,-1;0.2,0.2>
\Curve(0,0)<1,1>(70,0)<1,-1;2,2>
\Curve(0,0)<1,1>(70,0)<1,-1;4.5,4.5>
\Curve(0,0)<1,1>(70,0)<1,-1;0,3>
\Curve(0,0)<1,1>(70,0)<1,-1;3,0>
\end{picture}
\end{Esempio}
\caption{The effects of tension factors}\label{fig:tensions}
\end{figure}
Figure~\ref{fig:sinewave} displays two approximations of
a sine wave; Bézier splines can approximate transcendental
curves, but the approximation may be a poor one, depending
on the approximated curve, when few arcs are used to draw
it. With arcs specified with more complicated macros the
approximation is better even with a lower number of arcs.
With many arcs it is possible to approximate almost nything.
On the left side of figure~\ref{fig:sinewave} a modest
approximation is obtained with just three standard arcs
obtained with |\Curve| and four node specifications; on the
right we have just two arcs created with |\CBezierBetween|
with tension specification and control point distances;
this drawing is almost undistinguishable from a real
sinusoid.
\begin{figure}[!htb]
\begin{minipage}{\linewidth}\small
\begin{verbatim}
\unitlength=0.01\textwidth
\begin{picture}(100,50)(0,-25)
\put(0,0){%
\VECTOR(0,0)(45,0)\VECTOR(0,-25)(0,25)
\Pbox(45,0)[b]{x}[0]\Pbox(0,26)[tl]{y[0]}
\Curve(0,0)<77:1>(10,20)<1,0;2,0.4>(30,-20)<1,0;0.4,0.4>(40,0)<77:1;0.4,2>
}
\put(55,0){%
\VECTOR(0,0)(45,0)\VECTOR(0,-25)(0,25)
\Pbox(45,0)[b]{x}[0]\Pbox(0,26)[tl]{y}[0]
\CbezierBetween0,0And20,0WithDirs77:1And-77:1UsingDists28And{28}
\CbezierBetween20,0And40,0WithDirs-77:1And77:1UsingDists28And{28}}
\end{picture}
\end{verbatim}
\end{minipage}\vspace{\baselineskip}
\begin{minipage}{\linewidth}
\unitlength=0.01\textwidth
\begin{picture}(100,50)(0,-25)
\put(0,0){\VECTOR(0,0)(45,0)\VECTOR(0,-25)(0,25)
\Pbox(45,0)[b]{x}[0]\Pbox(0,26)[tl]{y}[0]
\Curve(0,0)<77:1>(10,20)<1,0;2,0.4>(30,-20)<1,0;0.4,0.4>(40,0)<77:1;0.4,2>
}
\put(55,0){\VECTOR(0,0)(45,0)\VECTOR(0,-25)(0,25)
\Pbox(45,0)[b]{x}[0]\Pbox(0,26)[tl]{y}[0]
\CbezierBetween0,0And20,0WithDirs77:1And-77:1UsingDists28And{28}
\CbezierBetween20,0And40,0WithDirs-77:1And77:1UsingDists28And{28}}
\end{picture}
\end{minipage}
\caption{A sequence of arcs; the left figure has been drawn with the
\cs{Curve} command with a sequence of four couples of node-direction
arguments; the right figure has been drawn with two commands
\cs{CbezierBetween} that include also the specification of the control
points}
\label{fig:sinewave}
\end{figure}
In figure~\ref{fig:quadratic-arcs} some lines are shown;
they are drawn with quadratic splines by means of the
|\Qurve| macro. In the left there are some open and closed
curves inscribed within a square.
On the right a “real" circle is compared to a quadratic
spline circle; the word “real†is emphasised because it
actually is an approximation with four quarter-circle cubic
splines that, in spite of being drawn with third degree
parametric polynomials, approximate very well a real circle;
on the opposite the quadratic spline circle is clearly a
poor approximation even if the maximum radial error amounts
just to about 6\% of the radius.
\begin{figure}[!htb]
\begin{minipage}{\linewidth}
\begin{Verbatim}[fontsize=\setfontsize{7.75}]
\unitlength=0.0045\textwidth
\begin{picture}(100,100)
\put(0,0){\framebox(100,100){}}
\put(50,50){%
\Qurve(0,-50)<1,0>(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>(0,-50)<1,0>
\color{green}
\Qurve*(0,-50)<0,1>(50,0)<1,0>[-1,0](0,50)<0,1>[0,-1](-50,0)<-1,0>[1,0](0,-50)<0,-1>
}
\Qurve(0,0)<1,4>(50,50)<1,0>(100,100)<1,4>
\put(5,50){\Qurve(0,0)<1,1.5>(22.5,20)<1,0>(45,0)<1,-1.5>%
(67.5,-20)<1,0>(90,0)<1,1.5>}
\Zbox(0,0)[tc]{0,0}\Zbox(100,0)[tc]{100,0}
\Zbox(100,100)[bc]{100,100}\Zbox(0,100)[bc]{0,100}
\Pall[2](0,0)\Pall[2](100,0)\Pall[2](100,100)\Pall[2](0,100)
\end{picture}
\hfill
\begin{picture}(100,100)
\put(0,0){\framebox(100,100){}}
\put(50,50){%
\Qurve(0,-50)<1,0>(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>(0,-50)<1,0>
\Curve(0,-50)<1,0>(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>(0,-50)<1,0>}
\Zbox(50,50)[t]{O}\Pall[2](50,50)\put(50,50){\Vector(45:50)}\Zbox(67,70)[tl]{R}
\end{picture}
\end{Verbatim}
\end{minipage}\vspace{2\baselineskip}
\begin{minipage}{\linewidth}
\unitlength=0.0045\textwidth
\begin{picture}(100,100)
\put(0,0){\framebox(100,100){}}
\put(50,50){\Qurve(0,-50)<1,0>(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>(0,-50)<1,0>}
\put(50,50){\color{green}%
\Qurve*(0,-50)<0,1>(50,0)<1,0>[-1,0](0,50)<0,1>[0,-1](-50,0)<-1,0>[1,0](0,-50)<0,-1>}
\Qurve(0,0)<1,4>(50,50)<1,0>(100,100)<1,4>
\put(5,50){\Qurve(0,0)<1,1.5>(22.5,20)<1,0>(45,0)<1,-1.5>(67.5,-20)<1,0>(90,0)<1,1.5>}
\Zbox(0,0)[tc]{0,0}\Zbox(100,0)[tc]{100,0}
\Zbox(100,100)[bc]{100,100}\Zbox(0,100)[bc]{0,100}
\Pall[2](0,0)\Pall[2](100,0)\Pall[2](100,100)\Pall[2](0,100)
\end{picture}
\hfill
\begin{picture}(100,100)
\put(0,0){\framebox(100,100){}}
\put(50,50){\Qurve(0,-50)<1,0>(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>(0,-50)<1,0>
\Curve(0,-50)<1,0>(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>(0,-50)<1,0>}
\Zbox(50,50)[t]{O}\Pall[2](50,50)\put(50,50){\Vector(45:50)}\Zbox(67,70)[tl]{R}[0]
\end{picture}
\end{minipage}
\caption{\rule{0pt}{4ex}Several graphs drawn with quadratic
Bézier splines. On the right a quadratic spline circle is
compared with a cubic line circle.}
\label{fig:quadratic-arcs}
\end{figure}
Notice that the previous version of \pack{curve2e} contained
an error and would color the outside of the green four-pointed
star. The |curve2e-v161| package, attached to this bundle, has
been corrected; therefore it is not actually identical to the
previous version, although the latter one performed correctly
for everything else except for color filled quadratic paths.
The “real†circle, even if rendered with quarter circles, is visually very similar to a true circumference, but any Bézier circle arc that approximates a circumference arc of the same amplitude, displays a small error at an angle of 1/4 and 3/4 the total arc amplitude; this error diminishes as the total arc amplitude diminishes, nevertheless the error is there. If the arc amplitude amounts to 180°, the maximum error is at 45° and at 135° angular distances from the staring point. It amounts to 2\% of the arc radius; see figure~\ref{fig:halfcircle}, where a half circle is compared with a sequence of four arcs of 45° each, drawn by means of the \cs{Curve} macro; the code is the following:
\begin{verbatim}
\unitlength=0.005\linewidth
\begin{picture}(100,50)(-50,0)
\AutoGrid
\Zbox(0,0)[t]{\textsf{O}}[1]
\Arc(0,0)(50,0){180}
\VECTOR(0,0)(45:50)\Zbox(45:25)[br]{R}[0]
\Curve(50,0)<0,1>(45:50)<135:1>(0,50)<-1,0>%
(135:50)<225:1>(-50,0)<0,-1>
% \Arc(0,0)(50,0){90}\Arc(0,0)(0,50){90}
% \Curve(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>
\end{picture}
\end{verbatim}
\begin{figure}\centering
\unitlength=0.005\linewidth
\begin{picture}(100,50)(-50,0)
\AutoGrid
\Zbox(0,0)[t]{\textsf{O}}[1]
\Arc(0,0)(50,0){180}
\VECTOR(0,0)(45:50)\Zbox(45:25)[br]{R}[0]
\Curve(50,0)<0,1>(45:50)<135:1>(0,50)<-1,0>%
(135:50)<225:1>(-50,0)<0,-1>
% \Arc(0,0)(50,0){90}\Arc(0,0)(0,50){90}
% \Curve(50,0)<0,1>(0,50)<-1,0>(-50,0)<0,-1>
\end{picture}
\caption{Comparison between a 180° arc (red) drawn with the \cs{Arc} macro, and a comparable half circle (blaxk) drawn with four 45° \cs{Curve} arcs}\label{fig:halfcircle}
\end{figure}
The circle radius amounts to $R=50$\cs{unitlength}, while the external line, drawn with \cs{Arc}, at 45° displays the maximum distance from the circle center \textsf{O}; it amounts to $51$\cs{unitlength}, 2\% larger than the correct value. In most circumstances this error is negligible, but sometimes the drawing by means of \cs{Curve} is more appropriate.
An alternative solution consists in tracing two consecutive arcs of 90° each drawn with \cs{Arc}, instead of four arcs of 45° each drawn with \cs{Curve} or with \cs{Arc}. The code above contains also the other solutions; they are commented out but the user can copy the code and paste it in a personal \texttt{.tex} file, so that each solution can be tested individually, so as to remark the (invisible) differences.
%
\item The new version of |\multiput| is backwards compatibile with
the original version contained in the \LaTeX\ kernel. The new macro
adds the handling of the coordinate increments from one position to
the next for the \meta{object} to include in the drawing.
The syntax is the following:
\begin{Sintassi}\setfontsize{8}
|\multiput|\parg{initial point}\parg{increment}\marg{number of items}\marg{object}\oarg{handler}
\end{Sintassi}
The only small change is the addition of the last optional argument that allows to do several interesting actions on the sequence o objects to be repeated, for example, to set them on a curved line, instead of on a straight line, as shown in figure~\ref{pag:multiput}.
In this figure we show the code for the picture shown there. The red grid
is nothing new, except that it displays the traditional |\multiput| used
in this code, shown in a previous example, produces exactly the same
result. But for what concerns the four “graphs†on the grid, it displays
an alignment of black dots along the diagonal of the grid (again
traditional |\multiput| rendered with the new version); a number of blue
dots along a parabola; another number of magenta coloured dots alined
along a half sine wave; a number of little green squares aligned along
a $-15~\circ$ sloping line starting from the center of the grid; notice
the polar values that are used as polar relative coordinate increments.
\noindent\begin{figure}[!htb]
\begin{minipage}{0.45\linewidth}
\begin{Verbatim}[fontsize=\setfontsize{8}]
\unitlength=0.01\linewidth
\begin{picture}(100,100)
\GraphGrid(100,100)
\multiput(0,0)(10,10){11}{\circle*{2}}
\color{blue!70!white}
\multiput(0,0)(10,0){11}{\circle*{2}}%
[\GetCoord(\R)\X\Y
\edef\X{\fpeval{\X+10}}
\edef\Y{\fpeval{(\X/10)**2}}
\CopyVect\X,\Y to\R]
\color{magenta}
\multiput(0,0)(10,1){11}{\circle*{2}}%
[\GetCoord(\R)\X\Y
\edef\X{\fpeval{\X+10}}
\edef\Y{\fpeval{sind(\X*1.8)*100}}
\CopyVect\X\Y to\R]
\color{green!80!black}
\multiput(50,50)(-15:5){11}}{%
\polygon*(-1,-1)(1,-1)(1,1)(-1,1)}
\end{picture}
\end{Verbatim}
\end{minipage}
\hfill
\begin{minipage}{0.45\linewidth}
\unitlength=0.01\linewidth
\begin{picture}(100,100)
\GraphGrid(100,100)
\multiput(0,0)(10,10){11}{\circle*{2}}
\color{blue!70!white}
\multiput(0,0)(10,0){11}{\circle*{2}}%
[\GetCoord(\R)\X\Y
\edef\X{\fpeval{\X+10}}
\edef\Y{\fpeval{(\X/10)**2}}
\CopyVect\X,\Y to\R]
\color{magenta}
\multiput(0,0)(10,1){11}{\circle*{2}}%
[\GetCoord(\R)\X\Y
\edef\X{\fpeval{\X+10}}
\edef\Y{\fpeval{sind(\X*1.8)*100}}
\CopyVect\X,\Y to\R]
\color{green!60!black}
\multiput(50,50)(-15:5){11}{\polygon*(-1,-1)(1,-1)(1,1)(-1,1)}
\end{picture}
\end{minipage}
\caption{Some examples of the \meta{handler} optional argument}\label{pag:multiput}
\end{figure}
A new command |\xmultiput| (not available with the previous versions
of \pack{curve2e}) is extended with respect to the original
|\multiput|; it is defined by using some L3 functions; in particular the
cycling counter is accessible to the \LaTeX\ commands and it is stepped
up from~1 to the value specified in the proper command argument
(in the original command it starts from that value and is stepped down
to zero). See the figure on page~\ref{pag:orologio} to inspect its
usage. It is important to notice that if the command|\rotatebox|
has to be used, as in the example of figure~\ref{pag:orologio}, the
package |graphicx| should be also loaded, because \pack{curve2e} does
not load it.
Th |\xmultiput| syntax is the is similar to that of |\multiput| but besides the stepping up or down of the iteration counter, it can access and modify certain internal with the commands that appear in the \meta{handler} argument. Actually this \meta{handler} is available also with |\multiput|. In both cases the handler can be defined to modify some internals, including the iteration counter only for |\xmultipot|, but also the |\R| and |\D| internals; |\R| contains the coordinates where to put the \meta{object}, while |\D|, if set, contains the angle of rotation of the object. The code and picture examples in figures~\ref{pag:multiput} and~\ref{pag:orologio} show some examples of usage through tis \meta{handler} code.
.
\begin{Sintassi}\small
|\xmultiput|\parg{initial point}\parg{increment}\marg{iterations}\marg{object}\oarg{handler}
\end{Sintassi}
\begin{figure}[!htb]
\begin{minipage}{0.45\textwidth}\setfontsize{9.5}%
\begin{verbatim}
\unitlength=0.0095\linewidth
\begin{picture}(100,100)
\GraphGrid(100,100)
\put(50,50){\thicklines\circle{100}}
\xmultiput[50,50](60:40)(-30:1){12}%
{\makebox(0,0){\circle*{2}}}%
[\MultVect\R by\D to\R]%
\xmultiput[50,50](60:46)(-30:1){12}%
{\ArgOfVect\R to\Ang
\rotatebox{\fpeval{\Ang-90}}%
{\makebox(0,0)[b]{\Roman{multicnt}}}}%
[\Multvect{\R}{\D}\R]
\end{picture}
\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}{0.40\textwidth}\raggedleft
\unitlength=0.0095\linewidth
\begin{picture}(100,100)
\GraphGrid(100,100)
\put(50,50){\thicklines\circle{100}}
\xmultiput[50,50](60:40)(-30:1){12}%
{\makebox(0,0){\circle*{2}}}[\Multvect{\R}{\D}{\R}]%
\xmultiput[50,50](60:43)(-30:1){12}%
{\ArgOfVect\R to\Ang\rotatebox{\fpeval{\Ang-90}}%
{\makebox(0,0)[b]{\Roman{multicnt}}}}%
[\Multvect{\R}{\D}\R]
\end{picture}
\end{minipage}
\caption{Usage example of the \texttt{\string\xmultiput} command}
\label{pag:orologio}\hfill
\end{figure}
\item This implementation of \pack{curve2e} includes an extension
to package |xfp|, in the sense that adds three more L3 commands:
|\fptest|, |\fpdowhile|, |\fpwhiledo| to the two already contained and
documented in the latter package. The syntax of such new commands
is the following
\begin{Sintassi}
\cs{fptest}\marg{test}\marg{true}\marg{false}
\cs{fpdowhile}\marg{test}\marg{operations to be repeated}
\cs{fpwhiledo}\marg{test}\marg{operations to be repeated}
\end{Sintassi}
The macro |\fptest| requires two further arguments that contain
what to do if the \meta{test} is true, and what to do if the
\meta{test} is false.
The \meta{test} is a logical expressions that connects math relation
expressions, even floating point ones, by means of \emph{logical
operators}; such operators are \verb+||+, \verb|&&|, and \verb|!|,
respectively for OR, AND, NOT; math relation expressions contain
relation operators, even negated ones: for example \verb|!<| means
“not lower thanâ€, which is equivalent to “equal or grater thanâ€, i.e.
\verb|=>|. The logical expression is parsed left to right and normal
parentheses may be used to alter this sequence. The logical operators
work also between logical variables, therefore the \meta{test} may
contain an interesting mixture of relation and logical operators.
Before using |\fpdowhile| and |\fpwhiledo|, the arguments of \meta{test}
depends-on must be set so that the test is true; during the execution
of the \meta{operations to be repeated} there must be some setting
that eventually renders the \meta{test} false. The user should
pay attention to set the elements that \meta{test} depends on,
because the risk is to enter an infinite loop and end up with some
error message stating that the working memory of the program is full.
Notice that |\fpdowhile| first puts the \meta{operations to be repeated}
into the work flow then checks the \meta{test} and possibly repeats the
cycle; on the opposite, |\fpwhiledo| first checks the \meta{test} then
possibly inserts the \meta{operations to be repeated} and cycles.
Evidently with the same \meta{test} the two while cycles produce
different results with a little, but important difference: if the input
data are macros defined by previous computations, there is no guarantee
that the \meta{test} is initially true; if it sis false, |fpwhiledo|
does not do anything, while |\fpdowhile| executes one cycle and produces
in the output stream something that might be nonsense. Cycles done
with |\fpwhiledo| should be safer and should be preferred.
Nevertheless such commands are very useful also for drawing graphics;
the |xmultiput| command already makes use of such L3~functions.
As an example of use, we show how to plot a mathematical function
expressed in parametric form:
\[\begin{cases}
x = f_1(t)\\
y = f_2(t)
\end{cases}\]
The plot is executed with a piecewise linear approximation of the
curve; if the $t$ steps are sufficiently small, the plot turns out to
be very nice; here we show an example where we plot a Lissajous curve
with two sinusoids of different periods.
We start by defining the Lissajous function with arguments
to specify the parameter $t$, the sinusoid amplitudes $A_1, A_2$,
the respective “frequenciesâ€, by means of integer multiples of
a unit pulsation, $N_1, N_2$, and the initial phases
$\phi_1, \phi_2$ of such sinusoids. It is better to keep
apart the input of the curve coefficients from the actual curve
argument/parameter and output point coordinates:
\begin{verbatim}
\def\LissajousCoefs#1,#2,#3,#4,#5,#6!{%
\edef\LAu{#1}\edef\LNu{#2}\edef\LFu{#3}%
\edef\LAd{#4}\edef\LNd{#5}\edef\LFd{#6}}
\def\LissajousCode#1#2{%
\edef\X{\fpeval{\LAu*cosd(\LNu*#1+\LFu)}}%
\edef\Y{\fpeval{\LAd*cosd(\LNd*#1+\LFd)}}%
\CopyVect\X,\Y to#2\ignorespaces}
\end{verbatim}
As it is shown, the coefficients are specified as a comma separated
list; the \verb|!| list terminator is taken care by the actual
drawing command.
Then the curve drawing command requires the coefficient specification
only the first time it is used; some messages\footnote{Here it would
be better to have available a “Macro Error†message; such a macro
is not available, but it would be possible to define it by means
of the \cs{GenericError} macro provided by the \LaTeX2e\ kernel.
Here we skip this definition in order to avoid overloading this
documentation with such details.} are output if the coefficients
have been “forgottenâ€.
\begin{verbatim}
\NewDocumentCommand\Lissajous{m o m}{%
\IfValueTF{#2}{\LissajousCoefs#2!\relax
\LissajousCode{#1}{#3}}%
{\ifcsname LAu\endcsname
\LissajousCode{#1}{#3}%
\else\PackageError{curve2e}%
{This Lissajous' curve coefficients\MessageBreak
are missing}{Nothing done}\fi}%
\ignorespaces}
\end{verbatim}
The syntax is the following:
\begin{Sintassi}
\cs{Lissajous}\marg{in}\Oarg{\meta{$A_1$},\meta{$N_1$},\meta{$\phi_1$},\meta{$A_2$},\meta{$N_2$},\meta{$\phi_2$}}\meta{$P_{\mathrm{out}}$}
\end{Sintassi}
where \meta{$P_{\mathrm{out}}$} is a macro that gets
defined with the cartesian coordinates of the computed output
point. Arguments \meta{in} (the $t$ parameter) and \meta{$P_\mathrm{out}$} (the comput coordinates) need not be enclosed within braces if they are given as macros; actually the code shown in figure~\ref{fig:lissajous} shows such procedure that renders the input code simpler to read.
After this definition the diagram is plotted in
figure~\ref{fig:lissajous}.
%
\begin{figure}[!htb]\centering
\begin{Esempio}[\setfontsize{8.5}](0.55)
\unitlength=0.01\linewidth
\begin{picture}(100,100)(-50,-50)
\AutoGrid
\VECTOR(-50,0)(50,0)\Pbox(50,0)[tr]{x}[0]
\VECTOR(0,-50)(0,50)\Pbox(0,50)[tr]{y}[0]
\Pbox(0,0)[tr]{O}[2]
\thicklines
{\countdef\I=2560 \I=0
\fpdowhile{\I !> 360}{%
\fptest{\I=0}%
{\Lissajous\I[40,2,90,40,3,0]\Pout
\moveto(\Pout)}%
{\Lissajous\I\Pout
\lineto(\Pout)}%
\advance\I by1}\strokepath}%
\end{picture}
\end{Esempio}
\caption{A Lissajous diagram}\label{fig:lissajous}
\end{figure}
For the independent variable $t$, the parameter of the Lissajous
parametric equations, it is better to work with degrees instead
of radians, and with integer numbers, so that the whole range
from $0^\circ$ to $360^\circ$ is certainly spanned. Notice the
braces that include the code for the Lissajous diagram; they may
be useful to render that group suitable to be |\put| somewhere
else than with its center at the origin of the canvas axes,
and/or to be used as the second argument of a
\cs{rotatebox}\marg{angle} command so as to rotate the whole
diagram.
%
\item Another useful application of |\fpdowhile| is the following: when making a diagram the axes should get suitable labeled ticks in order to show the graduations; the label of each tick should lay close to the axis on the other side than the tick. It is also necessary to know if the axis to be marked is horizontal or vertical, since in the former case each tick is vertical, while in the latter case it is horizontal. The example in figure~\ref{fig:ticks} shows both the code and its usage. The syntax of the |\Tbox| macro is the following.
\begin{Sintassi}
|\Tbox|\parg{coordinates}\oarg{reference}\marg{label}\oarg{size}\aarg{direction}
\end{Sintassi}
where \meta{coordinates} indicates the position of the tick base along its axis; \meta{reference} is a letter, either |t| (if the axis is on top of the label) or |b|(if the axis is at the bottom of the label) for vertical ticks or either |r| (if the axis is at the right of the label) or |l| (if the axis is at the left of the label) for horizontal ticks; \meta{label} is the value of the scale or a literal label that by default is typeset in math mode, so that a math symbol may be used without the need of entering math mode, while in the unusual circumstance that a textual label is to be used, users should use the |\text| macro; the \meta{size} argument is the size of the tick: if such size is zero, just the label is set, but in this case the |\Tbox| macro behaves as the the |\Zbox| one, and accepts two reference codes in order to print the label the same as |\Zbox| would do when the dot size is zero; the \meta{direction} argument is the letter |V| for vertical ticks, and |H| for horizontal ticks. There is some redundancy because |\Tbox| may behave as |\Zbox|, but experience shows that this is not a problem.
The source preamble should contain the following code.
{\small\begin{verbatim}
\makeatletter
\NewDocumentCommand\Tbox{D(){0,0} O{cc} m O{0pt} D<>{Z}}{\bgroup
\edef\TBoxCode{#5}\dimen0=#4\relax %
\edef\tempE{\fpeval{round(#4/\unitlength,3)}}%
\put(#1){%
\ifdim\dimen0=\z@
\Zbox(0,0)[#2]{#3}[\z@]%
\else
\if\TBoxCode V\relax
\let\tempC=b\relax
\if\tempC #2\edef\tempD{0,-\tempE}\else\edef\tempD{0,\tempE}\fi
\segment(0,0)(\tempD)\Zbox(0,0)[#2]{#3}[\z@]%
\else
\if\TBoxCode H\relax
\let\tempC=l\relax%
\if\tempC #2\edef\tempD{-\tempE,0}\else\edef\tempD{\tempE,0}\fi
\segment(0,0)(\tempD)\Zbox(0,0)[#2]{#3}[\z@]%
\else
\typeout{The specified code\space #5\space is invalid!}%
\typeout{\string\Tbox\space command ignored}%
\fi
\fi
\fi
}\egroup\ignorespaces}%
\end{verbatim}
}
If the code is contained in a personal |.sty| file the
|\makeatletter| should be omitted.
As it can be seen, the fifth argument code is preset to to |Z| so that if users forget to specify it, error messages pop op and can be seen in both the console window and in the log file, but no tick and label are typeset. This kind of commands to label in one way or another may be very useful depending on the users' kind of drawings. Figure~\ref{fig:labeled diagram} contains also the iterations to label the axes and are done with the
|\fpdowhile| macro; it can be seen that the actual coordinate of each tick is transformed into the actual label that is put in its position by the
|\Zbox| command; of course the diagram scale and the actual label are related to one another but do not have the same value.
\begin{figure}
{\small\begin{verbatim}
\centering\unitlength=0.007\linewidth
\begin{picture}(100,70)(-50,-10)%
\AutoGrid
\thicklines
\VECTOR(-50,0)(50,0)\Zbox(50,0)[br]{x}[0pt]%
\VECTOR(0,0)(0,60)\Zbox(0,60)[tl]{y}[0pt]%
%
{\def\Coord{-40}%
\fpdowhile{\Coord<=40}{\edef\X{\fpeval{round(\Coord/20,1)}}%
\Tbox(\Coord,0)[t]{\X}[1.5mm]<V>\edef\Coord{\fpeval{\Coord+10}}}%
%
\def\Coord{10}%
\fpdowhile{\Coord<=50}{\edef\Y{\fpeval{round(\Coord/20,1)}}%
\Tbox(0,\Coord)[r]{\Y}[1.5mm]<H>\edef\Coord{\fpeval{\Coord+10}}}%
}%
%
{\color{blue}\linethickness{1.5pt}%
\Curve(-40,0)<1,0>(0,20)<45:1>% Parabola: y=0.25(x_2)^2
\Curve(0,20)<1,0>(20,0)<0,-1>% Quarter circle: x^2+y^2=1
\Curve(20,0)<0,1>(40,34.64)<49:1>}% Hyperbola:x^2-y^=1
\thinlines
\Dashline(0,0)(45,45){2}% asymptote
\end{picture}
\end{verbatim}
}
\bigskip
\centering\unitlength=0.007\linewidth
\begin{picture}(100,70)(-50,-10)%
\AutoGrid
\thicklines
\VECTOR(-50,0)(50,0)\Zbox(50,0)[br]{x}[0pt]%
\VECTOR(0,0)(0,60)\Zbox(0,60)[tl]{y}[0pt]%
%
{\def\Coord{-40}%
\fpdowhile{\Coord<=40}{\edef\X{\fpeval{round(\Coord/20,1)}}%
\Tbox(\Coord,0)[t]{\X}[1ex]<V>\edef\Coord{\fpeval{\Coord+10}}}%
%
\def\Coord{10}%
\fpdowhile{\Coord<=50}{\edef\Y{\fpeval{round(\Coord/20,1)}}%
\Tbox(0,\Coord)[r]{\Y}[1ex]<H>\edef\Coord{\fpeval{\Coord+10}}}%
}%
{\color{red}\linethickness{1.5pt}%
\Curve(-40,0)<1,0>(0,20)<45:1>% Parabola: y=0.25(x_2)^2
\Curve(0,20)<1,0>(20,0)<0,-1>% Quarter circle: x^2+y^2=1
\Curve(20,0)<0,1>(40,34.64)<49:1>}% Hyperbola:x^2-y^2=1
\thinlines
\Dashline(0,0)(45,45){2}% asymptote
\end{picture}
\caption{The code to draw a diagram with labeled axes}\label{fig:labeled diagram}
\end{figure}
%
\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Remarks}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
In spite of the relative simplicity of the macros contained in this
package, the described macros, as well as the original ones included in
the \pack{pict2e} package, allow to produce fine drawings that were
unconceivable with the original \LaTeX\ picture environment. Leslie
Lamport himself announced an extension to his environment when \LaTeXe\
was first released in 1994; in the |ltnews| news-letter of December
2003, the first implementation of Lamport's extension was announced;
the first version of this package \pack{curve2e} was issued in 2006.
It was time to have a better drawing environment; this package
is a simple attempt to follow the initial path while further extending
the drawing facilities.
There are other packages in the \textsc{ctan} archives that deal with
tracing curves of various kinds. \pack{PSTricks} and \pack{pgf/tikz} are
the most powerful ones. And they are becoming the standard for computer
drawing. Their documentation is huge and the multitude of extra modules
to perform special tasks is countless. Therefore they are difficult to
use; when the user gets used to their particular syntax and got
sufficient familiarity with several modules, s/he can use these bundles
very comfortably.
This difficulty in becoming a TikZ or PS expert is why I think a simpler
drawing machinery should be appreciated. I admit it: I like the
\env{picture} environment; and I like to deal with simple codes so as to
create my own macros.
But there is also \pack{curves} that is intended to draw almost
anything by using little dots or other symbols partially superimposed
to one another. It uses only quadratic Bézier curves and the curve
tracing is eased by specifying only the curve nodes, without specifying
the control nodes; with a suitable package option, it is
possible to reduce the memory usage by using short straight segments
drawn with the PostScript facilities offered by the |dvips| driver.
Another package, \pack{ebezier} performs about the same as
\pack{curve2e} but draws its Bézier curves by using little dots
partially superimposed to one another. The documentation is quite
interesting since it explains very clearly what exactly are the Bézier
splines. Apparently \pack{ebezier} should be used only for DVI output
without recourse to PostScript or PDF machinery.
The \pack{picture} package extends the performance of the \env{picture}
environment (extended with \pack{pict2e}) by accepting coordinates
and lengths in real absolute dimensions, not only as multiples of
|\unitlength|; it provides commands to extend that functionality to
other packages. In certain circumstances it may be very useful.
Package \pack{xpicture} builds over the \env{picture} \LaTeX\
environment so as to allow to draw the usual curves that are part
of an introductory analytic geometry course; lines, circles,
parabolas, ellipses, hyperbolas, and polynomials; the syntax is
rather comfortable, although it is not a simple extension of the
\env{picture} own syntax; for all these curves it uses the quadratic
Bézier splines.
Package \pack{hobby} extends the cubic Bézier spline handling with the
algorithms John Hobby created for \MF\ and \MP. But by now this package
interfaces very well with |tikz|; it has not (yet) been adapted to the
common \env{picture} environment extended with \pack{pict2e}, and,
why not, with \pack{curve2e}.
If you are interested in further extensions of |curve2e|, besides creating yourself the macros you need, examine the |euclideangeometry| package; I created it in order to have available further functionalities useful to deal with more complicated geometrical constructions. Another small extension is |graphpaper| by which users can produce themselves drawing paper with bilinear coordinates, semi-logarithmic and bi-logarithmic coordinates, polar linear or semilogarithmic coordinates, and Smith charts. They are an extension chain of the packages that extend the picture environment: |graphpaper| calls |euclideangeometry| which calls
|curve2e| which calls |pict2e|. I find all this very useful. Of corse these packages and their documentation are all contained in \TeX~Live.
I am about to complete a book on electromagnetism and electronic circuit theory: it contains some 300 drawings, diagrams, electronic circuits. I created them with |curve2e| and some macros based on this |picture| extension package. The graphics of my book are pretty nice, and I am sure that a professional technical artist can draw better ones, but such an artist would be very expensive and the process would require a lot of time to correct, modify, add details, and so on, while doing things by oneself is certainly a better solution. Packages |tikz|/|pgfplots| and |PStricks|? Certainly they are very good and much more powerful, but, besides being sort of difficult to learn to use, they require a lot of working memory and more often than not I ran out of computer memory.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Acknowledgements}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
I wish to express my deepest thanks to the many persons who submitted notices about bugs or inconsistencies.
Michel Goosens spotted some errors and very kindly submitted
them to me so that I was able to correct them.
I collaborated extensively with Josef Tkadlec in order to
implement a better real long division so as to get correctly
the quotient fractional part and to avoid as much as
possible any numeric overflow; many Josef's ideas were
incorporated in the long division macro that was implemented
in the previous version of this package, although the macro
used by Josef was slightly different. Both versions
aim/aimed at a better accuracy and at widening the operand
ranges.
In this version of \pack{curve2e} I abandoned our long
division macro, and substituted it with the floating point
division provided by the |xfp| package functionalities that
are now part of the \LaTeX\ kernel.
Daniele Degiorgi spotted a fault in the kernel definition of
|\linethickness| that heavily influenced also \pack{curve2e}; see the code documentation \file{curve2e.pdf} file.
Domenicus van der Wijst spotted a sneaky bug in the updated |\Arc| macro; for arcs not wider than $180^\circ$ that macro worked properly, while for larger angle apertures it produced syntax errors. It was just a typo, but very sneaky.
Jin-Hwan Cho and Juho Lee suggested a small but crucial modification in order to have \pack{curve2e} work smoothly also with XeTeX (XeLaTeX). Actually if \pack{pict2e}, version 0.2x or later, dated 2009/08/05 or later, is being used, such modification is not necessary any more, but it is true that it was imperative when legacy versions were used.
Ashish Kumar Das spotted an inconsistency in the design of vectors with PostScript style arrow tips with large line width settings, that did not show up with \LaTeX\ styled ones.
\end{document}